Repository navigation
fix(members): read member sources on a home reached through a symlink (release/0.8.0) - #16265
Conversation
… (release/0.8.0) Two member-turn readers refused ordinary files on hosts whose home is a symlink (/home/<user> -> /local/home/<user>). The V2 memory reader compared the opened descriptor's real path with the requested path's lexical spelling, so every manual profile under a link-spelled home looked relocated: "Memory read refused (Opened manual profile file is outside its expected bound path)". It now resolves only the memory root's own spelling and keeps the part below the root lexical, so a leaf link, a hard link and any directory link below the root (one that stays inside included) are still refused. The essential-context reader fed the project root's implicit AGENTS.md and SOUL.md through the same fail-closed path as declared sources, so a guide that was a dangling link, a hard link, or a link to a file outside the project aborted every session start of the agent. Those two guides now go through the same reader, but a refusal leaves the guide unread, logs a warning and adds an in-band "#omitted" note instead of failing the turn. A template that declares the file still refuses, and an oversized guide still raises.
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the backport's semantics match merged #16263 — the reader lives in [DESIGN-REVIEWED] 9a7a3e9 |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify backport parity with #16263: this branch re-targets the memory fix onto What this change shipsInventory (7 items) — 7 justifiedIntent: FIX — member turns work on a symlink-spelled home, and an unreadable implicit project guide no longer stops every session from starting (issue #16255, backport of #16263).
Consumer/duplication checks run: [FIRST-PRINCIPLES-REVIEWED] 9a7a3e9 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Problem / Motivation
Goal: (release/0.8.0 backport of #16263) Member turns work on a host whose home directory is reached through a symlink, and an unreadable project
AGENTS.mdno longer stops every session of an agent from starting.Memory read refused (Opened manual profile file is outside its expected bound path).Essential source <workspace>/AGENTS.md: missing, unreadable, or outside the admitted document rootwhen that file is a dangling link, a hard link, or a link to a file outside the project.Why it matters
/home/<user>linking to/local/home/<user>is the standard layout on managed Linux desktops, so (1) hits every V2 member there. (2) blocks the agent entirely until the user finds and removes the link: no session starts.Not a goal
What changed (motivation → approach → change)
Memory read.
MemoryStore._read_entry_bytes(memory.pyon this branch; the reader moved tomemory_files.pyon main) checkedfd_real_path(descriptor), a real path, againstos.path.abspath(path), a lexical one. Under a link-spelled home those never match, so every file looked relocated. The containment check on the next line already usedrealpath. New_expected_opened_pathresolves only the memory root's own spelling (configuration the root guard has already screened). The part of the path below the root stays lexical. So:O_NOFOLLOWplus the existing lstat pre-check), a hard link, a directory link that leaves the store, and a directory link that stays inside the store are still refused, because each still disagrees with the opened path or with the root.Resolving the whole requested path would have admitted the last case. The tests include a mutation for it.
Implicit project guides.
documents_for_memberreads the project root'sAGENTS.md/SOUL.mdbecause they exist, not because the template declares them. It sent them through the same fail-closedaddas declared sources, so one refusal aborted the turn. They now go through_read_implicit_guide, which uses the same_read(containment against the resolved project root, managed-state isolation, no-follow descriptor read), so nothing that_readrefuses gets read. On refusal it logs a warning and adds an in-band<path>#omittednote that names the guide and tells the agent not to assume its contents, instead of raising. A link that resolves inside the project still loads, in any spelling. Declared sources andFileTooLargeErrorare unchanged.Spec:
docs/system-specs/modules/memory-skills-hooks.md(both behaviours).Backwards compatibility
Compatible: both changes only admit reads that used to fail (memory under a symlinked home) or turn a fatal refusal into a non-fatal omission (implicit guides). Everything refused before is still not read.
Removes nothing: no path, key, record or capability is hidden or removed. The only change to an error path is that an implicit guide refusal no longer fails the turn.
Tests
Same test file as #16263, with the memory half driving
MemoryStore(this branch predates theMemoryFilesseam).test/test_symlinked_home_member_sources.py(25 tests, POSIX, home =<tmp>/home/u-><tmp>/local/home/u):test_member_memory_reads_through_a_symlinked_home: anchor and dated history read under the link-spelled home.test_member_memory_still_refuses_a_link_under_a_symlinked_home: an escaping directory link, an in-store directory link, a leaf link and a hard link are each refused by_read_entry_bytes, read as empty, and raise withrequire_readable.test_workspace_guide_linked_inside_the_workspace_is_read: project in link and real spelling x link target relative, link-spelled or real-spelled; all load and none are omitted.test_unreadable_workspace_guide_is_omitted_not_fatal:AGENTS.mdandSOUL.md, each as a repo link outside the project, a dangling link, a link into managed memory, and a hard link. The turn proceeds, exactly one#omittednote appears, and no target content leaks.test_declared_resource_linked_outside_still_refuses: the same escaping link declared asfile://AGENTS.mdstill raises.With the fix reverted and the tests kept, 17 fail. Mutation (full
realpath(path)as the expectation): the in-store directory-link case fails.Local gates: black 26.3.1, isort, flake8, mypy (touched modules), comment-history (base origin/release/0.8.0). Essential/memory/context/steering test files on this branch: 4250 passed, 28 skipped.
Manual verification
N/A: the unit tests run the real readers against a real symlinked-home tree, which is the exact shape reported.
Related Issues
Fixes #16255
Pattern harvest
Rule candidate: review-prompt
Pattern: comparing an
fd_real_path/realpathresult with anabspathspelling of the same path. Resolve the trusted root on both sides, not just one.Checklist