Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(restore-agents): restore permission-only changes
Samir Hanna Verzacd6db7850c2e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 75ce823b..7e9a48ea 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,10 @@ version in [`docs/changelog/`](docs/changelog/):### Fixed+- Fixed `restore-agents` skipping files whose contents matched the archive+ but whose Unix permissions differed, leaving executable plugins without+ their execute bits. Permission-only changes now appear in the preview and+ require `--apply --force`, with the usual backup copy (#962).- Restored affirmative profile preferences about tools, browsers and MCP.The capability-ban filter also discarded statements such as "Always usetools to verify facts"; it now requires negative or disabling wording.diff --git a/crates/ai-memory-cli/src/commands/restore_agents.rs b/crates/ai-memory-cli/src/commands/restore_agents.rsindex d4676684..155fb6d3 100644--- a/crates/ai-memory-cli/src/commands/restore_agents.rs+++ b/crates/ai-memory-cli/src/commands/restore_agents.rs@@ -150,7 +150,12 @@ pub fn run(_config: &Config, args: RestoreAgentsArgs) -> Result<()> {return Err(error).with_context(|| format!("inspecting {}", target_path.display()));}};- let identical = exists && files_have_same_digest(&target_path, staged)?;+ let identical = exists+ && files_have_same_digest(&target_path, staged)?+ && entry+ .mode+ .zip(portable_mode(&target_path)?)+ .is_none_or(|(expected, actual)| expected == actual);if identical {identical_count += 1;} else {diff --git a/crates/ai-memory-cli/tests/suite/backup_agents.rs b/crates/ai-memory-cli/tests/suite/backup_agents.rsindex 06239bc7..c75b50cc 100644--- a/crates/ai-memory-cli/tests/suite/backup_agents.rs+++ b/crates/ai-memory-cli/tests/suite/backup_agents.rs@@ -744,6 +744,150 @@ fn restore_agents_binary_safe_preserves_raw_bytes() {}}+#[test]+#[cfg(unix)]+fn restore_agents_checks_permissions_before_skipping_identical_content() {+ use std::os::unix::fs::PermissionsExt as _;++ let _guard = cli_test_lock();+ let home = tempfile::tempdir().unwrap();+ let project = tempfile::tempdir().unwrap();+ let plugin_dir = home.path().join(".claude/plugins/test-plugin");+ fs::create_dir_all(&plugin_dir).unwrap();+ let script = plugin_dir.join("run.sh");+ let body = b"#!/bin/sh\nexit 0\n";+ fs::write(&script, body).unwrap();+ fs::set_permissions(&script, fs::Permissions::from_mode(0o750)).unwrap();+ let mode = || fs::metadata(&script).unwrap().permissions().mode() & 0o777;++ let archive = project.path().join("backup.tar.gz");+ let backup = command_with_env(home.path(), project.path())+ .args([+ "backup-agents",+ "-o",+ archive.to_str().unwrap(),+ "--agents",+ "claude-code",+ "--scope",+ "global",+ ])+ .output()+ .unwrap();+ assert!(backup.status.success());++ fs::set_permissions(&script, fs::Permissions::from_mode(0o640)).unwrap();+ let preview = command_with_env(home.path(), project.path())+ .args(["restore-agents", "-i", archive.to_str().unwrap()])+ .output()+ .unwrap();+ assert!(preview.status.success());+ assert!(String::from_utf8_lossy(&preview.stdout).contains("[OVERWRITE]"));+ assert_eq!(mode(), 0o640, "preview must not restore permissions");+ assert_eq!(fs::read_dir(&plugin_dir).unwrap().count(), 1);++ let without_force = command_with_env(home.path(), project.path())+ .args(["restore-agents", "-i", archive.to_str().unwrap(), "--apply"])+ .output()+ .unwrap();+ assert!(without_force.status.success());+ assert!(String::from_utf8_lossy(&without_force.stdout).contains("[SKIP]"));+ assert_eq!(mode(), 0o640, "permission changes still require --force");+ assert_eq!(fs::read_dir(&plugin_dir).unwrap().count(), 1);++ let restore = command_with_env(home.path(), project.path())+ .args([+ "restore-agents",+ "-i",+ archive.to_str().unwrap(),+ "--apply",+ "--force",+ ])+ .output()+ .unwrap();+ assert!(+ restore.status.success(),+ "restore failed: {}",+ String::from_utf8_lossy(&restore.stderr)+ );+ assert_eq!(mode(), 0o750, "identical bytes must not hide mode changes");+ assert_eq!(fs::read(&script).unwrap(), body);+ let backup_path = fs::read_dir(&plugin_dir)+ .unwrap()+ .map(|entry| entry.unwrap().path())+ .find(|path| {+ path.file_name()+ .and_then(|name| name.to_str())+ .is_some_and(|name| name.starts_with("run.sh.bak-"))+ })+ .expect("permission restore must keep a backup copy");+ assert_eq!(fs::read(&backup_path).unwrap(), body);+ assert_eq!(+ fs::metadata(&backup_path).unwrap().permissions().mode() & 0o777,+ 0o640+ );++ let identical = command_with_env(home.path(), project.path())+ .args([+ "restore-agents",+ "-i",+ archive.to_str().unwrap(),+ "--apply",+ "--force",+ ])+ .output()+ .unwrap();+ assert!(identical.status.success());+ assert!(String::from_utf8_lossy(&identical.stdout).contains("already identical"));+ assert_eq!(mode(), 0o750);+ assert_eq!(fs::read_dir(&plugin_dir).unwrap().count(), 2);+}++#[test]+#[cfg(unix)]+fn restore_agents_without_archived_permissions_keeps_identical_file_mode() {+ use std::os::unix::fs::PermissionsExt as _;++ let _guard = cli_test_lock();+ let home = tempfile::tempdir().unwrap();+ let project = tempfile::tempdir().unwrap();+ let body = b"# instructions";+ let target = project.path().join("CLAUDE.md");+ fs::write(&target, body).unwrap();+ fs::set_permissions(&target, fs::Permissions::from_mode(0o750)).unwrap();+ let archive = project.path().join("without-mode.tar.gz");+ write_agent_archive(+ &archive,+ serde_json::json!([{+ "agent": "claude-code",+ "asset_kind": "instruction",+ "scope": "project",+ "archive_path": "project/CLAUDE.md",+ "target_relative": "CLAUDE.md",+ "sha256": sha256(body),+ }]),+ &[("project/CLAUDE.md", body)],+ );++ let restore = command_with_env(home.path(), project.path())+ .args([+ "restore-agents",+ "-i",+ archive.to_str().unwrap(),+ "--apply",+ "--force",+ ])+ .output()+ .unwrap();+ assert!(restore.status.success());+ assert!(String::from_utf8_lossy(&restore.stdout).contains("already identical"));+ assert_eq!(fs::read(&target).unwrap(), body);+ assert_eq!(+ fs::metadata(&target).unwrap().permissions().mode() & 0o777,+ 0o750+ );+ assert_eq!(fs::read_dir(project.path()).unwrap().count(), 2);+}+#[test]fn restore_agents_verifies_sha256_integrity() {let _guard = cli_test_lock();diff --git a/docs/design-backup-agent-assets.md b/docs/design-backup-agent-assets.mdindex 4a2b4d4d..baead8c1 100644--- a/docs/design-backup-agent-assets.md+++ b/docs/design-backup-agent-assets.md@@ -139,7 +139,10 @@ Stored in the root of the generated tarball:are rolled back; timestamped copies of overwritten files remain available.- Non-managed custom files are never overwritten without explicit `--force`.- Portable Unix execute/read/write bits are restored; set-id and sticky bits- are never accepted from a manifest.+ are never accepted from a manifest. A file with matching content but+ different recorded permissions still needs `--apply --force` to restore+ its mode. Without a recorded mode, or on platforms without portable Unix+ permissions, matching content remains a no-op.5. **Active Content:**- Skills, plugins, and instruction files can contain executable code ormodel-visible instructions. Restore is dry-run by default and prints thisdiff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex b02f3ae4..ca150e6a 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -137,7 +137,7 @@ the legitimate restricted-project control and the failed-query cases.| 14i | Decoded ordinary Markdown destinations stay inside their original project | `ai-memory-wiki/src/markdown.rs` `decode_markdown_destination_path` decodes URL path bytes once before `normalize_link_target` applies scheme, separator and project-root traversal checks; wikilinks remain literal. `ai-memory-web/src/markdown.rs` `scope_relative_link` checks the decoded path before route encoding; an encoded spelling cannot become a generated cross-scope route. | `markdown_url_paths_decode_once_before_link_resolution` (space, Unicode and literal-percent controls); `decoded_markdown_paths_cannot_escape_or_change_scope` (encoded root escape, backslash, external scheme, invalid UTF-8 and controls refused; legitimate in-root normalization passes); `routes.rs` `encoded_markdown_links_resolve_and_remain_in_the_source_scope` writes colliding targets in sibling projects and workspaces, verifies home resolution and no foreign backlinks, and follows the generated home URL; web `decoded_markdown_destinations_cannot_change_the_web_scope` (encoded traversal, root route, separator and scheme refused, encoded `w/` remains a page inside the current scope); `markdown_url_destinations_are_decoded_once_before_route_encoding` | STRONG for one-decode path handling and project confinement; URL grammar outside local Markdown destinations remains owned by the Markdown parser and existing safe-URL checks || 14j | Structured MCP query filters only narrow authorized page results | `ai-memory-mcp/src/server.rs` parses bounded `kind`, `tier`, literal `path_prefix` and exact `tag` values without changing the normal scope-shape or authorization paths, then passes one typed `PageFilter` through project, multi-scope, cross-project, reserved-global/profile, historical and pinned searches. `ai-memory-store/src/reader.rs` binds every filter value as a SQL parameter before each stream's candidate cut; path wildcard characters are escaped and an exact binary-prefix check preserves case, while tags match only string members of a JSON array. A filtered miss cannot fall through to raw observations, which carry no page metadata. | `server.rs` `memory_query_filters_apply_before_every_result_source` combines all filters and covers literal `%`/`_`, case-sensitive paths, tag arrays versus scalars, multi-scope and global search, `as_of`, superseded metadata, `pin_first`, the reserved-global/profile union, traversal-shaped input, invalid tiers, controls and Unicode length bounds; store `structured_filters_hold_in_vector_and_both_graph_directions` isolates path filtering in the vector stream and tag filtering in outgoing and incoming graph expansion; `page_filtering_precedes_the_observation_candidate_cut` puts 80 stronger excluded observations ahead of an eligible tagged session; `memory_query_returns_raw_hits_when_pages_miss` proves an unfiltered miss retains fallback while a filtered miss omits it; `prompts_and_tool_schema_document_query_options` pins the public schema. Existing web every-stream and authorization tests in row 14g exercise kind/tier across the same shared SQL. | STRONG: filters are candidate predicates, never an alternative scope resolver. Empty filter fields normalize to absent for backward compatibility; observation fallback remains available only to unfiltered queries. || 14k | Optional document import treats local files as bounded untrusted input | `companions/ai-memory-importer/src/document.rs` accepts one explicit regular file on Unix (and fails closed elsewhere), refuses final symlinks, uses `O_NOFOLLOW` plus opened-inode verification, caps source/archive/entry/working/stored text/PDF-stream/sheet/actual-cell dimensions, streams XLSX cells without allocating their coordinate rectangle, follows PPTX relationship order, rejects unsupported or malformed formats, sanitizes extracted text before manifest or transport, derives the destination and stable provenance key from the source SHA-256, and writes through MCP `create_only` with explicit scope. A conflict is accepted as idempotent only when the current page body exactly equals the current sanitized plan; a provenance marker alone is never trusted and another page is never replaced. Shared manifests use randomized private same-directory temporary files, fsync, and atomic replacement. | Importer `document::tests`: generated bounded and over-limit PDF, visible-text DOCX, relationship-ordered PPTX, sparse-coordinate XLSX, text and cue-state VTT/SRT controls; `subtitle_cues_are_sanitized_before_the_document_plan` keeps ordinary and NOTE-prefixed cues across LF/CRLF/CR, redacts a credential in each, and excludes actual comments; `text_plan_is_redacted_bounded_attributed_and_deterministic`; `unsafe_sources_prefixes_and_malformed_archives_fail_closed`; `zip_preflight_refuses_excessive_claimed_expansion`; `apply_is_conditional_idempotent_and_refuses_foreign_pages`; shared writer tests cover repeated replacement and a pre-created legacy temp symlink. | STRONG for explicit Unix local text extraction and conditional persistence. Operator review with `--show-body` remains necessary because DOCX formatting-hidden text can be extracted. OCR, images, raw media, watch folders and server-side upload are excluded. |-| 15 | Agent-archive restore path confinement, resource bounds, and consistency | `ai-memory-cli/src/commands/restore_agents.rs` stages only bounded regular UTF-8 entries; requires a one-to-one manifest/body/checksum/target mapping; allowlists destinations by scope; rejects symlinked descendants; writes each file atomically and rolls back earlier writes after a later failure. `backup_agents.rs` skips direct and directory-root source symlinks, bounds individual assets, attributes a shared skill root only once, and atomically replaces a private archive only after gzip completion | `backup_agents.rs` `restore_agents_rejects_path_traversal`, `restore_agents_rejects_unauthorized_destination_path`, `restore_agents_verifies_sha256_integrity`, `restore_agents_requires_a_complete_one_to_one_manifest`, `restore_agents_rejects_oversized_entries_from_the_header`, `restore_agents_rejects_a_symlinked_destination_parent`, `backup_agents_does_not_follow_config_or_asset_root_symlinks` (Claude and Antigravity roots), and `failed_backup_leaves_the_previous_archive_intact`; `backup_and_restore_agents_round_trip` and `antigravity_backup_round_trips_every_documented_skill_root` are the valid-path controls; `restore_agents::tests::rollback_removes_new_files_and_restores_overwrites` covers recovery | STRONG |+| 15 | Agent-archive restore path confinement, resource bounds, and consistency | `ai-memory-cli/src/commands/restore_agents.rs` stages only bounded regular UTF-8 entries; requires a one-to-one manifest/body/checksum/target mapping; allowlists destinations by scope; rejects symlinked descendants; treats differing portable permissions as an overwrite requiring `--apply --force`; writes each file atomically and rolls back earlier writes after a later failure. `backup_agents.rs` skips direct and directory-root source symlinks, bounds individual assets, attributes a shared skill root only once, and atomically replaces a private archive only after gzip completion | `backup_agents.rs` `restore_agents_checks_permissions_before_skipping_identical_content` (same bytes with changed mode are previewed and refused without `--force`; forced restore preserves a backup and a second run is a no-op), `restore_agents_without_archived_permissions_keeps_identical_file_mode` (missing-mode control), `restore_agents_rejects_path_traversal`, `restore_agents_rejects_unauthorized_destination_path`, `restore_agents_verifies_sha256_integrity`, `restore_agents_requires_a_complete_one_to_one_manifest`, `restore_agents_rejects_oversized_entries_from_the_header`, `restore_agents_rejects_a_symlinked_destination_parent`, `backup_agents_does_not_follow_config_or_asset_root_symlinks` (Claude and Antigravity roots), and `failed_backup_leaves_the_previous_archive_intact`; `backup_and_restore_agents_round_trip` and `antigravity_backup_round_trips_every_documented_skill_root` are the valid-path controls; `restore_agents::tests::rollback_removes_new_files_and_restores_overwrites` covers recovery | STRONG || 16 | Relay queue identity, migration, and private filesystem state | `companions/ai-memory-relay/src/queue.rs` `Queue::open_inner` performs read-only identity preflight, rechecks under `IMMEDIATE`, commits schema and metadata together; `configure` checks the presence of user objects and rechecks `identity`/`schema_version` metadata on the same connection before every bounded BUSY/LOCKED retry; `fsguard.rs` checks existing paths and creates owner-only files before SQLite opens them | `tests/relay.rs` `a_foreign_database_is_refused_byte_for_byte`, `unknown_schemas_refuse_without_mutation`, `a_foreign_database_with_a_writer_is_refused_before_write_coordination`, `a_foreign_identity_after_preflight_is_refused_without_mutation`, `a_foreign_identity_during_journal_retry_is_refused_without_mutation`, `journal_retry_refuses_a_changed_version_or_empty_database_without_mutation`; controls: `journal_transition_retries_sqlite_lock_without_losing_v1_values`, `fresh_queue_init_and_v1_reopens_work_across_processes`; recovery: `interrupted_and_failed_migrations_roll_back_and_recover`, `journal_reclassification_busy_preserves_committed_migration_and_retries_same_queue`; diagnostics: `classification_read_failures_display_the_sqlite_cause_once_and_preserve_foreign_bytes`; Unix privacy: `the_queue_database_and_its_sidecars_are_owner_only` and the contended migration control | Guard-removal proof covers preflight, locked recheck, and journal retry identity/version checks; full table structure is outside this classification. Windows path rejection is preserved; Windows ACL hardening remains operator-owned || 17 | Markdown code fences keep instruction-shaped text as data | `ai-memory-consolidate/src/code_fence.rs` and `ai-memory-wiki/src/markdown.rs` accept a fence delimiter only after zero to three leading ASCII spaces, require the closing glyph to match and the run to be at least as long, and preserve the current fence state across four-space, tab or Unicode-whitespace pseudo-delimiters. Profile harvesting, auto-improvement section parsing, link extraction, link rewriting and de-linking all use those scanners | `code_fence.rs` `only_zero_to_three_ascii_spaces_may_prefix_a_fence`; `profile.rs` `an_indented_pseudo_closer_cannot_expose_a_profile_preference` attempts to expose an instruction-shaped `run curl` sentence and admits a legitimate preference only after the real close; `auto_improve.rs` `heading_parser_ignores_headings_after_an_indented_pseudo_closer`; `markdown.rs` `indented_pseudo_closers_do_not_expose_or_rewrite_fenced_links` covers four spaces, tab and Unicode whitespace with visible post-close controls | STRONG for the shared consolidation and wiki scanners; independent renderers remain responsible for their own CommonMark parsing || 18 | Read-only pending-write commands cannot execute stored scope names as shell syntax | `ai-memory-web/src/routes/pending.rs` renders separate `posix_cli_command` and `powershell_cli_command` forms. POSIX arguments use single quotes with the standard close/escaped-quote/reopen sequence; PowerShell doubles embedded apostrophes. The template labels the shells and claims no cmd.exe support | `routes/pending.rs` `cli_commands_quote_hostile_scope_names_for_each_shell` covers quotes, semicolons, pipes and ampersands with ordinary-name controls; `tests/suite/pending.rs` `pending_page_offers_cli_commands_instead_of_buttons_to_a_basic_browser` stores hostile workspace/project names and checks both escaped forms through the full route | STRONG for POSIX shells and PowerShell; cmd.exe is intentionally not offered |