Skip to content

fix(members): read member sources on a home reached through a symlink (release/0.8.0) - #16265

Merged
bolichen97 merged 1 commit into
release/0.8.0from
backport/0.8.0-symlink-home-paths
Oct 2, 2026
Merged

bolichen97 merged 1 commit into
release/0.8.0from
backport/0.8.0-symlink-home-paths

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

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.md no longer stops every session of an agent from starting.

  • Member memory reads are refused on a symlinked home: Memory read refused (Opened manual profile file is outside its expected bound path).
  • Every session with an agent that inherits default resources fails to start with Essential source <workspace>/AGENTS.md: missing, unreadable, or outside the admitted document root when 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

  • Admitting links that point outside the project (fix: admit approved global steering symlinks #14007 handles approved global-steering links behind an opt-in policy; this PR does not change that area).
  • Changing how declared template resources fail: they still fail closed.
  • Changing the oversize limit for essential sources.

What changed (motivation → approach → change)

Memory read. MemoryStore._read_entry_bytes (memory.py on this branch; the reader moved to memory_files.py on main) checked fd_real_path(descriptor), a real path, against os.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 used realpath. New _expected_opened_path resolves 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:

  • a store under a symlinked home reads normally;
  • a leaf link (O_NOFOLLOW plus 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_member reads the project root's AGENTS.md / SOUL.md because they exist, not because the template declares them. It sent them through the same fail-closed add as 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 _read refuses gets read. On refusal it logs a warning and adds an in-band <path>#omitted note 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 and FileTooLargeError are 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 the MemoryFiles seam). 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 with require_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.md and SOUL.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 #omitted note appears, and no target content leaks.
  • test_declared_resource_linked_outside_still_refuses: the same escaping link declared as file://AGENTS.md still 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/realpath result with an abspath spelling of the same path. Resolve the trusted root on both sides, not just one.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

… (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.
@bolichen97
bolichen97 requested a review from a team as a code owner October 2, 2026 21:21
@bolichen97
bolichen97 requested review from iamwhatever and removed request for a team October 2, 2026 21:21
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 2, 2026
@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 9a7a3e949ee29d2804ad27efdeb9386029aa0680 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the backport's semantics match merged #16263 — the reader lives in memory.py here, not main's memory_files.py seam.

[DESIGN-REVIEWED] 9a7a3e9

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 9a7a3e949ee29d2804ad27efdeb9386029aa0680 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify backport parity with #16263: this branch re-targets the memory fix onto MemoryStore._read_entry_bytes because main's memory_files.py seam does not exist here.

What this change ships

Inventory (7 items) — 7 justified

Intent: 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).

  1. Member memory reads succeed under a home reached through a symlink — justified
  2. A session with an unreadable implicit AGENTS.md/SOUL.md now starts instead of failing — justified
  3. An in-band <path>#omitted note names the refused guide so the agent does not assume its contents — justified
  4. A warning is logged when an implicit guide is refused — justified
  5. Every link below the memory root (escaping, in-store alias, leaf, hard link) is still refused — justified
  6. Spec section updated for both behaviours in the same commit — justified
  7. New POSIX test file pinning both the admitted layout and the escaping ones — justified

Consumer/duplication checks run: _expected_opened_path, _read_implicit_guide, _omitted_guide each have exactly one caller (private helpers, not surface); grep of all fd_real_path comparison sites (mcp_cron.py:1424, workflows/store.py:231, transcribe.py:1103, hooks.py witnesses) found zero unfixed siblings of the abspath-vs-realpath mismatch; pinned_fs.open_fenced_for_read has a different contract (fence re-ask on mismatch) and would admit the in-store directory-link case this PR deliberately refuses, so no existing mechanism does this job.

[FIRST-PRINCIPLES-REVIEWED] 9a7a3e9

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 9a7a3e949ee29d2804ad27efdeb9386029aa0680 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9a7a3e9

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9a7a3e949ee29d2804ad27efdeb9386029aa0680: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 9a7a3e949ee29d2804ad27efdeb9386029aa0680 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9a7a3e9

Verdict parsed from the review's SHA-scoped output markers for commit 9a7a3e949ee29d2804ad27efdeb9386029aa0680.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9a7a3e949ee29d2804ad27efdeb9386029aa0680: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 2, 2026
@bolichen97
bolichen97 merged commit f7ffeed into release/0.8.0 Oct 2, 2026
22 checks passed
@bolichen97
bolichen97 deleted the backport/0.8.0-symlink-home-paths branch October 2, 2026 21:43
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant