Expand on os.Root coverage

[pjbgf]

https://entire.io/gh/entireio/cli/trails/1202

Follow-up to #2180. A second pass over the migrated tree found five places still
doing filesystem work outside an anchor, and the diagnostic that would surface the
condition they now refuse. This brings them onto the same footing as the rest of
the tree.

Pi's extension directory

agent/pi/hooks.go was the last registered agent whose hook-config surface had
not moved. It joined .pi/extensions/entire/index.ts onto the repo root and
handed the result to os.ReadFile / os.MkdirAll / os.WriteFile /
os.RemoveAll, each with a //nolint:gosec about where the path was built
rather than where it resolves — the justification agent.HookConfigFile's doc
comment already calls out as the one that says nothing useful. A working tree
arrives by clone, so .pi is a component the repository supplies, and every one
of those four calls resolved through it.

Routed through agent.OpenHookConfig, which the other eight agents already use:
the base is the worktree root, .pi/extensions/entire/index.ts is a name inside
it, and directories are created with MkdirAllNoSymlink so a symlinked compon
is refused by name instead of followed. .opencode/plugins/entire.ts is the
structurally identical case — embedded TS file, worktree-resident, marker-chec
— and was already on this path; pi is now the same shape rather than the exception
beside it. Worth noting for the next integration: pi is auto-detected
(DetectPresence stats .pi), so it reaches these operations without the user
naming it, which is the argument for routing a new agent through the anchor by
default rather than trusting review to notice.

Two supporting pieces:

• osroot.RemoveAllNoSymlinks. os.Root.RemoveAll refuses a descent that
  would leave the root and unlinks a symlinked leaf rather than following it, but
  it says nothing about the components above the leaf — which is where .pi
  sits. This pins the parent first, then removes a single named component. Same
  relationship OpenChild has to a bare Root.OpenRoot.
• HookConfigFile.RemoveDir. Pi discovers extensions by directory, so
  removing only the file leaves an empty .pi/extensions/entire for pi to find
  with nothing to load. Deliberately not general: every other agent writes into a
  directory the agent itself owns, where Remove of the file is the correct
  uninstall and taking the parent would delete the user's own config with it.
  Refuses the case where the directory to remove would be the worktree root.

agent.GeneratedHookFileState — the path-based drift check that predates the
rooted HookConfigFile.GeneratedState — had pi as its only caller and is
deleted, so there is no unrooted variant left to pick up.

Four sites beside it

• vercel.json (setup.go, vercelconfig). A working-tree file read wit
  os.Stat / os.ReadFile on a joined path. Now read through the worktree an
  as LoadIn(root, name), with a 1 MiB cap: the file arrives with the checkout, so
  its size is not ours to choose, and everything downstream of the parse collapses
  to a single bool. In-repo symlinks are still followed on purpose — pointing
  vercel.json at a monorepo's shared config is a real setup, and this file i
  user's rather than Entire's — while one leaving the worktree is refused, which is
  the property the anchor exists to give.
• worktreedir.Name. Given the VolumeName pairing SessionStore.Name got in
  57b275a, which ValidateSessionID and gitrepo's alternates checks already
  os.Root rejects a drive-relative name one layer down (filepathlite.IsLocal),
  so this changes no behaviour today; it is closed because Name exists to an
  "is this inside the worktree?" independently of its caller, and
  readWorktreeFileSafely feeds it paths that arrive from the API. It was the
  remaining IsAbs in a containment role without the pairing.
• The persistent-ref lock (checkpoint/persistent_ref_update.go). The las
  .git-resident lock still opening by path rather than through the common dir's
  root. Now mirrors shadowBranchLock: gitdir.OpenAt + MkdirAllNoSymlink +
  AcquireContextIn. Git will not check a path out into .git, so this is
  consistency and defence in depth — but openLockFileIn exists for exactly t
  and one caller sitting outside it is how the next one gets written that way
