fix(api): resolve zip-namespace collisions when merging drive mounts

[ardaerzin]

Context

"Download all" in the Files drawer produced a zip missing the agent-files content (#5482).

The archive merges several mounts into ONE zip: the session cwd at the root, and the artifact's agent mount folded in under agent-files/. A zip carries no directory entries — a member a/b implies the directory a — so a member that is a FILE named a blocks that directory and everything under a/ is lost on extraction. An object store holds a and a/b side by side happily, so the merged namespace can contain a pair a zip cannot represent.

That is the shape of this bug. The runner symlinks the agent mount into the cwd as agent-files/; geesefs degrades that symlink to a plain object named agent-files in the cwd store ("geesefs silently degrades symlinks to empty files across remounts"). Archived as a file, it shadowed the agent-files/ directory the agent-mount source contributes, and the agent's files never landed.

Changes

• build_archive_work_list runs the merged work list through a new _resolve_zip_namespace: a member shadowed by a directory is dropped, and a duplicate path keeps the first source. This fixes the bug by the invariant rather than by name — whatever the degraded object is called and whatever its size — and closes the whole collision class, which is reachable across sources for any pair of mounts.
• The degraded link is also skipped up front, scoped to the cwd mount root — the one path the runner reserves (it unlinks whatever else sits there on every attach). A real agent-files file anywhere else, including at the agent mount's own root (presented as agent-files/agent-files), still ships. Without this, an empty agent mount would leave the marker in the zip as a phantom file the drive itself hides.

Before (zip entries): agent-files (degraded object), agent-files/plan.md, … → a file-vs-directory collision.
After: agent-files/plan.md, … — the shadowing member is dropped.

Tests

TestArchiveZipNamespace, against the in-memory fake store, models the real two-source shape (cwd mount + folded agent mount) rather than one synthetic mount:

• the degraded link does not block the folded mount (the reported bug) — passes under either rule alone, so the fix survives a cwd mount the identity check doesn't recognize;
• the link is still dropped when the agent mount is empty (only the cwd-root rule can catch it);
• agent-files is not a reserved name outside the cwd root (docs/agent-files and the agent mount's own agent-files both ship);
• a file shadowing a directory is dropped whatever its name (report vs report/q1.csv);
• a duplicate zip path keeps the first source.

Each rule is independently covered: disabling either one fails only its own tests. Full api unit suite green (1475 passed). ruff format + ruff check clean.

What to QA

• On a session with agent files, open the Files drawer and "Download all". Unzip: the agent-files/ folder and its files are present.
• Regression: a normal cwd file archive still contains all files, and nested folders still extract.
• A session whose agent folder is empty: the zip has no stray agent-files entry.

Fixes #5482

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 29, 2026 3:25pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: f33292c9-cd9c-4676-a126-666c625c12a4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Archive generation now filters the degraded session agent-files marker and normalizes merged mount entries to remove file-directory conflicts and duplicate ZIP paths. Unit tests cover marker handling, root-only reservation, directory precedence, and deterministic duplicate retention.

Changes

Archive namespace handling

Layer / File(s)	Summary
Normalize archive member paths api/oss/src/core/mounts/service.py	Identifies the session cwd mount, excludes its degraded root agent-files marker, and resolves file-directory conflicts and duplicate ZIP paths across archive sources.
Validate namespace rules api/oss/tests/pytest/unit/test_mounts_file_ops.py	Adds multi-mount test helpers and verifies marker filtering, preservation of user content, directory precedence, and first-entry retention for duplicate paths.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• Agenta-AI/agenta#5411: Also changes archive work-list generation in MountsService and relates to ZIP namespace handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title accurately summarizes the main change: fixing archive zip namespace collisions when merging drive mounts.
Description check	✅ Passed	The description is directly about the archive bug and the fix, with relevant context, implementation details, and tests.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch api-fix/drive-download-agent-files

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ffc47d5-da40-47d3-8b1c-0b958a0b9a5a

📥 Commits

Reviewing files that changed from the base of the PR and between a3e7fdf and 99d7026.

📒 Files selected for processing (2)

• api/oss/src/core/mounts/service.py
• api/oss/tests/pytest/unit/test_mounts_file_ops.py

[github-actions]

Railway Preview Environment

Preview URL	https://gateway-production-b9f1.up.railway.app/w
Project	agenta-oss-pr-5524
Image tag	pr-5524-9f9ce40
Status	Deployed
Railway logs	Open logs
Workflow logs	View workflow run
Updated at 2026-07-29T15:39:33.399Z