8000 feat(base): wire the memory loop in create-agent when a checkout is present (#21) by simon-inkie · Pull Request #67 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

feat(base): wire the memory loop in create-agent when a checkout is present (#21) - #67

Merged
simon-inkie merged 17 commits into
mainfrom
claude/dazzling-davinci-h66qwp-issue-21
Oct 16, 2026
Merged

simon-inkie merged 17 commits into
mainfrom
claude/dazzling-davinci-h66qwp-issue-21

Conversation

@simon-inkie
@simon-inkie simon-inkie commented Oct 14, 2026 •
Copy link
Copy Markdown
Owner

Refs #21 (M1 slice only, so this does not close the issue).

TL;DR

create-agent.sh can now wire the memory loop for a new agent. Given a built memory-layer checkout (MEMORY_LAYER_ROOT or --memory-root), it runs that checkout's own non-interactive install command against the agent's own .claude/settings.json (hooks) and seeds the agent's silo, then records USER_NAME in the settings env. Memory is wired on exit, after the verification probe, so the probe's own turn is not recorded as a first memory; a run interrupted by SIGINT, SIGTERM or SIGHUP wires nothing. With no checkout, an unbuilt one (hook scripts or tsx missing, checked before anything is written), --no-memory, or a failing install command, the last output line says memory off (reason), a warning explains why, and creation carries on with an unchanged exit code. INSTALL.md tier 3 gains an optional memory step (fenced sh-manual, since it needs a real checkout). SPEC: .specs/21-memory-loop-install/SPEC.md.

Live and wrong, up front

  • If the memory install command fails part way after the pre-checks pass, the agent is reported off although its settings may already hold the hooks. The warning says so; the command is idempotent, so re-running it repairs it.
  • Deck does not build the memory-layer checkout. It must already be built and installed, otherwise memory is reported off (not built: missing ...).

Note for the maintainer (leak gate and trailers)

The first two commits carry a Claude-Session: trailer, which the repo's private-session-link leak rule flags in pnpm check:leaks:messages (not part of the required check list). Later commits omit it. A squash merge should strip any Claude-Session lines from the message.

Verified interface (memory layer v0.3.0, after its #11)

scripts/install.sh --skip-build --settings FILE --agent NAME: non-interactive, idempotent, any checkout name; exit 0/1/2/3. Needs a prior build and installed dependencies. Silo routing is by AGENT_NAME, which Deck already writes, so --link is not used. Incompatibilities with the issue text are in the SPEC.

Test plan

  • pnpm -C packages/base exec vitest run test/create-agent.test.ts: new memory cases in temporary directories with a fixture checkout that mirrors the installer (hooks merged before the tsx check, PreCompact auto and manual), including present, absent, unbuilt, built but tsx missing (no hooks written), probe-before-wiring, terminated mid-probe, install fails, --no-memory, USER_NAME unset.
  • Manual: the real hook merge from the real install command in a temp HOME. Silo seeding through the real tsx was not run (dependencies could not be fetched in the sandbox).
  • Typecheck, boundaries, leaks, licence, lib-version, dashes, the rig self-test and the full pnpm test pass after merging current main.

Out of scope, follow-ups

  • M2 semantic search guidance and recall MCP wiring (paid-key boundary).
  • M3 watcher daemon and systemd units.
  • Leak-gate relaxation for the public memory-layer name, with a self-test.
  • TOOLS.md naming the memory layer; installing the recall instruction into agent homes.
  • Path convention docs; decision on shipping CORE.md for the persona-inject hook.
  • Tier-3 rig stage and an end-to-end check against a real built checkout.

🤖 Generated with Claude Code

…resent (#21)

M1 slice only. Opt-in safe: absence or failure reports memory off and
creation continues with an unchanged exit code.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GNgHnmc7XDCrYeFW1SMTDd
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GNgHnmc7XDCrYeFW1SMTDd
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review of the M1 slice, checked against the memory layer's scripts/install.sh and scripts/install-hooks.mjs on its current main (05c47be).

Interface: correct. --skip-build --settings <agent>/.claude/settings.json --agent <name> matches the real flags. The exit codes (0/1/2/3, with agent init passed through) and the hook set (UserPromptSubmit, Stop, PreCompact auto+manual) match too. Silo routing by the AGENT_NAME that merge_settings stamps is right: memory-root.ts tier 0. The agent name regexes are identical on both sides. The script runs under set -uo pipefail without -e, so a non-zero installer status is captured and never aborts. All five off paths keep the exit code, and the tests prove it.

Findings, most important first:

  1. The "built" pre-check misses a prerequisite the real installer checks only after it has written the hooks (packages/base/bin/create-agent.sh:455). The real install.sh merges the hooks first and checks node_modules/.bin/tsx afterwards, exiting 2 if it is missing. So a checkout with dist/ but no node_modules has its hooks wired, then gets reported off. That is the "known limitation" in the SPEC, and in this case it can be avoided. Also checking [[ -x "$root/node_modules/.bin/tsx" ]] (and, if you like, the four dist/claude-code/bin/*.sh files that install-hooks.mjs requires) before calling the installer removes the predictable half-wired case. Only real mid-run failures would be left.

  2. Both commits carry a Claude-Session: trailer, and pnpm check:leaks:messages flags them (private-session-link on f76901c and 54efe35). It is a real rule, not a false positive. CI only runs the tree-scope gate, so CI will not catch it, but a squash merge that keeps the default body puts the link onto main. That has happened once already, in 9201da1. Please drop those lines from the squash message when merging.

  3. The test file rebuilds a denied name to get past the leak gate (packages/base/test/create-agent.test.ts:677, [".the", "brain"].join("-")). It doesn't need to. Deck never refers to the silo directory, and the fixture installer decides where it seeds. A neutral name such as memory-silo tests the same behaviour, and the denied name stays out of the tree completely. Splitting a string to slip past the denylist is the pattern the gate is there to stop, even when the name is arguably public. Relaxing the gate is already listed as a follow-up, and that is the right place to settle it.

  4. The verification probe now fires the memory hooks (create-agent.sh:727, before the probe at around :829). With memory on and claude on PATH, the boot-phrase probe's claude -p runs UserPromptSubmit and Stop. Stop then starts a detached session-flush observation: one model-CLI call, which writes an observation of the verification turn into the new silo. It does not change the exit code (the hooks have 5s timeouts and the observer is detached). It does mean every new agent's first memory is the probe turn. Either accept that and say so in the SPEC and INSTALL.md, or keep the probe out of memory.

  5. Nit: the fixture's PreCompact entry has no auto/manual matchers and does not model the dist or tsx prerequisites. That is fine for a stand-in, but if (1) is fixed, add a test for "dist present, tsx missing => off, hooks untouched".

Scope is clean: no semantic search, paid keys, watcher, systemd or cross-repo changes, and the follow-ups are listed in the SPEC. I re-ran pnpm test: the 8 new tests pass. The 4 failures (one create-agent verification case and three shell suites) are identical on main at 433ebb2. check:leaks on the tree is clean.


Generated by Claude Code

…#21)

Check hook scripts and tsx before running the memory install, so a missing
dependency leaves settings untouched. Wire memory on exit, after the
verification probe, so the probe is not recorded as a first memory. Stricter
fixture and new tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Re-review of 42266ec. All four earlier findings are fixed. The pre-check matches the real scripts/install.sh / install-hooks.mjs in the memory layer (v0.3.0: the three dist/claude-code/bin/*.sh scripts, then node_modules/.bin/tsx). The fixture now uses .memory-fixture. The probe-before-wiring test passes. The fixture merges hooks before checking for tsx. The EXIT trap keeps the original exit code on every path I tried: VERIFIED 0, FAILED 3, CANNOT VERIFY 4, a set -u failure added after the trap (1), and SIGTERM (143). Settings are not touched when the checkout isn't built. There's no scope creep.

Remaining items, most important first:

  1. The PR conflicts with main (mergeable_state dirty), and CI has not run on the head. The conflicts are in packages/base/bin/create-agent.sh, against First-boot polish: day-one first message, focus-events, --model (#35, #36) #61's --model: the variable block near line 503 and the summary line near line 742. Both are trivial, so keep both sides. I tried that merge locally: create-agent.test.ts passes 48/48 and leak-gate is clean. On the branch as it stands, one existing test ("no runtime on PATH") fails in any environment that has a global claude next to node. main already fixed this in testPath, so it goes away once the branch is updated.
  2. INSTALL.md:366 adds an sh block that no rig run claims (optional-give-the-agent-a-memory-loop/sh#1), so rig/stages/05-install-doc.mjs (every-executable-block-claimed) will flag it. Either fence it as sh-manual and say it isn't executed, or claim it in rig/install-plan.mjs. Separately, main already has an unclaimed block of its own (1-prerequisites/sh#4), which isn't this PR's problem.
  3. Memory gets wired on runs killed by a signal (create-agent.sh:813-826). With SIGTERM or SIGHUP during the probe, the trap still runs the installer, and the last line says memory on. The exit code is kept (143 or 129). Ctrl-C will very likely do the same, but I only tested TERM and HUP. Running agent init after the user aborted is surprising. One fix is trap 'MEMORY_PENDING=0; exit 130' INT (and the same for TERM and HUP with their codes), or else document it.
  4. Minor: in .specs/21-memory-loop-install/SPEC.md, lines 15 and 28 still describe a memory off (reason) line in the summary. The final format is a last line, create-agent: memory on|off (...), which INSTALL.md describes correctly. Also, the summary prints memory wired after verification even with --no-memory or when no checkout is configured.

Not verified: silo seeding through the real tsx agent init (needs a built checkout), and behaviour if that command hangs (the trap has no timeout).


Generated by Claude Code

Keep both the memory and --model variable blocks and summary lines. Also
handle INT/TERM/HUP during the probe, make the summary memory line
conditional, and fence the INSTALL.md memory block as sh-manual.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review findings for head 945d527

Two independent reviews of this PR. Please address the Critical and Major items and reply to each Minor with a fix or a one-line reason to defer, then push. Keep the spec in sync with what changes.

Review A

Verdict: MERGE AFTER FIXES. No Critical finding identified.

The requested main...HEAD diff spans 333 files because local main predates merged work. I isolated #21's four changed files against HEAD's second parent, 81a7169, for detailed review.

  • Major: memory can route to another agent. create-agent.sh:476 installs with --agent "$NAME", but merge_settings preserves an existing, conflicting env.AGENT_NAME (line 268). Create wren over settings containing AGENT_NAME=fern: installation seeds wren, while hooks route to fern under the SPEC's stated contract. This risks mixing agents' memories. Reject conflicting identities before wiring; add a regression test.

  • Major: failed installation can leave active hooks while reporting “off”. create-agent.sh:479. If hook merging succeeds but silo initialisation fails, settings remain modified and subsequent sessions can execute those hooks despite the final “memory off” verdict. The SPEC acknowledges this, but INSTALL.md:809 omits it. Restore prior settings on failure, or report an explicit partial state and document recovery accurately.

  • Major: the per-agent settings boundary permits symlink escapes. create-agent.sh:441. An otherwise unoccupied agent home can contain .claude/settings.json linked to global settings. Creation accepts it; JSON writes follow the link, and the installer receives that same path. Thus “never a global one” is not guaranteed. Settings handling already had this weakness; the new integration extends its impact to memory hooks. Validate containment and reject settings symlinks before mutation.

  • Major: private session links remain in PR commit text. .specs/21-memory-loop-install/SPEC.md:116 acknowledges the issue; I independently confirmed Claude-Session URLs in commits f76901c and 54efe35. A history-preserving merge publishes those references. Remove the trailers from the published merge result. I did not access the sessions.

  • Minor: tests do not substantiate a functioning memory loop. create-agent.test.ts:725 installs nonexistent /fixture/ hook commands; assertions inspect configuration and directories without executing hooks. The failure fixture exits before mutation (line 712), so it misses the partial-install defect. Add a failure after hook merging and an integration check that produces an observation through the real hooks.

Read-only checks passed: shell syntax, diff whitespace, and the leak gate across 435 tracked files, excluding environment/credential-like paths and symlinks. No additional denied material was reported; this is not an exhaustive commercial-information audit.

Not checked: browser, real installation/runtime, executable tests, Windows/macOS execution, credentials, or a complete behavioural review of the inherited 333-file diff. No files were changed, servers started, or network/database operations performed.

Review B

Verdict: MERGE AFTER FIXES

Summary

PR 67 wires the memory layer hooks (UserPromptSubmit, Stop, PreCompact) into newly created agent .claude/settings.json and seeds the agent's memory silo when a built memory layer checkout is present or configured via MEMORY_LAYER_ROOT / --memory-root.

Findings

Critical

None.

Major

  1. Commit message history — Private session links leaked in git log
    • Failure scenario: Commits f76901c and 54efe35 contain commit trailers:
      Claude-Session: <session link>
      If merged with a standard merge commit or rebased into a public repository, these internal session URLs are permanently exposed.
    • Remediation: Squash merge or rewrite git commit history to remove the Claude-Session trailers before merging (as noted in .specs/21-memory-loop-install/SPEC.md).

Minor

  1. packages/base/bin/create-agent.sh:839-854 — Memory wired on failed verification probe
    • Failure scenario: MEMORY_PENDING=1 is armed after scaffolding. If the verification probe fails (times out or returns unexpected text), report_cannot_verify calls exit "$EXIT_CANNOT_VERIFY". The EXIT trap (memory_on_exit) still proceeds to wire memory hooks and seed the memory silo for an unverified or malfunctioning agent.
    • Recommendation: Clear MEMORY_PENDING=0 in report_cannot_verify when verification was attempted and failed, leaving memory un-wired until the user successfully runs --verify-only.

Correctness & Safety Checks

  • Failure isolation: If memory install fails or dependencies are missing, MEMORY_REPORT notes the failure and agent creation continues without failing the exit code.
  • Dependency pre-flight: Checks dist/claude-code/bin/*.sh and node_modules/.bin/tsx before invoking install.sh, preventing partial hook writes.
  • Signal handling: Traps for INT (130), TERM (143), and HUP (129) set MEMORY_PENDING=0 to ensure an aborted run does not wire hooks.
  • Probe isolation: Memory is wired strictly after the verification probe exits, ensuring probe turns are not recorded as agent memories.
  • Cross-platform: Standard Bash syntax; environment variables and arguments properly quoted.

What Was Not Checked

  • Integration with external Qdrant vector database or embedding providers.
  • Behavior with alternate agent runtimes (e.g. agy, codex).

Related Brain Files

  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-67-comment]] (1.00) — pr-67-comment
  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-67-aggy]] (0.95) — PR 67 Review: Memory Loop in create-agent (The Deck install does not set up the brain, so tier-3 agents have no memory #21)
  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-67-sol]] (0.95) — pr-67-sol
  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-18-sol]] (0.78) — pr-18-sol
  • [[../../.the-brain/agents/greymatter-dev/memory/observations/2026-04-19-20-55-59]] (0.78) — Observation — 2026-04-19 20:56

@simon-inkie
Copy link
Copy Markdown
Owner Author

Automated review (CodeRabbit CLI, run against this branch) found one minor issue:

Minor, packages/base/bin/create-agent.sh:841-851: interrupt during memory wiring leaves no report. wire_memory runs inside the EXIT trap. If SIGINT or SIGTERM arrives while the installer runs, the INT/TERM trap sets MEMORY_PENDING=0 and exits 130, so hooks can be partly written while the final create-agent: memory ... line never prints. The window is narrow and the installer is idempotent, so a re-run recovers, but the outcome should be visible: for example set MEMORY_REPORT="off (interrupted during install)" before the installer runs and let the signal traps print it when wire_memory is in progress.

…-install cases (#21)

Refuse memory when env.AGENT_NAME names another agent, reject a symlinked
per-agent settings file before any write, restore the previous settings (or
report a PARTIAL state) when the memory install fails after merging hooks,
leave memory unwired when the verification probe fails, and leave a visible
report when interrupted during the install. Tests, SPEC and INSTALL.md updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Fixes pushed in d5484a8 (fast-forward, no history rewrite). Reply to each finding:

Major, conflicting env.AGENT_NAME: fixed. Before wiring, Deck reads the settings; if env.AGENT_NAME is not the agent being created, memory is reported off (settings env.AGENT_NAME is "x", not "y") and nothing is written. Regression test: "refuses memory when the settings already route to a different agent".

Major, failure after hooks merged: fixed. A snapshot is taken first; on a non-zero install the settings are restored and the report says settings restored, nothing wired. If the restore itself fails the line is off (PARTIAL: ...) and names the file. Tests: failure after merge (hooks absent afterwards) and an unrestorable case. INSTALL.md and SPEC document both.

Major, symlinked settings: fixed. A symlinked .claude or settings.json is a scaffold error before any file is created, and wiring re-checks. Test: the symlink target is untouched and nothing is created.

Major, Claude-Session trailers in commit text (f76901c, 54efe35): NOT fixed, deliberately. Removing them means rewriting history and force-pushing, which this task forbids. New commits omit the trailer. A squash merge must drop the Claude-Session lines from the message. The user can decide whether to rewrite those two commits.

Minor, memory wired after a failed probe: fixed. A wrong phrase, empty reply or runtime error now leaves memory unwired with off (verification did not pass ...). --no-verify and "no runtime on PATH" (nothing attempted) still wire. Two tests.

Minor (CodeRabbit), interrupt during wiring leaves no report: fixed. The signal handler prints off (interrupted during memory install; settings restored, nothing wired) and restores the settings; an interrupt before wiring prints off (run interrupted before memory was wired). Test sends SIGTERM mid-install.

Minor, tests do not substantiate a working loop: partly. A failure-after-merge test was added. An integration check producing a real observation through the real hooks still needs a built checkout; listed as a follow-up, not done here.


Generated by Claude Code

@simon-inkie
Copy link
Copy Markdown
Owner Author

Review of head d5484a8. I checked it against the memory layer's real scripts/install.sh and scripts/install-hooks.mjs (memory layer main at 05c47be), and drove the real installer in a temporary HOME. For that 8000 I used a stand-in checkout: stub dist/claude-code/bin/*.sh files and a stub tsx.

Verdict: merge after one fix. I confirmed every fix from the previous round. The conflicting env.AGENT_NAME is refused before anything is written. A failure after the hooks merge restores the settings; I checked this with the real install-hooks.mjs and a tsx exiting 3. A failed or erroring probe leaves memory unwired, while --no-verify and the no-runtime case still wire it. SIGTERM during the install restores the settings and prints the off (interrupted ...) line; I ran that 7 times with the real installer and the exit code was 143 each time. Exit codes are kept on every path I tried (0, 3, 4, and 143 on a signal). Memory never aborts creation. Settings always exist by the time wiring runs, so the "settings did not exist before" restore case cannot happen. If it somehow did, the read of AGENT_NAME fails and the result is off. Scope is clean: no semantic search, no paid keys, no watcher or systemd. No new commit carries a Claude-Session trailer.

Findings

  1. [Major] packages/base/bin/create-agent.sh:439. The symlink guard does not cover the installer's own write paths. install-hooks.mjs writes <settings>.the-brain.tmp with writeFileSync, which follows symlinks, then renames it over settings.json (lines 93-99). It also copies into <settings>.the-brain.bak when no file exists at that path, so a dangling link is followed. settings_is_contained checks only .claude and settings.json, and the scaffold deliberately accepts a pre-existing .claude/. I reproduced it: plant agents/wren/.claude/settings.json.the-brain.tmp -> $HOME/.claude/settings.json, then run create-agent.sh wren --no-verify against the real installer. The global settings file is overwritten with wren's env (AGENT_NAME=wren, INBOX_ROOT) and all the memory hooks. The agent's settings.json becomes a symlink to the global file. stamp_user_name (line 556) then writes USER_NAME through that link, and the last line says memory on. The exit code was unchanged (4).
    Fix: before the snapshot, refuse (memory_skip) when settings.json.the-brain.tmp or settings.json.the-brain.bak exists as a symlink. Simpler still, refuse when any entry in .claude/ is a symlink. After the installer returns, re-run settings_is_contained before stamp_user_name and before reporting on. If the check fails, treat it as PARTIAL. Add a test with a planted .the-brain.tmp link and assert the link target is untouched.

  2. [Minor] create-agent.sh:920 and :946: the snapshot leaks. When on_signal runs inside the EXIT trap it calls exit itself, so rm -f "$MEMORY_SNAPSHOT" never runs. A copy of the agent's settings stays in $TMPDIR after every interrupted install; it was 1 file in each of my 7 runs. Because of cp -p (line 530), the copy gets the settings file's mode (0644 here) rather than mktemp's 0600. Fix: remove the snapshot in on_signal before exit. Drop -p, or chmod 600 the snapshot. restore_settings writes with cat >, so it does not need the mode.

  3. [Minor] create-agent.sh:928. The comment "Bash runs a trap after the foreground child finishes, so the installer is not cut off half way" holds only for a signal sent to bash's own PID. Ctrl-C and a terminal hangup go to the whole foreground process group, so the installer and tsx die mid-run too. The restore still happens afterwards, and install-hooks writes atomically through tmp+rename, so the result is right. But a stray .the-brain.tmp can be left behind, and the comment overstates the guarantee. Fix: reword it, and after a restore remove settings.json.the-brain.tmp if it is a regular file.

  4. [Nit] After a restore, settings.json.the-brain.bak is left in .claude/. It is harmless (its content matches the restored file), but the report says "nothing wired". INSTALL.md (around line 820) could mention it, or Deck could remove it when it did not exist before the snapshot.

  5. [Nit] packages/base/test/create-agent.test.ts:926. The symlink test covers a linked settings.json but not a linked .claude directory, which the guard also claims to handle. Add one case for it.

  6. [Known, not new] Commits f76901c and 54efe35 still carry Claude-Session trailers, pending the maintainer's decision. A squash merge must drop those lines.

CI on d5484a8: all 4 check runs succeeded: test (22.x), test (24.x), guards, licence. The combined commit-status API reads pending with 0 statuses, meaning no legacy statuses are posted; that is not a failing check. Locally, vitest run test/create-agent.test.ts passes 57/57.

Not verified: silo seeding through a real tsx agent init (no built checkout available); a real Ctrl-C from a terminal (only kill -TERM to the script's PID was tested); behaviour if the installer hangs (there is still no timeout on the wiring step); macOS cp -p and mktemp behaviour.


Generated by Claude Code

…ean up the snapshot (#21)

The memory installer writes a temporary file and a backup beside the settings
and follows links, so refuse when anything in .claude is a symlink, and check
again after the install before stamping USER_NAME or reporting on. Create the
settings snapshot 0600 and remove it on signal, remove files a failed install
left beside the settings, correct the signal comment, and add REVIEW.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
…#21)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review of head 887d0b3. I checked it against the memory layer's real scripts/install.sh, scripts/install-hooks.mjs and scripts/lib/merge-hooks.mjs (memory layer main at 05c47be), and drove them in temporary HOMEs. The stand-in checkout had stub dist/claude-code/bin/*.sh files and a stub tsx.

Verdict: merge after fixes (one Major). The round-4 symlink fix works for symlinks. The exploit from my previous comment no longer works: with settings.json.the-brain.tmp -> $HOME/.claude/settings.json planted, the global file is left byte-for-byte unchanged, memory is off (a symlink ...; nothing written), and the exit code is still 4. A dangling .the-brain.bak link and a link nested in a subdirectory of .claude are refused the same way. But the same attack works with a hard link, and with a symlinked agent home.

Findings

  1. [Major] packages/base/bin/create-agent.sh:448 (memory_dir_is_clean): the containment check only looks for symlinks. Two variants of the round-4 exploit still overwrite the global settings and report memory on. I reproduced both with the real installer:

    • Hard link. Plant agents/wren/.claude/settings.json.the-brain.tmp as a hard link (ln, same filesystem) to $HOME/.claude/settings.json, then run create-agent.sh wren --no-verify. install-hooks.mjs calls writeFileSync(tmp), which truncates and rewrites the shared inode, then renames it over the agent's settings.json. Results: the global file holds wren's env (AGENT_NAME=wren, INBOX_ROOT) and all four memory hooks, USER_NAME gets stamped into it, the agent's settings.json is the global inode (link count 2), and the last line reads memory on. The post-install re-check misses all of it because nothing is a symlink. Note also that if the install then fails, restore_settings would cat the snapshot into that same shared inode.
    • Symlinked agent home (a parent directory of .claude). The scaffold accepts a pre-existing agents/wren that holds no persona files, and it never checks whether agents/wren itself is a link. With agents/wren -> $HOME, $AGENT_HOME/.claude is the real global .claude, so both settings_is_contained and memory_dir_is_clean pass. Results: the persona files land in $HOME, the global settings are merged and then memory-wired, and the line reads memory on. The scaffold part of this is older than this PR, but the PR's "never a global one" claim, and the round-3 and round-4 "Fixed" entries, do not hold.
    • Suggested fix: (a) refuse, at scaffold time and before wiring, when $AGENT_HOME is a symlink, or when realpath "$AGENT_HOME/.claude" is not $(realpath "$AGENTS_HOME")/$NAME/.claude. (b) Before wiring, refuse when any regular file in .claude has more than one link (find "$AGENT_HOME/.claude" -type f -links +1). The simplest rule is to refuse when any settings.json.* entry exists at all, since a new agent home has none. Re-run the same check after the installer. (c) Add tests for a hard-linked .tmp name and for a symlinked agents/<name>, asserting the victim file is unchanged. Remaining TOCTOU: a link planted between the pre-check and the installer's write is only caught by the post-check, after the write has happened. Under a same-user threat model that is acceptable, but say so in the SPEC rather than calling it fixed.
  2. [Minor] packages/base/bin/create-agent.sh:975-998 (on_signal): a signal that arrives inside the EXIT trap while MEMORY_WIRING=0 prints no memory line at all. This covers the pre-checks, the AGENT_NAME read, the snapshot, the post-install re-check and stamp_user_name. In those cases on_signal sets MEMORY_PRINT=1 and calls exit, and bash does not run the EXIT trap a second time. I confirmed this by slowing the post-install find with a PATH shim and sending SIGTERM after the installer had finished. Result: exit 143, hooks wired and silo seeded in the agent's settings, no USER_NAME, and no create-agent: memory ... line. That contradicts the comment ("The handler prints in that case because it may be running inside the EXIT trap") and INSTALL.md ("Before wiring nothing is wired"). stamp_user_name also writes in place with writeFileSync, so a signal during that write could truncate the settings. Suggested fix: set a flag such as MEMORY_IN_EXIT=1 in memory_on_exit and make on_signal print whenever it is set. Track the stage too (for example MEMORY_STAGE=installed after a zero status) so that the report reads on (interrupted before USER_NAME was stamped) instead of off. Write USER_NAME through tmp+rename.

  3. [Minor] .specs/21-memory-loop-install/REVIEW.md:55-60: the round-3 symlink row ("Fixed ... Widened in round 4") and the round-4 row ("Fixed") overstate the result, given finding 1. Line 22 says the trailer item was "Raised in rounds 1 and 3", but round 4 raised it as well (item 6). Update both rows when finding 1 is fixed. Otherwise the log matches the earlier comments: every round 1-4 item is present, with accurate outcomes.

  4. [Nit] packages/base/test/create-agent.test.ts:1019-1052: the TMPDIR leak test is meaningful. It would have failed on d5484a8: --no-verify exits before the probe mktemp, so the only file that can appear in TMPDIR is the snapshot, and GNU mktemp honours TMPDIR. It does not assert the snapshot's mode, though, and the planted-link tests use settings.json.planted.* rather than the installer's real .the-brain.tmp / .the-brain.bak names. Optional: assert 0600 while the install is held, and use the real names in one case.

  5. [Nit] INSTALL.md:830: a blank line separates the symlink bullet from the rest of the "memory is off when" list, so the bullet renders as a separate list. Remove the blank line.

Confirmed, no regression:

  • Process-group SIGINT, SIGHUP and SIGTERM (via setsid / kill -- -pgid) during the real installer each restore the settings. They also remove the settings.json.the-brain.bak the failed run created, leave TMPDIR empty, and print off (interrupted during memory install; settings restored, nothing wired). INT exited 130.
  • restore_settings refuses a symlinked settings.json before cat >. remove_new_settings_extras deletes only regular, non-link settings.json.* files that were absent before the install, so it cannot follow a link or delete a pre-existing file. The narrow exception is a file of that name created by someone else during the install window.
  • The successful-install backup is kept and documented (INSTALL.md around line 842).
  • The snapshot is created 0600 under umask 077 with no cp -p.
  • The signal comment is now accurate about the process-group case, apart from finding 2.
  • vitest run test/create-agent.test.ts passes 60/60 locally, covering conflicting AGENT_NAME, restore/PARTIAL, probe failure/error, interrupt report, exit codes and memory never aborting creation. pnpm check:leaks is clean (437 files).
  • Scope is clean: no semantic search, paid keys, watcher or systemd.
  • No new commit carries a Claude-Session trailer. Only f76901c and 54efe35 (already known) do, and a squash merge must still drop those lines.

CI on 887d0b3: all 4 check runs completed with success: test (22.x), test (24.x), guards, licence.

Not verified: silo seeding through a real tsx agent init (no built checkout); a real terminal Ctrl-C (only process-group signals via kill); behaviour if the installer hangs (there is still no timeout on wiring); macOS mktemp/find -links behaviour; hard links across filesystems (impossible, so that variant needs the agents home and $HOME on one filesystem, which is the default layout).


Generated by Claude Code

…port signals in the exit handler (#21)

Contain the agent home and .claude by real path, refuse any hard link or
pre-existing settings.json.* entry before the install, re-check after it,
track a stage so a signal in the exit handler always prints a memory line, and
write USER_NAME through a temporary file and a rename. Tests, SPEC, INSTALL.md
and REVIEW.md updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review of head 3b96653. I checked it against the memory layer's real scripts/install.sh and scripts/install-hooks.mjs (memory layer main at 05c47be) and drove the real installer in temporary HOMEs. The stand-in checkout had stub dist/claude-code/bin/*.sh files and a stub tsx. Every run used a throwaway HOME, never a real one.

Verdict: merge after fixes (two Major). Both round-5 exploits are fixed with the real installer. With a hard-linked settings.json.the-brain.tmp pointing at $HOME/.claude/settings.json, memory is off (... hard link; nothing written) and the global file is byte-identical with the same inode. The same holds for a hard link under any other name in .claude. With agents/wren -> $HOME, the run stops with a scaffold error and nothing is written. But the new realpath check breaks first-time creation on some ordinary layouts. Separately, a hard link on settings.json itself still lets the scaffold write the global file.

Findings

  • [Major] packages/base/bin/create-agent.sh:448 (with resolve_path at :350, called at :877) - this is a regression from ce2c6a2. When the agents home does not exist yet, which is the normal first run, the check fails if the path has a symlinked ancestor or a trailing slash. create-agent.sh then stops with SCAFFOLD ERROR "refusing to write settings outside the agent's own directory". GNU readlink -f resolves $AGENTS_HOME because only its last component is missing. It fails on $AGENTS_HOME/$NAME because two components are missing, and the fallback returns the raw path, so the two strings differ. I reproduced it with AGENTS_HOME=<dir>/homes/u/agents, where homes is a symlink (the layout of /home -> /var/home on Fedora Atomic, or any symlinked $HOME). It also happens with a missing AGENTS_HOME=<dir>/agents2/. The same case works at 887d0b3. The tests always pre-create the agents home, so they miss it. - Suggested fix: resolve only paths that exist. For example, mkdir -p "$AGENTS_HOME" before the check, and compare resolve_path "$AGENT_HOME" only when it exists (otherwise check that it is not a link and that its parent resolves to the agents home). Add a test with a missing agents home under a symlinked parent, and one with a trailing slash.
  • [Major] packages/base/bin/create-agent.sh:445-452 and :275 - a hard link already in place on .claude/settings.json itself still writes the global file. settings_is_contained, the gate the scaffold uses, checks symlinks and realpaths but not link counts. merge_settings writes in place with writeFileSync. I reproduced it with a pre-existing agents/wren/.claude/settings.json hard-linked to $HOME/.claude/settings.json. Memory is refused correctly, but the global settings gain AGENT_NAME=wren, INBOX_ROOT and promptSuggestionEnabled. That routes any global memory hooks to wren's silo. This contradicts SPEC.md:148 ("never a global one" holds "for links already in place"), REVIEW.md:71 ("Fixed for links already in place") and INSTALL.md:849. - Suggested fix: in settings_is_contained, also refuse when settings.json (and .claude) has a link count above one, and fail closed. node -e with fs.lstatSync(...).nlink is portable. Better still, have merge_settings write through tmp+rename with flag: "wx". Add a test that asserts the victim file is unchanged.
  • [Minor] packages/base/bin/create-agent.sh:463-464 - the link checks fail open. [[ -z "$(find ... 2>/dev/null)" ]] treats a missing find, a failing find (unreadable subdirectory, or a BusyBox build without -quit or -links) and an empty result all the same. I tested two cases, find absent from PATH and a find that exits 1. In both, a hard link planted during the install was not caught by the post-check: the last line said memory on while the global file held wren's env and all four memory hooks. With a pre-existing hard-linked settings.json, the last line also said on. - Suggested fix: capture the status (out=$(find ...) || return 1) and require command -v find, or do the walk in node, which is already a hard dependency.
  • [Minor] packages/base/bin/create-agent.sh:535-536 and :650 - the USER_NAME write has an unchecked race that ends in on. The temporary name .settings-stamp-<pid>.tmp is predictable. writeFileSync follows a symlink there, and nothing re-checks after the stamp. I planted the link once the post-install check had passed. Result: the global file was overwritten with wren's full settings, including USER_NAME, the agent's settings.json became a symlink to it, and the line said memory on. This is the same-user race class the SPEC accepts, but there it is supposed to be reported PARTIAL, never on. Separately, the mode option is masked by the umask: a 10000 0664 settings file becomes 0644 after the stamp, so "keeps mode" does not hold. Without USER_NAME it stays 0664. - Suggested fix: write with { flag: "wx" } under a random name (fs.mkdtempSync or crypto.randomUUID), chmodSync(tmp, mode) after the write, as the installer does, and run memory_dir_is_clean again before setting the report to on.
  • [Minor] packages/base/bin/create-agent.sh:445-452 - the containment check cannot see links that point the other way, from the global config into the agent home. Two cases: $HOME/.claude -> $AGENTS_HOME/wren/.claude, with a pre-existing agent home and no persona files; and an agents home that resolves to the parent of $HOME, with the agent named after the home directory. In both, everything resolves "inside" the agent home, and the global settings get the scaffold env, all memory hooks and USER_NAME, with memory on. Both are contrived (same-user setup), but the "never a global one" claim does not hold. - Suggested fix: also refuse when the agent's settings resolve to the same file (realpath or dev+inode) as $HOME/.claude/settings.json, or as ${CLAUDE_CONFIG_DIR}/settings.json when that is set. Or narrow the claim in SPEC/INSTALL.
  • [Minor] .specs/21-memory-loop-install/REVIEW.md:71, SPEC.md:148, INSTALL.md:849 - the "Fixed for links already in place" wording overstates the result, given the hard-linked settings.json above and the fail-open find. Change the round-5 row to "Partly fixed" when those are addressed, the way the round-3 and round-4 rows were corrected. Otherwise the log is accurate: the round-3 and round-4 rows now say "Partly fixed", and the trailer line lists rounds 1, 3, 4 and 5.
  • [Nit] packages/base/bin/create-agent.sh:1043 - "interrupted before USER_NAME was stamped ... add env.USER_NAME by hand" can be wrong. A signal sent only to the script's PID lets the stamp finish (bash waits for the child), and I saw USER_NAME present beside this line. - Suggested fix: say "USER_NAME may not have been stamped; check env.USER_NAME".
  • [Nit] packages/base/bin/create-agent.sh:616-617 - MEMORY_WIRING=0 is set before MEMORY_STAGE="ran", so a signal between the two reports "before the memory install ran; nothing written". In addition, stage "" is also the state after early returns that never call memory_skip (--no-memory, not built, no root), and in --verify-only runs. A signal there replaces the true reason with "interrupted before the memory install ran". - Suggested fix: set the stage before clearing the flag, and set it in those early returns too.

Confirmed, no regression:

  • The TOCTOU limitation (f) behaves as the SPEC says. I planted a hard link or a symlink at the installer's .the-brain.tmp name just before install-hooks.mjs ran. Each time the result was off (PARTIAL: a symlink or hard link appeared ...), exit 4, no USER_NAME stamped, never on. In both cases the global file's original content was replaced by the agent's settings plus the four memory hooks. In the symlink case the agent's settings.json became a symlink to the global file. In the hard-link case it shares the global inode. Deck keeps nothing that restores the global file's previous content; its snapshot is of the agent file. The SPEC's "the write itself is not prevented" is accurate. You could add that the global file's earlier content is lost.
  • The restore refuses hard-linked settings. A hard link to the global file appeared mid-install and then SIGTERM arrived: the result was off (PARTIAL: ... could NOT be restored) with the global file unchanged. A plain install failure (tsx exits 1) restores the agent's settings, removes the new backup, and reports off (memory install exited 1; settings restored, nothing wired).
  • on_signal stages, tested by slowing steps with PATH shims. A signal during the pre-check (TERM, INT) gives off (interrupted before ...; nothing written) with no hooks written. During the post-install check (TERM, HUP) it gives PARTIAL ... hooks may be wired (they were). During the stamp it gives on (...) (hooks were wired). Exit codes were 143, 130 and 129. The settings were never reported on without hooks wired.
  • The stamp writes through tmp+rename, so it never writes through a symlinked settings.json itself. The remaining gaps are the predictable temporary name and the mode, both above.
  • Earlier fixes still hold: conflicting AGENT_NAME, restore/PARTIAL, probe failure, interrupt report, exit codes kept, and memory never aborting creation. vitest run test/create-agent.test.ts passes 67/67 locally, and pnpm check:leaks is clean (437 files). Scope is clean.
  • No new commit carries a Claude-Session trailer. Only f76901c and 54efe35 do (already known), and a squash merge must drop those lines.

CI on 3b96653: all 4 check runs completed with success: test (22.x), test (24.x), guards, licence.

Not verified: macOS behaviour. On macOS, readlink -f exists only from 12.3; older versions fall back to the raw path, so the realpath part of the check is skipped there. BSD realpath may also treat a missing last component differently from GNU. /var vs /private/var resolves consistently whenever readlink -f works on both sides, but it hits the missing-agents-home regression above. Not verified either: case-insensitive filesystems (both sides use the same input case, so I expect no mismatch, but I could not test it), BusyBox find, silo seeding through a real tsx agent init, a real terminal Ctrl-C, and a hanging installer (there is still no timeout).


Generated by Claude Code

…mp hardening, signal output (#21)

Resolve the agent home through symlinked ancestors even when it does not exist
yet, refuse a hard-linked settings.json and settings that are the user's own
global file, fail closed instead of relying on find, stamp USER_NAME through a
random exclusively created file, and print the signal report through a saved
stdout. Tests, SPEC, INSTALL.md and REVIEW.md updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review of head c616a9d. I checked it against the memory layer's real scripts/install.sh, scripts/install-hooks.mjs and scripts/lib/merge-hooks.mjs (memory layer main at 05c47be). I drove them in throwaway HOMEs; no real HOME was touched. The stand-in checkout had stub dist/claude-code/bin/*.sh files and a stub tsx.

Verdict: merge after minor fixes. No Critical or Major findings. I checked every round-6 item myself. All of them are fixed or honestly narrowed. The exploits that used to work are all refused now. What is left are four Minor edge cases and some doc nits.

Exploits re-run with the real installer

  • (a) settings.json.the-brain.tmp hard-linked to $HOME/.claude/settings.json: memory off (... symlink or hard link; nothing written). The global file kept the same hash and inode, and the exit code was 4. A symlinked .tmp, and a hard link under any other name in .claude, give the same result.
  • (b) agents/wren -> $HOME: SCAFFOLD ERROR, exit 1. Nothing was written to $HOME.
  • (c) Agents home set to the parent of $HOME, with the agent named after the home directory: SCAFFOLD ERROR, global file unchanged.
  • (d) Pre-existing agents/wren/.claude/settings.json hard-linked to the global file: SCAFFOLD ERROR before any write. The global file is byte-identical and still has nlink 2. It is now refused at the scaffold, not only for memory.
  • (e) $HOME/.claude -> agents/wren/.claude, both with and without an existing settings file: SCAFFOLD ERROR. CLAUDE_CONFIG_DIR=agents/wren/.claude, both with and without an existing file: SCAFFOLD ERROR. CLAUDE_CONFIG_DIR=agents/wren (not .claude) wires normally, which is correct. One gap is in the findings below.
  • (f) A hard link or a symlink planted at the .the-brain.tmp name inside install.sh, just before install-hooks.mjs runs: off (PARTIAL: ... failed its containment check after the install ...). No USER_NAME was stamped and the line never said on. As documented, the global file's content is replaced.
  • (g) First-time creation: missing agents home under a symlinked ancestor, a symlinked $HOME with the default ~/agents, a trailing slash, // combined with a symlinked ancestor, and an agents home that is itself a symlink. All of them create the agent and print memory on. The round-6 regression is gone.
  • (h) Stamp temp file: the name is crypto.randomBytes(8), and {flag:"wx"} against a planted symlink gives EEXIST, so it is never written through. The mode survives the stamp under umask 002, 077 and 022 (664, 600, 644), and no .settings-stamp-* files are left behind.

Other checks that passed: the containment check fails closed in every case I tried:

  • node exiting 127 at the scaffold check: SCAFFOLD ERROR
  • at the pre-install check: off, no hooks
  • at the post-install check: PARTIAL
  • at the post-stamp check: PARTIAL
  • at the restore check after tsx exits 1: PARTIAL ... could NOT be restored
  • an EACCES thrown from readdirSync in the tree walk: off
  • no node on PATH: SCAFFOLD ERROR, nothing created

settings.json replaced by a directory gives PARTIAL whether the installer exits 0 or 1, and also under SIGTERM mid-install (could NOT be restored).

Signal stages: I slowed individual node steps with a PATH shim, then sent the signal either to the script's PID or to its process group. The results:

  • before the install: off ... nothing written, no hooks (TERM 143, INT 130, HUP 129)
  • during the installer: restored, nothing wired, TMPDIR empty (TERM, INT)
  • during the post-install check: PARTIAL ... hooks may be wired
  • during the stamp: hedged on (... may or may not be there)

The line never said on without the hooks wired. With stdout redirected to a file, the handler's line still arrives through fd 7. Earlier fixes still hold: conflicting AGENT_NAME, restore/PARTIAL, probe failure, the interrupt report, exit codes kept, memory never aborting creation, and scope.

Findings

  • [Minor] packages/base/bin/create-agent.sh:77 - exec 7>&1 is never closed for child processes, so the installer, tsx, node and the probe's claude -p all inherit fd 7. I confirmed it with /proc/$$/fd inside tsx. A detached grandchild that redirects its own stdout and stderr keeps the caller's pipe open through fd 7. With a tsx that starts (sleep 6 >/dev/null 2>&1 &), create-agent.sh ... | tail -1 took 7s; with the exec removed it took 1s. A realistic trigger is a user whose global settings already hold the memory hooks: the probe's Stop hook starts a detached observer, and create-agent.sh | tee log then waits for it. A caller's own fd 7 is also replaced for children, though nothing in Deck relies on that. - Close it for children: add 7>&- to the installer call (:701), the probe subshells (:1186, :1189) and node_run. Alternatively, open fd 7 only inside memory_on_exit/wire_memory.

  • [Minor] packages/base/bin/create-agent.sh:470-484 and :514-520 - links pointing the other way are still missed when the global settings path is a dangling symlink. loose() drops a missing last component without reading the link, and the inode test needs the agent's file to exist already. I reproduced it with $HOME/.claude/settings.json -> agents/wren/.claude/settings.json, before wren existed. The scaffold passes and merge_settings creates that file, so the user's global settings now resolve to AGENT_NAME=wren, INBOX_ROOT and promptSuggestionEnabled:false. Memory is then refused correctly by the inode check, but INSTALL.md:78 says "whichever way a link points". - In loose(), when lstat shows the component is a symlink, resolve readlinkSync relative to its directory and continue. Or compare stat (dev+ino) of $HOME/.claude and $CLAUDE_CONFIG_DIR against the agent's .claude once it exists, which also avoids case-only path mismatches on macOS. Add a test.

  • [Minor] packages/base/bin/create-agent.sh:491 - path.resolve collapses .. lexically before any symlink is resolved, while bash and cp resolve it physically. With AGENTS_HOME=$T/l/../.. (where l -> $HOME/sub) and name home, the physical agent home is $HOME. The check compares lexical paths that do not exist, so it passes. cp then puts CLAUDE.md, IDENTITY.md, SOUL.md, TOOLS.md and USER.md into $HOME. The global settings survived only because stamp_templates (also lexical, via path.join) failed with ENOENT before merge_settings. - Canonicalise once in bash before the check: mkdir -p "$AGENTS_HOME" && AGENTS_HOME="$(cd -P "$AGENTS_HOME" && pwd)". Or refuse ./.. components in AGENTS_HOME.

  • [Minor] packages/base/bin/create-agent.sh:971 vs :276 - the scaffold's own check happens well before its write. mkdir, cp, stamp_templates and more run in between, and merge_settings still writes in place with writeFileSync. REVIEW.md:83 records this as a choice, but SPEC.md:148/155 and INSTALL.md:66-82 describe the timing limit only for the memory install. - Either write through a random wx temp plus rename, as the stamp does, or add one sentence on the scaffold window to SPEC and INSTALL.

  • [Nit] packages/base/bin/create-agent.sh:971 - the SCAFFOLD ERROR text always says "is a symlink, or resolves somewhere other than ...". It says the same for a hard-linked settings.json, for settings that are the global file, and when node is missing; I saw that wording in all three. - Name all three reasons, or have the node check print the reason it failed to stderr, and show that.

  • [Nit] .specs/21-memory-loop-install/REVIEW.md:88 - this row has two inaccuracies:

    • "an unarmed run (--verify-only) prints nothing" is wrong for a signal during the probe. --verify-only killed with TERM prints create-agent: memory off (run interrupted before memory was wired), because the else branch at :1145 sets MEMORY_PRINT=1.
    • The "few instructions" window is really the whole post-stamp containment check, a node process. INT to the process group there gives the stamping line although the stamp had finished.

    The early wire_memory returns (--no-memory, not built, no root) still leave the stage at "". - Fix the wording, skip the print when MEMORY_ARMED=0, and set the stage after the stamp returns.

  • [Nit] .specs/21-memory-loop-install/SPEC.md:75 - the test plan still says "11 new memory cases". The file now has 72 tests, compared with 37 on main. - Update the count or drop it.

  • [Known, not new] f76901c and 54efe35 carry Claude-Session trailers. No newer commit carries one, so the 13 commits through c616a9d add nothing new. A squash merge must drop those lines.

CI on c616a9d: all four check runs completed with success: test (22.x), test (24.x), guards and licence. Locally, vitest run test/create-agent.test.ts passes 72/72 and pnpm check:leaks is clean (437 files, 33 rules). The doc diff has no em-dashes or en-dashes.

Not verified: macOS. From reading the code: node's JS realpathSync resolves /var to /private/var the same way on both sides, and does not fold case. home and want come from the same input string, so they agree. A global path whose case differs from AGENTS_HOME is caught only by the inode test, so only when the agent's file already exists. A real case-insensitive filesystem was not tested. Also not verified:

  • silo seeding through a real tsx agent init (no built checkout)
  • a real terminal Ctrl-C (only kill to the PID or the process group)
  • a hanging installer (there is still no timeout)
  • EACCES as a non-root user (I simulated it by patching readdirSync, because the sandbox runs as root)
  • hard links across filesystems (impossible)

Generated by Claude Code

… agents home (#21)

Open fd 7 only in the exit handler and close it for the installer and the node
helper so a detached child cannot hold the caller's pipe, and refuse an agents
home with a .. component that a symlink would resolve differently. Narrow the
INSTALL.md and SPEC claims about dangling links and the in-place settings
merge. Add the round 7 section to REVIEW.md.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Final focused review of head 823d230 (round 7 code in be8d318). Scope: real bugs and regressions only, as the maintainer asked.

Verdict: approve. No new findings. Both round-7 code changes do what they say. I found no regression in the earlier security fixes, the exit codes, or the rule that memory never aborts creation.

fd 7

  • Output of the signal line, with a TERM to the script PID during the installer and during the post-install containment check (the check runs in-shell with >/dev/null; an INT was also tried):
    • stdout to a file: the line arrives (settings restored, nothing wired, PARTIAL ... before its result was checked)
    • stdout to a pipe: the line arrives
    • the caller's own fd 7 open on a separate file: the line goes to stdout, and nothing is written to the caller's fd 7
    • stdout to /dev/null: the line is dropped, as expected
    • rc stays 143 or 130
  • A TERM during the probe gives off (run interrupted before memory was wired) on stdout, with no hooks written.
  • A run with stdout closed (>&-) logs Bad file descriptor at the exec and still creates and wires. This is not a regression: the old top-level exec had the same exposure.
  • No leak into children. I checked /proc/<pid>/fd through PATH shims:
    • every node_run, install-hooks.mjs, node -p and the stub tsx: 0 1 2 only
    • the probe's claude -p: no fd 7, except the caller's own fd 7 when the caller opened one, which is ordinary inheritance
  • Short-lived cat/mktemp/rm in the exit handler do inherit fd 7. That is harmless, because none of them can detach.
  • The fallback when fd 7 is not open can only trigger in the two-statement window between MEMORY_IN_EXIT=1 and exec 7>&1. That is not a real case.

.. refusal (AGENTS_HOME must already be absolute, a check that existed before this round)

  • Refused, with SCAFFOLD ERROR (rc 1) and nothing created: trailing /.., l/.. and l/../.. through a symlink, sub/../ with a trailing slash, and --agents-home <l>/... Relative values such as ../x were already refused as not absolute.
  • Accepted, with the files landing where the path says: ./ components and a trailing /., //, and directories literally named a..b, ... and %2e%2e. The kernel does not decode percent forms, so %2e%2e cannot bypass the check.
  • Two remaining effects:
    • A HOME containing .. with the default agents home is refused. That is fail-safe, not a bug.
    • INBOX_ROOT is not covered by the .. check, but the inbox is not a settings path.

Earlier exploits re-run against the real scripts/install.sh and install-hooks.mjs from the memory layer's main (05c47be). I used throwaway HOMEs, stub hook scripts and a stub tsx.

  • Hard link at settings.json.the-brain.tmp, and a symlink at .the-brain.bak: memory off (... symlink or hard link; nothing written). The global file is unchanged.
  • agents/wren -> $HOME: SCAFFOLD ERROR.
  • Agents home set to the parent of HOME, with the agent named home: SCAFFOLD ERROR.
  • Existing hard-linked settings.json: SCAFFOLD ERROR. The global file is unchanged, with nlink 2.
  • $HOME/.claude -> agents/wren/.claude, and CLAUDE_CONFIG_DIR pointing at it: SCAFFOLD ERROR.
  • A hard link planted at the .tmp name inside install.sh: PARTIAL, with no USER_NAME stamped. As documented, the global content is replaced.
  • First creation under a symlinked ancestor with a trailing slash: memory on.
  • Failing tsx: off (... settings restored, nothing wired), and the verified rc of 0 is kept.
  • Exit codes are unchanged: 0 verified, 1 scaffold, 4 with --no-verify, 143/130 on a signal.

The INSTALL.md and SPEC changes are accurate. The "whichever way a link points" claim is gone, and both same-user limitations are stated. I found no false safety claim.

Findings: none.

CI on 823d230: all four checks completed with success: test (22.x), test (24.x), guards and licence. Locally: vitest run test/create-agent.test.ts passes 74/74, and pnpm check:leaks is clean (437 files, 33 rules).

Unverified:

  • macOS, or a case-insensitive filesystem
  • a real terminal Ctrl-C (only kill to the PID was tried)
  • silo seeding through a real tsx agent init (no built checkout)
  • a hanging installer (there is still no timeout)
  • non-root EACCES
  • that the new detach test fails without the fix (taken from REVIEW.md, not re-run)
  • the Claude-Session trailers on f76901c and 54efe35 remain a squash-merge concern, already known

Generated by Claude Code

…the run first (#21)

Replace the runtime-assembled gated name with neutral installer-style names, and
assert exit status, the installer call, the memory line and the wired hooks
before the timing assertion in the detached-child test. REVIEW.md and SPEC
updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Focused review of head cd07102 (round 8: test changes in b0b1469, plus a docs commit). I looked only for real bugs and regressions.

Verdict: approve. No findings.

(a) Leak-gate evasion

  • I grepped every added line in the full main...HEAD diff for join(, concat, fromCharCode, atob/btoa/base64, Buffer.from, \x/\u/octal escapes, String.raw, reverse(/split(/slice(, quoted + concatenation and rev/tr. No gated name is built at run time anywhere: not in the tests, the fixture installer, create-agent.sh, INSTALL.md, SPEC or REVIEW.md.
  • The only remaining hits are ordinary path operations (path.join, split(path.sep), rest.reverse() in the containment helper) and the random stamp-file name.
  • The memory layer's repo or silo name appears nowhere in the added lines.
  • scripts/ and package.json are untouched in the diff, so the gate and its rules are unchanged.
  • node scripts/leak-gate.mjs is clean (437 files, 33 rules), and --self-test passes.
  • --messages flags only the two known commits (f76901c, 54efe35). No new commit carries a Claude-Session trailer.

(b) Neutral names

  • The guard does not depend on the name. It refuses on any symlink or nlink > 1 entry in .claude, and on any pre-existing settings.json.*. So settings.json.installer.tmp/.bak exercise the same code paths as before, and settings.json.stray still covers the plain-file case.
  • I re-checked against the REAL scripts/install.sh + install-hooks.mjs + lib/merge-hooks.mjs from the memory layer's main (05c47be). I used throwaway HOME and agents dirs, stub hook scripts and a stub tsx. The tmp and backup names were read out of install-hooks.mjs (lines 93-95):
    • baseline: memory on, three hooks wired, USER_NAME stamped, exit 4
    • symlink at the real tmp name: refused, nothing written, victim unchanged
    • dangling symlink at the real backup name: refused, no target created
    • symlink at the real backup name: refused
    • hard link at the real tmp name: refused, victim unchanged
    • hard link at the real backup name: refused, victim unchanged

(c) Detached-child test

  • The test can no longer pass on an early failure. It needs exit 4, CREATED wren, the fixture's calls.log, memory on and all three hooks before it checks the time.
  • I removed 7>&- from the installer call (create-agent.sh:711) locally, and the test fails at the timing assertion: expected 3600 to be less than 2500. Without the fix the time cannot go below 3 s, because the 3 s sleep starts only after scaffolding. So it fails for real, not just slowly.
  • With the fix the test takes 483 ms locally, about 5x headroom under 2.5 s. I don't consider it a real flake risk.

(d) Regressions and scope

  • The round diff touches only create-agent.test.ts, REVIEW.md and SPEC.md. The whole PR touches the five intended files.
  • Locally: create-agent.test.ts passes 74/74, and full pnpm test passes (2227 passed, 11 skipped). Typecheck, boundaries, lib-version and licence pass, and there are no en or em dashes in the added lines.

CI on cd07102: test (22.x), test (24.x), guards and licence all completed with success.

Unverified or known:

  • Silo seeding through a real tsx agent init: no built checkout, a stub was used.
  • macOS.
  • Claude-Session trailers on f76901c and 54efe35: already known, and need stripping on squash.
  • --history still sees intermediate branch blobs, the earlier runtime-joined name and the REVIEW.md commit-id citations that later commits fixed. A squash merge drops them. CI does not run that scope.

Generated by Claude Code

@simon-inkie
simon-inkie merged commit 370d31a into main Oct 16, 2026
4 checks passed
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.

2 participants

0