• readCapped (runner_gather.go). Bounds the read, not just the result.
  These are working-tree files named by convention (README.md, CLAUDE.md), so
  their size is not ours to assume, and the caller has already said how much of one
  it will use. Reading a gigabyte to keep its first 4 KB is a cost with no ret

doctor now reports symlinked agent directories

The condition these refusals produce was invisible after the fact. enable fa
loudly on it, but once a repo is enabled HookConfigFile.Exists() deliberately
reports a symlinked parent as absent — so entire status showed hooks missi
without saying why, and entire clean skipped the directory on the stated grounds
that doctor reports a symlinked agent directory. Nothing did.

checkAgentDirSymlinks runs beside checkEntireDirSymlinks and names the
outermost link, once per finding. Candidates come from the registry and the
scaffold templates rather than a list in the function. Unlike .entire, these
trees are largely the user's, so it examines only the components Entire itself
creates and writes through: `.claude/skills/my-own -> ../../shared/skills/my-o
is a real setup, and reporting it would train people to skip this section.

Follow-up

agentSymlinkCheckPaths derives from AllProtectedDirs() plus the skill
templates, not from the hook-config relPaths, so the two agents whose config nests
below their top-level directory have their Entire-created intermediate directories
unchecked — a symlink at .pi/extensions or .opencode/plugins produces no
doctor output. The refusals cover both; this is reporting only.

---

Note

Medium Risk
Touches hook install/uninstall and recursive delete paths where symlink mistakes could write or destroy files outside the repo; changes are defensive with new doctor reporting and tests, but they affect every agent’s enable flow.

Overview
This PR finishes os.Root / worktree anchoring for agent hook configuration and closes gaps where symlinked repo paths could still be followed or deleted outside the worktree.

Pi is migrated off raw os.ReadFile / MkdirAll / WriteFile / RemoveAll onto agent.HookConfigFile like the other agents. Uninstall uses new HookConfigFile.RemoveDir (backed by osroot.RemoveAllNoSymlinks) so the whole .pi/extensions/entire tree is removed without following a symlinked .pi. Path-based GeneratedHookFileState is removed; drift checks go through HookConfigFile.GeneratedState.

agent.HookConfigLocator (HookConfigRelPath) centralizes each agent’s config path for AllHookConfigRelPaths(), refactors all OpenHookConfig call sites, and powers a build guard ensuring every agent that opens a hook config declares its path.

entire doctor gains checkAgentDirSymlinks, listing symlinked or unreadable components on paths Entire creates (hook config paths from the locator plus skill scaffold parents), so “hooks missing” on status gets an explicit cause.

Additional hardening: persistent ref flock via gitdir + flock.AcquireContextIn; vercelconfig.LoadIn and setup’s Vercel probe through the worktree with a read cap; readCapped bounded reads; worktreedir.Name treats Windows drive-relative paths like other containment checks. Docs in CLAUDE.md are expanded for symlinked hook files/dirs and Pi auto-detection.

^{Reviewed by Cursor Bugbot for commit 98bdf18. Configure here.}

[pjbgf]

@cursor review

[Copilot]

Pull request overview

This PR continues the follow-up work from #2180 by expanding os.Root anchor coverage across the codebase, migrating remaining worktree / git-dir filesystem operations onto anchored helpers, and making symlink-refusal conditions visible via entire doctor—notably for agent hook/config directories (including auto-detected Pi).

Changes:

• Migrate Pi’s extension install/uninstall/read paths to agent.HookConfigFile (anchored worktree I/O), add HookConfigLocator, and add safe directory removal (RemoveDir, RemoveAllNoSymlinks).
• Anchor remaining filesystem call sites (Vercel config reads, persistent-ref lock files in git common dir, capped worktree file reads) and strengthen Windows path containment (worktreedir.Name).
• Extend doctor to diagnose symlinked agent config/scaffold paths (plus tests and guard coverage).

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
cmd/entire/cli/worktreedir/worktreedir.go	Strengthen Name containment on Windows by pairing IsAbs with VolumeName.
cmd/entire/cli/worktreedir/worktreedir_test.go	Add unit tests covering relative/absolute containment and drive-relative behavior.
cmd/entire/cli/vercelconfig/vercelconfig.go	Replace path-based read with LoadIn(*os.Root, name) plus a 1MiB read cap.
cmd/entire/cli/vercelconfig/vercelconfig_test.go	Add tests for missing/malformed/oversized configs and symlink behavior.
cmd/entire/cli/setup.go	Route Vercel presence checks and config reads through the worktree root.
cmd/entire/cli/runner_gather.go	Bound worktree file reads at the read layer (not just truncation of output).
cmd/entire/cli/osroot/osroot.go	Add RemoveAllNoSymlinks to refuse symlinked parent components during recursive deletes.
cmd/entire/cli/osroot/osroot_test.go	Add coverage for RemoveAllNoSymlinks behavior (real tree, missing, symlink parent/leaf).
cmd/entire/cli/doctor.go	Add checkAgentDirSymlinks and supporting helpers to report symlinked agent paths.
cmd/entire/cli/doctor_test.go	Add tests for new doctor diagnostics and candidate-path coverage/behavior.
cmd/entire/cli/checkpoint/persistent_ref_update.go	Move persistent-ref lock creation/acquire under gitdir root + AcquireContextIn.
cmd/entire/cli/checkpoint/persistent_ref_update_test.go	Update tests to use rooted lock acquisition.
cmd/entire/cli/agent/registry.go	Add AllHookConfigRelPaths to enumerate locator paths from the agent registry.
cmd/entire/cli/agent/pi/hooks.go	Migrate Pi to anchored hook-config operations; add HookConfigRelPath; remove unrooted drift checker usage.
cmd/entire/cli/agent/pi/hooks_test.go	Add tests pinning symlink refusal and directory-uninstall behavior for Pi.
cmd/entire/cli/agent/opencode/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent/hook_config_file.go	Add HookConfigLocator and HookConfigFile.RemoveDir for Pi’s directory-scoped uninstall.
cmd/entire/cli/agent/hook_command.go	Remove path-based GeneratedHookFileState; keep content-based drift helper.
cmd/entire/cli/agent/geminicli/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent/factoryaidroid/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent/cursor/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent/copilotcli/lifecycle.go	Add compile-time assertion for HookConfigLocator.
cmd/entire/cli/agent/copilotcli/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent/codex/lifecycle.go	Add compile-time assertion for HookConfigLocator.
cmd/entire/cli/agent/codex/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent/codex/hook_root.go	Use the declared HookConfigRelPath for worktree config resolution.
cmd/entire/cli/agent/claudecode/hooks.go	Implement HookConfigLocator and centralize rel-path declaration.
cmd/entire/cli/agent_hook_config_guard_test.go	Add a source-level guard test ensuring every OpenHookConfig user declares a locator path.
CLAUDE.md	Update architecture docs to reflect expanded anchored coverage and diagnostics.

Suppressed comments (1)

cmd/entire/cli/agent_hook_config_guard_test.go:38

• For the same reason as the rev-parse call above, git grep should also run with repo-override env vars scrubbed; otherwise it can search a different repository than grep.Dir points at when GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE are set.

	grep := exec.Command("git", "grep", "-l", "--fixed-strings", "--", //nolint:noctx // guard test, no cancellation needed
		"agent.OpenHookConfig(", "--", ":(glob)cmd/entire/cli/agent/**/*.go")
	grep.Dir = strings.TrimSpace(string(repoRoot))
	out, grepErr := grep.Output()
	require.NoError(t, grepErr, "no agent calls agent.OpenHookConfig, which cannot be right")

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[pjbgf]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 98bdf18. Configure here.}