Repository navigation
fix(installer): a symlinked instructions or config file is written through, not replaced - #2768
Merged
Merged
Conversation
…rough, not replaced
Root cause: every installer write goes through one helper that writes
`<path>.tmp.<pid>` and renames it onto the path. A rename replaces a
symbolic link itself, not the file it points to. So a `~/.codex/AGENTS.md`
or `~/.claude.json` linked from a dotfiles repo became a detached regular
copy on install: the shared file never got CodeGraph's settings, and later
edits to it no longer reached the agent. This held for every target (Claude
Code, Codex, opencode, Cursor, Gemini, Antigravity, Kiro, Hermes and the
Copilot family) and for install, the refresh that `codegraph upgrade` runs,
and uninstall. Uninstall also deleted a link whose file it had emptied,
leaving CodeGraph's entry behind in the shared file.
Fix:
- The write helper resolves a link to the file at the end of its chain and
writes and renames there, so the link stays exactly as it was, relative
or absolute.
- A link to a file that doesn't exist yet gets that file created, but only
in a folder that already exists, as writing through it in a shell would.
No folder is ever created where a link points.
- A dangling chain is followed hop by hop from the real folder holding each
link, so a relative link under a linked folder lands where the OS would
put it.
- When the linked file can't be written (a read-only file, a folder that
doesn't exist), the error names the link and its target and nothing
changes.
- Where uninstall used to delete a user's file it had emptied (an
instructions file, Codex's config.toml, Copilot CLI's mcp-config.json,
the legacy project .claude.json), a link is kept and the emptied content
is written through it.
- The refresh sweep catches a failure per agent, reports it, still
refreshes the others, and exits non-zero, so the upgrade warns.
Decided: links to CodeGraph's own legacy files (Cursor's codegraph.mdc,
Kiro's steering doc), which install only ever deletes, are still removed.
Validation:
- 28 new tests. 25 are in installer-targets.test.ts:
- every target and location: install and uninstall keep each of its
files that is a link (18 cases);
- the shared files' content through install and uninstall for Claude
Code, Codex, opencode (two agents sharing one AGENTS.md) and Cursor;
- relative links under a linked folder;
- a link into a missing folder;
- a link to a read-only file;
- uninstall emptying through links;
- a failing link in a refresh;
- a folder link guard.
The other 3:
- 1 in upgrade.test.ts, where the refresh runs the built CLI;
- 2 in a new installer-links-simulated.test.ts, which simulates the
link with spied lstat/realpath/readlink, so it runs on machines that
can't create file symlinks.
With main's sources put back, 27 fail; the folder-link guard passes on
both. All pass with the fix. The real-link tests are skipped, with the
reason in their names, where file symlinks can't be created (Windows
without Developer Mode or admin).
- This Windows machine has Developer Mode on, so the real-link tests ran
for real.
- The real CLI against a private home (`install --yes`, `install
--refresh`, `uninstall --yes --keep-cli`), 10 linked files for five
agents plus relative, dangling and read-only links:
- on main, all 29 link checks found the link replaced by a copy;
- with the fix, none did, every link's text was unchanged, the shared
files got CodeGraph's settings and lost them again on uninstall, and
the missing-folder and read-only cases exited 1 with the new message
and changed nothing.
Fixes #2721
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2 tasks done
Dankosik
added a commit
to Dankosik/agent-ready
that referenced
this pull request
Nov 5, 2026
…ed agents (#38) ## Problem An audit with the real `codegraph` 1.6.2 and `rtk` in an isolated `HOME` found four bugs that the fake tools in `test-install.sh` could not show: 1. `codegraph install` writes a config by renaming a new file over it, which replaces a dotfiles symlink with a plain copy. `rtk` 1.0.1 does the same to `~/.gemini/settings.json`. 2. Automatic detection misses Devin Desktop when only `devin-desktop` or `Devin.app` is present and `~/.devin` does not exist yet. 3. `any_enabled` accepts only `1` and `true`. OpenCode and Kilo read their disable flags as Effect booleans, which also accept `yes`, `on`, and `y`. 4. Automatic detection misses Antigravity when it has only `~/.gemini/config`. ## User impact - **Symlinks:** the file in the dotfiles stops reaching the agent. The block ends up in both places, and `uninstall` removes it only from the copy. - **Devin Desktop and Antigravity:** an automatic install skips the agent without saying so. - **Flags:** with `KILO_DISABLE_CLAUDE_CODE=yes`, or the OpenCode equivalent on 1.x, the block goes to a `CLAUDE.md` the agent skips, so the agent never reads it. ## Diff scope - `install.sh`: - `remember_links` records symlinks in the agents' directories and `~/.claude.json` before `rtk` and `codegraph` run. - `restore_links` moves the new content to each link's target and puts the link back, after `codegraph` and from the `EXIT` trap when a later step stops the run. A read-only target is refused with a message and a non-zero exit. - `detect_windsurf` and `detect_antigravity` gain the new signs, and `any_enabled` gains `yes`, `on`, and `y`. - `test-install.sh`: regressions for all four. The fake `codegraph` and `rtk` here rename over the path, as the real ones do. - `README.md`: detection wording, and the symlink behaviour, including the affected codegraph versions and that running them by hand has no such protection. ## Validation Run on macOS against the tree of the branch head: | Check | Result | |---|---| | `bash -n`, `shellcheck`, `actionlint` | pass | | `gitleaks dir`, `gitleaks git` | pass | | `./test-install.sh` | pass | | `./verify.sh` | 16 held, 0 failed, 2 skipped (`osv-scanner` and `timeout` not installed on this machine) | | `./languages/go/verify.sh` | pass with the real `gopls`; it fails through a local wrapper that prints nothing outside a Go module | | `brew bundle check` (both Brewfiles) | **fails on this machine**: formulas missing or outdated, the same as before this change | | `git diff --check` | pass | Each new regression failed on the previous code for the intended reason, then passed after the fix. The real `codegraph` 1.6.2 and `rtk` 1.0.1 were also run in a sandboxed temporary `HOME`, with writes to the real home denied: - all 14 checked configs stayed symlinks; - the block and CodeGraph's section landed in the dotfiles; - a second run changed nothing; - `uninstall` left no block in the dotfiles and kept user data; - one file shared by four agents got one block and one section. **Not verified:** - Linux and WSL2, which CI covers. - `rtk` 1.1.0, because the lab ran 1.0.1. - The `Devin.app` branch, because `/Applications` cannot be redirected in a test. - An agent actually loading the block in a live session. **Known limits:** symlinks already replaced by an earlier install are not restored. `rtk` sets `settings.json` to mode 600, for plain files too; this change leaves that alone. The symlink bug's root cause is upstream: it was reported as colbymchenry/codegraph#2721 and fixed on their `main` by colbymchenry/codegraph#2768, but the latest release, v1.6.2, predates that fix and still reproduces it. This workaround stays needed until installs move past v1.6.2, and it does nothing when the link is already intact. It also covers `rtk`, which that fix does not touch. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When an agent's instructions or config file is a symbolic link, for example
~/.codex/AGENTS.md -> ~/dotfiles/AGENTS.mdor a linked~/.claude.json,codegraph installreplaced the link with a regular copy. The shared file never got CodeGraph's settings, later edits to it stopped reaching the agent, and nothing was reported. Install, the refresh thatcodegraph upgraderuns, and uninstall now write through the link: the shared file gets the change, and the link stays exactly as it was.Root cause
Every installer write goes through
atomicWriteFileSync(src/installer/targets/shared.ts). It writes<path>.tmp.<pid>and callsrenameSynconto the path, and a rename replaces the link itself. All of these go through it: the JSON and JSONC writers, Codex's TOML and the marker-fenced instructions block. So every target was affected: Claude Code, Codex, opencode, Cursor, Gemini, Antigravity, Kiro, Hermes, Copilot CLI, VS Code and JetBrains.Uninstall had a second problem. Where it deletes a file it has emptied (an instructions file holding only the block, Codex's
config.toml, Copilot CLI'smcp-config.json, the legacy project.claude.json), it deleted the link and left CodeGraph's entry in the shared file.Fix
atomicWriteFileSyncresolves the file at the end of the chain (realpath) and writes the temp file next to it and renames it there. The link is never touched, so relative link text stays relative. The atomic write-then-rename is kept, and nothing changes for regular files.echo > linkwould in a shell. No folder is ever created where a link points: pre-creating, say, a not-yet-cloned~/dotfiles/would break the latergit clone. The chain is followed hop by hop, each hop from the real folder holding the link, so a relative link under a linked folder lands where the OS would put it. A loop is reported (ELOOP).removeFileUnlessLinkedwrites the emptied content ('', or{}for JSON) through a link instead of deleting it.refreshTargetscatches a failure per target and reports it (status: 'failed',error). The others are still refreshed.install --refreshprints<agent>: could not refresh — <reason>and exits 1, socodegraph upgradeshows its usual warning. Before this, any write error ended the whole sweep with an unhandled rejection..cursor/rules/codegraph.mdcand Kiro's steering doc, are still removed when present. Install creates neither file and only ever deletes them.Validation
Windows symlink rights: this machine has Developer Mode on (
AllowDevelopmentWithoutDevLicense=1), so file symlinks, relative symlinks, directory symlinks and junctions can all be created without admin. The real-link tests ran for real here.Tests: 28 new.
__tests__/installer-targets.test.ts:describePathsthat is a link;unchanged) and uninstall for Claude Code, Codex, opencode and Cursor, with two agents sharing oneAGENTS.md;__tests__/upgrade.test.ts:runUpgrade, whose refresh runs the built CLI, warns, keeps the link and still refreshes Gemini.__tests__/installer-links-simulated.test.ts: the link is simulated with spiedlstat/realpath/readlink, so the write-target logic is also covered on machines that can't create file symlinks.describe.skipIf/it.skipIf, with the reason in the name ("creating a file symlink needs Developer Mode or admin rights on Windows").Real CLI on this Windows machine, private temp HOME:
install --yes,install --refreshanduninstall --yes --keep-clifor five agents. The run covered 10 linked files (~/.claude.json,.claude/settings.json,CLAUDE.md, Codexconfig.toml+AGENTS.md, opencodeopencode.jsonc+ the sameAGENTS.md,~/.cursor/mcp.json, Geminisettings.json+GEMINI.md), plus relative, dangling and read-only links.The same message from
install --refresh:✗ Codex CLI: could not refresh — …\.codex\AGENTS.md is a symbolic link to …\dotfiles-not-cloned\AGENTS.md, which can't be written (its folder does not exist). CodeGraph writes through links and never replaces one with a copy: fix the link or make its file writable, then run this again.Refresh isolation, real CLI: with Codex's (regular)
AGENTS.mdgiven the read-only attribute and Gemini's block stale,install --refreshbehaves as follows.[CodeGraph] Unhandled rejection: Error: EPERM …, exit 1, and Gemini is not refreshed.Codex CLI: could not refresh — EPERM …, Gemini refreshed, exit 1.tsc clean; the test files add no type errors (48 before and after, all pre-existing).
Full suite on this commit (847f01b, native kernel built,
CODEGRAPH_KERNEL_EXPECT=1 npx vitest run --maxWorkers=4 --minWorkers=1, Windows 11 with Developer Mode): 702 files (696 passed, 6 skipped), 8429 tests: 8347 passed, 0 failed, 82 skipped. That is 28 more tests than on main, with the same 82 skipped, so every new test ran. No reruns needed.Contributor PR #2747 (@danusha2345) was read for guidance; its resolve-before-rename approach is the same idea. This PR adds:
Left out, and why
0600) across the temp-file rename would be a separate small change.Fixes #2721
🤖 Generated with Claude Code