Repository navigation
v5.1.2 — The One Where the Restart Nudge Finally Shuts Up
What this release is about
When your brain asked you to restart Claude, doing exactly what it asked did not make the request go away. This release ends that.
Your second brain updates itself in the background. When it does, the conversation you are in is still
running the older version, so it tells you: close Claude, reopen it, and come back to this same
conversation. That message is deliberate and it matters, because until you restart, your brain cannot
use what the update just installed.
The trouble was that it had no way of noticing you had obeyed. Coming back to a conversation does not
count as starting a session, and starting a session was the only moment the reminder was cleared. So
for some people the message came back on every single reply, in front of every answer, with no way out
short of deleting a hidden file. It was never wrong about the update, only unable to see that you had
already done your part.
Now it can. Your brain remembers which running copy of Claude asked for the restart, and stops the
moment it is talking to a different one.
What you get
In ordinary conversations, right away
- 🤫 The restart reminder stops when you restart. Quit Claude, reopen it, return to the very same
conversation, and it is simply gone. Nothing to delete, nothing to type. - 🔔 And it still speaks up when it should. A reminder that has not been acted on stays, message
after message. Silence has to be earned by an actual restart, never assumed: being told nothing when
your brain is running old code is the worse of the two failures. - 💬 Opening a fresh conversation is no longer the secret way out. It worked before, and nobody was
told. Now the instruction you are given is the one that works.
When you update your brain
- ⚙️ Nothing changes in how updates run. Same command, same report, same promise that your notes,
your keys, your constitution and the skills you tailored are left alone.
What you have to do
Ask your brain to update its engine (/update-engine), say yes, then restart Claude once. That last
restart is the thing this release just made honest.
Under the hood
The mechanism. .cache/restart-needed is the marker that drives the reminder. It is armed by the
session self-heal, by the updater and by the startup pull, and it was read on every prompt by the
UserPromptSubmit hook. Its only eraser was a SessionStart self-heal that found no convergence gap
— and resuming a conversation runs no SessionStart. The directive's own wording ("come back to THIS
same conversation") therefore guaranteed the marker's survival.
Why the obvious fix was measured, and rejected. The first attempt asked the search server to stamp
a boot trace, on the theory that a full quit respawns it. A rehearsal in Claude Desktop on a throwaway
brain, on 2026-09-08, disproved it: opening a new conversation without quitting anything also
respawns a server and stamps an indistinguishable trace. A verdict built on that would have gone
silent on a reminder that was still true — a false alarm traded for a silent one, which is worse. The
instrument was write-only precisely so this could be found out safely, and it has since been removed
(7d8980b), because the fix that shipped never reads it.
What the same readings handed over. Across three readings exactly one thing discriminated: the
Claude application process. It changed on a real ⌘Q and held across a new conversation. The hook
that repeats the reminder runs inside the conversation process, whose ancestor is that application,
so it reads the identity itself — no trace file, no second writer, and no SessionStart needed.
scripts/lib/claude-app-identity.mjs walks up from process.ppid through one read of the process
table; the marker records the app that armed it; the prompt hook compares, stays silent when they
differ, and erases the stale marker so the rest of that conversation costs nothing.
The detail the whole fix hangs on. The per-conversation process lives at
…/claude-code/<version>/claude.app/Contents/MacOS/claude, which differs from the application's own
path only by case. The match is therefore case-sensitive and additionally refuses anything under
/claude-code/. Matching it would have called every new conversation a restart, which is exactly the
silent failure the measurement existed to prevent.
Failing towards the reminder, everywhere. No identity in the marker, none resolvable now (every
CLI session, every platform the match does not cover), a marker written by an older engine as prose,
an unreadable file: every one of those keeps today's behaviour. And only the marker half is ever
disarmed — a convergence gap is present tense, and no restart installs a skill still sitting on disk
uninstalled.
Verification. Scripts suite 3268 green, RAG suite 539 green, CI green on Linux, macOS and Windows.
A regression test replays the lived sequence through the hook's own entry function against a real brain
folder: marker armed, app restarted, no SessionStart, two prompts, silence. The field rehearsal
(CONVENTIONS §10ter) ran on copies of two real brains, one installed at v3.4.0 and one at
v5.1.1; both converged to v5.1.2 and both reported owner territory byte-identical.
Marketing surface re-read (CONVENTIONS §10). Nothing became false. One sentence became true: the
README's "it says so… until you close and reopen" was a half-truth until today, since coming back to
the same conversation never stopped it. No board copy affected, no re-render.
Issues (CONVENTIONS §10bis). Nothing closed by this tag, deliberately. #90
is the defect fixed here and stays open until the fix has run on a real owner's brain — its evidence is
field evidence, and a rehearsal brain, however faithful, is not the field. #92
(shipped in v5.1.1) stays open for the same reason. Every other open issue was read and none is covered
by this release.
Engine versions. scripts 1.16.0 → 1.17.0. The search engine and local-mirror are byte-identical
to v5.1.1 and their versions do not move.