Environment setup script has drifted to a 264-byte stub — three of its four jobs are not being done

[bdelanghe]

The environment's setup-script field no longer matches the canonical text in .claude/README.md. It is down to 264 bytes — per Running initialization script {"script_length":264} in /tmp/env-manager.log — which is just the settings.json heredoc. Everything the canonical script does after writing that file is gone.

Filed as the follow-up to #84, which makes a session survive one of these but does not remove the need to fix the field.

Observed in a four-repo session, 2026-08-01

canonical step	state	consequence
write $HOME/.claude/settings.json	✅ done	dispatcher runs; repo hooks fan out correctly
node $BOOT/register-mcp.mjs	❌ missing	~/.claude.json had mcpServers: null — no MCP tools at all
cp $BOOT/stop-hook-git-check.sh	❌ missing	the stock Stop hook is installed; infra#112 is live again
CLAUDE_SESSION_ROOT=$ROOT on the hook command	❌ missing	benign today, load-bearing in the fallback path

Verified:

$ sha256sum .claude/stop-hook-git-check.sh /root/.claude/stop-hook-git-check.sh
d124f7e8844ce1bd…  .claude/stop-hook-git-check.sh          (5458 bytes — matches SUM_stop_hook_git_check_sh)
1e1c49718621d862…  /root/.claude/stop-hook-git-check.sh    (3262 bytes — the platform's stock hook)

$ cat /root/.claude/settings.json
… "command": "node /home/user/.github/.claude/session-start-dispatch.mjs"    # no CLAUDE_SESSION_ROOT

What it cost

A session asked "what should we work on next?", found no next tool, and ranked the org's work by hand from list_issues / list_pull_requests — the one move front-desk-scheduler's CLAUDE.md forbids in its opening paragraph. The answer looked exactly like a Front Desk answer. Nothing in the session said the tool was missing.

Note how little of the machinery was actually broken: the dispatcher ran, every repo's hook ran, deno / dolt / node_modules were all present, and the MCP server started cleanly when invoked by hand. One absent line in a field no reviewer and no gate can read.

The stop-hook-git-check.sh regression is the same shape and has been quieter — the stock hook scopes its check to origin/<branch>..HEAD, so it warns "Unverified" after every squash merge and advises an --amend that would rewrite already-merged history. That is exactly the infra#112 bug the repo copy exists to fix.

Fix

Restore the field to the script in .claude/README.md under Install. That file is explicitly the canonical text for this purpose: "If the two drift, this file is what the field should be returned to."

The part that stays open after that

Nothing detects this. It is the third recurrence of one failure mode:

• infra#122 — logic in an unreviewable place, no drift gate
• register-mcp: register each repo's MCP servers at user scope #71 / bootstrap: verify fetched scripts before executing, and bump the pin #72 — the pin and its digests, hand-maintained, both wrong inside one afternoon → fixed by bootstrap-pin.test.mjs
• this one — the field itself, which no test can read

#84 narrows it: the dispatcher now re-runs register-mcp.mjs and warns when it had to, so that line going missing is self-healing and loud. The other two steps have no such backstop, and the general problem — a bootstrap field that can silently lose lines — is unsolved.

Worth considering, roughly in order of cost:

1. Have the dispatcher compare the installed stop-hook-git-check.sh against the repo copy and re-copy on mismatch, the way session-start: register MCP servers from the dispatcher when the setup script did not #84 does for MCP. Cheap, and closes the second row of the table.
2. Have the dispatcher emit one line naming which canonical steps it can detect were skipped, so drift shows up in the session log rather than in a hand investigation.
3. Reduce the field to a single exec of one versioned script, so there is less surface to lose. It cannot go to zero — something has to name the entry point — but a one-line field either works or fails loudly, with no partial state.

Option 3 is the real fix and the biggest change; 1 and 2 are worth doing regardless, since they hold the line for whatever the field looks like.

[bdelanghe]

Can the field be deployed instead of hand-edited?

Checked the docs rather than assuming. No — it is UI-only, and there is no API, CLI, or repo-committed form. Recording the citations so nobody re-researches this:

Create, edit, and archive environments from the environment selector at claude.ai/code […] There's no settings page or direct URL for the selector.

/remote-env only sets the default: it doesn't start a session, and it can't add or edit environments. Manage them at claude.ai/code.

Setup scripts are listed as environment configuration alongside network access and env vars, all edited in the same dialog. Nothing in the docs offers a devcontainer-style file, an environments API, or any other programmatic path. So "make CI own this field" is not available, and option 3 in the body — shrink the field so there is less to lose — is the best that can be done to the field.

One useful detail for whoever fixes it: editing the setup script invalidates the environment cache and re-runs the script. So the fix is one UI action that propagates to every subsequent session, not something needing per-session repair.

Option 4, better than 3: delete the field instead of shrinking it

Server-managed settings look like they can carry the SessionStart hook outright, which would remove the reason the field writes $HOME/.claude/settings.json at all:

All settings available in settings.json are supported except those restricted to OS-level policy delivery […] This includes hooks, environment variables, and managed-only settings

Endpoint-managed settings don't reach cloud sessions, so organizations using Claude Code on the web should configure server-managed settings as well.

That is the opposite of the usual caveat and the reason this is worth trying: managed settings are one of the few centrally-controlled surfaces that does reach a cloud session. One org-level SessionStart hook pointing at /home/user/.github/.claude/session-start-dispatch.mjs would apply to every environment and every member, with no per-environment field to drift.

Not free, and unverified — nobody has tried it here:

• Still authored in a UI (admin settings), Owner/Primary-Owner only. It is one place instead of one per environment, not version control.
• Teams/Enterprise plans only.
• Hook definitions trigger a security approval dialog, and "if a user rejects the settings, Claude Code exits". Behaviour in a cloud session needs checking before relying on it.
• It can only point at the dispatcher, never fetch it — so this replaces the settings.json write, not the digest-verified fallback, and only works with .github attached. The dispatcher's contract already requires that.

Worth one experiment: set it for one environment's worth of users, start a session with an empty setup script, and see whether the dispatcher runs.

What stays irreducible either way

Something outside the repos has to name the entry point. The hook that could self-heal a missing hook is the thing being installed, so there is no bootstrap from nothing. The goal is not zero — it is one line that either works or fails loudly, instead of four steps where losing one is silent. That is what this issue is about, and #84 only closed the first of the four.

---

Generated by Claude Code

[bdelanghe]

Decision: restore the field now; treat server-managed settings as a later experiment, not a blocker

Reasoning, so the choice is auditable rather than just made:

1. The restore is safe, known, and one UI action. The canonical text is on main, its pin is current (7ee3d5cc6416), and all three digests verify against the git objects at that pin. Editing the field invalidates the environment cache and re-runs the script, so it propagates to every subsequent session with no per-session repair.
2. Option 4 (server-managed settings) is unverified on two load-bearing points — whether the hook-approval dialog fires usably in a cloud session, and whether the org's plan tier even carries the feature. An unverified route must not gate an available fix; that would be a fresh instance of I4 (building on an undated "should work").
3. They compose. Restoring the field costs nothing if the experiment later succeeds — the experiment's success criterion is "empty the field afterwards", not "never fill it".

Steps (Owner, one time): claude.ai/code → environment selector (cloud icon above the message box) → hover the environment → gear → Setup script → replace contents with the canonical block from .claude/README.md § Install, as of main@6170e3b or later → save.

Verification, next session in that environment — all three lines should be absent from the session log:

session-start-dispatch: WARN registered MCP server(s) the setup script did not
session-start-dispatch: WARN installed the Stop hook the setup script did not
bootstrap: WARN ...

The dispatcher's fallbacks (#84, #88) stay silent when the field has done its job, so their silence is now the health check for this field. If either WARN still appears after the restore, the field text drifted again — return here.

The server-managed-settings experiment stays recorded in the comment above as option 4, to be run whenever someone with Owner access has an idle half hour; #91's manifest is unaffected either way.

---

Generated by Claude Code

[bdelanghe]

Both fallbacks fired in production, 2026-08-03 — unprompted, and observed after the fact

Not a fixture run. A real cloud session resumed into a fresh VM this morning and repaired itself, exactly as #84 and #88 intended. The filesystem timestamps are the record:

2026-08-03 15:36:35   VM boot
2026-08-03 15:36:41   /root/.claude/launcher-settings.json   (platform)
2026-08-01 12:22:55   /root/.claude/settings.json            ← NOT rewritten
2026-08-03 15:36:44   /root/.claude.json                     ← front-desk registered
2026-08-03 15:36:44   /root/.claude/stop-hook-git-check.sh   ← 5458 bytes, matches the repo

Read the third line first. settings.json still carries its 2026-08-01 mtime, two days before this boot — so the setup script did not run at all on this VM. That is the environment cache working as documented: the snapshot was taken on Aug 1 after the (stub) script completed, and later sessions restore it and skip the script entirely.

So the snapshot restored the degraded Aug 1 state — mcpServers: null, stock 3262-byte Stop hook — and three seconds after boot both were correct. Nothing else runs in that window. The dispatcher did it.

Verified in-session afterwards:

$ node -e '…mcpServers…'                    → [ 'front-desk' ]
$ syncStopHook()                            → "current"    (already correct, nothing to do)
$ sha256sum vs .claude/stop-hook-git-check.sh → identical

What this changes

I1's grade is better than recorded. session-capability-invariants.md grades it Partial on the strength of unit tests and scratch-directory runs. It now has production evidence on real degraded state, which is a stronger claim than any test in the suite — the repair path ran without anyone invoking it, against the exact failure it was written for.

And it sharpens the argument for fixing the field anyway. The cache means a stub field is not merely wrong, it is inert — it does not even execute on a cached boot, so nothing about it will drift back toward correct on its own. Editing the field is what invalidates the cache and re-runs it, which is why the restore in the comment above is a real action and not a formality.

The verification recipe in that comment still stands, with one correction. I said the dispatcher's WARN … the setup script did not lines should be absent once the field is restored. That remains the test — but note that on a cached boot they will be absent for the wrong reason, since the script never ran to be compared against. Check after a boot that actually re-ran the script, i.e. the first session started after saving the field.

---

Generated by Claude Code