Repository navigation
fix(members): read member sources on a home reached through a symlink - #16263
Conversation
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.
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every new test skips on Windows ( What this change shipsInventory (6 items) — 6 justifiedIntent: FIX (issue #16255) — member turns work on a home reached through a symlink, and an unreadable implicit project guide no longer blocks every session start.
Both halves trace to the linked issue; 17 tests fail with the fix reverted. The memory fix sits at cause level (lexical expectation vs. real-path witness), and the only other realpath-vs-abspath comparison in the tree ( [FIRST-PRINCIPLES-REVIEWED] 50e3941 Description read[DESCRIPTION-READ] 8c843b84d90fc6f355f5c8015760aad7c24266b523a848a22be3def6033f050e That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] 50e3941 Description read[DESCRIPTION-READ] 84666970c1be3e327bcd4bb9283958e322a71b8dde99fa68f8a56854dad70899 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 |
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: 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.
LocalMemoryFiles._read_entry_bytes(memory_files.py) 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
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/main), agent-sdk boundary, docs-lint. The 108 essential/memory/context/steering test files: 4525 passed, 30 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