Skip to content

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

Rust

Merge remote-tracking branch 'origin/main' into HEAD

AkitaOnRails3b11876dad41
diff --cc CHANGELOG.md
index 7c672ab4,e17b2932..888c7e65
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -7,154 -7,163 +7,318 @@@ and this project adheres to [Semantic V
## [Unreleased]
+### Added
+- Added the end reason to session-end observations. When a harness's
+ `SessionEnd` payload carries a `reason` (Claude Code sends `clear`,
+ `logout`, `prompt_input_exit` or `other`), its first line is stored,
+ sanitized, as the observation body, so consolidation can tell a normal
+ quit from anything else, and the zero-LLM session page closes its summary
+ with `ended (<reason>)`. Payloads without a reason are stored as before.
+ (#1225)
-
+- The web UI shows pending cross-project mail. Project cards carry an amber
+ `N inbox` badge when messages are waiting for an agent in that project, the
+ home page summarises the total and links the projects holding mail, and the
+ project page gains a read-only Mailbox section listing up to five of them
+ (subject, sender, a snippet, age; "5 of N" when more are waiting), with an
+ empty state when there are none. A sender the viewer may not read is shown as
+ "a project you cannot read", and the page never pops or cancels a message.
+ (#1202)
+- `install-mcp --client prime-agent` registers ai-memory with Prime Agent
+ (PrimeIntellect-ai/prime-agent), merging an HTTP entry into the `mcpServers`
+ map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default
+ `~/.prime/agent/settings.json`) and preserving other settings and servers.
+ With a token the entry names `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`
+ and the token is not written; Prime Agent 0.10 counts a user HTTP server as
+ connected, and lists it to the model, only with that variable set (or an
+ OAuth grant), so export it where you launch `prime-agent`. Without a token
+ the server is still callable through `mcp.call_tool("ai-memory", ...)` but is
+ not listed. MCP-only: Prime Agent 0.10 has no lifecycle hooks. (#1163)
+- `memory_write_page` accepts `expected_page_id` (write only if that is still
+ the page's latest version) or `create_only` (write only if the page does not
+ exist), and `memory_delete_page` accepts `expected_page_id`. A precondition
+ that no longer holds fails with `reason: "precondition_failed"` and the
+ current version, and changes nothing. `memory_read_page` returns the version
+ as `page_id` and `/api/v1` pages as `id`. This is the compare-and-write the
+ team-wiki sync needed (#986).
+- The `ai-memory-wikisync` companion gained CI and post-merge integration
+ (#986, slice 5): `sync --check` writes nothing and exits 0 in sync, 3 on
+ drift and 4 on conflicts or refusals (a clone without sync state compares
+ the repository with the server directly), and `install-hook` /
+ `uninstall-hook` manage a marked git `post-merge` block that runs `sync`
+ after each merge: a dry-run report unless `--on-merge apply`, never with
+ `--prefer`, and never with a stored token. The cookbook has a GitHub
+ Actions recipe. (#986)
+- The `ai-memory-wikisync` companion now propagates deletes with
+ `sync --propagate-deletes` (#986, slice 4): a file deleted in the repository
+ deletes its server page through `memory_delete_page`, and a page deleted on
+ the server deletes its file, when the other side is unchanged since the last
+ sync. A delete against an edit is a conflict that `--prefer` resolves, more
+ than `--max-deletes` (default 10) refuses the run, and a pinned page is
+ deleted only with `--prefer repo`. Every sync write and delete now carries
+ the page version it was planned against, so a page changed during the run is
+ reported and left alone while the rest apply, and `sync --apply` refuses a
+ server older than 2.7. Without the flag deletes are still only reported.
+ (#986)
+- `ai-memory doctor` now reports three silent capture failures: an unreachable
+ server (reported instead of aborting the check), a hook spool that is full and
+ evicting undelivered events, and installed ai-memory Codex hooks that Codex
+ skips because they are untrusted or changed since they were trusted (asked
+ of Codex itself through `codex app-server`). `ai-memory status` no longer says
+ queued events will be delivered once the spool has started evicting them.
+- Added two-way sync to the `ai-memory-wikisync` companion (#986, slice 3):
+ `sync` imports repository edits and new pages through the public
+ `memory_write_page` MCP tool and exports server edits, comparing each
+ page with the last sync. A page changed on both sides is a conflict until
+ `--prefer repo` or `--prefer server`; deletes are reported, not synced.
+ It is a dry-run without `--apply`, refuses files without frontmatter,
+ refuses to overwrite server pages whose metadata a write would clear, and
+ re-reads each page right before writing it. (#1164)
+- `finalize-session --agent antigravity-cli` now replays the session's typed
+ prompts from `agy`'s `history.jsonl` before its synthetic session-end, so
+ live Antigravity sessions, whose hooks carry no prompt event, get a summary
+ page titled by the first prompt, a handoff with "Started/Last", and prompts
+ that `memory_query` and `memory_recent` can find. Only lines whose
+ conversation and workspace match the session are read; each prompt carries
+ the key `backfill` mints for it, so a repeated `--reopen` stores it once and a
+ prompt typed after the first finalize arrives with the next one. A checkout
+ the capture allowlist does not admit and `--all-owners` runs replay nothing,
+ and a missing `history.jsonl` only warns. (#1160)
+- `ai-memory run` accepts `copilot` (alias `copilot-cli`) and manages GitHub
+ Copilot CLI as a workstream harness: a fresh session gets a generated
+ `--session-id`, a returning one is resumed with `--resume=<id>`, user
+ selectors (`--resume`, `--continue`, `--session-id`, `--connect`) win,
+ utility subcommands pass through, and `--yolo` maps to Copilot's native
+ `--yolo`. Visible messages, tool calls and results, and compaction summaries
+ are imported read-only from `$COPILOT_HOME/session-state/<uuid>/events.jsonl`
+ (system prompts, hidden reasoning, hook output, and telemetry are excluded),
+ and the existing SessionStart hook delivers the workstream context. The
+ first managed launch auto-wires Copilot's hooks and MCP, and `doctor` now
+ counts its local sessions. Verified against Copilot CLI 1.0.92. (#1040)
+- GitHub Copilot CLI is now a first-class routing target:
+ `install-skills --agent copilot-cli` (and `install-instructions
+ --skills-agent copilot-cli`) writes the managed Agent Skills to the
+ repository's `.github/skills` or, globally, to `$COPILOT_HOME/skills`
+ (default `~/.copilot/skills`); `memory_install_self_routing` returns
+ `copilot_cli` filename and skill-root hints; the routing snippet, the
+ routing-install skill, and the MCP instructions name Copilot CLI with
+ `AGENTS.md`; and `uninstall` sweeps both Copilot roots, removing only
+ marker-bearing ai-memory skills. (#1040)
+- Added `ai-memory recover` and a bounded local recovery journal for server
+ outages. Offline managed launches now record only uniquely correlated native
+ session locators; recovery quarantines overlapping spool entries before exact
+ `/hook/batch` transcript replay, journals harnesses without transcript export
+ as spool-only without calling their exporter, retains bounded recovery dedup
+ keys with their sessions,
+ fails closed on terminal drops, and lets only the original owner finish an
+ expired unsuperseded managed run through exact idempotent replay. Backfill
+ and recovery replay now use reserved `recovery_*` idempotency keys, so
+ re-running `backfill --force` over sessions imported by ai-memory ≤2.6.0 (or
+ plain-backfilling a recovery-replayed session) can duplicate those older
+ observations. (#1125)
+- Added `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING` for the `openai-compat`
+ provider (opt-in, off by default, ignored by every other provider): when
+ set, every chat request carries
+ `chat_template_kwargs: {"enable_thinking": false}`, so thinking-capable
+ local engines (vLLM / SGLang serving Qwen3-class models) spend the output
+ budget on the structured payload instead of a reasoning pass. (#1130)
+- Added the `cursor` LLM provider. Consolidation calls the logged-in Cursor
+ Agent CLI (`agent --print --mode ask`) so a Cursor subscription can drive
+ summaries without an API key. The default model is `cursor-grok-4.6-high`
+ ("Grok 4.6"). `AI_MEMORY_CURSOR_AGENT` overrides the binary. The provider never passes
+ `--yolo` or `--force`, because the prompt is captured session text. (#1127)
+- Added `applies_to` and `enforced_by` arguments to `memory_write_page`, and
+ `--applies-to` / `--enforced-by` to `ai-memory write-page`, for profile
+ entries. Both fields were documented as profile-entry frontmatter, but no
+ tool could set them, so scoping an entry to a stack or keeping it out of the
+ digest meant editing the wiki file by hand, and the next tool rewrite of the
+ entry dropped the value. A tag the profile cannot detect in any project
+ (`typscript`) is refused instead of silently hiding the entry, and both
+ arguments are refused on any page the digest does not read: one outside
+ `profile/`, or a `profile/` path in an ordinary project. (#1178)
-
+- Added the server version to the footer of every signed-in `/web` page (the
+ public login and change-password pages leave it out), on the right
+ side opposite "ai-memory · read-only", so you can tell which build a browser
+ tab is talking to without running `ai-memory status`. (#1171)
-
+- Added `install-mcp --client dsh` for the DeepSeek Harness (aliases
+ `deepseek-harness` and `deepseek_harness`). DSH keeps its MCP client in
+ a Cordis profile patch rather than a fixed config file, so the command prints a
+ ready-to-merge `- insert:` fragment for `@deepseek-ai/dsh-mcp-client` and
+ refuses `--apply`. (#1193)
+
+### Changed
+- Changed `ai-memory-wikisync` files to carry a small frontmatter (`title`,
+ plus `tags`, `pinned` and a non-default `tier` when set) above the body,
+ so metadata survives a round trip. The first run after upgrading rewrites
+ unedited files of an earlier export in place. (#1164)
+
+### Fixed
++- Fixed SessionEnd consolidation repeating the same expensive prompt on the
++ durable queue when the structured LLM response fails deterministically: a
++ truncated or empty response, malformed JSON, or an unexpected response
++ shape now ends the queue on the first attempt, keeping the heuristic page
++ the hook already wrote; pre-send connection and capacity (`503`) failures
++ retain the bounded backoff. (#1131)
++- Fixed structured LLM responses stopped at the output budget
++ (`finish_reason = "length"`) or returned without usable content: they now
++ fail with redacted terminal errors, without copying the response. (#1130)
++
+ ## [2.6.4] - 2026-10-12
+
+ ### Fixed
+ - Fixed Gemini CLI's `run_shell_command` and `read_many_files` tools being
+ classified as unknown, so `[capture] ignore_paths` never checked them and a
+ call reading an ignored file still had its output written to the local hook
+ spool and sent to the server, which then discarded it. `run_shell_command` is
+ now a shell tool, read like `Bash` and resolved from its `dir_path`, and
+ `read_many_files` is a file tool: the call is dropped when any of its
+ `include` globs names or could expand into an ignored path, and glob syntax
+ the matcher cannot evaluate makes it metadata-only. Gemini's
+ `list_directory` and the legacy `search_file_content` name are now search
+ tools, dropped under an active policy like `grep_search` and `glob`. A shell
+ command whose `**` glob could recurse into an ignored directory (zsh, or bash
+ with `globstar`) is now dropped too. A `read_many_files` entry naming a
+ directory above an ignored path (`docs`, `.`), which Gemini reads
+ recursively, is dropped as well. GitHub Copilot CLI's `view`, `create` and
+ `str_replace_editor` are now file tools, checked against `ignore_paths` like
+ `Read` and `Write`. Under an active or invalid policy, tools that read back
+ output of an earlier command (Claude Code `BashOutput`/`TaskOutput`, Codex
+ `write_stdin`, Hermes and OpenClaw `process`, Copilot CLI `read_bash` and
+ `write_bash`) and shell commands using brace expansion or a bracket class
+ are now metadata-only, since the matcher cannot prove they miss an ignored
+ path; upgrade the server before the clients, because an older server drops
+ those events. A script quoted inside a string-form shell command (an
+ `sh -c` argument, a command substitution in double quotes) is now read like
+ the rest of the command line, the path in a git object name (`REV:path`) is
+ checked, Antigravity's `run_command` resolves its arguments from its `Cwd`,
+ and ANSI-C strings and backslash-escaped letters are read the way the shell
+ reads them. Inline interpreter code (`python3 -c`, `node -e` and similar)
+ and further glob syntax the matcher does not evaluate (zsh glob groups,
+ extglobs, encoded escapes) are now metadata-only under an active policy.
+ Line continuations, parameter defaults, values glued to short flags,
+ `file:` URLs, `~+`, PowerShell and cmd escape characters, and shell or
+ interpreter options placed before the script or code are now read too, and
+ more script runners and interpreters are recognized. A path under a
+ directory only the running shell knows (`~-`, `~name`) makes the call
+ metadata-only, and on macOS paths match without regard to case, as its
+ default filesystem does, including non-ASCII letters and decomposed accents.
+ A checkout's `ignore_paths` now also hold for a file, search/list or shell
+ tool call made from another checkout or from an unmarked directory that
+ reaches one of its files, including through glob syntax in a directory
+ name, a search's path or file filter, or the files an `apply_patch` names.
+ Glob directories outside the event's own checkout are followed through the
+ directories on disk within fixed bounds of count and time; past them, or for
+ glob syntax that cannot be followed, the call is metadata-only, and so is a
+ file tool whose target cannot be read. A glob inside the event's own
+ checkout is not walked, so ordinary monorepo commands over many packages
+ (`cat packages/*/package.json`, `du -sh packages/*`) keep their output with
+ or without a marker, and neither are a large brace expansion that cannot
+ leave it (`touch test/file{1..200}.txt`) or the checkout's own subtree under
+ a `**` that starts above it. Each directory's marker is looked up once, so
+ many paths in a deep tree stay within the hook's time budget, and a
+ dotfiles `.git` in the home directory no longer counts as every project's
+ own checkout. A `..` after a `**`, a dot glob that older bash
+ expands to the parent directory (POSIX classes and extglobs included), a
+ brace expansion, a zsh glob group, an ANSI-C escape (also inside a
+ double-quoted `bash -c` or `eval` script), an indented `apply_patch` header
+ and Hermes `search_files`' `file_glob` filter can no longer hide which
+ checkout a call reaches. A broken
+ marker makes a search metadata-only, as it does a file or shell call.
+ Reading back a file a harness saved an earlier tool's output to
+ (Claude Code's saved large results and background task output, OpenCode's
+ and Pi's truncated output files), or a glob that could match one, is
+ metadata-only under an active or invalid policy, like `BashOutput`; an
+ ordinary log glob (`tail -n 50 log/*.log`, `cat /tmp/*.log`) is not taken
+ for one. A `file:` URL's query or fragment is no longer
+ read as part of its path, a parameter default nested deeper than the matcher
+ reads is metadata-only, and a backslash escape inside a default is read. A
+ quoted `~` (`git commit -m "fix ~approx"`) is no longer treated as a home
+ or user directory, so such commands are kept again.
+ In a Windows session, Git Bash, MSYS2 and Cygwin spellings (`/c/...`,
+ `/cygdrive/c/...`), a rooted path without a drive, the `\\?\`, `\\.\` and
+ `\\localhost\C$` prefixes, an alternate data stream suffix and trailing dots
+ or spaces are read as the file they open, so they no longer slip past a
+ pattern. The `cwd`, the marker's directory and an absolute pattern get the
+ same reading, so a session started from `\\?\C:\repo` or
+ `\\localhost\C$\repo` matches its relative patterns again. A bare or
+ double-quoted `\\server\share\...` or `\\?\C:\...` argument keeps both
+ backslashes, as PowerShell and cmd read it, and `/a/x` is also read from the
+ root of the `cwd`'s drive, as a native tool reads it. The generated
+ TypeScript marker reader no longer takes a line inside a multi-line array
+ (`["docs"]`) for a table header. Hermes `execute_code` is metadata-only under an active policy, like
+ `python3 -c`, and a shell command longer than 1 MiB is metadata-only instead
+ of being split. The generated TypeScript integrations now read a dotted
+ `capture.ignore_paths` key and quoted `[capture]` headers, reject the shapes
+ the native hook rejects (an inline `capture = { ... }` table among them),
+ recognize the same file tools (`read_file`, `patch`, `fs_read`, ...), and stop
+ reading a directory at the walk's entry bound. Checking a path of thousands
+ of wildcard segments for a saved output file no longer takes seconds.
+ In a Windows session, a shell argument or `workdir` that is drive-relative
+ (`C:docs\x`) or a device path naming no drive (`\\?\GLOBALROOT\...`) now
+ makes the command metadata-only instead of being skipped, a PowerShell
+ `FileSystem::` provider prefix is read as the path after it, and a Windows
+ marker holding a POSIX absolute pattern (`/c/repo/docs/**`), which matched
+ nothing, is now invalid and fails closed.
+ This applies to the native hook, the server, and the
+ generated TypeScript integrations. (GHSA-gcpc-88hm-3xqr)
+ - Fixed `ai-memory backfill`, including the automatic first-boot import, and
+ the `ai-memory run` workstream ledger not applying `[capture] ignore_paths`
+ to the harness transcripts they import, so the arguments and output of a
+ tool call on an ignored file could be stored even though live hooks drop
+ them. Both now apply the same decision as the live hook to every imported
+ tool call and its result: an excluded call is not imported at all, one the
+ policy cannot prove safe keeps only its tool family, and prompts and
+ assistant messages are imported as before, and under allowlist capture
+ mode a checkout without a marker imports nothing. Results recorded without an id
+ linking them to their call take the strictest decision of their turn.
+ A call the transcript names differently from the hook (Codex's shell tool) is
+ judged under the hook's name, each event is judged from the working directory
+ its own record names, and a call or event the live hook would deliver to
+ another checkout is imported only when that checkout would capture it and
+ sends to the same server and project; events recorded in, or calls reaching
+ into, a checkout of another project are left out instead of being filed
+ under the importing project, and so are events from a different
+ subdirectory of the same repository, which the server files under a
+ project of their own. The output of a Claude Code `!` shell command,
+ which live capture never receives, is no longer imported. Claude Code's
+ background-task notifications (a monitored command's output, a finished
+ background command or agent) are no longer imported as prompts, whatever the
+ case or spacing of their opening tag, and its compaction summary is
+ imported as a compaction record instead of a prompt.
+ A tool ai-memory does not recognize, such as an MCP tool, is imported as a
+ record that it ran without its arguments, output or name, which is all live
+ capture stores for it, and so is a result whose call is not in the
+ transcript. (GHSA-gcpc-88hm-3xqr)
+ - Fixed a web page open in the operator's browser being able to act on an
+ unauthenticated server (the loopback default, no token), such as claiming a
+ project's pending handoff or starting admin jobs. With auth off, the machine
+ and admin routes now refuse browser requests that come from another site or
+ that are not script calls from a page, such as links and images; hooks, the
+ CLI, MCP clients and the built-in web UI are unaffected, and servers with a
+ bearer token are unchanged. Images in wiki pages rendered by the web UI are
+ also limited to relative paths that stay inside the UI. When an
+ unauthenticated server is reached through a non-loopback host name in its
+ allowlist (a LAN address or name, or `host.docker.internal`), where browsers
+ do not send the request metadata the check relies on, the session-start
+ handoff fetch now also requires an `X-AI-Memory-Client` header that every
+ ai-memory hook, CLI command and generated integration sends; the same holds
+ for a request that arrives through a forwarding proxy or CDN (any of the
+ common forwarding headers, including `CF-Connecting-IP`, `True-Client-IP`
+ and `X-Forwarded-Proto`), even one that rewrites
+ the host to the loopback address. Hooks on such a
+ server must be re-staged with `ai-memory install-hooks` (or
+ `ai-memory upgrade`); loopback installs need nothing.
+ (GHSA-6mc4-46pr-w82w)
+ - Fixed `POST /auth/login` and `POST /auth/recovery` accepting request bodies
+ that are not declared as JSON, which a page on another site could use to
+ sign the operator's browser in or to try passwords when human sign-in is
+ enabled. Both routes now answer 415 unless the body is `application/json`;
+ the built-in login page and the documented `curl` recovery already send
+ that. (GHSA-6mc4-46pr-w82w)
+ - Fixed the web UI allowing other sites to frame it. With auth off, a page
+ that framed `/web/pending` could trick a click on Approve or Reject, since
+ the framed page's own requests are same-origin. Every web page and API
+ response now sends `X-Frame-Options: DENY` and
+ `Content-Security-Policy: frame-ancestors 'none'`. (GHSA-6mc4-46pr-w82w)
- Fixed the cross-project profile harvester treating pages the auto-improve
scheduler auto-approved as curated human input: model output nobody
reviewed fed the profile like a hand-written rule. A page stamped from an
diff --cc crates/ai-memory-cli/src/commands/backfill.rs
index 88de8778,4c5b5535..8e340f36
--- a/crates/ai-memory-cli/src/commands/backfill.rs
+++ b/crates/ai-memory-cli/src/commands/backfill.rs
@@@ -39,10 -39,10 +39,11 @@@ use anyhow::{Context, Result, bail}
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, build_launch_plan_with_env, export_transcript,
- list_native_sessions, wait_for_transcript_flush,
+ export_transcript_delta, export_transcript_range, list_native_sessions,
+ wait_for_transcript_flush,
};
use super::doctor::{SCANNED_HARNESSES, relocated_session_dir};
@@@ -518,105 -487,29 +542,111 @@@ async fn import_one
build_launch_plan_with_env(session.harness, None, Vec::new(), None, &[], Some(roots))
.ok()
.and_then(|plan| plan.session_dir);
- // These are historical sessions, so the flush wait is a quick no-op; ignore
- // its result and read whatever is on disk.
- let _ = wait_for_transcript_flush(
- session.harness,
+ import_exact_session(
+ endpoint,
+ workspace,
+ project,
home,
cwd,
- session_dir.as_deref(),
+ session.harness,
&session.native_session_id,
+ session_dir.as_deref(),
+ None,
++ capture,
)
- .await;
- let transcript = export_transcript(
- session.harness,
+ .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.as_deref(),
- &session.native_session_id,
+ 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
- .with_context(|| format!("reading the {} transcript", session.harness.as_str()))?;
+}
- let sid = &session.native_session_id;
- let agent = session.harness.agent_kind().as_str();
+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(
@@@ -631,8 -524,14 +661,20 @@@
serde_json::json!({ "session_id": sid, "occurred_at": resolved.earliest }),
)?);
let mut content = 0usize;
- for (event, occurred_at) in transcript.events.iter().zip(&resolved.per_event) {
- if let Some(mapped) = map_event(recovery_interval_id, sid, event, occurred_at.as_deref()) {
+ 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(sid, event, occurred_at.as_deref(), capture) {
++ if let Some(mapped) = map_event(
++ recovery_interval_id,
++ sid,
++ event,
++ occurred_at.as_deref(),
++ capture,
++ ) {
items.push(hook_item(
endpoint,
workspace,
@@@ -663,79 -562,6 +705,88 @@@
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) {
- let Some(mapped) = map_event(None, native_session_id, event, occurred_at.as_deref()) else {
++ // 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 {
@@@ -824,8 -650,18 +875,19 @@@ struct MappedEvent
/// `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>,
@@@ -834,13 -671,13 +897,18 @@@
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 = format!("{session_id}:{}", event.event_id);
+ 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(),
@@@ -1915,7 -1144,13 +2017,14 @@@ mod tests
WorkstreamEventKind::Annotation,
] {
assert!(
- map_event(None, "sid", &event(kind, None, "boundary"), None).is_none(),
+ map_event(
++ None,
+ "sid",
+ &event(kind, None, "boundary"),
+ None,
+ &EventCapture::Keep
+ )
+ .is_none(),
"{kind:?} is not session content"
);
}
diff --cc crates/ai-memory-cli/src/commands/recovery.rs
index 92109b7c,00000000..6d0be311
mode 100644,000000..100644
--- a/crates/ai-memory-cli/src/commands/recovery.rs
+++ b/crates/ai-memory-cli/src/commands/recovery.rs
@@@ -1,2207 -1,0 +1,2210 @@@
+//! Downtime recovery — the offline journal and `ai-memory recover`.
+//!
+//! When the server is unreachable, `ai-memory run` degrades instead of
+//! failing: hooks spool locally and a degraded launch still runs the harness.
+//! The spool returns by itself, but two kinds of history used to need a
+//! hand-typed repair and, for the transcript, were simply lost:
+//!
+//! - a run whose lease existed but whose transcript `finish` could not reach
+//! the dead server (`finish-failed`);
+//! - a degraded launch's session, which no server run ever recorded
+//! (`degraded-run`).
+//!
+//! Both now append a bounded, metadata-only entry to a local journal
+//! (`<data_dir>/recovery-journal.json`). `ai-memory recover`, run once the
+//! server is back, drains the spool and then works the journal: it re-exports
+//! each `finish-failed` session's transcript from the native store through the
+//! ordinary managed-run finish path, and replays each degraded launch's exact
+//! native transcript through the ordinary sanitized `/hook/batch` backfill
+//! path. Harnesses without transcript export are journaled explicitly as
+//! spool-only and recovery never invokes their exporter. Stable ingest and
+//! event keys make both paths idempotent. Entries clear as they succeed;
+//! failures stay journaled with their reason.
+//!
+//! The journal never holds transcript content or secrets — only locators,
+//! ordered semantic digests, and delivery evidence. Recovery never regenerates
+//! the original repository checkpoint, so later repository state is not
+//! attributed to the interrupted run. Transcripts are re-exported from the native store
+//! at recover time instead of being copied into the data dir: the store is
+//! the same durable local source the online path reads seconds after the
+//! child exits, and re-export reuses the exact adapter path rather than
+//! maintaining a second serialized copy of private conversation content.
+
+use std::collections::HashMap;
+use std::fs::{self, File, OpenOptions};
+use std::path::{Component, Path, PathBuf};
+use std::str::FromStr as _;
+use std::time::{Duration, Instant};
+
+use ai_memory_core::{ManagedRunId, Sanitizer};
+use ai_memory_workstream::TranscriptCapability;
+use anyhow::{Context as _, Result, anyhow, bail};
+use fs2::FileExt as _;
+use serde::{Deserialize, Serialize};
+
+use crate::cli::RecoverArgs;
+use crate::commands::hook_spool::{self, DrainLockWait, MaxAttempts, RestoreOutcome};
++use crate::commands::transcript_capture::TranscriptCapture;
+use crate::config::Config;
+use crate::http_client::{ServerEndpoint, ServerProbe, probe_server};
+
+/// Journal file name inside the data dir.
+const JOURNAL_FILE: &str = "recovery-journal.json";
+/// Exclusive-mutation lock file name inside the data dir.
+const JOURNAL_LOCK_FILE: &str = "recovery-journal.lock";
+/// Journal schema version.
+const JOURNAL_VERSION: u32 = 1;
+/// Most entries kept. Appends at capacity are refused so recovery work is
+/// never silently evicted.
+pub(crate) const MAX_JOURNAL_ENTRIES: usize = 256;
+/// Refuse to load or overwrite a journal larger than this, mirroring the
+/// client project registry's guard: a swollen file is corruption, not backlog.
+const MAX_JOURNAL_BYTES: u64 = 16 * 1024 * 1024;
+/// Reasons remembered per entry across recover attempts.
+const MAX_ENTRY_FAILURES: usize = 3;
+const MAX_FAILURE_REASON_BYTES: usize = 2_048;
+
+/// How the entry's history was cut off from the server.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub(crate) enum JournalKind {
+ /// A degraded launch made while the server was unreachable: no managed
+ /// run ever existed, so recovery replays its exact native transcript
+ /// through the hook backfill path after draining the spool.
+ DegradedRun,
+ /// A run whose transcript import failed because the server died after the
+ /// child exited: the run still exists server-side, so recovery re-exports
+ /// the transcript and finishes it again.
+ FinishFailed,
+}
+
+impl JournalKind {
+ /// Stable label for reports.
+ #[must_use]
+ pub(crate) fn as_str(self) -> &'static str {
+ match self {
+ Self::DegradedRun => "degraded-run",
+ Self::FinishFailed => "finish-failed",
+ }
+ }
+}
+
+/// One bounded, metadata-only record of history the server missed.
+///
+/// Constructed by `run` at the moment the loss is detected; consumed by
+/// `recover` once the server answers again.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub(crate) struct JournalEntry {
+ /// Unique entry id; recovery clears per entry.
+ pub(crate) id: String,
+ /// When the loss was recorded (RFC 3339, UTC).
+ pub(crate) recorded_at: String,
+ /// Inclusive lower bound for hook events belonging to this launch.
+ pub(crate) interval_started_ms: u64,
+ /// Inclusive upper bound for hook events belonging to this launch.
+ pub(crate) interval_ended_ms: u64,
+ /// How the run was cut off.
+ pub(crate) kind: JournalKind,
+ /// Managed harness name (`ManagedHarness::as_str`), including the exact
+ /// Kiro engine flavor so recovery reads the right native store.
+ pub(crate) harness: String,
+ /// Native session locator for transcript re-export.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) native_session_id: Option<String>,
+ /// Session-store override the launch resolved (`--session-dir` and kin),
+ /// without which the native transcript may be unreachable.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) session_dir: Option<String>,
+ /// Canonical checkout directory the run launched from.
+ pub(crate) cwd: String,
+ /// Workspace name for degraded transcript replay and reporting.
+ pub(crate) workspace: String,
+ /// Project name for degraded transcript replay and reporting.
+ pub(crate) project: String,
+ /// Server URL the run targeted, for a mismatch warning at recover time.
+ pub(crate) server_url: String,
+ /// Managed run id (`finish-failed` only): the recovery import target.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) run_id: Option<String>,
+ /// Ordered semantic digests for this exact transcript interval. `Some([])`
+ /// proves a successful empty export; `None` means export was unavailable.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) event_digests: Option<Vec<String>>,
+ /// Whether this typed harness capability permits spool evidence only and
+ /// must never invoke a native transcript exporter.
+ #[serde(default)]
+ pub(crate) spool_only: bool,
+ /// Exact native adapter cursor captured before a resumed launch.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) source_cursor: Option<String>,
+ /// Exact native adapter cursor captured immediately after child exit.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) final_cursor: Option<String>,
+ /// Whether correlated hook events have ever been observed locally.
+ #[serde(default)]
+ pub(crate) correlated_events_seen: bool,
+ /// Whether a prior pass durably delivered all correlated hook evidence.
+ #[serde(default)]
+ pub(crate) correlated_delivery_confirmed: bool,
+ /// Whether a prior pass lost potentially correlated hook evidence.
+ #[serde(default)]
+ pub(crate) correlated_loss: bool,
+ /// Child exit code, replayed with the recovered import.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub(crate) exit_code: Option<i32>,
+ /// Reasons from previous recover attempts, newest last, bounded.
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
+ pub(crate) failures: Vec<String>,
+}
+
+/// Wire shape of the journal file.
+#[derive(Debug, Serialize, Deserialize)]
+struct JournalFile {
+ version: u32,
+ entries: Vec<JournalEntry>,
+}
+
+/// `<data_dir>/recovery-journal.json`.
+#[must_use]
+pub(crate) fn journal_path(data_dir: &Path) -> PathBuf {
+ data_dir.join(JOURNAL_FILE)
+}
+
+/// Read the journal; a missing file is an empty journal, a corrupt or swollen
+/// one is an error the caller surfaces (never silently reset: the file is the
+/// only record of what the server missed).
+pub(crate) fn load_journal(data_dir: &Path) -> Result<Vec<JournalEntry>> {
+ let path = journal_path(data_dir);
+ refuse_symlink(data_dir, &path)?;
+ let mut file = match open_journal_read(&path) {
+ Ok(file) => file,
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
+ Err(error) => {
+ return Err(error).with_context(|| format!("reading {}", path.display()));
+ }
+ };
+ if file.metadata()?.len() > MAX_JOURNAL_BYTES {
+ bail!(
+ "recovery journal {} exceeds the {} byte limit",
+ path.display(),
+ MAX_JOURNAL_BYTES
+ );
+ }
+ let mut bytes = Vec::new();
+ use std::io::Read as _;
+ file.read_to_end(&mut bytes)?;
+ if bytes.len() as u64 > MAX_JOURNAL_BYTES {
+ bail!(
+ "recovery journal {} exceeds the {} byte limit",
+ path.display(),
+ MAX_JOURNAL_BYTES
+ );
+ }
+ let journal: JournalFile = serde_json::from_slice(&bytes).with_context(|| {
+ format!(
+ "parsing {}; refusing to discard the recorded recovery work",
+ path.display()
+ )
+ })?;
+ if journal.version != JOURNAL_VERSION {
+ bail!(
+ "unsupported recovery journal version {} in {} (expected {JOURNAL_VERSION})",
+ journal.version,
+ path.display()
+ );
+ }
+ if journal.entries.len() > MAX_JOURNAL_ENTRIES {
+ bail!(
+ "recovery journal {} exceeds the {} entry limit",
+ path.display(),
+ MAX_JOURNAL_ENTRIES
+ );
+ }
+ Ok(journal.entries)
+}
+
+/// Append one entry under the exclusive lock. Atomic (tmp + rename),
+/// owner-only, and symlink-refusing so a swapped file cannot be trampled.
+pub(crate) fn append_journal_entry(data_dir: &Path, entry: JournalEntry) -> Result<()> {
+ mutate_journal(data_dir, |entries| {
+ if entries.len() >= MAX_JOURNAL_ENTRIES {
+ bail!(
+ "recovery journal is full ({MAX_JOURNAL_ENTRIES} entries); run `ai-memory recover` before another degraded launch"
+ );
+ }
+ entries.push(entry);
+ Ok(())
+ })
+}
+
+/// Rewrite the journal under the exclusive lock with `mutate` applied. The
+/// lock spans the whole read-modify-write so two finishing launches cannot
+/// lose each other's entry.
+fn mutate_journal(
+ data_dir: &Path,
+ mutate: impl FnOnce(&mut Vec<JournalEntry>) -> Result<()>,
+) -> Result<()> {
+ validate_journal_entry_limit(data_dir)?;
+ let path = journal_path(data_dir);
+ let lock = open_private_lock(data_dir, &data_dir.join(JOURNAL_LOCK_FILE))?;
+ lock.lock_exclusive()
+ .with_context(|| format!("locking {}", data_dir.join(JOURNAL_LOCK_FILE).display()))?;
+ let mut entries = load_journal(data_dir)?;
+ mutate(&mut entries)?;
+ let journal = JournalFile {
+ version: JOURNAL_VERSION,
+ entries,
+ };
+ let mut rendered =
+ serde_json::to_vec_pretty(&journal).context("serializing the recovery journal")?;
+ rendered.push(b'\n');
+ refuse_symlink(data_dir, &path)?;
+ if rendered.len() as u64 > MAX_JOURNAL_BYTES {
+ bail!(
+ "recovery journal {} would exceed the {} byte limit",
+ path.display(),
+ MAX_JOURNAL_BYTES
+ );
+ }
+ write_journal_atomic(data_dir, &path, &rendered)
+ .with_context(|| format!("writing {}", path.display()))?;
+ make_private(&path)?;
+ Ok(())
+}
+
+fn write_journal_atomic(data_dir: &Path, path: &Path, bytes: &[u8]) -> Result<()> {
+ let parent = path
+ .parent()
+ .ok_or_else(|| anyhow!("recovery journal path has no parent"))?;
+ refuse_symlink(data_dir, parent)?;
+ let mut temp = tempfile::Builder::new()
+ .prefix(".recovery-journal.")
+ .tempfile_in(parent)?;
+ {
+ use std::io::Write as _;
+ temp.write_all(bytes)?;
+ temp.as_file().sync_data()?;
+ }
+ refuse_symlink(data_dir, path)?;
+ temp.persist(path).map_err(|error| error.error)?;
+ if let Ok(directory) = File::open(parent) {
+ let _ = directory.sync_all();
+ }
+ Ok(())
+}
+
+fn validate_journal_entry_limit(data_dir: &Path) -> Result<()> {
+ let path = journal_path(data_dir);
+ refuse_symlink(data_dir, &path)?;
+ match fs::metadata(&path) {
+ Ok(metadata) if metadata.len() > MAX_JOURNAL_BYTES => bail!(
+ "recovery journal {} exceeds the {} byte limit",
+ path.display(),
+ MAX_JOURNAL_BYTES
+ ),
+ Ok(_) => Ok(()),
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
+ Err(error) => Err(error).with_context(|| format!("inspecting {}", path.display())),
+ }
+}
+
+fn open_journal_read(path: &Path) -> std::io::Result<File> {
+ let mut options = OpenOptions::new();
+ options.read(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt as _;
+ options.custom_flags(libc::O_NOFOLLOW);
+ }
+ options.open(path)
+}
+
+fn open_private_lock(data_dir: &Path, path: &Path) -> Result<File> {
+ if let Some(parent) = path.parent() {
+ refuse_symlink(data_dir, parent)?;
+ crate::commands::path_util::create_private_dir(parent)
+ .with_context(|| format!("creating {}", parent.display()))?;
+ refuse_symlink(data_dir, parent)?;
+ }
+ refuse_symlink(data_dir, path)?;
+ let mut options = OpenOptions::new();
+ options.create(true).read(true).write(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt as _;
+ options.mode(0o600).custom_flags(libc::O_NOFOLLOW);
+ }
+ let file = options
+ .open(path)
+ .with_context(|| format!("opening {}", path.display()))?;
+ refuse_symlink(data_dir, path)?;
+ make_private(path)?;
+ Ok(file)
+}
+
+/// Refuse a symlink at or below `data_dir` on the way to `path`.
+///
+/// The data dir is the trust root. Its ancestors are the operator's and the
+/// system's (`/var` is a symlink to `/private/var` on macOS, `/home` is often
+/// a symlink), so they are not inspected. The data dir itself, and every
+/// component inside it, must not be a symlink: that is where another local
+/// user could plant one. The comparison is lexical; canonicalizing would
+/// rewrite the ancestors this deliberately trusts.
+fn refuse_symlink(data_dir: &Path, path: &Path) -> Result<()> {
+ let relative = path.strip_prefix(data_dir).with_context(|| {
+ format!(
+ "recovery journal path {} is outside the data dir {}",
+ path.display(),
+ data_dir.display()
+ )
+ })?;
+ if !refuse_symlink_component(data_dir)? {
+ return Ok(());
+ }
+ let mut current = data_dir.to_path_buf();
+ for component in relative.components() {
+ let Component::Normal(component) = component else {
+ bail!("recovery journal path contains a non-normal component");
+ };
+ current.push(component);
+ if !refuse_symlink_component(&current)? {
+ break;
+ }
+ }
+ Ok(())
+}
+
+/// Fail if `path` is a symlink; `Ok(false)` once it does not exist (nothing
+/// below a missing component can exist either).
+fn refuse_symlink_component(path: &Path) -> Result<bool> {
+ match fs::symlink_metadata(path) {
+ Ok(metadata) if metadata.file_type().is_symlink() => {
+ bail!("refusing recovery journal symlink {}", path.display());
+ }
+ Ok(_) => Ok(true),
+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(false),
+ Err(error) => Err(error).with_context(|| format!("inspecting {}", path.display())),
+ }
+}
+
+#[cfg(unix)]
+fn make_private(path: &Path) -> Result<()> {
+ use std::os::unix::fs::PermissionsExt as _;
+ fs::set_permissions(path, fs::Permissions::from_mode(0o600))
+ .with_context(|| format!("restricting permissions on {}", path.display()))
+}
+
+#[cfg(windows)]
+fn make_private(path: &Path) -> Result<()> {
+ let identity = std::process::Command::new("whoami")
+ .output()
+ .context("resolving the Windows recovery-journal owner")?;
+ if !identity.status.success() {
+ bail!("could not resolve the Windows recovery-journal owner");
+ }
+ let owner =
+ String::from_utf8(identity.stdout).context("reading the Windows recovery-journal owner")?;
+ let grant = format!("{}:(F)", owner.trim());
+ let restricted = std::process::Command::new("icacls")
+ .arg(path)
+ .args(["/inheritance:r", "/grant:r"])
+ .arg(grant)
+ .output()
+ .with_context(|| format!("restricting permissions on {}", path.display()))?;
+ if !restricted.status.success() {
+ bail!("could not restrict permissions on {}", path.display());
+ }
+ Ok(())
+}
+
+#[cfg(not(any(unix, windows)))]
+fn make_private(_path: &Path) -> Result<()> {
+ Ok(())
+}
+
+/// Count journal entries for status lines; an unreadable journal reports zero
+/// with its error carried back, never blocking status output.
+pub(crate) fn journal_summary(data_dir: &Path) -> (usize, usize, usize, Option<String>) {
+ match load_journal(data_dir) {
+ Ok(entries) => {
+ let degraded = entries
+ .iter()
+ .filter(|entry| entry.kind == JournalKind::DegradedRun)
+ .count();
+ let finish_failed = entries.len() - degraded;
+ (entries.len(), degraded, finish_failed, None)
+ }
+ Err(error) => (0, 0, 0, Some(format!("{error:#}"))),
+ }
+}
+
+/// Budgets for one `recover` invocation; injectable so tests can prove the
+/// bounds bite.
+#[derive(Debug, Clone, Copy)]
+struct RecoverBudgets {
+ /// Total spool-drain budget. Generous but bounded, matching the hook
+ /// background-drain default: recovery must not hang forever on a wedged
+ /// server, but a large outage backlog must fully flush.
+ drain_total: Duration,
+ /// Per-event POST timeout while draining.
+ drain_event_timeout: Duration,
+ /// Per-journal-entry transcript HTTP budget.
+ entry_timeout: Duration,
+ /// Total journal HTTP budget.
+ journal_total: Duration,
+ /// How long recovery waits on another process's drain lock.
+ drain_lock_wait: Duration,
+}
+
+impl Default for RecoverBudgets {
+ fn default() -> Self {
+ Self {
+ drain_total: Duration::from_secs(5 * 60),
+ drain_event_timeout: Duration::from_secs(30),
+ entry_timeout: Duration::from_secs(60),
+ journal_total: Duration::from_secs(10 * 60),
+ drain_lock_wait: Duration::from_secs(30),
+ }
+ }
+}
+
+/// What recovery did for one journal entry.
+#[derive(Debug)]
+enum EntryRecovery {
+ /// Re-exported and imported; the count is newly imported content events.
+ Imported(usize),
+ /// The harness has no transcript exporter and its complete spool was delivered.
+ RecoveredViaSpool,
+ /// Recovery failed; the entry stays journaled with the reason.
+ Failed(String),
+}
+
+/// Spool-drain counts for the report.
+#[derive(Debug, Default, Clone, Copy, Serialize)]
+struct SpoolOutcome {
+ sent: usize,
+ remaining: usize,
+ dropped: usize,
+}
+
+/// One recovered (or failed) session, for the report.
+#[derive(Debug, Serialize)]
+struct SessionOutcome {
+ kind: &'static str,
+ harness: String,
+ native_session_id: Option<String>,
+ workspace: String,
+ project: String,
+ recorded_at: String,
+ outcome: &'static str,
+ imported_events: usize,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ detail: Option<String>,
+}
+
+/// The full `ai-memory recover` report.
+#[derive(Debug, Serialize)]
+struct RecoverReport {
+ server: String,
+ reachable: bool,
+ spool: SpoolOutcome,
+ spool_lock_busy: bool,
+ spool_incomplete: bool,
+ journal_pending: usize,
+ journal_degraded: usize,
+ journal_finish_failed: usize,
+ sessions: Vec<SessionOutcome>,
+ journal_remaining: usize,
+ #[serde(skip_serializing_if = "Option::is_none")]
+ journal_error: Option<String>,
+}
+
+impl RecoverReport {
+ fn failures(&self) -> usize {
+ self.sessions
+ .iter()
+ .filter(|session| session.outcome == "failed")
+ .count()
+ }
+
+ fn imported_total(&self) -> usize {
+ self.sessions.iter().map(|s| s.imported_events).sum()
+ }
+}
+
+/// Run the `recover` subcommand and return its process exit code.
+///
+/// # Errors
+/// Returns an error only for local infrastructure failures.
+pub async fn run(config: &Config, args: RecoverArgs) -> Result<i32> {
+ let report = recover(config, &RecoverBudgets::default()).await?;
+ if args.json {
+ println!("{}", serde_json::to_string_pretty(&report)?);
+ } else {
+ print_report(&report);
+ }
+ Ok(i32::from(
+ report.reachable
+ && (report.spool_incomplete || report.failures() > 0 || report.journal_error.is_some()),
+ ))
+}
+
+async fn recover(config: &Config, budgets: &RecoverBudgets) -> Result<RecoverReport> {
+ let endpoint = ServerEndpoint::from_config_resolving_auth(config).await;
+ let spool_dir = hook_spool::spool_dir(&config.data_dir);
+ let (mut journal, journal_error) = match load_journal(&config.data_dir) {
+ Ok(entries) => (entries, None),
+ // A broken journal still leaves the spool drain: the two recover
+ // independent halves of the outage.
+ Err(error) => (Vec::new(), Some(format!("{error:#}"))),
+ };
+ let journal_degraded = journal
+ .iter()
+ .filter(|entry| entry.kind == JournalKind::DegradedRun)
+ .count();
+ let journal_finish_failed = journal.len() - journal_degraded;
+
+ if let ServerProbe::Unreachable(_) = probe_server(&endpoint).await {
+ return Ok(RecoverReport {
+ server: endpoint.url.clone(),
+ reachable: false,
+ spool: SpoolOutcome {
+ remaining: hook_spool::spool_len(&spool_dir),
+ ..SpoolOutcome::default()
+ },
+ spool_lock_busy: false,
+ spool_incomplete: false,
+ journal_pending: journal.len(),
+ journal_degraded,
+ journal_finish_failed,
+ sessions: Vec::new(),
+ journal_remaining: journal.len(),
+ journal_error,
+ });
+ }
+
+ let sanitizer = Sanitizer::new(&config.sanitize).map_err(|error| anyhow!(error.to_string()))?;
+ let journal_pending = journal.len();
+ let mut quarantined = HashMap::new();
+ let drain_lock = match hook_spool::acquire_drain_lock(
+ &spool_dir,
+ DrainLockWait::Bounded(budgets.drain_lock_wait),
+ ) {
+ Ok(Some(lock)) => lock,
+ Ok(None) => {
+ return Ok(lock_busy_report(
+ &endpoint,
+ &spool_dir,
+ journal_pending,
+ journal_degraded,
+ journal_finish_failed,
+ journal_error,
+ ));
+ }
+ Err(error) => {
+ return Err(error).context("acquiring the recovery spool lock");
+ }
+ };
+ let restore_quarantine = |quarantined: HashMap<String, hook_spool::QuarantinedSpool>| {
+ let mut first_error = None;
+ for (_, quarantine) in quarantined {
+ if let Err(error) = quarantine.restore(&spool_dir)
+ && first_error.is_none()
+ {
+ first_error = Some(error);
+ }
+ }
+ first_error.map_or(Ok(()), Err)
+ };
+ for entry in &journal {
+ if entry.kind != JournalKind::DegradedRun && !entry.spool_only {
+ continue;
+ }
+ let Some(native_session_id) = entry.native_session_id.as_deref() else {
+ continue;
+ };
+ match hook_spool::quarantine_session_entries(
+ config,
+ &spool_dir,
+ &entry.id,
+ entry.interval_started_ms,
+ entry.interval_ended_ms,
+ &entry.server_url,
+ super::run::harness_from_journal_name(&entry.harness)
+ .map(|harness| harness.agent_kind().as_str())
+ .unwrap_or(&entry.harness),
+ &entry.workspace,
+ &entry.project,
+ Path::new(&entry.cwd),
+ native_session_id,
+ ) {
+ Ok(quarantine) => {
+ quarantined.insert(entry.id.clone(), quarantine);
+ }
+ Err(error) => {
+ restore_quarantine(quarantined)
+ .context("restoring previously quarantined hook events")?;
+ return Err(error).context("quarantining correlated hook events");
+ }
+ }
+ }
+ let mut evidence_started = Vec::new();
+ for entry in &mut journal {
+ if entry.kind != JournalKind::DegradedRun && !entry.spool_only {
+ continue;
+ }
+ let correlated_count = quarantined.get(&entry.id).map_or(0, |value| value.len());
+ if correlated_count > 0 {
+ entry.correlated_events_seen = true;
+ entry.correlated_loss = true;
+ evidence_started.push(entry.id.clone());
+ }
+ }
+ if !evidence_started.is_empty() {
+ update_journal_evidence(&config.data_dir, &journal)?;
+ }
+ for entry in &mut journal {
+ if !entry_supports_transcript_export(entry)
+ && let Some(quarantine) = quarantined.get(&entry.id)
+ && quarantine.len() > 0
+ {
+ let outcome = quarantine
+ .drain_strict(
+ &config.data_dir,
+ budgets.drain_total,
+ budgets.drain_event_timeout,
+ MaxAttempts::new(config.hook_spool.max_attempts),
+ )
+ .await;
+ if outcome.durable > 0 {
+ entry.correlated_events_seen = true;
+ }
+ if outcome.dropped > 0 {
+ entry.correlated_loss = true;
+ }
+ if outcome.remaining == 0
+ && outcome.dropped == 0
+ && outcome.durable > 0
+ && quarantine.complete_spool_only()?
+ {
+ entry.correlated_delivery_confirmed = true;
+ entry.correlated_loss = false;
+ }
+ }
+ }
+ update_journal_evidence(&config.data_dir, &journal)?;
+ let drained = hook_spool::drain_until_quiescent_locked_with_live_token(
+ &spool_dir,
+ &config.data_dir,
+ budgets.drain_total,
+ budgets.drain_event_timeout,
+ config.auth.bearer_token.as_deref(),
+ MaxAttempts::new(config.hook_spool.max_attempts),
+ )
+ .await;
+ let spool = SpoolOutcome {
+ sent: drained.sent,
+ remaining: drained.remaining,
+ dropped: drained.dropped,
+ };
+ let spool_incomplete = spool_is_incomplete(&spool);
+ if spool.dropped > 0 {
+ eprintln!(
+ "ai-memory: recovery: {count} hook event(s) were dropped; recovery remains incomplete unless an exact correlated transcript replaces them",
+ count = spool.dropped
+ );
+ }
+
+ let mut sessions = Vec::with_capacity(journal.len());
+ let mut cleared: Vec<String> = Vec::with_capacity(journal.len());
+ let mut annotated: Vec<(String, String)> = Vec::new();
+ let journal_started = Instant::now();
+ for entry in journal {
+ let mut recovery = if spool_incomplete {
+ EntryRecovery::Failed(format!(
+ "hook spool recovery was incomplete ({} queued, {} dropped); transcript recovery was deferred",
+ spool.remaining, spool.dropped
+ ))
+ } else if let Some(timeout) = entry_budget(journal_started, budgets) {
+ if timeout.is_zero() {
+ failed_reason(
+ &sanitizer,
+ "journal entry recovery timed out; rerun to continue",
+ )
+ } else {
+ match tokio::time::timeout(
+ timeout,
+ recover_entry(config, &endpoint, &sanitizer, &entry),
+ )
+ .await
+ {
+ Ok(recovery) => recovery,
+ Err(_) => failed_reason(
+ &sanitizer,
+ "journal entry recovery timed out; rerun to continue",
+ ),
+ }
+ }
+ } else {
+ failed_reason(
+ &sanitizer,
+ "total recovery budget exhausted; rerun to continue",
+ )
+ };
+ if let Some(quarantine) = quarantined.remove(&entry.id) {
+ let restored = match &recovery {
+ EntryRecovery::Imported(_) => {
+ quarantine.complete().map(|()| RestoreOutcome::Restored)
+ }
+ EntryRecovery::RecoveredViaSpool => Ok(RestoreOutcome::Restored),
+ EntryRecovery::Failed(_) => quarantine.restore(&spool_dir),
+ }
+ .context("restoring quarantined hook events")?;
+ if matches!(restored, RestoreOutcome::AlreadyDelivered) {
+ // The completed marker is durable proof this interval's
+ // correlated evidence reached the server on a prior pass;
+ // the failure only deferred work there is none left of, so
+ // the entry clears instead of staying journaled behind it.
+ recovery = EntryRecovery::RecoveredViaSpool;
+ }
+ }
+ let outcome = match &recovery {
+ EntryRecovery::Imported(_) => "imported",
+ EntryRecovery::RecoveredViaSpool => "recovered-via-spool",
+ EntryRecovery::Failed(_) => "failed",
+ };
+ let imported_events = match &recovery {
+ EntryRecovery::Imported(events) => *events,
+ _ => 0,
+ };
+ let detail = match &recovery {
+ EntryRecovery::Imported(_) | EntryRecovery::RecoveredViaSpool => None,
+ EntryRecovery::Failed(note) => Some(note.clone()),
+ };
+ if let EntryRecovery::Failed(reason) = &recovery {
+ annotated.push((entry.id.clone(), reason.clone()));
+ } else {
+ cleared.push(entry.id.clone());
+ }
+ sessions.push(SessionOutcome {
+ kind: entry.kind.as_str(),
+ harness: entry.harness.clone(),
+ native_session_id: entry.native_session_id.clone(),
+ workspace: entry.workspace.clone(),
+ project: entry.project.clone(),
+ recorded_at: entry.recorded_at.clone(),
+ outcome,
+ imported_events,
+ detail,
+ });
+ }
+
+ restore_quarantine(quarantined)?;
+ drop(drain_lock);
+
+ // (d) Clear succeeded entries; failures stay with their reason.
+ let journal_remaining = finish_journal(&config.data_dir, &sanitizer, &cleared, &annotated)?;
+
+ Ok(RecoverReport {
+ server: endpoint.url.clone(),
+ reachable: true,
+ spool,
+ spool_lock_busy: false,
+ spool_incomplete,
+ journal_pending,
+ journal_degraded,
+ journal_finish_failed,
+ sessions,
+ journal_remaining,
+ journal_error,
+ })
+}
+
+fn entry_budget(started: Instant, budgets: &RecoverBudgets) -> Option<Duration> {
+ if budgets.entry_timeout.is_zero() {
+ return Some(Duration::ZERO);
+ }
+ let remaining = budgets.journal_total.checked_sub(started.elapsed())?;
+ (!remaining.is_zero()).then(|| budgets.entry_timeout.min(remaining))
+}
+
+fn spool_is_incomplete(spool: &SpoolOutcome) -> bool {
+ spool.remaining > 0 || spool.dropped > 0
+}
+
+fn lock_busy_report(
+ endpoint: &ServerEndpoint,
+ spool_dir: &Path,
+ journal_pending: usize,
+ journal_degraded: usize,
+ journal_finish_failed: usize,
+ journal_error: Option<String>,
+) -> RecoverReport {
+ RecoverReport {
+ server: endpoint.url.clone(),
+ reachable: true,
+ spool: SpoolOutcome {
+ remaining: hook_spool::spool_len(spool_dir),
+ ..SpoolOutcome::default()
+ },
+ spool_lock_busy: true,
+ spool_incomplete: true,
+ journal_pending,
+ journal_degraded,
+ journal_finish_failed,
+ sessions: Vec::new(),
+ journal_remaining: journal_pending,
+ journal_error,
+ }
+}
+
+async fn recover_entry(
+ config: &Config,
+ endpoint: &ServerEndpoint,
+ sanitizer: &Sanitizer,
+ entry: &JournalEntry,
+) -> EntryRecovery {
+ let recorded = entry.server_url.trim_end_matches('/');
+ let configured_identity = endpoint.identity();
+ let configured = configured_identity.trim_end_matches('/');
+ if recorded.is_empty() || recorded != configured {
+ return failed_reason(
+ sanitizer,
+ &format!("refusing to replay an entry recorded for {recorded:?} against {configured}"),
+ );
+ }
+ if entry.spool_only {
+ return recover_spool_only(sanitizer, entry);
+ }
+ match entry.kind {
+ JournalKind::FinishFailed => {
+ recover_finish_failed(config, endpoint, sanitizer, entry).await
+ }
+ JournalKind::DegradedRun => recover_degraded_run(config, endpoint, sanitizer, entry).await,
+ }
+}
+
+/// Re-export the transcript from the native store and finish the run again.
+/// Reuses `run`'s import machinery verbatim: the server dedups by stable event
+/// id, so a full re-export cannot duplicate history a partial import landed.
+fn recovery_session_dir(entry: &JournalEntry) -> Option<PathBuf> {
+ entry.session_dir.as_deref().map(|path| {
+ let path = Path::new(path);
+ if path.is_absolute() {
+ path.to_path_buf()
+ } else {
+ Path::new(&entry.cwd).join(path)
+ }
+ })
+}
+
+async fn recover_finish_failed(
+ config: &Config,
+ endpoint: &ServerEndpoint,
+ sanitizer: &Sanitizer,
+ entry: &JournalEntry,
+) -> EntryRecovery {
+ let Some(run_id) = entry.run_id.as_deref() else {
+ return failed_reason(sanitizer, "finish-failed entry records no run id");
+ };
+ if ManagedRunId::from_str(run_id).is_err() {
+ return failed_reason(
+ sanitizer,
+ &format!("journal records an invalid run id {run_id}"),
+ );
+ }
+ let Some(harness) = super::run::harness_from_journal_name(&entry.harness) else {
+ return failed_reason(
+ sanitizer,
+ &format!("journal names unsupported harness '{}'", entry.harness),
+ );
+ };
+ let Some(home) = super::run::native_home(config) else {
+ return failed_reason(
+ sanitizer,
+ "the native harness home directory could not be located",
+ );
+ };
+ let Some(expected_digests) = entry.event_digests.as_ref() else {
+ return failed_reason(
+ sanitizer,
+ "finish-failed entry has no exact ordered transcript identity; refusing full transcript replay",
+ );
+ };
+ let Some(final_cursor) = entry.final_cursor.as_deref() else {
+ return failed_reason(
+ sanitizer,
+ "finish-failed entry has no exact post-run transcript cursor; refusing replay",
+ );
+ };
+ let transcript = match entry.native_session_id.as_deref() {
+ Some(native_session_id) => {
+ match ai_memory_workstream::export_transcript_range(
+ harness,
+ &home,
+ Path::new(&entry.cwd),
+ recovery_session_dir(entry).as_deref(),
+ native_session_id,
+ entry.source_cursor.as_deref(),
+ final_cursor,
+ )
+ .await
+ {
+ Ok(transcript) => transcript,
+ Err(error) => {
+ return failed_reason(
+ sanitizer,
+ &format!("native transcript re-export failed: {error:#}"),
+ );
+ }
+ }
+ }
+ None => {
+ return failed_reason(
+ sanitizer,
+ "finish-failed entry records no native transcript locator",
+ );
+ }
+ };
+ let run_path = format!("/workstream/runs/{run_id}/recover");
+ let actual = ai_memory_workstream::transcript_interval_digests(&transcript.events);
+ if &actual != expected_digests {
+ return failed_reason(
+ sanitizer,
+ "native transcript changed since the failed finish; refusing non-identical replay",
+ );
+ }
+ let transcript = ai_memory_workstream::ExportedTranscript {
+ source_cursor: Some(final_cursor.to_owned()),
+ ..transcript
+ };
+ match super::run::import_batches(
+ endpoint,
+ &run_path,
+ transcript,
+ ai_memory_core::WorkstreamCheckpoint::default(),
+ entry.exit_code,
+ sanitizer,
++ &TranscriptCapture::for_checkout(&config.data_dir, Path::new(&entry.cwd)),
+ )
+ .await
+ {
+ Ok(imported) => EntryRecovery::Imported(imported),
+ Err(error) => failed_reason(sanitizer, &format!("managed finish failed: {error:#}")),
+ }
+}
+
+fn failed_reason(sanitizer: &Sanitizer, reason: &str) -> EntryRecovery {
+ EntryRecovery::Failed(ai_memory_core::truncate_utf8_bytes(
+ &sanitizer.scrub(reason),
+ MAX_FAILURE_REASON_BYTES,
+ ))
+}
+
+/// A degraded launch had no server run, so recover its exact native transcript
+/// through the ordinary backfill ingress. That path emits stable keyed
+/// session-start/content/session-end items through `/hook/batch`, making a
+/// repeated recovery idempotent while still crossing the normal sanitizer and
+/// consolidation boundary.
+fn entry_supports_transcript_export(entry: &JournalEntry) -> bool {
+ !entry.spool_only
+ && super::run::harness_from_journal_name(&entry.harness)
+ .is_some_and(|harness| harness.transcript_capability() == TranscriptCapability::Export)
+}
+
+fn recover_spool_only(sanitizer: &Sanitizer, entry: &JournalEntry) -> EntryRecovery {
+ if entry.correlated_delivery_confirmed && !entry.correlated_loss {
+ EntryRecovery::RecoveredViaSpool
+ } else {
+ failed_reason(
+ sanitizer,
+ "no durably delivered correlated hook evidence exists; retain this entry and repair the native session manually",
+ )
+ }
+}
+
+async fn recover_degraded_run(
+ config: &Config,
+ endpoint: &ServerEndpoint,
+ sanitizer: &Sanitizer,
+ entry: &JournalEntry,
+) -> EntryRecovery {
+ let Some(harness) = super::run::harness_from_journal_name(&entry.harness) else {
+ return failed_reason(
+ sanitizer,
+ &format!("journal names unsupported harness '{}'", entry.harness),
+ );
+ };
+ if harness.transcript_capability() == TranscriptCapability::SpoolOnly {
+ return recover_spool_only(sanitizer, entry);
+ }
+ let Some(native_session_id) = entry.native_session_id.as_deref() else {
+ return failed_reason(
+ sanitizer,
+ "no native session was recorded for this degraded run",
+ );
+ };
+ let Some(home) = super::run::native_home(config) else {
+ return failed_reason(
+ sanitizer,
+ "the native harness home directory could not be located",
+ );
+ };
+ let Some(expected_digests) = entry.event_digests.as_deref() else {
+ return failed_reason(
+ sanitizer,
+ "degraded-run entry has no exact ordered transcript identity; repair the native session manually",
+ );
+ };
+ let Some(final_cursor) = entry.final_cursor.as_deref() else {
+ return failed_reason(
+ sanitizer,
+ "degraded-run entry has no exact post-run transcript cursor; repair the native session manually",
+ );
+ };
+ match super::backfill::import_exact_session_range(
+ endpoint,
+ &entry.workspace,
+ &entry.project,
+ &home,
+ Path::new(&entry.cwd),
+ harness,
+ native_session_id,
+ &entry.id,
+ recovery_session_dir(entry).as_deref(),
+ entry.source_cursor.as_deref(),
+ final_cursor,
+ expected_digests,
++ &TranscriptCapture::for_checkout(&config.data_dir, Path::new(&entry.cwd)),
+ )
+ .await
+ {
+ Ok(imported) => EntryRecovery::Imported(imported),
+ Err(error) => failed_reason(
+ sanitizer,
+ &format!("native transcript replay failed: {error:#}"),
+ ),
+ }
+}
+
+/// Apply clears and failure annotations in one locked rewrite; returns the
+/// remaining entry count.
+fn update_journal_evidence(data_dir: &Path, current: &[JournalEntry]) -> Result<()> {
+ mutate_journal(data_dir, |entries| {
+ for entry in entries {
+ if let Some(updated) = current.iter().find(|candidate| candidate.id == entry.id) {
+ entry.correlated_events_seen = updated.correlated_events_seen;
+ entry.correlated_delivery_confirmed = updated.correlated_delivery_confirmed;
+ entry.correlated_loss = updated.correlated_loss;
+ }
+ }
+ Ok(())
+ })
+}
+
+fn finish_journal(
+ data_dir: &Path,
+ sanitizer: &Sanitizer,
+ cleared: &[String],
+ annotated: &[(String, String)],
+) -> Result<usize> {
+ if cleared.is_empty() && annotated.is_empty() {
+ return Ok(load_journal(data_dir).map_or(0, |entries| entries.len()));
+ }
+ let mut remaining = 0_usize;
+ mutate_journal(data_dir, |entries| {
+ entries.retain(|entry| !cleared.contains(&entry.id));
+ for (id, reason) in annotated {
+ if let Some(entry) = entries.iter_mut().find(|entry| &entry.id == id) {
+ let reason = ai_memory_core::truncate_utf8_bytes(
+ &sanitizer.scrub(reason),
+ MAX_FAILURE_REASON_BYTES,
+ );
+ if !entry.failures.contains(&reason) {
+ entry.failures.push(reason);
+ }
+ let overflow = entry.failures.len().saturating_sub(MAX_ENTRY_FAILURES);
+ if overflow > 0 {
+ entry.failures.drain(..overflow);
+ }
+ }
+ }
+ remaining = entries.len();
+ Ok(())
+ })?;
+ Ok(remaining)
+}
+
+fn print_report(report: &RecoverReport) {
+ if !report.reachable {
+ println!(
+ "ai-memory: server at {} is unreachable — nothing to recover yet.",
+ report.server
+ );
+ if let Some(error) = &report.journal_error {
+ println!(" journal: unreadable ({error})");
+ } else {
+ println!(
+ " journal: {} entr{} await{} recovery ({} degraded launch(es), {} failed \
+ transcript import(s))",
+ report.journal_pending,
+ if report.journal_pending == 1 {
+ "y"
+ } else {
+ "ies"
+ },
+ if report.journal_pending == 1 { "s" } else { "" },
+ report.journal_degraded,
+ report.journal_finish_failed,
+ );
+ }
+ println!(
+ " spool: {} hook event(s) queued locally",
+ report.spool.remaining
+ );
+ println!(
+ "Start the server (or fix AI_MEMORY_SERVER_URL), then run `ai-memory recover` again."
+ );
+ return;
+ }
+ println!("ai-memory: recovering against {}…", report.server);
+ if report.spool_lock_busy {
+ println!(" spool: another drainer held the lock; transcript recovery was deferred");
+ } else {
+ println!(
+ " spool: {} hook event(s) delivered, {} remain queued, {} dropped",
+ report.spool.sent, report.spool.remaining, report.spool.dropped
+ );
+ }
+ if report.spool_incomplete {
+ println!(
+ " recovery is incomplete because hook events remain queued or were dropped; exact correlated transcripts may still replace quarantined events"
+ );
+ }
+ for session in &report.sessions {
+ let target = session
+ .native_session_id
+ .as_deref()
+ .unwrap_or("(no session id)");
+ let mut line = format!(
+ " [{}] {} {} in {}/{} — {}",
+ session.kind,
+ session.harness,
+ target,
+ session.workspace,
+ session.project,
+ session.outcome,
+ );
+ if session.imported_events > 0 {
+ line.push_str(&format!(" ({} events)", session.imported_events));
+ }
+ println!("{line}");
+ if let Some(detail) = &session.detail {
+ println!(" {detail}");
+ }
+ }
+ println!(
+ "recovered {} event(s) across {} journal entr{}; {} failed; {} remain",
+ report.imported_total(),
+ report.sessions.len(),
+ if report.sessions.len() == 1 {
+ "y"
+ } else {
+ "ies"
+ },
+ report.failures(),
+ report.journal_remaining,
+ );
+ if let Some(error) = &report.journal_error {
+ println!("recovery journal error: {error}");
+ }
+ if report.failures() > 0 {
+ println!(
+ "failed entries stay journaled with their reason; fix the cause and re-run \
+ `ai-memory recover` (re-running is safe — imports dedup)"
+ );
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn test_entry(id: &str, kind: JournalKind) -> JournalEntry {
+ JournalEntry {
+ id: id.to_string(),
+ recorded_at: "2026-10-07T12:00:00Z".to_string(),
+ interval_started_ms: 1_000,
+ interval_ended_ms: 2_000,
+ kind,
+ harness: "claude".to_string(),
+ native_session_id: Some("sess-1".to_string()),
+ session_dir: None,
+ cwd: "/tmp/repo".to_string(),
+ workspace: "ws".to_string(),
+ project: "proj".to_string(),
+ server_url: "http://127.0.0.1:49374".to_string(),
+ run_id: (kind == JournalKind::FinishFailed)
+ .then(|| "12345678-1234-4234-9234-123456789abe".to_string()),
+ event_digests: Some(Vec::new()),
+ spool_only: false,
+ source_cursor: None,
+ final_cursor: None,
+ correlated_events_seen: false,
+ correlated_delivery_confirmed: false,
+ correlated_loss: false,
+ exit_code: Some(0),
+ failures: Vec::new(),
+ }
+ }
+
+ #[test]
+ fn append_then_load_round_trips() {
+ let temp = tempfile::tempdir().unwrap();
+ let entry = test_entry("run-1", JournalKind::FinishFailed);
+ append_journal_entry(temp.path(), entry.clone()).unwrap();
+ let loaded = load_journal(temp.path()).unwrap();
+ assert_eq!(loaded.len(), 1);
+ assert_eq!(loaded[0].id, "run-1");
+ assert_eq!(loaded[0].kind, JournalKind::FinishFailed);
+ assert_eq!(loaded[0].harness, entry.harness);
+ assert_eq!(loaded[0].native_session_id.as_deref(), Some("sess-1"));
+ }
+
+ #[test]
+ fn missing_journal_is_empty_and_append_creates_it_private() {
+ let temp = tempfile::tempdir().unwrap();
+ assert!(load_journal(temp.path()).unwrap().is_empty());
+ append_journal_entry(temp.path(), test_entry("a", JournalKind::DegradedRun)).unwrap();
+ assert_eq!(load_journal(temp.path()).unwrap().len(), 1);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::PermissionsExt as _;
+ let mode = fs::metadata(journal_path(temp.path()))
+ .unwrap()
+ .permissions()
+ .mode();
+ assert_eq!(mode & 0o777, 0o600, "the journal is owner-only");
+ }
+ }
+
+ #[test]
+ fn full_journal_refuses_append_without_evicting() {
+ let temp = tempfile::tempdir().unwrap();
+ for index in 0..MAX_JOURNAL_ENTRIES {
+ append_journal_entry(
+ temp.path(),
+ test_entry(&format!("entry-{index}"), JournalKind::DegradedRun),
+ )
+ .unwrap();
+ }
+ let error = append_journal_entry(
+ temp.path(),
+ test_entry("must-not-fit", JournalKind::DegradedRun),
+ )
+ .unwrap_err();
+ assert!(format!("{error:#}").contains("ai-memory recover"));
+ let loaded = load_journal(temp.path()).unwrap();
+ assert_eq!(loaded.len(), MAX_JOURNAL_ENTRIES);
+ assert_eq!(loaded[0].id, "entry-0");
+ assert_eq!(
+ loaded.last().unwrap().id,
+ format!("entry-{}", MAX_JOURNAL_ENTRIES - 1)
+ );
+ }
+
+ #[test]
+ fn appends_are_atomic_and_leave_no_temporary_files() {
+ // The writer only ever renames a complete tmp file into place, so a
+ // crash between appends cannot leave a half-written journal: the
+ // previous complete file is still there and parseable.
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(temp.path(), test_entry("first", JournalKind::DegradedRun)).unwrap();
+ let before = fs::read(journal_path(temp.path())).unwrap();
+ append_journal_entry(temp.path(), test_entry("second", JournalKind::DegradedRun)).unwrap();
+ let after = fs::read(journal_path(temp.path())).unwrap();
+ assert!(before.len() < after.len());
+ assert_eq!(load_journal(temp.path()).unwrap().len(), 2);
+ assert!(
+ !fs::read_dir(temp.path()).unwrap().any(|entry| entry
+ .unwrap()
+ .file_name()
+ .to_string_lossy()
+ .contains(".tmp")),
+ "no temporary file is left behind"
+ );
+ }
+
+ #[test]
+ fn corrupt_oversized_or_wrong_version_journal_is_refused_not_reset() {
+ let temp = tempfile::tempdir().unwrap();
+ let path = journal_path(temp.path());
+ fs::write(&path, b"{ not json").unwrap();
+ let error = load_journal(temp.path()).unwrap_err();
+ assert!(
+ format!("{error:#}").contains("refusing to discard"),
+ "{error:#}"
+ );
+ let error = append_journal_entry(temp.path(), test_entry("x", JournalKind::DegradedRun))
+ .unwrap_err();
+ assert!(
+ format!("{error:#}").contains("refusing to discard"),
+ "{error:#}"
+ );
+ assert_eq!(fs::read(&path).unwrap(), b"{ not json");
+
+ let entries = (0..=MAX_JOURNAL_ENTRIES)
+ .map(|index| test_entry(&index.to_string(), JournalKind::DegradedRun))
+ .collect();
+ fs::write(
+ &path,
+ serde_json::to_vec(&JournalFile {
+ version: JOURNAL_VERSION,
+ entries,
+ })
+ .unwrap(),
+ )
+ .unwrap();
+ let error = load_journal(temp.path()).unwrap_err();
+ assert!(format!("{error:#}").contains("entry limit"), "{error:#}");
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn symlinked_lock_is_refused_without_touching_its_target() {
+ let temp = tempfile::tempdir().unwrap();
+ let outside = temp.path().join("outside-lock");
+ fs::write(&outside, b"canary").unwrap();
+ std::os::unix::fs::symlink(&outside, temp.path().join(JOURNAL_LOCK_FILE)).unwrap();
+ let error =
+ append_journal_entry(temp.path(), test_entry("outside", JournalKind::DegradedRun))
+ .unwrap_err();
+ assert!(format!("{error:#}").contains("symlink"), "{error:#}");
+ assert_eq!(fs::read(outside).unwrap(), b"canary");
+ }
+
+ #[cfg(unix)]
+ #[test]
+ fn symlinked_journal_and_ancestor_are_refused() {
+ let temp = tempfile::tempdir().unwrap();
+ let real = temp.path().join("real.json");
+ fs::write(&real, b"{}").unwrap();
+ std::os::unix::fs::symlink(&real, journal_path(temp.path())).unwrap();
+ let error = load_journal(temp.path()).unwrap_err();
+ assert!(format!("{error:#}").contains("symlink"), "{error:#}");
+
+ let outside = tempfile::tempdir().unwrap();
+ let linked_data = temp.path().join("linked-data");
+ std::os::unix::fs::symlink(outside.path(), &linked_data).unwrap();
+ let error = append_journal_entry(
+ &linked_data,
+ test_entry("outside", JournalKind::DegradedRun),
+ )
+ .unwrap_err();
+ assert!(format!("{error:#}").contains("symlink"), "{error:#}");
+ assert!(!outside.path().join(JOURNAL_FILE).exists());
+ }
+
+ /// A symlink ABOVE the data dir is the operator's or the system's (macOS
+ /// `/var` → `/private/var`): the journal works through it. The data dir
+ /// is reached here only through `link/`, and nothing inside it is a link.
+ #[cfg(unix)]
+ #[test]
+ fn a_symlinked_ancestor_of_the_data_dir_is_trusted() {
+ let temp = tempfile::tempdir().unwrap();
+ let real = temp.path().join("real");
+ fs::create_dir(&real).unwrap();
+ let link = temp.path().join("link");
+ std::os::unix::fs::symlink(&real, &link).unwrap();
+ let data_dir = link.join("data");
+ append_journal_entry(&data_dir, test_entry("ancestor", JournalKind::DegradedRun)).unwrap();
+ assert_eq!(load_journal(&data_dir).unwrap().len(), 1);
+ assert!(real.join("data").join(JOURNAL_FILE).exists());
+ }
+
+ /// The trust stops at the data dir: a link planted on the lock path
+ /// inside a data dir reached through a symlinked ancestor is still
+ /// refused, and its target is never touched.
+ #[cfg(unix)]
+ #[test]
+ fn a_symlink_inside_a_data_dir_under_a_symlinked_ancestor_is_refused() {
+ let temp = tempfile::tempdir().unwrap();
+ let real = temp.path().join("real");
+ fs::create_dir_all(real.join("data")).unwrap();
+ let link = temp.path().join("link");
+ std::os::unix::fs::symlink(&real, &link).unwrap();
+ let data_dir = link.join("data");
+ let outside = temp.path().join("outside-journal.json");
+ fs::write(&outside, b"canary").unwrap();
+ std::os::unix::fs::symlink(&outside, journal_path(&data_dir)).unwrap();
+ let error =
+ append_journal_entry(&data_dir, test_entry("planted", JournalKind::DegradedRun))
+ .unwrap_err();
+ assert!(format!("{error:#}").contains("symlink"), "{error:#}");
+ assert_eq!(fs::read(&outside).unwrap(), b"canary");
+ }
+
+ #[cfg(windows)]
+ #[test]
+ fn journal_acl_is_restricted_to_the_current_owner() {
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(temp.path(), test_entry("acl", JournalKind::DegradedRun)).unwrap();
+ let output = std::process::Command::new("icacls")
+ .arg(journal_path(temp.path()))
+ .output()
+ .unwrap();
+ assert!(output.status.success());
+ let acl = String::from_utf8_lossy(&output.stdout).to_ascii_lowercase();
+ assert!(!acl.contains("everyone"), "{acl}");
+ assert!(!acl.contains("authenticated users"), "{acl}");
+ }
+
+ #[test]
+ fn clearing_entries_and_annotating_failures_rewrites_the_journal() {
+ let temp = tempfile::tempdir().unwrap();
+ for id in ["keep", "clear", "fail"] {
+ append_journal_entry(temp.path(), test_entry(id, JournalKind::DegradedRun)).unwrap();
+ }
+ finish_journal(
+ temp.path(),
+ &Sanitizer::builtin(),
+ &["clear".to_string()],
+ &[("fail".to_string(), "server said no".to_string())],
+ )
+ .unwrap();
+ let loaded = load_journal(temp.path()).unwrap();
+ assert_eq!(loaded.len(), 2);
+ assert!(loaded.iter().all(|entry| entry.id != "clear"));
+ let failed = loaded.iter().find(|entry| entry.id == "fail").unwrap();
+ assert_eq!(failed.failures, vec!["server said no".to_string()]);
+ // The same failure reason is not recorded twice.
+ finish_journal(
+ temp.path(),
+ &Sanitizer::builtin(),
+ &[],
+ &[("fail".to_string(), "server said no".to_string())],
+ )
+ .unwrap();
+ let loaded = load_journal(temp.path()).unwrap();
+ assert_eq!(
+ loaded
+ .iter()
+ .find(|entry| entry.id == "fail")
+ .unwrap()
+ .failures,
+ vec!["server said no".to_string()]
+ );
+ }
+
+ #[test]
+ fn failure_reasons_are_sanitized_and_bounded_per_entry() {
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(temp.path(), test_entry("e", JournalKind::DegradedRun)).unwrap();
+ for index in 0..(MAX_ENTRY_FAILURES + 2) {
+ finish_journal(
+ temp.path(),
+ &Sanitizer::builtin(),
+ &[],
+ &[(
+ "e".to_string(),
+ format!(
+ "reason {index} token sk-{} {}",
+ "a".repeat(32),
+ "x".repeat(MAX_FAILURE_REASON_BYTES * 2)
+ ),
+ )],
+ )
+ .unwrap();
+ }
+ let loaded = load_journal(temp.path()).unwrap();
+ assert_eq!(loaded[0].failures.len(), MAX_ENTRY_FAILURES);
+ assert!(loaded[0].failures[0].starts_with("reason 2 token [REDACTED:api_key]"));
+ assert!(
+ loaded[0]
+ .failures
+ .iter()
+ .all(|reason| reason.len() <= MAX_FAILURE_REASON_BYTES)
+ );
+ }
+
+ #[test]
+ fn unknown_and_known_empty_event_sets_remain_distinct() {
+ let mut unknown = test_entry("unknown", JournalKind::FinishFailed);
+ unknown.event_digests = None;
+ let unknown_json = serde_json::to_value(&unknown).unwrap();
+ assert!(unknown_json.get("event_digests").is_none());
+
+ let empty = test_entry("empty", JournalKind::FinishFailed);
+ let empty_json = serde_json::to_value(&empty).unwrap();
+ assert_eq!(empty_json["event_digests"], serde_json::json!([]));
+ }
+
+ #[test]
+ fn recovery_journal_omits_repository_state() {
+ let bytes = serde_json::to_vec(&test_entry("id", JournalKind::FinishFailed)).unwrap();
+ let text = String::from_utf8(bytes).unwrap();
+ assert!(!text.contains("checkpoint"));
+ assert!(!text.contains("changed_paths"));
+ assert!(!text.contains("branch"));
+ }
+
+ #[test]
+ fn legacy_relative_session_dir_resolves_against_recorded_cwd() {
+ let mut entry = test_entry("legacy", JournalKind::DegradedRun);
+ entry.cwd = "/original/repo".into();
+ entry.session_dir = Some("stores/native".into());
+ assert_eq!(
+ recovery_session_dir(&entry),
+ Some(PathBuf::from("/original/repo/stores/native"))
+ );
+ }
+
+ #[test]
+ fn journal_entry_serializes_without_optional_noise() {
+ let bytes = serde_json::to_vec(&test_entry("id", JournalKind::DegradedRun)).unwrap();
+ let text = String::from_utf8(bytes).unwrap();
+ assert!(text.contains("\"kind\":\"degraded-run\""));
+ assert!(
+ !text.contains("run_id"),
+ "absent fields are omitted: {text}"
+ );
+ }
+
+ #[test]
+ fn journal_summary_counts_kinds_and_carries_errors() {
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(temp.path(), test_entry("d1", JournalKind::DegradedRun)).unwrap();
+ append_journal_entry(temp.path(), test_entry("f1", JournalKind::FinishFailed)).unwrap();
+ assert_eq!(
+ journal_summary(temp.path()),
+ (2, 1, 1, None),
+ "(total, degraded, finish-failed, error)"
+ );
+ fs::write(journal_path(temp.path()), b"nope").unwrap();
+ let (total, _, _, error) = journal_summary(temp.path());
+ assert_eq!(total, 0);
+ assert!(error.is_some());
+ }
+
+ #[test]
+ fn dropped_spool_events_make_recovery_incomplete() {
+ assert!(spool_is_incomplete(&SpoolOutcome {
+ sent: 3,
+ remaining: 0,
+ dropped: 1,
+ }));
+ assert!(!spool_is_incomplete(&SpoolOutcome {
+ sent: 3,
+ remaining: 0,
+ dropped: 0,
+ }));
+ }
+
+ #[tokio::test]
+ async fn failed_exact_replay_restores_correlated_spool_entry() {
+ let temp = tempfile::tempdir().unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap()
+ });
+ let server_url = format!("http://{address}");
+ let spool = hook_spool::spool_dir(temp.path());
+ let created_ms = u64::try_from(jiff::Timestamp::now().as_millisecond()).unwrap();
+ let correlated = hook_spool::SpoolEntry {
+ url: format!(
+ "{server_url}/hook?event=user-prompt-submit&agent=claude-code&workspace=ws&project=proj&session_id=sess-1"
+ ),
+ body: r#"{"session_id":"sess-1","cwd":"/tmp/repo","prompt":"same prompt"}"#.into(),
+ created_ms,
+ auth_mode: hook_spool::AuthMode::Anonymous,
+ token: None,
+ attempts: 0,
+ profile: None,
+ };
+ hook_spool::enqueue(&spool, &correlated).unwrap();
+ let entry = JournalEntry {
+ server_url: server_url.clone(),
+ interval_started_ms: created_ms.saturating_sub(1),
+ interval_ended_ms: created_ms.saturating_add(1),
+ ..test_entry("restore", JournalKind::DegradedRun)
+ };
+ append_journal_entry(temp.path(), entry).unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url,
+ ..Config::default()
+ };
+ let report = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(report.failures(), 1);
+ assert_eq!(report.journal_remaining, 1);
+ assert_eq!(hook_spool::spool_len(&spool), 1);
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn spool_only_harness_clears_only_after_a_complete_drain() {
+ let temp = tempfile::tempdir().unwrap();
+ let cwd = temp.path().join("proj");
+ fs::create_dir_all(&cwd).unwrap();
+ 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,
+ axum::Router::new()
+ .route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ )
+ .route(
+ "/hook/batch",
+ axum::routing::post(|| async {
+ axum::Json(serde_json::json!({
+ "accepted": 1,
+ "results": [{"index": 0, "outcome": "stored"}]
+ }))
+ }),
+ ),
+ )
+ .await
+ .unwrap()
+ });
+ let server_url = format!("http://{address}");
+ let spool = hook_spool::spool_dir(temp.path());
+ let created_ms = u64::try_from(jiff::Timestamp::now().as_millisecond()).unwrap();
+ hook_spool::enqueue(
+ &spool,
+ &hook_spool::SpoolEntry {
+ url: format!(
+ "{server_url}/hook?event=user-prompt-submit&agent=antigravity-cli&workspace=ws&project=proj"
+ ),
+ body: serde_json::json!({
+ "conversationId": "sess-1",
+ "cwd": cwd,
+ "prompt": "captured"
+ })
+ .to_string(),
+ created_ms,
+ auth_mode: hook_spool::AuthMode::Anonymous,
+ token: None,
+ attempts: 0,
+ profile: None,
+ },
+ )
+ .unwrap();
+ let entry = JournalEntry {
+ harness: "antigravity".into(),
+ cwd: cwd.to_string_lossy().into_owned(),
+ project: "proj".into(),
+ server_url: server_url.clone(),
+ interval_started_ms: created_ms.saturating_sub(1),
+ interval_ended_ms: created_ms.saturating_add(1),
+ ..test_entry("spool-only", JournalKind::DegradedRun)
+ };
+ append_journal_entry(temp.path(), entry).unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url,
+ ..Config::default()
+ };
+ let report = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(
+ report.spool.sent, 0,
+ "correlated evidence drains separately"
+ );
+ assert_eq!(report.sessions[0].outcome, "recovered-via-spool");
+ assert_eq!(report.journal_remaining, 0);
+ assert!(load_journal(temp.path()).unwrap().is_empty());
+ server.abort();
+ }
+
+ /// A spool-only entry dispositioned Failed because an *unrelated* queued
+ /// event kept the drain incomplete must not wedge recovery after its own
+ /// interval already completed: restoring the quarantine treats the
+ /// completed marker as durable delivery, the rerun neither errors nor
+ /// re-delivers, and the journal clears.
+ #[tokio::test]
+ async fn completed_spool_only_interval_survives_an_unrelated_incomplete_drain() {
+ use axum::response::IntoResponse as _;
+
+ let temp = tempfile::tempdir().unwrap();
+ let cwd = temp.path().join("proj");
+ fs::create_dir_all(&cwd).unwrap();
+ let deliveries = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+ let handler_deliveries = deliveries.clone();
+ 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,
+ axum::Router::new()
+ .route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ )
+ .route(
+ "/hook/batch",
+ axum::routing::post(move |body: axum::body::Bytes| {
+ let deliveries = handler_deliveries.clone();
+ async move {
+ let Ok(items) =
+ serde_json::from_slice::<Vec<serde_json::Value>>(&body)
+ else {
+ return (
+ axum::http::StatusCode::BAD_REQUEST,
+ "malformed batch",
+ )
+ .into_response();
+ };
+ let prompts: Vec<String> = items
+ .iter()
+ .filter_map(|item| {
+ item.get("body")?.get("prompt")?.as_str().map(str::to_owned)
+ })
+ .collect();
+ if prompts.iter().any(|prompt| prompt == "unrelated") {
+ return (
+ axum::http::StatusCode::INTERNAL_SERVER_ERROR,
+ "unrelated event refused",
+ )
+ .into_response();
+ }
+ deliveries.lock().unwrap().extend(prompts);
+ axum::Json(serde_json::json!({
+ "accepted": items.len(),
+ "results": (0..items.len())
+ .map(|index| serde_json::json!({
+ "index": index,
+ "outcome": "stored"
+ }))
+ .collect::<Vec<_>>()
+ }))
+ .into_response()
+ }
+ }),
+ ),
+ )
+ .await
+ .unwrap()
+ });
+ let server_url = format!("http://{address}");
+ let spool = hook_spool::spool_dir(temp.path());
+ let created_ms = u64::try_from(jiff::Timestamp::now().as_millisecond()).unwrap();
+ let correlated = hook_spool::SpoolEntry {
+ url: format!(
+ "{server_url}/hook?event=user-prompt-submit&agent=antigravity-cli&workspace=ws&project=proj"
+ ),
+ body: serde_json::json!({
+ "conversationId": "sess-1",
+ "cwd": cwd,
+ "prompt": "captured"
+ })
+ .to_string(),
+ created_ms,
+ auth_mode: hook_spool::AuthMode::Anonymous,
+ token: None,
+ attempts: 0,
+ profile: None,
+ };
+ let unrelated = hook_spool::SpoolEntry {
+ url: format!(
+ "{server_url}/hook?event=user-prompt-submit&agent=claude-code&workspace=ws&project=proj&session_id=unrelated-1"
+ ),
+ body: r#"{"session_id":"unrelated-1","cwd":"/tmp/repo","prompt":"unrelated"}"#.into(),
+ created_ms: created_ms.saturating_add(1),
+ auth_mode: hook_spool::AuthMode::Anonymous,
+ token: None,
+ attempts: 0,
+ profile: None,
+ };
+ hook_spool::enqueue(&spool, &correlated).unwrap();
+ hook_spool::enqueue(&spool, &unrelated).unwrap();
+ let entry = JournalEntry {
+ harness: "antigravity".into(),
+ spool_only: true,
+ native_session_id: Some("sess-1".into()),
+ cwd: cwd.to_string_lossy().into_owned(),
+ workspace: "ws".into(),
+ project: "proj".into(),
+ server_url: server_url.clone(),
+ interval_started_ms: created_ms.saturating_sub(1),
+ interval_ended_ms: created_ms.saturating_add(2),
+ ..test_entry("completed-rerun", JournalKind::DegradedRun)
+ };
+ append_journal_entry(temp.path(), entry).unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url,
+ ..Config::default()
+ };
+ let first = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(first.sessions[0].outcome, "recovered-via-spool");
+ assert_eq!(first.journal_remaining, 0);
+ assert!(first.spool_incomplete, "the unrelated event still queues");
+ assert!(load_journal(temp.path()).unwrap().is_empty());
+
+ let rerun = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert!(rerun.sessions.is_empty());
+ assert_eq!(rerun.failures(), 0);
+ assert_eq!(rerun.journal_remaining, 0);
+ assert!(rerun.spool_incomplete);
+ assert!(
+ load_journal(temp.path()).unwrap().is_empty(),
+ "the rerun must clear the journal"
+ );
+ assert_eq!(
+ deliveries
+ .lock()
+ .unwrap()
+ .iter()
+ .filter(|prompt| *prompt == "captured")
+ .count(),
+ 1,
+ "the completed interval's evidence is never re-delivered"
+ );
+ assert_eq!(
+ hook_spool::spool_len(&spool),
+ 1,
+ "only the unrelated event stays queued"
+ );
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn spool_only_without_correlated_evidence_never_auto_clears() {
+ let temp = tempfile::tempdir().unwrap();
+ let mut entry = test_entry("no-hooks", JournalKind::DegradedRun);
+ entry.harness = "antigravity".into();
+ append_journal_entry(temp.path(), entry).unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ let server_url = format!("http://{address}");
+ mutate_journal(temp.path(), |entries| {
+ entries[0].server_url.clone_from(&server_url);
+ Ok(())
+ })
+ .unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url,
+ ..Config::default()
+ };
+ for _ in 0..2 {
+ let report = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(report.failures(), 1);
+ assert_eq!(report.journal_remaining, 1);
+ assert!(
+ report.sessions[0]
+ .detail
+ .as_deref()
+ .unwrap()
+ .contains("no durably delivered")
+ );
+ }
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn a_dropped_spool_event_stays_lost_on_the_next_empty_pass() {
+ let temp = tempfile::tempdir().unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ let server_url = format!("http://{address}");
+ let spool = hook_spool::spool_dir(temp.path());
+ let created_ms = u64::try_from(jiff::Timestamp::now().as_millisecond()).unwrap();
+ hook_spool::enqueue(
+ &spool,
+ &hook_spool::SpoolEntry {
+ url: format!(
+ "{server_url}/hook?event=user-prompt-submit&agent=antigravity-cli&workspace=ws&project=proj"
+ ),
+ body: r#"{"conversationId":"sess-1","cwd":"/tmp/repo","prompt":"lost"}"#.into(),
+ created_ms,
+ auth_mode: hook_spool::AuthMode::Anonymous,
+ token: None,
+ attempts: 7,
+ profile: None,
+ },
+ )
+ .unwrap();
+ let entry = JournalEntry {
+ harness: "antigravity".into(),
+ server_url: server_url.clone(),
+ interval_started_ms: created_ms.saturating_sub(1),
+ interval_ended_ms: created_ms.saturating_add(1),
+ ..test_entry("dropped", JournalKind::DegradedRun)
+ };
+ append_journal_entry(temp.path(), entry).unwrap();
+ mutate_journal(temp.path(), |entries| {
+ entries[0].correlated_events_seen = true;
+ entries[0].correlated_loss = true;
+ Ok(())
+ })
+ .unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url,
+ ..Config::default()
+ };
+ let first = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(
+ first.spool.sent, 0,
+ "correlated evidence never rides the main drain"
+ );
+ assert_eq!(
+ first.failures(),
+ 1,
+ "the correlated loss keeps the journal entry"
+ );
+ assert!(load_journal(temp.path()).unwrap()[0].correlated_loss);
+ let second = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(second.spool.dropped, 0, "the dropped evidence stays lost");
+ assert_eq!(second.journal_remaining, 1);
+ assert!(load_journal(temp.path()).unwrap()[0].correlated_loss);
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn a_lossy_spool_pass_keeps_the_recovery_journal() {
+ let temp = tempfile::tempdir().unwrap();
+ let mut entry = test_entry("keep", JournalKind::DegradedRun);
+ entry.harness = "antigravity".into();
+ append_journal_entry(temp.path(), entry).unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ let spool = hook_spool::spool_dir(temp.path());
+ hook_spool::enqueue(
+ &spool,
+ &hook_spool::SpoolEntry {
+ url: format!("http://{address}/hook?event=user-prompt-submit"),
+ body: "not-json".into(),
+ created_ms: u64::try_from(jiff::Timestamp::now().as_millisecond()).unwrap(),
+ auth_mode: hook_spool::AuthMode::Anonymous,
+ token: None,
+ attempts: 7,
+ profile: None,
+ },
+ )
+ .unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url: format!("http://{address}"),
+ ..Config::default()
+ };
+ let report = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(report.spool.dropped, 1);
+ assert!(report.spool_incomplete);
+ assert_eq!(report.journal_remaining, 1);
+ assert!(
+ report.sessions[0]
+ .detail
+ .as_deref()
+ .is_some_and(|detail| detail.contains("1 dropped"))
+ );
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn per_entry_budget_times_out_and_keeps_the_entry() {
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(temp.path(), test_entry("one", JournalKind::DegradedRun)).unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url: format!("http://{address}"),
+ ..Config::default()
+ };
+ let report = recover(
+ &config,
+ &RecoverBudgets {
+ entry_timeout: Duration::ZERO,
+ ..RecoverBudgets::default()
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(report.failures(), 1);
+ assert!(
+ report.sessions[0]
+ .detail
+ .as_deref()
+ .is_some_and(|detail| detail.contains("timed out"))
+ );
+ assert_eq!(load_journal(temp.path()).unwrap().len(), 1);
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn total_journal_budget_keeps_unattempted_entries() {
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(temp.path(), test_entry("one", JournalKind::DegradedRun)).unwrap();
+ append_journal_entry(temp.path(), test_entry("two", JournalKind::DegradedRun)).unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url: format!("http://{address}"),
+ ..Config::default()
+ };
+ let report = recover(
+ &config,
+ &RecoverBudgets {
+ journal_total: Duration::ZERO,
+ ..RecoverBudgets::default()
+ },
+ )
+ .await
+ .unwrap();
+ assert_eq!(report.failures(), 2);
+ assert!(report.sessions.iter().all(|session| {
+ session
+ .detail
+ .as_deref()
+ .is_some_and(|detail| detail.contains("budget exhausted"))
+ }));
+ assert_eq!(load_journal(temp.path()).unwrap().len(), 2);
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn a_journal_entry_cannot_be_replayed_to_another_server() {
+ let temp = tempfile::tempdir().unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ append_journal_entry(
+ temp.path(),
+ JournalEntry {
+ server_url: "http://127.0.0.1:1".to_string(),
+ ..test_entry("foreign-server", JournalKind::DegradedRun)
+ },
+ )
+ .unwrap();
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url: format!("http://{address}"),
+ ..Config::default()
+ };
+ let report = recover(&config, &RecoverBudgets::default()).await.unwrap();
+ assert_eq!(report.failures(), 1);
+ assert!(
+ report.sessions[0]
+ .detail
+ .as_deref()
+ .unwrap()
+ .contains("refusing to replay")
+ );
+ assert_eq!(load_journal(temp.path()).unwrap().len(), 1);
+ server.abort();
+ }
+
+ #[tokio::test]
+ async fn failed_recovery_returns_a_testable_nonzero_code_without_exiting() {
+ let temp = tempfile::tempdir().unwrap();
+ append_journal_entry(
+ temp.path(),
+ JournalEntry {
+ native_session_id: None,
+ ..test_entry("bad", JournalKind::FinishFailed)
+ },
+ )
+ .unwrap();
+ 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,
+ axum::Router::new().route(
+ "/healthz",
+ axum::routing::get(|| async { axum::http::StatusCode::OK }),
+ ),
+ )
+ .await
+ .unwrap();
+ });
+ let config = Config {
+ data_dir: temp.path().to_path_buf(),
+ server_url: format!("http://{address}"),
+ ..Config::default()
+ };
+ let code = run(&config, RecoverArgs { json: false }).await.unwrap();
+ assert_eq!(code, 1);
+ assert_eq!(load_journal(temp.path()).unwrap().len(), 1);
+ server.abort();
+ }
+}
diff --cc crates/ai-memory-cli/src/commands/run.rs
index 78097bd4,4c4e4703..bd79ec51
--- a/crates/ai-memory-cli/src/commands/run.rs
+++ b/crates/ai-memory-cli/src/commands/run.rs
@@@ -3756,7 -3339,11 +3758,11 @@@ async fn export_after_flush
}
}
+ /// Upload the exported transcript as the run's ledger segments. `capture`
+ /// applies the checkout's `[capture] ignore_paths` first, so an excluded tool
+ /// call and its output never reach a segment; a result whose call was imported
+ /// by an earlier run has no call here and is dropped under a policy.
-async fn import_batches(
+pub(crate) async fn import_batches(
endpoint: &ServerEndpoint,
run_path: &str,
transcript: ExportedTranscript,
diff --cc crates/ai-memory-workstream/src/lib.rs
index f5e371f6,be653988..ae5613bc
--- a/crates/ai-memory-workstream/src/lib.rs
+++ b/crates/ai-memory-workstream/src/lib.rs
@@@ -26,9 -26,9 +26,10 @@@ pub use repository::
};
pub use transcript::{
AmbiguousNativeSession, ClaudeContinuation, ExportedTranscript, NativeSessionCandidate,
- claude_continued_session, claude_live_background_attach_id, claude_session_ran_in_background,
- discover_native_session, export_transcript, export_transcript_delta, export_transcript_range,
- kiro_harness_from_source_cursor, kiro_v3_resume_uses_default_store, list_native_sessions,
- native_memory_dir, native_session_exists, native_session_in_checkout, native_store_root,
- transcript_baseline, transcript_interval_digests, wait_for_transcript_flush,
+ RECORD_CWD_KEY, claude_continued_session, claude_live_background_attach_id,
+ claude_session_ran_in_background, discover_native_session, export_transcript,
- kiro_harness_from_source_cursor, kiro_v3_resume_uses_default_store, list_native_sessions,
- native_memory_dir, native_session_exists, native_session_in_checkout, native_store_root,
- wait_for_transcript_flush,
++ export_transcript_delta, export_transcript_range, kiro_harness_from_source_cursor,
++ kiro_v3_resume_uses_default_store, list_native_sessions, native_memory_dir,
++ native_session_exists, native_session_in_checkout, native_store_root, transcript_baseline,
++ transcript_interval_digests, wait_for_transcript_flush,
};
diff --cc crates/ai-memory-workstream/src/transcript.rs
index 15cc46ee,221a4e78..9d877f88
--- a/crates/ai-memory-workstream/src/transcript.rs
+++ b/crates/ai-memory-workstream/src/transcript.rs
@@@ -1134,20 -671,10 +1137,21 @@@ fn export_jsonl_range
let mut line = Vec::new();
let mut events = Vec::new();
let mut losses = Vec::new();
+ let mut records = 0_usize;
+ let mut source_bytes = 0_usize;
+ let mut checked_events = 0_usize;
+ let mut event_bytes = 0_usize;
+ let mut codex_turn_cwd: Option<String> = None;
loop {
line.clear();
- let read = reader.read_until(b'\n', &mut line)?;
+ let remaining = len.saturating_sub(offset);
+ if remaining == 0 {
+ break;
+ }
+ let read_limit = remaining.min((MAX_SOURCE_RECORD_BYTES + 1) as u64);
+ let read = std::io::Read::by_ref(&mut reader)
+ .take(read_limit)
+ .read_until(b'\n', &mut line)?;
if read == 0 {
break;
}
@@@ -1276,13 -779,21 +1281,28 @@@
));
}
}
+ let record_cwd = match harness {
+ ManagedHarness::Claude => value.get("cwd").and_then(Value::as_str),
+ ManagedHarness::Codex => {
+ if matches!(
+ value.get("type").and_then(Value::as_str),
+ Some("session_meta" | "turn_context")
+ ) && let Some(cwd) = value.pointer("/payload/cwd").and_then(Value::as_str)
+ {
+ codex_turn_cwd = Some(cwd.to_owned());
+ }
+ codex_turn_cwd.as_deref()
+ }
+ _ => None,
+ };
+ stamp_record_cwd(&mut events[first_event..], record_cwd);
+ enforce_parse_bounds(
+ &events,
+ &mut checked_events,
+ &mut event_bytes,
+ &mut source_bytes,
+ 0,
+ )?;
}
if harness == ManagedHarness::Kimi {
annotate_kimi_subagents(path, &mut losses);
@@@ -2539,146 -2149,6 +2663,152 @@@ fn parse_grok
}
}
+/// Copilot CLI `events.jsonl` records (verified on 1.0.92). Each record is
+/// `{type, data, id, timestamp, parentId}`. Only the user's typed text, the
+/// assistant's visible text and tool requests, completed tool output, and
+/// compaction summaries are imported. `transformedContent` (the prompt with
+/// injected datetime/context), `reasoningText`/`reasoningOpaque`, hook output
+/// (where ai-memory's own startup packet lands), permission prompts, model
+/// snapshots, and session telemetry never reach the ledger.
+fn parse_copilot(
+ value: &Value,
+ session: &str,
+ record_id: &str,
+ events: &mut Vec<NewWorkstreamEvent>,
+ losses: &mut Vec<String>,
+) {
+ let record_type = value
+ .get("type")
+ .and_then(Value::as_str)
+ .unwrap_or_default();
+ let data = value.get("data").unwrap_or(&Value::Null);
+ match record_type {
+ "system.message" => {
+ losses.push("Copilot system prompt records were intentionally excluded".into());
+ }
+ "model.messages_snapshot" => {
+ losses.push("Copilot model message snapshots were intentionally excluded".into());
+ }
+ "user.message" => {
+ if let Some(text) = data.get("content").and_then(Value::as_str) {
+ push_event(
+ events,
+ AgentKind::CopilotCli,
+ session,
+ record_id,
+ 0,
+ WorkstreamEventKind::Message,
+ Some("user"),
+ text,
+ timestamp(value),
+ json!({}),
+ );
+ }
+ }
+ "assistant.message" => {
+ if ["reasoningText", "reasoningOpaque", "reasoningBlocks"]
+ .iter()
+ .any(|key| data.get(*key).is_some_and(|value| !value.is_null()))
+ {
+ losses.push("Copilot hidden reasoning was intentionally excluded".into());
+ }
+ let block_count = match data.get("content").and_then(Value::as_str) {
+ Some(text) if !text.trim().is_empty() => {
+ push_event(
+ events,
+ AgentKind::CopilotCli,
+ session,
+ record_id,
+ 0,
+ WorkstreamEventKind::Message,
+ Some("assistant"),
+ text,
+ timestamp(value),
+ json!({}),
+ );
+ 1
+ }
+ _ => 0,
+ };
+ let requests = data
+ .get("toolRequests")
+ .and_then(Value::as_array)
+ .map_or(&[][..], Vec::as_slice);
+ for (index, request) in requests.iter().enumerate() {
+ let name = first_string(request, &["name"]).unwrap_or("tool");
+ let arguments = request
+ .get("arguments")
+ .map(compact_json)
+ .unwrap_or_default();
+ push_event(
+ events,
+ AgentKind::CopilotCli,
+ session,
+ record_id,
+ block_count + index,
+ WorkstreamEventKind::ToolCall,
+ Some("assistant"),
+ &format!("{name}: {arguments}"),
+ timestamp(value),
- json!({"tool": name}),
++ with_tool_use_id(
++ json!({"tool": name}),
++ first_string(request, &["toolCallId"]),
++ ),
+ );
+ }
+ }
+ "tool.execution_complete" => {
+ let success = data.get("success").and_then(Value::as_bool);
+ // `detailedContent` repeats the output as a diff carrying absolute
+ // paths; the model-visible `content` is the portable record.
+ let body = if success == Some(false) {
+ data.get("error")
+ .and_then(|error| error.get("message"))
+ .and_then(Value::as_str)
+ .map(|message| format!("error: {message}"))
+ } else {
+ data.get("result")
+ .and_then(|result| result.get("content"))
+ .map(value_text)
+ };
+ push_event(
+ events,
+ AgentKind::CopilotCli,
+ session,
+ record_id,
+ 0,
+ WorkstreamEventKind::ToolResult,
+ Some("tool"),
+ body.as_deref().unwrap_or_default(),
+ timestamp(value),
- json!({"success": success}),
++ with_tool_use_id(
++ json!({"success": success}),
++ first_string(data, &["toolCallId"]),
++ ),
+ );
+ }
+ "session.compaction_complete" => {
+ if data.get("success").and_then(Value::as_bool) == Some(true)
+ && let Some(text) = data.get("summaryContent").and_then(Value::as_str)
+ {
+ push_event(
+ events,
+ AgentKind::CopilotCli,
+ session,
+ record_id,
+ 0,
+ WorkstreamEventKind::Compaction,
+ Some("assistant"),
+ text,
+ timestamp(value),
+ json!({}),
+ );
+ }
+ }
+ _ => {}
+ }
+}
+
#[allow(clippy::too_many_arguments)]
fn parse_content_blocks(
agent: AgentKind,
@@@ -7715,209 -6814,6 +8037,223 @@@ mod tests
);
}
+ fn copilot_session_start(id: &str, cwd: &Path) -> Value {
+ json!({"type":"session.start","data":{"sessionId":id,"version":1,
+ "producer":"copilot-agent","copilotVersion":"1.0.92",
+ "context":{"cwd":cwd}},"id":"start","timestamp":"2026-10-07T13:00:33.339Z"})
+ }
+
+ #[tokio::test]
+ async fn copilot_discovery_requires_uuid_directory_header_and_checkout() {
+ let temp = tempfile::tempdir().unwrap();
+ let cwd = temp.path().join("repo");
+ let other = temp.path().join("other");
+ let root = temp.path().join("session-state");
+ fs::create_dir_all(&cwd).unwrap();
+ fs::create_dir_all(&other).unwrap();
+
+ let matching = "318db77d-e19b-4750-82df-192a6b931437";
+ let wrong_checkout = "c79ce9b8-de85-442e-915a-1c6ec4f74719";
+ let mismatched_header = "0e88ebd2-ed54-4f5a-9056-46e041e3b44d";
+ let phantom = "5b1f0c3e-7a2d-4e8b-9c6f-1d2e3f4a5b6c";
+ for (dir, header) in [
+ (matching, copilot_session_start(matching, &cwd)),
+ (
+ wrong_checkout,
+ copilot_session_start(wrong_checkout, &other),
+ ),
+ // A header naming a session other than its directory must never
+ // surface that phantom id as a candidate.
+ (mismatched_header, copilot_session_start(phantom, &cwd)),
+ ] {
+ fs::create_dir_all(root.join(dir)).unwrap();
+ fs::write(root.join(dir).join("events.jsonl"), format!("{header}\n")).unwrap();
+ }
+ // Workspace metadata and non-UUID directories are not transcripts.
+ fs::write(root.join(matching).join("workspace.yaml"), "id: x\n").unwrap();
+ fs::create_dir_all(root.join("not-a-uuid")).unwrap();
+ fs::write(
+ root.join("not-a-uuid/events.jsonl"),
+ format!("{}\n", copilot_session_start("not-a-uuid", &cwd)),
+ )
+ .unwrap();
+
+ let sessions =
+ list_native_sessions(ManagedHarness::Copilot, temp.path(), &cwd, Some(&root), 8)
+ .await
+ .unwrap();
+ let ids: Vec<_> = sessions
+ .iter()
+ .map(|session| session.native_session_id.as_str())
+ .collect();
+ assert_eq!(ids, [matching]);
+
+ let found = locate_session_file(
+ ManagedHarness::Copilot,
+ temp.path(),
+ &cwd,
+ Some(&root),
+ matching,
+ )
+ .unwrap();
+ assert_eq!(found, Some(root.join(matching).join("events.jsonl")));
+ for foreign in [
+ wrong_checkout,
+ mismatched_header,
+ phantom,
+ "not-a-uuid",
+ "../x",
+ ] {
+ assert!(
+ !native_session_exists(
+ ManagedHarness::Copilot,
+ temp.path(),
+ &cwd,
+ Some(&root),
+ foreign
+ )
+ .unwrap(),
+ "{foreign} must not resolve for this checkout"
+ );
+ }
+ }
+
+ #[test]
+ fn copilot_store_defaults_below_home() {
+ let home = Path::new("/home/user");
+ assert_eq!(
+ session_root(ManagedHarness::Copilot, home, None),
+ home.join(".copilot/session-state")
+ );
+ }
+
+ /// Record shapes captured from a real Copilot CLI 1.0.92 session (paths,
+ /// ids, and long fields shortened).
+ #[test]
+ fn copilot_adapter_excludes_private_records_and_keeps_visible_history() {
+ let temp = tempfile::tempdir().unwrap();
+ let path = temp.path().join("events.jsonl");
+ let records = [
+ copilot_session_start("318db77d-e19b-4750-82df-192a6b931437", temp.path()),
+ json!({"type":"session.model_change","data":{"newModel":"claude-sonnet-5"},"id":"r1"}),
+ json!({"type":"user.message","data":{"content":"read note.txt",
+ "transformedContent":"<current_datetime>2026-10-07</current_datetime>\n\nread note.txt"},
+ "id":"r2","timestamp":"2026-10-07T13:00:35.074Z"}),
+ json!({"type":"system.message","data":{"role":"system","content":"You are the GitHub Copilot CLI"},"id":"r3"}),
+ json!({"type":"hook.end","data":{"hookType":"sessionStart","success":true,
+ "output":{"additionalContext":"ai-memory startup packet"}},"id":"r4"}),
+ json!({"type":"assistant.message","data":{"content":"","reasoningText":"private plan",
+ "reasoningOpaque":"opaque","toolRequests":[{"toolCallId":"call-1","name":"view",
+ "arguments":{"path":"note.txt"},"type":"function"}]},"id":"r5"}),
+ json!({"type":"tool.execution_start","data":{"toolCallId":"call-1","toolName":"view",
+ "arguments":{"path":"note.txt"}},"id":"r6"}),
+ json!({"type":"permission.requested","data":{"permissionRequest":{"kind":"shell"}},"id":"r7"}),
+ json!({"type":"tool.execution_complete","data":{"toolCallId":"call-1","success":true,
+ "result":{"content":"hello\n","detailedContent":"diff --git a/abs/path"}},"id":"r8"}),
+ json!({"type":"tool.execution_complete","data":{"toolCallId":"call-2","success":false,
+ "result":null,"error":{"message":"Permission denied","code":"denied"}},"id":"r9"}),
+ json!({"type":"assistant.message","data":{"content":"hello","toolRequests":[]},"id":"r10"}),
+ json!({"type":"session.resume","data":{"context":{"cwd":temp.path()}},"id":"r11"}),
+ json!({"type":"model.messages_snapshot","data":{"messages":[{"role":"system","content":"private"}]},"id":"r12"}),
+ json!({"type":"session.compaction_complete","data":{"success":true,
+ "summaryContent":"<overview>read a file</overview>"},"id":"r13"}),
+ json!({"type":"session.compaction_complete","data":{"success":false,
+ "summaryContent":"failed attempt"},"id":"r14"}),
+ ];
+ let body = records
+ .iter()
+ .map(|record| format!("{record}\n"))
+ .collect::<String>();
+ fs::write(&path, body).unwrap();
+
+ let export = export_jsonl(ManagedHarness::Copilot, &path, "copilot-session", None).unwrap();
++ // A call and its result share the Copilot call id, so a transcript
++ // import can give the result the call's capture decision.
++ let ids: Vec<_> = export
++ .events
++ .iter()
++ .filter(|event| {
++ matches!(
++ event.kind,
++ WorkstreamEventKind::ToolCall | WorkstreamEventKind::ToolResult
++ )
++ })
++ .map(|event| event.metadata.get("tool_use_id").and_then(Value::as_str))
++ .collect();
++ assert_eq!(ids, [Some("call-1"), Some("call-1"), Some("call-2")]);
+ let contents: Vec<_> = export
+ .events
+ .iter()
+ .map(|event| (event.kind, event.content.as_str()))
+ .collect();
+ assert_eq!(
+ contents,
+ [
+ (WorkstreamEventKind::Message, "read note.txt"),
+ (
+ WorkstreamEventKind::ToolCall,
+ "view: {\"path\":\"note.txt\"}"
+ ),
+ (WorkstreamEventKind::ToolResult, "hello\n"),
+ (WorkstreamEventKind::ToolResult, "error: Permission denied"),
+ (WorkstreamEventKind::Message, "hello"),
+ (
+ WorkstreamEventKind::Compaction,
+ "<overview>read a file</overview>"
+ ),
+ ]
+ );
+ assert!(export.events.iter().all(|event| {
+ event.agent == AgentKind::CopilotCli
+ && !event.content.contains("private")
+ && !event.content.contains("startup packet")
+ && !event.content.contains("current_datetime")
+ && !event.content.contains("abs/path")
+ }));
+ for expected in [
+ "system prompt records",
+ "hidden reasoning",
+ "message snapshots",
+ ] {
+ assert!(
+ export.losses.iter().any(|loss| loss.contains(expected)),
+ "missing loss annotation for {expected}"
+ );
+ }
+ let cursor: FileCursor = serde_json::from_str(&export.source_cursor.unwrap()).unwrap();
+ assert!(cursor.prefix_sha256.is_some());
+ }
+
+ #[test]
+ fn copilot_export_is_incremental_and_holds_back_an_incomplete_record() {
+ let temp = tempfile::tempdir().unwrap();
+ let path = temp.path().join("events.jsonl");
+ let first_line = json!({"type":"user.message","data":{"content":"one"},"id":"a"});
+ let second_line = json!({"type":"assistant.message","data":{"content":"two"},"id":"b"});
+ // A record still being written has no trailing newline yet.
+ let partial = second_line.to_string();
+ fs::write(&path, format!("{first_line}\n{}", &partial[..10])).unwrap();
+ let first = export_jsonl(ManagedHarness::Copilot, &path, "s", None).unwrap();
+ assert_eq!(first.events.len(), 1);
+ assert!(first.losses.is_empty());
+
+ fs::write(&path, format!("{first_line}\n{second_line}\n")).unwrap();
+ let second = export_jsonl(
+ ManagedHarness::Copilot,
+ &path,
+ "s",
+ first.source_cursor.as_deref(),
+ )
+ .unwrap();
+ assert_eq!(second.events.len(), 1);
+ assert_eq!(second.events[0].content, "two");
+
+ // Re-reading from scratch yields identical event ids.
+ let replay = export_jsonl(ManagedHarness::Copilot, &path, "s", None).unwrap();
+ assert_eq!(replay.events[0].event_id, first.events[0].event_id);
+ assert_eq!(replay.events[1].event_id, second.events[0].event_id);
+ }
+
fn push_protobuf_varint(output: &mut Vec<u8>, mut value: u64) {
loop {
let byte = (value & 0x7f) as u8;