Skip to content

fix: keep the live workspace agent config on restore - #38689

Draft
chenmingwei23 wants to merge 4 commits into
mainfrom
mkt-pkg/fix-restore-agent-config
Draft

chenmingwei23 wants to merge 4 commits into
mainfrom
mkt-pkg/fix-restore-agent-config

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Restoring a snapshot archive never lets the archive's agent-config files decide how this install's next agent session runs.

kirocrew restore of the workspace component replaces the whole workspace/ tree (Replace) or adds every missing file to it (Merge). That tree is where agent sessions start, in workspace/ itself and in its project folders. It can hold .claude/settings.local.json (permission mode, allow rules, hooks), .claude/skills/, and .mcp.json (MCP servers). Nothing is filtered or held back, so an archive from someone else can turn on bypassPermissions, add shell hooks, or add MCP servers for the next session.

Why it matters

A restore is a routine thing to do with a file somebody sent you. After it, the next agent session in a restored folder can run commands with no prompts. The operator never reviewed that file.

Not a goal

  • No new option or flag for restoring these files.
  • CLAUDE.md and AGENTS.md stay restorable: they are notes with no permissions, hooks or servers of their own.
  • No change to other restore paths (the config component keys, memory, crons and hooks are other work).
  • No change to how snapshots are created.

What changed (motivation -> approach -> change)

Symptom: the archive's .claude/ and .mcp.json land in the live workspace. Cause: restore copies the staged workspace/ tree as it is. Change: before either mode reads the staged bundle, _hold_back_agent_config (in snapshot.py, next to _hold_back_executables) removes every agent-config name at any depth under the staged workspace/ (names matched case-insensitively, links unlinked and never followed). The names are .claude, .mcp.json, .kiro, .codex, .goose, .goosehints, .opencode, opencode.json, opencode.jsonc, .pi, .mimocode, mimocode.json, mimocode.jsonc. They come from the project config the harness code reads or fences (acp/claude_settings_sources.py:171, acp/kas_settings_mcp.py:209, acp/session_mcp.py:1501, acp/kas_skill_scope.py:128, agent_sdk/native_allow_stores.py:126-143); .codex, .goose and .goosehints were named by the security review and nothing in this tree reads them. A test fails if a name in PROJECT_ALLOW_STORES is not held back.

Checked, no project config name found: antigravity, copilot, deepseek, strands. Where I looked: agent_sdk/native_allow_stores.py:99 (copilot has only ~/.copilot rows), :106-118 (NATIVE_ALLOW_STORES_NONE: antigravity, deepseek and strands have no on-disk config known), :125-144 (PROJECT_ALLOW_STORES, no entry for them). No code for them.

  • Merge installs only what is missing, so nothing is installed for those names.
  • Replace swaps the whole tree, so the live copies are staged in their place. A live name with no copy ends up absent, never the archive's. Both walks (the staged archive and the live tree) enter every directory, node_modules, .git, .venv and venv included, so an agent config inside one of those is neither lost nor installed (shortcut: comment in the code: the live walk reads the whole workspace tree).
  • A live link or odd entry is refused by the existing fatal pinned skip, and a staged parent that is a link is refused. A refusal returns 1 with the live state unchanged.
  • The restore summary names each held path under workspace/.
  • The dashboard zip import (apply_import_zip in portability.py) runs the same hold-back on the extracted copy before either mode, so Replace and Merge both see the held-back staging. Its summary gets a held_agent_config list of workspace/<path> entries. The call is a local import inside the function because test_portability_facade.py pins which names portability binds from snapshot. Listing restored notes is CLI only; the import summary does not list them (Follow-up).
  • CLAUDE.md and AGENTS.md stay restorable. The summary prints Restored notes: workspace/<path> for each one a restore installed (Replace: all outside held directories; Merge: only those the live tree lacked).
  • Follow-up (not in this PR): the dashboard import summary does not name the CLAUDE.md / AGENTS.md notes it installed (the CLI restore does; portability.py:899 only reports held agent config).
  • Follow-up (not in this PR): holding CLAUDE.md and AGENTS.md back too. They are instructions an agent reads, so that decision is separate from the settings, hooks and servers held back here.
  • One docs paragraph in snapshot-and-restore.md.

Backwards compatibility

