Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(wikisync): preserve pages for recreated repository files
Samir Hanna Verza1a3969a0b682
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e65cba04..821bd510 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,11 @@ version in [`docs/changelog/`](docs/changelog/):### Fixed+- Kept a wiki-sync server page when its repository file was recreated after+ the sync planned a deletion. `sync --propagate-deletes --apply` now rechecks+ local absence before sending the delete, preserves the page's baseline and+ reports the changed file for the next sync, including with `--prefer repo`+ (#PR).- Refused empty and whitespace-only `--workspace` and `--project` flags at theshared CLI scope-resolution choke point (`resolve_scope`,`resolve_scope_noting_marker_project`, `resolve_scope_with_marker`, anddiff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.mdindex 65fce1f6..61667b6e 100644--- a/companions/ai-memory-wikisync/README.md+++ b/companions/ai-memory-wikisync/README.md@@ -199,9 +199,12 @@ Safety rules:the whole run. A pinned server page is never deleted unless `--prefer repo`is given. A file is deleted only through the same path checks as a write(no symlinked file or directory, nothing outside `--dest`) and only if it- still holds the bytes the plan classified. The tool never runs git: it- prints the `git rm` to stage the deletes. Apply order is imports, exports,- server deletes, file deletes.+ still holds the bytes the plan classified. Before deleting a server page,+ the tool rechecks that its repository file is still absent. A file restored+ during planning keeps the server page and baseline, even with `--prefer repo`;+ the run reports the change and exits non-zero so the next sync can reconsider+ it. The tool never runs git: it prints the `git rm` to stage the deletes.+ Apply order is imports, exports, server deletes, file deletes.## CI and post-mergediff --git a/companions/ai-memory-wikisync/src/bidi.rs b/companions/ai-memory-wikisync/src/bidi.rsindex decbea05..5cb59c83 100644--- a/companions/ai-memory-wikisync/src/bidi.rs+++ b/companions/ai-memory-wikisync/src/bidi.rs@@ -809,14 +809,14 @@ async fn apply_plan();}for delete in &plan.server_deletes {- let result = match &delete.expected_page_id {- Some(expected) => mcp.delete_page(&scope, &delete.path, expected).await,- None => Err(anyhow::anyhow!(mcp::server_too_old())),- };- match result {- Ok(()) => {+ match delete_server_page(mcp, &scope, dest_root, delete).await {+ Ok(true) => {new_state.pages.remove(&delete.path);}+ Ok(false) => {+ report_local_change(&delete.path);+ applied.raced.push(delete.path.clone());+ }Err(error) if error.is::<PreconditionFailed>() => {report_race(&delete.path, &error);applied.raced.push(delete.path.clone());@@ -867,6 +867,32 @@ fn report_race(path: &str, error: &anyhow::Error) {);}+/// A planned server deletion depends on the repository file still being+/// absent. Recheck immediately before the request, without reading a recreated+/// file's content; the server separately guards its own version.+async fn delete_server_page(+ mcp: &McpClient,+ scope: &Scope<'_>,+ dest_root: &Path,+ delete: &ServerDelete,+) -> Result<bool> {+ let target = paths::secure_join(dest_root, &delete.path)?;+ match fs::symlink_metadata(&target) {+ Ok(_) => return Ok(false),+ Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}+ Err(error) => {+ return Err(anyhow::Error::new(error))+ .context(format!("cannot inspect {}", target.display()));+ }+ }+ let expected = delete+ .expected_page_id+ .as_deref()+ .ok_or_else(|| anyhow::anyhow!(mcp::server_too_old()))?;+ mcp.delete_page(scope, &delete.path, expected).await?;+ Ok(true)+}+/// Delete one repository file through the same confinement as every write:/// a validated path, no symlinked component, a regular file. The file must/// still be the bytes the plan classified; returns `false` when it is not.diff --git a/companions/ai-memory-wikisync/tests/api_server.rs b/companions/ai-memory-wikisync/tests/api_server.rsindex df458eeb..27adc078 100644--- a/companions/ai-memory-wikisync/tests/api_server.rs+++ b/companions/ai-memory-wikisync/tests/api_server.rs@@ -1455,6 +1455,75 @@ async fn sync_propagates_deletes_from_an_unchanged_side() {);}+/// A restored file invalidates the planned repository-side deletion even+/// though the server's version precondition still holds.+#[tokio::test]+async fn sync_keeps_a_server_page_when_its_file_reappears_during_planning() {+ for prefer in [None, Some(Prefer::Repo)] {+ let mut page = decision();+ page.pinned = false;+ let mut other = page.clone();+ other.path = "decisions/other.md".to_string();+ let (addr, fixture) = serve(Fixture::with_pages(vec![page, other])).await;+ let (_tmp, dest) = temp_dest();+ sync(addr, &dest).await.expect("first sync");+ let before = state::load(&dest).unwrap();+ let original = fixture.page("decisions/db.md").unwrap();+ let restored = DECISION_FILE+ .replace("pinned: true\n", "")+ .replace("Use Postgres.", "Restored with a new repository edit.");+ fs::remove_file(dest.join("decisions/db.md")).unwrap();+ fs::remove_file(dest.join("decisions/other.md")).unwrap();+ // The file is restored after the plan read its absence, while the+ // server request is in flight, before any delete is sent.+ *fixture.repository_edit_on_read.lock().unwrap() =+ Some((dest.join("decisions/db.md"), restored.as_bytes().to_vec()));++ let result = bidi::run(&deleting_args(addr, &dest, prefer), SyncMode::Apply).await;+ assert!(+ fixture.page("decisions/db.md").is_some(),+ "a recreated file must prevent deleting its unchanged server page"+ );+ let kept = fixture.page("decisions/db.md").unwrap();+ assert_eq!(kept.id, original.id);+ assert_eq!(kept.body, original.body);+ assert_eq!(+ fs::read(dest.join("decisions/db.md")).unwrap(),+ restored.as_bytes()+ );+ let after = state::load(&dest).unwrap();+ assert_eq!(+ after.pages["decisions/db.md"],+ before.pages["decisions/db.md"]+ );+ let message = result+ .expect_err("the local race must be reported")+ .to_string();+ assert!(message.contains("changed during this run"), "{message}");+ assert!(message.contains("decisions/db.md"), "{message}");++ // Control: the other file stayed absent, so its deletion proceeds.+ assert!(fixture.page("decisions/other.md").is_none());+ assert!(!after.pages.contains_key("decisions/other.md"));+ assert_eq!(fixture.mcp_deletes.load(Ordering::SeqCst), 1);+ let calls = fixture.mcp_calls.lock().unwrap().clone();+ assert_eq!(calls.len(), 1, "{calls:?}");+ assert_eq!(calls[0]["arguments"]["path"], "decisions/other.md");++ // Retaining the baseline lets a later sync import the restored edit.+ sync(addr, &dest)+ .await+ .expect("the next sync imports the restored file");+ assert!(+ fixture+ .page("decisions/db.md")+ .unwrap()+ .body+ .contains("Restored with a new repository edit.")+ );+ }+}+#[tokio::test]async fn sync_delete_conflicts_follow_prefer() {let mut other = decision();diff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 23b2d5a6..c296c47a 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -70,7 +70,7 @@ the legitimate restricted-project control and the failed-query cases.| 5b | Page supersession (loser stays reachable) | `ai-memory-store/src/ops.rs` `upsert_page_in_tx` — demote `is_latest=0` (never delete) + `supersedes` chain; read side: `reader.rs` `page_versions` lists every row at the path, with no `is_latest` filter, for `/web/w/…/h/*path` and `/api/v1/…/history/*path`. It does apply TTL expiry (`reader.rs` `history_visible`): a version whose own `expires_at` passed is neither listed nor readable by id, a path whose live version expired shows no history at all (the forget sweep hard-deletes every row there), and a `supersedes` link to a hidden version reads as `null`. Expiry is the only thing that hides a superseded version; a concurrent write never does | `multi_session.rs` `concurrent_writes_to_one_path_supersede_rather_than_destroy`; `retrieval_superseded.rs`; `multi_session.rs` `page_history_keeps_the_overwritten_version_and_stays_in_scope`; `ai-memory-web` `history_replay.rs` `history_keeps_both_sides_of_a_concurrent_divergent_write` (two attributed writers on one base: all three versions and both authors listed, one `is_latest`, the two writers' versions diff by id) and `history_lists_k_plus_one_versions_newest_first_and_diffs_the_latest`; bite: an `is_latest = 1` filter in `page_versions` fails both; `history_hides_expired_versions_and_expired_pages` (an expired superseded version and every version of a page whose live version expired answer 404 by path and by id on HTML and JSON, and the live successor's `supersedes` is `null`; control: a TTL in the future is listed and diffable; bites with the per-row predicate removed, with the live-version clause disabled, and with the `supersedes` hiding removed) | STRONG || 5c | Watcher reindex and Wiki writes share per-page serialization (invariant #16) | `ai-memory-wiki/src/wiki.rs` `reindex_page` takes `mutation_lock.read` before `reindex_page_locked` takes `lock_page`, covering disk read through the single-writer upsert; callers already holding the exclusive global guard do not reacquire it. `write_page` uses the same page mutex and `apply_batch` retains sorted, deduplicated locks; embedding runs after both guards are released | `wiki.rs` `reindex_page_lock_waits_before_reading_and_allows_another_path` (transient snapshot refused while locked, another path progresses, release indexes the committed bytes without rewriting disk), `reindex_page_lock_serializes_write_through_the_upsert` and `reindex_page_lock_and_reversed_duplicate_batches_do_not_deadlock` (real concurrent operations, final disk/SQL winner and supersession ancestry preserved); all three fail with the reindex page guard removed. `reindex_page_lock_releases_both_guards_before_embedding` checks both body and abstract embedding; `decay_cleanup_reindex_does_not_embed_under_the_exclusive_lock` covers the exclusive caller | STRONG for a shared Wiki handle and its clones. External editors and independently constructed Wiki handles do not participate in these locks || 5d | Wiki project-tree filesystem confinement | `ai-memory-wiki/src/confinement.rs` checks the wiki root, workspace/project roots, every existing ancestor, the final component, and the in-root ordinary `.git` directory with link-aware metadata; repository workdir/gitdir/commondir are containment-checked after opening, and write parents are created one component at a time and rechecked. `Wiki` checks before admission and again under mutation/page locks, while `GitAdapter` rechecks immediately before writes, appends, renames, and removals. Direct reindex, checkpoint restore, manifests, auto-improvement artifacts, ledger append, startup repair, purge/session moves, rollback, migrations, and git tree staging use the same boundary. Confinement is a distinct `WikiError` and therefore cannot trigger missing-file DB fallback | `wiki.rs` `page_reads_refuse_leaf_and_ancestor_symlinks_without_fallback_classification`, `ai-memory-mcp` `admin_read_page.rs` `read_page_does_not_db_fallback_through_a_symlink`, `page_mutations_refuse_ancestor_symlink_and_leave_outside_and_store_unchanged`, `confinement_refusal_happens_before_blocking_and_observer_admission`, `restore_and_reindex_refuse_ancestor_symlink_without_touching_canary_or_db`; `git.rs` `git_metadata_link_is_refused_without_touching_external_repository`, `gitfile_redirect_outside_is_refused_without_touching_target`, `git_metadata_redirect_files_are_refused_before_repository_open`, `configured_worktree_outside_the_wiki_root_is_refused`, `linked_git_metadata_never_reaches_commit_fallback`, `gitfile_metadata_never_reaches_commit_fallback`, `out_of_root_worktree_never_reaches_commit_fallback`, `fallback_preflight_refuses_invalid_git_metadata`, `windows_commit_fallback_accepts_established_eligible_errors`, `eligible_windows_open_error_dispatches_the_fallback_after_validation`, `windows_init_error_dispatches_fallback_after_root_preflight`, `invalid_root_never_reaches_init_fallback`, `checkpoint_and_revision_reads_refuse_a_replaced_git_directory`, and ordinary-repository/API controls `init_is_idempotent_and_creates_dotgit`; `linked_wiki_root_is_refused_during_construction`, `linked_or_dangling_scope_roots_are_refused_but_real_roots_work`, existing `decay_cleanup_refuses_to_reindex_a_symlinked_recreation` and `reindex_rejects_symlinked_scope_manifest`; `ai-memory-mcp` `admin_move.rs` `true_move_refuses_an_invalid_destination_namespace_without_db_changes` and `delete_workspace_refuses_invalid_namespace_before_db_or_notification`; `admin_backup.rs` `backup_refuses_redirected_git_metadata_before_returning_an_archive`, `backup_refuses_wiki_leaf_links_before_returning_an_archive`, `backup_refuses_linked_wiki_directories_before_returning_an_archive`, and ordinary archive controls; `watcher.rs` `direct_file_event_skips_symlink`, `walk_markdown_skips_linked_directories_and_their_ledgers`, and `shared_link_like_helper_accepts_regular_files_and_directories` (Windows directory-link coverage exercises reparse metadata when privilege is available); `backup.rs` `a_pre_migration_backup_refuses_a_linked_wiki_tree_without_an_archive`; `confinement.rs` metadata-helper controls run on every platform | STRONG for imported/static links and same-process mutations. Component checks do not claim descriptor-relative protection against a concurrently malicious same-user process; Windows reparse behavior requires the `windows` PR label/full CI |-| 5e | Conditional page mutation (#986, invariant #16) | `ai-memory-store/src/ops.rs` `upsert_page_if` reads the latest version and writes in one transaction, the authority; `ai-memory-wiki/src/wiki.rs` `write_page_if` pre-checks under the per-page lock before touching disk and restores the file when the store check fails; conditional deletes reuse `delete_page_if_latest` (exclusive mutation lock plus an in-transaction check). `ai-memory-mcp/src/server.rs` checks the precondition only after scope resolution and the write grant, against the resolved scope's own latest row, and returns `precondition_failed` with no write, checkpoint or webhook dispatch. The agentmemory importer (`agentmemory/mod.rs` `apply_page`) resumes from a conflicting destination only when its complete body equals a planned version; a retained attribution key alone cannot supply the next write's expected version. `companions/ai-memory-wikisync/src/bidi.rs` `build_plan` reads the full page for an edited repository file, keeping classification and `expected_page_id` on the same server version | `multi_session.rs` `conditional_writers_on_one_base_exactly_one_wins_and_nothing_is_destroyed` (two writers from one version: one wins, the base stays reachable, no loser row; fails with the store check removed); `server.rs` `conditional_page_writes::*` (stale id, `create_only` on an existing page, a version id from another project, and conditional deletes are refused and change nothing, with and without the wiki pre-check; the store check proven to bite with the reader pre-check off); `a_reader_may_read_everything_and_change_nothing` (a read-only user's conditional write or delete, with the right id or a wrong one, gets the authorization error and no version data; the page is unchanged); importer `resume_refuses_an_edited_body_even_with_the_original_ingest_key` and `e2e_export_import_rebuilds_chains_and_honours_ttl` (an edited destination body keeps its attribution key but cannot be superseded by a resumed import; both fail with marker-only matching); `resume_after_an_injected_failure_writes_no_duplicates` and `a_foreign_page_at_the_destination_is_never_replaced` are the legitimate-resume and foreign-page controls; wikisync `tests/api_server.rs` `sync_does_not_rebase_an_import_onto_a_concurrent_server_edit` (an edit after the read snapshot is refused by the original version precondition, preserving server, repository and baseline; fails without the conditional-read guard), `sync_imports_a_repo_edit_with_its_metadata` and `sync_exports_metadata_and_round_trips_without_writes` (ordinary import and unchanged-file ETag controls) | STRONG. Importer resumption compares bodies, not frontmatter-only edits; custom server sanitation that changes the planned body fails closed |+| 5e | Conditional page mutation (#986, invariant #16) | `ai-memory-store/src/ops.rs` `upsert_page_if` reads the latest version and writes in one transaction, the authority; `ai-memory-wiki/src/wiki.rs` `write_page_if` pre-checks under the per-page lock before touching disk and restores the file when the store check fails; conditional deletes reuse `delete_page_if_latest` (exclusive mutation lock plus an in-transaction check). `ai-memory-mcp/src/server.rs` checks the precondition only after scope resolution and the write grant, against the resolved scope's own latest row, and returns `precondition_failed` with no write, checkpoint or webhook dispatch. The agentmemory importer (`agentmemory/mod.rs` `apply_page`) resumes from a conflicting destination only when its complete body equals a planned version; a retained attribution key alone cannot supply the next write's expected version. `companions/ai-memory-wikisync/src/bidi.rs` `build_plan` reads the full page for an edited repository file, keeping classification and `expected_page_id` on the same server version; `delete_server_page` rechecks the repository file's absence before sending a conditional server delete | `multi_session.rs` `conditional_writers_on_one_base_exactly_one_wins_and_nothing_is_destroyed` (two writers from one version: one wins, the base stays reachable, no loser row; fails with the store check removed); `server.rs` `conditional_page_writes::*` (stale id, `create_only` on an existing page, a version id from another project, and conditional deletes are refused and change nothing, with and without the wiki pre-check; the store check proven to bite with the reader pre-check off); `a_reader_may_read_everything_and_change_nothing` (a read-only user's conditional write or delete, with the right id or a wrong one, gets the authorization error and no version data; the page is unchanged); importer `resume_refuses_an_edited_body_even_with_the_original_ingest_key` and `e2e_export_import_rebuilds_chains_and_honours_ttl` (an edited destination body keeps its attribution key but cannot be superseded by a resumed import; both fail with marker-only matching); `resume_after_an_injected_failure_writes_no_duplicates` and `a_foreign_page_at_the_destination_is_never_replaced` are the legitimate-resume and foreign-page controls; wikisync `tests/api_server.rs` `sync_does_not_rebase_an_import_onto_a_concurrent_server_edit` (an edit after the read snapshot is refused by the original version precondition, preserving server, repository and baseline; fails without the conditional-read guard), `sync_imports_a_repo_edit_with_its_metadata` and `sync_exports_metadata_and_round_trips_without_writes` (ordinary import and unchanged-file ETag controls); `sync_keeps_a_server_page_when_its_file_reappears_during_planning` (restored file blocks server deletion and keeps the baseline, with and without `--prefer repo`; another absent file is deleted and a later sync imports the restored edit; fails without the local-absence recheck) | STRONG. Importer resumption compares bodies, not frontmatter-only edits; custom server sanitation that changes the planned body fails closed. Wiki-sync rechecks local absence immediately before the request; this is not atomic across the filesystem and server || 5f | Wiki-sync companion destination confinement | `companions/ai-memory-wikisync/src/paths.rs` `prepare_dest` compares canonical and lexical destination components without resolving the lexical path; Windows disk and UNC verbatim prefixes compare as equivalent spellings, while changed directory components are refused. `secure_join` keeps validated page paths below that root and refuses existing symlink components | `paths.rs` `prepare_dest_refuses_windows_junctions_without_touching_the_target` refuses a junction and a destination reached through it, leaves an outside canary unchanged, and accepts the real directory; `windows_destination_prefixes_do_not_hide_different_paths` refuses different drives, shares and directory components with ordinary/verbatim controls; `prepare_dest_refuses_symlinks_and_files` and `secure_join_stays_under_root_and_refuses_symlink_components` retain the Unix link controls | Static path checks; no descriptor-relative protection against a concurrently malicious same-user process. The dedicated `windows.yml` wiki sync companion job runs the prefix and junction tests on companion/workflow changes, `windows` or `full-ci` labels, nightly runs and dispatch || 6 | Active-project pointer (PerActor, no clobber) | `ai-memory-core/src/active_project.rs` `set_for`/`lookup_for` (fail-closed on `Mismatch`); `ai-memory-cli/src/commands/mcp_bridge.rs` `bridge_session_id`: the session-less bridge (`--no-session-id`, every non-Claude stdio client on a token-file install) never forwards an inherited `CLAUDE_CODE_SESSION_ID`, so a client launched from a Claude Code terminal cannot steer that session's per-session pointer; the session-aware bridge reads only the variable its `--agent` names (`CLAUDE_CODE_SESSION_ID`, or `MUSE_SESSION_ID` for Meta Muse Code), so neither harness's id stands in for the other's | `active_project.rs` `parallel_harnesses_of_one_user_keep_separate_pointers`, `two_operators_never_read_each_others_pointer`, `a_session_mismatch_fails_closed_once_anything_has_been_keyed`; `multi_session.rs` `same_operator_multiple_sessions_isolate_active_project_pointers_and_resolution` (concurrent sessions of one operator under `AccessMode::Restricted` resolve unscoped reads/writes to their own active project without cross-session clobber, while an unbound session of the same operator fails closed on unscoped write with `AmbiguousUnscopedWrite` and falls back to `DefaultAfterMismatch` on read); `mcp_bridge.rs` `only_the_session_aware_mode_forwards_and_requires_a_session_id` (an inherited id is dropped in session-less mode; the session-aware control forwards it and still fails closed without one), `each_harness_forwards_only_its_own_session_id` (a Muse bridge never forwards an inherited Claude id and fails closed without its own, a Claude bridge never forwards an inherited Muse id; controls forward each harness's own id) and `a_session_less_upstream_config_carries_no_session_header`; `auth_default_e2e.rs` `a_session_less_bridge_serves_any_client_without_holding_the_token` (the built `mcp-bridge --agent muse` refuses to start with only `CLAUDE_CODE_SESSION_ID` set) | STRONG || 6b | Native `_meta` routing coordinate is routing-only (never grants identity) | `ai-memory-mcp/src/server.rs` `attach_native_session` reads only `_meta["ai.opencode/sessionID"]` into `ActorKey.session_id` (trimmed, non-empty-string-validated); `user` still comes from the authenticated `ActorContext`, so a forged `_meta` cannot cross a user/scope boundary — it only selects a session slot behind the existing `active_project` guard | `server.rs` `native_session_metadata_is_routing_only_and_preserves_precedence`, `native_session_metadata_validates_strings_without_granting_identity`; `autoscope_multiuser.rs` `native_metadata_routes_concurrent_reads_and_writes_to_hook_workspaces` (#864) | STRONG |