Stabilize default backup root across sandbox and permission contexts

[gaoguobin]

Problem

list-backups can resolve a different default �ackup_root than �ackup, depending on the current process sandbox or permission view of ~/Documents.

Observed on Ubuntu/Linux:

�ash agent-environment-backup --profile codex list-backups --backup-root /home/cedric/Documents/CodexBackups

This works and lists the latest backup, including:

ext codex-backup-20260520-141125 status=ok

But without an explicit backup root:

�ash agent-environment-backup --profile codex list-backups

It resolves:

ext backup_root: /home/cedric/CodexBackups backups: []

The actual backup was written to:

ext /home/cedric/Documents/CodexBackups

So a user can successfully create a backup and then immediately get an empty list from the natural-language/default workflow, depending on sandbox or permissions.

Expected behavior

The default �ackup_root used by �ackup, list-backups, and
estore should be stable for the same profile and user environment.

A backup created with defaults should be discoverable by list-backups with defaults.

Suggested fixes

• Make default �ackup_root deterministic and independent of transient write checks where possible.
• If fallback behavior is kept, add a discoverability mechanism so list-backups checks both the primary default and known fallback/default roots.
• Consider recording the last successful backup root in local tool state or deriving it from existing backup roots safely.
• Ensure
  estore default behavior is consistent with �ackup and list-backups.

Documentation follow-up

UPDATE.md and/or the Agent Skill docs should mention that sandbox validation should use the same explicit --backup-root for �ackup, list-backups, and
estore until the default-root behavior is stable. This avoids users misreading an empty fallback directory as no backups.

Safety notes

This should not change backup contents, restore overwrite rules, credential handling, ACL handling, or .sandbox-secrets behavior.

[gaoguobin]

@codex investigate this issue and open a pull request with a fix.

[chatgpt-codex-connector]

Summary

• Implemented a deterministic default backup root policy by removing writability-based fallback checks for ~/Documents; fallback now only occurs when ~/Documents exists but is not a directory. This prevents sandbox/permission-context drift across commands. src/agent_environment_backup/core.pyL102-L109
• Added multi-root implicit discovery for list-backups (primary default + legacy fallback), with manifest deduplication and an explicit discovery_roots field when default discovery is used. This makes backups created under older/fallback roots still discoverable by default workflows. src/agent_environment_backup/core.pyL113-L120 src/agent_environment_backup/core.pyL1939-L1973
• Added regression tests for:
  • deterministic default-root behavior even when writability checks would fail, and
  • fallback-root discovery during default list-backups. tests/test_core.pyL685-L727
• Updated user documentation to reflect the adjusted fallback condition (not a directory). README.mdL227-L228
• Added operational validation notes in both Codex and Claude skill docs recommending a consistent explicit --backup-root across backup, list-backups, and restore when validating across sandbox/permission boundaries. skills/codex-environment-backup/SKILL.mdL147-L147 skills/claude-code-environment-backup/SKILL.mdL146-L146

Testing

• ✅ python -m pytest tests/test_core.py -k "default_backup_root or list_backups_discovers_legacy_home_fallback_root"
• ✅ python -m pytest tests/test_docs.py
• ❌ python -m pytest tests/test_docs.py -k "CodexBackups or restore-environment" (no tests matched this -k filter; exited with code 5, then ran full tests/test_docs.py successfully)

View task →

[gaoguobin]

#7 #8