Breaking: a restore no longer installs any of the agent-config names listed under "What changed" (.claude/, .mcp.json, .kiro/ with its skills and steering, .codex/, .goose/, .goosehints, .opencode/, opencode.json(c), .pi/, .mimocode/, mimocode.json(c)) from an archive's workspace/, at any depth. Someone restoring their own backup onto a fresh home gets none of them back and copies them by hand; the summary names each one left out. Writer sweep on origin/main @ e3b3b13: kirocrew restore writes these paths through the workspace tree copy in Replace (_do_replace_mutations) and Merge (_do_merge), both fed from the staged bundle this change edits. The memory component names workspace/memory and workspace/knowledge only, so it is not affected. The dashboard import (portability.py, apply_import_zip) also writes a workspace/ tree; it runs the same hold-back (see Sibling sweep).

Reader: src/kiro_crew/snapshot.py:restore_main -- entry: release (CLI restore) -- stages the bundle once and both modes read the edited copy; tests test_replace_keeps_the_live_agent_config, test_merge_never_installs_the_archives_agent_config.
Reader: src/kiro_crew/snapshot_restore.py:_do_replace_mutations -- entry: release (CLI restore, Replace) -- unchanged; it copies the staged tree, which now holds the live copies.
Reader: src/kiro_crew/snapshot_merge_driver.py:_do_merge -- entry: release (CLI restore, Merge) -- unchanged; it skips what the staged tree no longer carries.

Tests

test/test_snapshot_restore_agent_config.py (87 tests) and test/test_portability_import_agent_config.py (4 tests):

  • one row per config name x depth (workspace/, workspace/proj/, workspace/a/b/) x mode (Replace, Merge): the archive's copy is not installed and a plain file beside it is;
  • Replace and Merge with and without a live agent config at two depths: the live copy is kept;
  • notes: Replace names each installed note and not one inside a held directory; Merge names only the notes it added;
  • a drift test: every first segment of PROJECT_ALLOW_STORES is held back;
  • two rows (venv, node_modules/pkg): a live agent config under a dependency directory survives Replace and the archive's copy there is not installed;
  • the restore summary says "kept your current copy" only for paths that exist live and "Not installed (no current copy)" for the rest;
  • test/test_portability_import_agent_config.py, 4 more tests: apply_import_zip in Replace and Merge keeps the live .mcp.json, installs no archive .claude/, proj/.mcp.json or a/b/.kiro/, still imports a plain file, and held_agent_config names the four held paths.

Red/green record: there is no local pytest on the machine this was written on, so CI is the record. Commit 1 (bc08210) is tests only and was pushed first. On it, run 44153487197 failed 85 tests, the same count as the new tests (only the first 10 per job are annotated; the other 75 were not read one by one): New-test stability (ubuntu-latest and windows-latest) and Backend Tests (3.12, 4) and (Windows, 4) report "85 tests failed or errored", and the annotated ones are test_every_harness_config_name_is_held_back_at_any_depth[...] with "AssertionError: from the archive was installed". Latest red record: commit 1 alone (cecccb6) failed 89 tests, the 85 CLI rows plus the 4 import rows (New-test stability reports "89 tests failed or errored"; annotated ones are test_every_harness_config_name_is_held_back_at_any_depth[...] and test_import_holds_back_the_archives_agent_config[replace|merge] with "the live .mcp.json was replaced" / "assert not True", and test_import_names_each_held_back_path[...] with "assert set() == {...}"). Commit 2 holds the fix and one registry row that declares the new code (test/link_screen_sites.py: snapshot.py::_hold_back_agent_config, which refuses on a link). The per-name ownership table in test/test_snapshot_refactor_ownership.py no longer exists on main, so there is no row for it. (The commit shas quoted in this record are from earlier heads, before the rebase onto main.) On its first head (56185e3) run 44164101257 showed the 85 new tests green and only those two registry tests red; its CI run is the green record.

Proof: not provable -- no local pytest; red run 44153487197 on the tests-only first commit is the record.

Review note at head 8fcd28a (answered in a PR comment, no code change): the GPT 6.1 finding at crew_mode.py:603 is on a file this PR does not touch and a line already on main.

