Skip to content

fix(members): read member sources on a home reached through a symlink - #16263

Merged
bolichen97 merged 1 commit into
mainfrom
fix/symlink-home-paths
Oct 2, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/symlink-home-paths

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: 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. LocalMemoryFiles._read_entry_bytes (memory_files.py) 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

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/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/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

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:07
@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

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 50e39415d77066347cd4fb61c9530826287b6202 — 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

Every new test skips on Windows (os.name == "nt"), yet _expected_opened_path's drive-mismatch ValueError branch runs there — confirm existing Windows memory tests still cover that reader.

What this change ships

Inventory (6 items) — 6 justified

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

  1. Member memory reads now succeed when $HOME is a symlink — justified
  2. An unreadable implicit AGENTS.md/SOUL.md no longer aborts session start; the turn proceeds — justified
  3. A skipped guide is named by an in-band #omitted note telling the agent not to assume its contents — justified
  4. A warning is logged when a guide is skipped — justified
  5. The memory-skills-hooks spec is updated in the same commit — justified
  6. 25 new POSIX tests pin both the admitted layout and every refused link shape — justified

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 (transcribe.py:684) is a deliberate link refusal, not an unfixed sibling. The lens-9 valve holds: both items fix behaviour an issue already pins.

[FIRST-PRINCIPLES-REVIEWED] 50e3941

Description read

[DESCRIPTION-READ] 8c843b84d90fc6f355f5c8015760aad7c24266b523a848a22be3def6033f050e

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@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 50e39415d77066347cd4fb61c9530826287b6202 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 50e3941

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

@github-actions

github-actions Bot commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 50e39415d77066347cd4fb61c9530826287b6202 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 50e3941

Verdict parsed from the review's SHA-scoped output markers for commit 50e39415d77066347cd4fb61c9530826287b6202.

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

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.

Member memory reads and project AGENTS.md refused on a home reached through a symlink

1 participant