Review notes at head 56185e3 (answered, no code change):

  • Opus 5.5 Review BLOCK ("Replace now refuses when a live agent-config entry is a link"): Replace already refuses a live link or hardlink anywhere under workspace/ before this change. Phase one backs the live tree up with _backup_tree_or_refuse (snapshot_restore.py:997-998, defined at :504-532), whose skip reporter is fatal on a symlink or non-regular file, and it runs on the whole workspace/ tree whenever the archive carries it. The new keep-the-live-copy step uses the same pinned primitives on a subset of the same files, so it refuses no input that was accepted before. By reading only; not run.
  • UX note (wording "kept your current copy" when there was no live copy): done; the summary now separates "kept your current copy" from "Not installed (no current copy)".
  • First Principles note (the restored-notes listing is beyond the Goal): the listing was asked for by the security review; keeping it.
  • Design notes: the Breaking line now names every held name; the dashboard import sibling is declared in Sibling sweep.

Out of scope: links in the live agent config

Replace already refuses a workspace that holds a live symlink or hard link before this change runs: the pre-Replace backup (src/kiro_crew/snapshot_restore.py, _backup_tree_or_refuse, fatal skip reporter) stops first. CI run 44384822036 shows that refusal. This PR does not change link handling; the agent-config hold-back only runs on workspaces the backup accepts.

Manual verification

N/A -- unit coverage sufficient: the tests drive restore_main end to end on a real tar archive and a real data home.

Screenshots / video

N/A -- no user-visible UI change (CLI restore output gains a short list of held files).

Related Issues

None.

Sibling sweep

Swept: git grep -n "_hold_back_executables" -- src/
Swept: git grep -n ""workspace", "plan_memory"" -- src/kiro_crew/
Sibling: src/kiro_crew/portability.py:1038 -- changed here: the dashboard import merges the archive's workspace/ tree, so apply_import_zip now holds the same names back first (both modes, tests in test/test_portability_import_agent_config.py).

Pattern harvest

Not generalizable: one restore path copied a whole tree that holds files the agent obeys; the fix is specific to those names.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 662449b83003d26d5c798967288052164274d20c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 662449b83003d26d5c798967288052164274d20c — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. One rider goes beyond the Goal: the "Restored notes" listing. The PR works without it, so it is a note.

Notes

  • Item 4 — rides along, oversized: the Goal is that the archive's config never decides the next session, and ## Not a goal keeps CLAUDE.md/AGENTS.md restorable as before. Listing them adds _NOTE_NAMES, a second tree walk and the Restored notes: lines. The hold-back fixes the defect without any of this.
    Subtraction: delete _NOTE_NAMES, the notes return value of _hold_back_agent_config and the held.get("notes") print loop in _report_held_back.

What this change ships

Inventory (7 items) — 6 justified

Intent: restoring someone else's snapshot can't turn on permissions, hooks or MCP servers for this install's next agent session. FIX.

  1. CLI restore (Replace and Merge) no longer installs the archive's .claude/, .mcp.json, .kiro/ and the other harness config names, at any depth under workspace/ — justified
  2. Replace keeps the live copies of those files instead of losing them — justified
  3. Restore summary lists each held path and says whether a current copy was kept — justified
  4. Restore summary prints Restored notes: for each CLAUDE.md/AGENTS.md it installed — rides along, oversized
  5. Dashboard zip import holds back the same names and adds a held_agent_config summary key — justified
  6. Workspace .kiro/skills from your own backup are no longer restored (declared as breaking) — justified
  7. One paragraph in the snapshot-and-restore docs — justified

[FIRST-PRINCIPLES-REVIEWED] 662449b

Description read

[DESCRIPTION-READ] c3193d2c3865f871131a619ab859066513af27ee96b5d2580b9cd57ad4e1cc6e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 662449b83003d26d5c798967288052164274d20c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the hold-back runs once on the staged bundle, before either mode reads it, and covers both writers (CLI restore and dashboard import). The take-away is declared as Breaking: and accepted.

Notes

  • A restore of your own backup onto a fresh home deletes the held config from the staged copy. That includes product-written crewmate skills under workspace/.kiro/skills and steering. The user is then told to copy these back from the archive by hand. Moving them aside into a reviewable folder would keep the safety and drop the manual step.
  • .codex, .goose and .goosehints have no reader in this tree. The drift test only pins PROJECT_ALLOW_STORES, so the list's hand-added names won't be caught if they go stale.

[DESIGN-REVIEWED] 662449b

Description read

[DESCRIPTION-READ] 83f7f6422247a8d78a7b3c33c76f344abb2fb54fcf447d48225d508b6022443c

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 9212053bcb5c8a1512f19873f3f56893b12df81f and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9212053

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9212053bcb5c8a1512f19873f3f56893b12df81f false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 662449b83003d26d5c798967288052164274d20c — this comment is updated in place on each push.

Review details

No findings.

Notes:

  • Candidate 1 (Copilot/Antigravity names): acp/harness/copilot.py:_project_config_in already refuses a Copilot session when .github/hooks, .github/copilot, .mcp.json or similar files are present. So restoring those files does not let them steer a session. Asking for more names on top of that would widen the fence, not fix a defect.
  • The dashboard import throws away the _notes list, while snapshot-and-restore.md says the result names each note it installed. Notes restored the same way before this change, so nothing regressed.

[OPUS-REVIEWED] 662449b

Verdict parsed from the review's SHA-scoped output markers for commit 662449b83003d26d5c798967288052164274d20c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 662449b83003d26d5c798967288052164274d20c false-positive: <reason, 20 to 500 characters>

@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from 407ffe9 to bc08210 Compare November 17, 2026 18:57
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 17, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from 56185e3 to adc85aa Compare November 17, 2026 21:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 17, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from adc85aa to cecccb6 Compare November 17, 2026 22:54
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 17, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

GPT 6.1 finding at 8fcd28a (src/kiro_crew/crew_mode.py:603, session-list decision): not caused by this PR.

  • This PR changes 7 files (snapshot.py, portability.py, one docs file, four test files); src/kiro_crew/crew_mode.py is not among them, and git diff origin/main..HEAD -- src/kiro_crew/crew_mode.py is empty.
  • The hiding line at crew_mode.py:603 is already on main, so it is pre-existing. The review's own adjudication reaches the same reading (empty diff against the base, the superseding decision entry already merged on main).
  • Nothing here reverses a recorded decision: this PR only changes which agent-config files a snapshot restore or dashboard import installs.

So no code change is made here. The block is a security-fenced finding on code this PR does not touch; it needs a repository writer's override, not a fix in this PR.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 18, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override gpt 8fcd28a pre-existing: Finding is in src/kiro_crew/crew_mode.py:603, which this PR does not change (diff: snapshot.py, portability.py, docs, tests). Pre-existing code outside scope; answered in #38689 (comment)

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 recorded a pre-existing release (class pre-existing) for the gpt AI finding on 8fcd28a063686f7f510b2f6a5d1728343bfbddcc.

Finding is in src/kiro_crew/crew_mode.py:603, which this PR does not change (diff: snapshot.py, portability.py, docs, tests). Pre-existing code outside scope; answered in #38689 (comment)

This decision applies only to this commit. A new push requires a new judgment.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: GPT 6.1. Re-run the lane's latest workflow run for 8fcd28a063686f7f510b2f6a5d1728343bfbddcc manually from the Actions tab.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from 8fcd28a to 0215486 Compare November 18, 2026 15:26
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from 0215486 to 730d161 Compare November 18, 2026 18:41
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch 2 times, most recently from 20731d6 to e47eaf0 Compare November 18, 2026 19:45
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from e47eaf0 to 3573cd0 Compare November 18, 2026 21:14
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 18, 2026
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from 3573cd0 to 56d320c Compare November 18, 2026 22:30
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Nov 18, 2026
Red first. Restoring the workspace component, in Replace or Merge, currently
installs the archive's agent config (.claude/, .mcp.json, .kiro/, .pi/ and the
other harness names), in workspace/ and in its project folders at any depth,
over or beside the live ones, so an archive can set permissions, hooks and MCP
servers for the next agent session started there. One row per name, at depth 0,
1 and 2, plus the notes the summary must name. The dashboard zip import
(apply_import_zip) is driven in both modes too.
Restore now removes every harness's project config (.claude/, .mcp.json,
.kiro/, .codex/, .goose/, .goosehints, .opencode/, opencode.json(c), .pi/,
.mimocode/, mimocode.json(c)), at any depth under workspace/, from the staged
bundle, in Replace and Merge. Replace stages this install's own copy in their
place, so the whole-tree swap keeps it. The result names what was left out.
CLAUDE.md and AGENTS.md stay restorable, and the result names each one it
installed. The dashboard zip import runs the same hold-back before either mode
and reports held_agent_config in its summary. The new code is declared in the
link-screen and snapshot ownership registries.
@chenmingwei23
chenmingwei23 force-pushed the mkt-pkg/fix-restore-agent-config branch from 56d320c to ec1c57d Compare November 18, 2026 23:36
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 19, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 22, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 22, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant