I've added a hidden entire checkpoint create [session-id] command. It prints the new checkpoint ID, or with --json returns {checkpoint_id, session_id, resolution}. Unit tests, lint and a Windows vet pass; nothing is committed yet.

How it behaves

• Picking the session: with an argument, it validates the ID and uses it. Without one, it only proceeds if the agent's session was actually identified, from its session environment variable or from process ancestry. If the lookup would fall back to "most recent session in this worktree" or anywhere in the repo, it refuses and asks for an ID, because that guess can name someone else's session. It also refuses when the agent names a session Entire has no state for yet.
• Writing the checkpoint: it goes through the same code path a commit's checkpoint uses, so extraction, redaction, summary generation (if enabled) and the store write are unchanged. It uses the live transcript when that's newer than the last saved step, so a call mid-turn includes the current turn. Redaction setup fails closed.
• Queueing: the store write already puts the checkpoint in the push queue (git-refs backend) or on the checkpoints branch as an unpushed commit (branch backend), so there's no extra push step.
• Snapshot, as you chose: the session state is loaded, used, and never saved back. The next commit's checkpoint covers the same work again, and a mid-turn call can't interfere with the agent's own hooks. I also skipped skill telemetry here, because the next commit would otherwise count those events a second time.
• No commit link: the checkpoint isn't tied to any commit, the same way checkpoints created by entire doctor aren't.

The code is in strategy/manual_commit_snapshot.go and cli/checkpoint_create.go, and the command is registered in checkpoint_group.go.

Tests

• Strategy tests check three things:
  • The checkpoint includes a turn that exists only in the live transcript, and the secret in it is redacted.
  • The session state is identical before and after.
  • An unknown session and an empty session both give errors.
• Command tests cover:
  • The caller's session being resolved and returned in --json.
  • The worktree-guess and untracked-caller refusals.
  • Invalid, unknown and empty session IDs.
• Mutation check: I turned off the refusal check and confirmed the refusal test then fails.

Not run: mise run check, the integration tests, and a live run from a real agent session. I didn't run it against this repo because it would create a real checkpoint that goes out with your next push.

Decisions for you

• Agent-help entry: I listed checkpoint create as user-owned and unlisted, which is the repo's safe default; being hidden, it isn't advertised to agents anyway. If agents are meant to call it on their own, it needs to be task-driven, and the "never create checkpoints by hand" line that Entire injects into agent sessions would need rewording.
• Overlapping checkpoints: because of the snapshot choice, the same prompts will show up in both this checkpoint and the next commit's checkpoint in the web UI.
• Disabled repos: if Entire is disabled in a repo, the command prints the usual disabled message to stdout and exits 0, even with --json. Other commands do the same.

The finding was correct, and snapshot checkpoints no longer record code attribution. Lint is clean and the cli and strategy unit tests pass; nothing is committed yet.

The bug: attribution compares the saved agent work (the session's shadow branch) against HEAD. It assumes HEAD holds the work that was just committed. A snapshot creates no commit, so HEAD is still the commit from before the agent's work. Uncommitted agent changes therefore looked like human edits. The new test showed it: the agent's one-line edit was stored as HumanModified: 1, AgentLines: 0, 0% agent.

The fix: I took the finding's first option and left attribution out. Comparing against some other tree would still have produced numbers for a commit that doesn't exist.

• condenseOpts in manual_commit_condensation.go has a new noCommitAttribution flag. When it's set, the attribution calculation is skipped and the checkpoint stores no attribution. That's the same thing the existing error paths store when attribution fails.
• Only CreateSnapshotCheckpoint sets the flag, so commit, doctor and session-end checkpoints are unchanged.
• The per-prompt attributions come from session state rather than comparing against HEAD, so they're still recorded.

Test: TestCreateSnapshotCheckpoint_RecordsNoCommitAttribution uses an existing test setup whose saved agent work contains an uncommitted edit, and checks that the stored attribution is nil. It fails without the flag and passes with it.

Code attribution for this work still gets recorded: snapshots leave the session's own tracking alone, so the next real commit calculates it as usual.

mise run check is running in the background. I'll commit and push once it finishes.

The change is committed and pushed to soph/checkpoint-create as a single commit (bef1c24d0d); I haven't opened a PR.

• Before committing: the repo's full mise run check passed (format, lint, unit, integration and the canary end-to-end test).
• What's in it: only the seven files for this change. The working tree was clean after the push.
• Trail findings: the repo's post-push step is to check the PR trail's findings, but that only applies once there's an open PR. When you open one, I can go through those findings.

entire agent-help <name> now runs entire-<name> agent-help whenever <name> isn't a built-in command and that plugin is installed. It's on a new branch, soph/agent-help-plugin-delegation, off origin/main, because it's unrelated to checkpoint create. Nothing is committed yet.

How it works: an agent running entire agent-help pgr sync --json gets entire-pgr agent-help sync --json. The --json flag is added back because agent-help consumes it as its own flag. The plugin writes directly to the terminal, just like a normal entire pgr run.

Why not a bare exec.LookPath: I reused the plugin lookup and launch functions that entire <name> already uses (resolvePlugin and runPlugin in plugin.go). A bare lookup plus exec would have bypassed the environment filter and handed the plugin our full environment, tokens included. Going through the existing code keeps these behaviours:

• Built-in commands still win over a plugin with the same name.
• agent- names stay reserved for the agent protocol, and bad names are rejected.
• A plugin file that isn't executable is reported as a launch error rather than "unknown command".

Deliberate differences from running a plugin directly:

• No install offer: for graph and investigate, a missing plugin is normally offered for install. Here it just reads as an unknown command, because agents run agent-help unprompted and a help lookup shouldn't end in a download.
• No telemetry or version notice: the plugin was only asked for help, not run as a command.
• CLI only, not MCP: the MCP agent_help tool doesn't delegate. The plugin writes to the process's stdout, and under entire mcp that's the MCP protocol stream, so plugin output would corrupt it.
• Exit code: a failing plugin makes agent-help exit 1 without printing a second error. It doesn't pass through the plugin's own exit code, because that would need a change to main.go.

Tests:

• Unit tests cover the delegated arguments, a failing plugin, every case that should fall through to "unknown command", and the missing-plugin case not triggering an install.
• Integration test: it runs through the real binary and checks that the plugin's output comes through and that GITHUB_TOKEN doesn't reach the plugin. With delegation switched off it fails with "unknown command".
• Also passing: the full cli unit tests, the external-command integration tests, lint, the docs check and a Windows vet.

I also added a section on this to docs/architecture/external-commands.md, so plugin authors know what shape their agent-help verb needs.

Not done: the "External commands" heading in bare agent-help. The difficulty is that a plugin being on PATH doesn't tell us it has an agent-help verb. Listing every entire-* binary would point agents at commands that may just fail. Two options:

• List only plugins installed through entire plugin install, whose install records we could extend to say they support agent help.
• Run each plugin's agent-help to check, which costs a process launch per plugin on every bare call.

Which do you want? I can also commit and push this branch the same way as the last one.

mise run check is running in the background. I'll commit and push when it finishes.

The agent-help delegation is committed and pushed to soph/agent-help-plugin-delegation as one commit (e1035d1c56); I haven't opened a PR.

• Before committing: mise run check passed with no failures, including the new integration test.
• What's in it: the four files for this change, and the working tree is clean.
• Postponed: the "External commands" heading in bare agent-help and passing through the plugin's own exit code.

The PR is open at https://github.com/entireio/cli/pull/2599. I'll force-push the stacked checkpoint-create once the check finishes, then look at the new PR's trail findings.

The trail has one open finding on #2599 (low severity, 0.45 confidence), at agent_help_cmd.go:512.

The finding: code, _ := runPlugin(...) throws away killedBy. If a plugin is killed by a signal that didn't also cancel our context, agent-help exits 1 instead of the conventional 128+signal code that entire <plugin> produces.

My read: it's real, and there are two concrete ways to hit it.

• entire agent-help pgr | head -1 kills the plugin with SIGPIPE, so we exit 1 instead of 141.
• If Ctrl-C kills the plugin before our signal handler cancels the context, ctx.Err() is still nil and we exit 1. The shell then doesn't see a signal exit, so an enclosing while loop doesn't break on a single Ctrl-C.

Why it's open: it's the same gap as the exit-code propagation you just postponed. From inside the command, the only way back to main is a returned error, and main turns any error into exit 1. The fix is the same small main.go change either way: a typed error carrying the exit code or signal, which main handles the way it already does for plugins run as entire <name>.

Which do you want?

1. Fix it now in #2599. Adding that error type covers both the signal case and exact exit codes, so the postponed item goes away too. It's about 20 lines plus a test.
2. Dismiss it as deferred, with a note pointing at the postponed exit-code follow-up.

I haven't touched the finding, since resolving or dismissing it posts to the trail.

Everything else is done:

• PR: https://github.com/entireio/cli/pull/2599, soph/agent-help-plugin-delegation into main.
• Stack: soph/checkpoint-create is rebased onto it, so its only commit is now dfb704b621 on top of e1035d1c56. mise run check passed on the stacked tree before I force-pushed.

I went through the four open items on PR #2599. The Cursor one is a real bug, and I've fixed it locally, uncommitted. Two others needed only a docs fix and a clarification, and the last is a conversation you've already answered.

1. Cursor, high: plugins installed with entire plugin install aren't found. Real bug, fixed.

• Cause: main.go adds the managed plugin directory to PATH only while it checks for entire <plugin>. It removes it again before any command runs. So by the time agent-help looks up the plugin, only plugins elsewhere on PATH are visible. My tests only used those, which is why they passed.
• Fix: delegation now adds the managed directory back for the lookup and the plugin run, then restores PATH. The plugin inherits the extended PATH, just as it does when run as entire <plugin>.
• Tests: a unit test and an integration test through the real binary. Both fail without the fix and pass with it.

2. Copilot, medium: the version notice still fires. The claim was right; I corrected the docs, not the behaviour.

• The notice comes from the check every non-hidden command runs after it finishes, and it already fires for built-in agent-help lookups. It goes to stderr, so it doesn't touch the plugin's output. Suppressing it only for plugin lookups would make agent-help inconsistent with itself, and Copilot suggested revising the contract as an alternative.
• The false line was mine: the code comment and the external-commands doc said no version notice fires. Both now say agent-help's usual after-run behaviour still happens.
• That behaviour includes command telemetry, so I checked it: it records only the command path and flag names, never positional arguments. A third-party plugin name therefore can't leak through it, and the docs now say so.

3. Copilot, overview only: plugin-specific flags are rejected. True, but the same as built-ins, so no code change. On a real build, entire agent-help pgr --verbose fails with unknown flag: --verbose, and --json is forwarded. entire agent-help checkpoint --verbose fails the same way: agent-help takes a command path, not flags. Letting unknown flags through would mean turning off Cobra's flag parsing for agent-help as a whole. I've made the docs say it takes a command path and that other flags are rejected before the plugin is consulted.

4. The contributor thread. MuskanPaliwal offered to pick up the "Not in this PR" items and you declined, so there's nothing for me to do there.

Lint, the full cli unit suite, the new integration tests and the docs check pass. I haven't run mise run check, since I haven't committed.

I haven't replied to or resolved any of the comments, and the trail finding about the dropped signal is still open. Should I run mise run check, commit and push this? After that I'd re-check the trail findings, and rebase soph/checkpoint-create onto the new commit so the stack stays linear.

There are two unresolved bot threads, and the trail still has only the one open finding (the dropped killedBy signal). Once the check passes, I'll push and look at the trail again, since it re-reviews after a push.

mise run check is still running, and I'll commit and push once it passes. I'll wait for it to finish.

The first mise run check failed in TestDiscoverAndRegister_FindsAgent, a package my change doesn't touch. It passes on its own, so it looks like a timeout under load. The full check is re-running now, and I'll commit, push and resolve the two bot threads once it passes.

The fixes are pushed to PR #2599 as 0fe06f5fb8, and I resolved both bot threads without replying. Your thread with Muskan is untouched.

• Cursor thread: the fix for plugins installed with entire plugin install not being found is in this commit.
• Copilot thread: the version-notice claim was right about my docs. The commit corrects the contract text instead of suppressing the notice.

Checks before committing: mise run check failed twice, each time on a different test in packages this change can't affect.

• TestDiscoverAndRegister_FindsAgent in agent/external hit its 10-second timeout.
• REDACTED in dispatch also failed.
• Both pass when run on their own, and the machine's load average was 32–40, which fits flakes caused by load.
• Everything else passed on the final run: fmt, lint (0 issues), the cli package, and the integration tests including the two new ones.

I committed without a fully green check. If you'd rather have one, I can re-run it once the machine is quieter.

Trail: there's still only the one open finding, the low-severity dropped killedBy signal at agent_help_cmd.go:512. The trail may not have re-reviewed the new push yet, so it's worth checking again later. That finding still needs your call: fix it now with a small exit-code error type in main.go (which also covers exact exit-code propagation), or dismiss it as deferred.

Stack: soph/checkpoint-create still sits on the previous commit (e1035d1c56). I can rebase it onto 0fe06f5fb8 if you want it current.

soph/checkpoint-create is rebased onto the new agent-help commit (now 69d3875e6f) but not pushed yet. mise run check is running on the stacked tree, and I'll force-push once it passes.

soph/checkpoint-create is rebased onto the latest agent-help commit and force-pushed. It's one commit (69d3875e6f) on top of the branch behind PR #2599. mise run check passed on the stacked tree before the push, with no failures.

One thing still needs your call: the open trail finding about the dropped killedBy signal. Either I fix it now with a small exit-code error type in main.go, which also gives exact exit-code propagation, or it gets dismissed as deferred.

The fix is in and tested, and mise run check is running. Once it passes I'll commit and push, resolve the trail finding, update the PR description's exit-code lines, and restack checkpoint-create.

The fix is pushed and the trail finding is resolved. soph/checkpoint-create is rebased locally, and I'll force-push it once mise run check passes on the stacked tree.

I fixed it, and it's pushed to PR #2599 as 0e1685bb19. entire agent-help <plugin> now exits the same way entire <plugin> would, instead of always exiting 1. This also covers the exact exit-code passing you'd postponed.

The fix:

• Error type: agent-help returns a new error type, PluginExitError, that carries the plugin's exit code and the signal that killed it.
• main.go: it exits with that outcome through exitWithPluginOutcome. That function is main's existing plugin-exit handling, moved unchanged so both paths use one copy of the signal-priority rules.
• No duplicate message: the plugin's stderr is the message, so main prints nothing of its own.

Tests: an integration test through the real binary covers three cases. Without the main.go change, all three exit 1.

• A plugin exiting 42 makes agent-help exit 42.
• A plugin killed by its own SIGTERM is re-signalled, so an enclosing shell loop stops.
• SIGPIPE exits 141. My first version of the test expected a re-raised signal, which was wrong: Go ignores a SIGPIPE it sends itself, so it falls back to 141. I checked that entire <plugin> also exits 141 in this case, so the two paths match.

PR and trail:

• mise run check passed with no failures, and I resolved the trail finding with a short note.
• The trail now shows no open findings. It may not have re-reviewed the latest push yet.
• I updated the PR description, since it still said a failing plugin exits 1 and listed exit codes as out of scope. My first edit put a paragraph inside the bullet list; I've corrected it.

Stack: soph/checkpoint-create is rebased onto the new commit (now b7a1493ec1), passed mise run check, and is force-pushed.

PR #2599 is only waiting on an approval. Nothing else has happened since the last push.

• CI: every check is green on the current head (0e1685bb19), including the Windows and integration tests; the Slack notification was skipped.
• Entire Gates: this is the only red check, and the only failing part is "no reviewers have approved this trail". Its CI and findings parts both pass. The PR is marked mergeable but blocked until someone approves.
• Trail #1433: it has no open, resolved or dismissed findings. The re-review after the last push found nothing new. (The trail number isn't the PR number, which is why looking it up as "2599" failed earlier.)
• Reviews: there's nothing new since the Cursor and Copilot reviews of the first commit, and both of their threads are resolved. Cursor and Copilot haven't re-reviewed the later commits.
• soph/checkpoint-create: it has no trail or PR yet, as you asked.

So #2599 needs a human approval, and there's nothing for me to fix. Want me to request a review from anyone?

The description is ready. I'll push and open the PR once the check finishes.

The checkpoint-create PR is open: https://github.com/entireio/cli/pull/2632. It's the single commit 30c1012b5e, rebased onto current main.

• Rebase: #2599 was merged with a merge commit, so only the checkpoint-create commit needed moving. It applied cleanly, and the condensation file it changes hasn't moved on main.
• Checks: lint and the packages this touches (cli, strategy, and the integration tests) pass, and the canary end-to-end test passes. mise run check did fail on one test, TestOpenCodeSeedRepoPlantsDeps. That test needs a local opencode 1.18.30 dependency cache that this machine doesn't have yet. It isn't part of this change, and the PR description says so.
• PR description: it has a section setting out the product calls for reviewers:
  • Hidden and unlisted for agents (user-owned).
  • Snapshot semantics, so the snapshot and the next commit's checkpoint overlap.
  • No code attribution on snapshot checkpoints.
• Trail: it doesn't have one yet, so there are no findings to check. I'll look again once it's created.

Copilot's comment is a real bug, and I've fixed it locally; it isn't committed or pushed yet. The trail has no findings so far, but its review hasn't finished.

Copilot's comment: if redacting the transcript fails at runtime, redactOrDrop logs a warning and carries on without the transcript. That's right for commit hooks, since a commit must never be blocked on redaction. For checkpoint create, whose whole point is the transcript, it goes wrong in two ways:

• Files touched: it writes a checkpoint with no transcript and prints its ID as if it had worked.
• No files: it reports "nothing to checkpoint", which hides the real failure.

Fix: I added an option only checkpoint create sets, failOnRedactionError. With it, a redaction failure returns an error and nothing is written. Commit hooks behave exactly as before.

Test: it forces a redaction failure through the existing test hook for this. It checks that the command errors with the redaction failure (not "nothing to checkpoint") and that no checkpoint is written.

• It fails when the option is turned off.
• The existing tests that expect commit hooks to drop the transcript still pass.
• The full strategy package passes and lint is clean.

Trail #1458: its status is still "reviewing", so it has produced no findings yet. I'll check it again after the next push.

Should I run mise run check, commit and push this, and resolve the Copilot thread?

mise run check is running. When it passes I'll commit, push, resolve the Copilot thread and re-check trail #1458.

The redaction fix is pushed to PR #2632 as f3b1fcd79a, the Copilot thread is resolved, and the PR description now explains the new behavior. The trail has no findings yet because its review is still running.

• Before committing: mise run check failed only on TestOpenCodeSeedRepoPlantsDeps, the same missing local opencode 1.18.30 dependency cache as last time. Everything this change touches passed: lint, cli, strategy and the integration tests. That failure stopped the check before the canary end-to-end test, so I ran the canary separately and it passed.
• Trail #1458: it's still "reviewing" the push I just made, which is why it shows no findings yet. I'll check it once the review finishes.

Answering now; I'm not changing anything. Short version: an agent checkpointing before commit, from a normally started session, is a small change. The session-started-outside-a-repo case is the hard one, and a one-off checkpoint create can't put it into the regular flow. Here's why, and what I think would work.

Why one call isn't enough. Three things drive the regular flow: agent hooks at turn start and end, which save steps and track touched files; the git hook that adds the trailer at commit; and post-commit condensation.

For a session started outside the repo, the first of those never touches the repo:

• Hooks never reach the repo. Entire installs agent hooks into the repo's own agent config (.claude/settings.json and so on). An agent started in ~/ loads ~/'s config, so the hooks likely never fire at all.
• Even if they fire, they exit. They look up the repo from the agent's working directory and return immediately when it isn't an Entire-enabled repo (hook_registry.go, the IsSetUpAndEnabled check).
• So nothing is ever recorded. No session state, no saved steps, no touched files. A call to checkpoint create wouldn't change that: the next turn is just as invisible.

The git hooks do run inside the repo when the agent commits there, but they find no session to link.

What can work: an "enroll" step. The agent runs a command from inside the repo. It writes live session state there with BaseCommit set to HEAD, the transcript path and the owning process, but doesn't mark it ended the way attach does. Commits made after that can then link through the git hooks. The agent identifies itself through its session env var, and since Entire has no state for it yet, that's the "untracked caller" case checkpoint create currently refuses. Here it's exactly the right input: we know which session is calling, and there's nothing to overwrite.

Where it gets complicated:

1. Commits would get a trailer but no checkpoint. Touched files are only recorded at turn end, which never runs, so post-commit has nothing to condense, while the trailer would likely still be added. That's the known "dangling trailer" gap: a trailer pointing at a checkpoint that's never written. Enrollment would hit it on every commit. The fix is either to have post-commit read touched files from the live transcript for enrolled sessions, or to persist the file association the trailer step already finds. That fix has to land first.
2. The session state goes stale. With no turn hooks, phase, prompt counts and last-interaction time never update. The existing sweep that finalizes sessions whose owner exited could cover the end, if enrollment records the owner.
3. Wrong-session risk. It should accept only an agent identified by its env var or process ancestry, never a "most recent session" guess.

The real fix: make agent hooks find the repo from the event or the files touched, not the process working directory. That's the worktree/cwd work I've already measured. It touches seven places in turn end, and moving settings resolution along with it is a redaction-safety risk. It's the right long-term answer, but a big change.

Recommendation:

1. Keep checkpoint create as a snapshot. Checkpointing before commit for a normal session also doesn't need the regular flow. The snapshot already captures the work, the next commit links as usual, and the cost is only the overlap.
2. Treat enrollment as its own, separate feature (session enroll, or a reworked session attach that keeps the session live), to replace attach/adopt for this case. Fix the dangling-trailer gap first, otherwise enrolled sessions would produce trailers pointing at nothing. Enrollment is a moderate change; the trailer fix is the real work.
3. Leave the hook working-directory fix as the long-term fix, not the first step.

One fact would settle how far enrollment gets you. Does the outside-repo session stay outside for the whole session (cd in each command, or files edited by absolute path), or does the agent's working directory move into the repo partway through? If it moves, hooks might start working mid-session, and enrollment only has to bridge the start.

I've checked every item against the code, and nothing is changed yet. Short version: the race is real and the most important fix. The docs item is real. I agree with most of the SHOULDs, with two caveats: marking snapshots in metadata is bigger than it looks, and skipping the summary becomes mandatory once the snapshot holds the session lock.

MUST

1. Redaction cache race: confirmed, and I'd fix it with the lock.

• How it breaks: the cache entry for a session's transcript is written in two steps (storePrefixBytes). First the redacted prefix goes to a payload file whose name is fixed per session, then the entry recording which source prefix that covers is written separately. A snapshot and a post-commit writing at the same moment can leave an entry describing one write's prefix while pointing at the other's payload.
• Why nothing catches it: reusePrefix only checks the source-prefix hash and that the payload ends in a newline. It joins the mismatched pieces, duplicating or dropping lines, then stores the result as the new prefix, so every later checkpoint of that session inherits it. Reads race the same way.
• Only unlocked caller: every other caller holds the per-session lock (PostCommit at manual_commit_hooks.go:1207, doctor, eager condense, the turn-end finalize).
• Fix: run the snapshot inside MutateSessionState and return ErrMutationSkip. That fits the snapshot design: it works on the locked, fresh state and still never saves.
• Why not skip the cache instead: that would re-redact the whole transcript on every snapshot, which was 67s for a 70MB Codex session before the cache existed.
• Cost: a concurrent commit for the same session waits for the snapshot to finish. That's why the summary item below becomes required.

2. Stale docs: confirmed.

• caller-session-resolution.md:91 says "IsCaller() currently guards nothing", which is no longer true.
• security-and-privacy.md:392 says checkpoints are "written locally at commit time". That was already loose, since doctor and eager condense write without a commit, but snapshots make it more wrong.
• checkpoint-implementation.md doesn't mention snapshots.
• I didn't find a line in sessions-and-checkpoints.md that says this outright. I'd still add a short snapshot entry there rather than argue the point.

SHOULD

• Refusal prints the guessed session ID: agree, and it's my mistake. The error says "candidate X; pass a session ID", which practically invites an agent to paste the guess straight back in. The guard can't stop a deliberate explicit ID, but it shouldn't hand one out. I'd drop the ID and say the caller couldn't be identified.
• Mark snapshots in metadata: agree on the problem, but it's a schema change.
  • What's duplicated: token usage and skill events are stored by both the snapshot and the next commit for the same window, so anything summing across checkpoints double-counts. I confirmed the summing within one checkpoint (persistent.go:931), but not which consumers sum across checkpoints.
  • Why it's bigger: the metadata type lives in the shared api/checkpoint package. A flag only helps if the web, entire tokens and the others learn to skip it.
  • Proposal: add snapshot: true with omitempty now, and treat teaching consumers to use it as a follow-up for whoever owns them. The PR should say that explicitly.
• Skip the AI summary: agree, and with the lock it's required. generateSummary is a synchronous model call. Under the session lock it would hold up any concurrent commit for that session for the length of the call.
• Disabled-repo guard: agree. I flagged this in the PR as matching other commands, but id=$(entire checkpoint create) capturing prose with exit 0 is worse than consistency is worth. With --json, or whenever stdout isn't for a person, return an error instead.
• Subagent redaction failure: agree, though it isn't fully silent. A failed subagent transcript is stored without its transcript and with TranscriptUnavailableReason = redaction_failed in the metadata. The command still succeeds, which goes against the reasoning for failing on the main transcript. I'd make it fail the same way.
• Sessions from other worktrees: agree, and I'd refuse them rather than support them.
  • What breaks: Branch comes from the current worktree (manual_commit_condensation.go:752), and settings, and therefore redaction rules, come from the current directory.
  • Why refuse: supporting it properly would mean resolving the session's own worktree and settings, the same hazard as the hook working-directory problem.
  • Change: an explicit ID whose session belongs to a different worktree gets an error pointing at that worktree.
• Cleanup: agree with all four.
  • Use printJSON (corecmd.go:735) instead of my own encoder.
  • Type the JSON field as strategy.SessionResolution with omitempty.
  • The nolint:wrapcheck reason is inaccurate: loadSessionState's error doesn't name the session, so I'd wrap the error instead.
  • Restore redactOrDrop's original signature, since a "drop" function with a fail mode contradicts its name. The snapshot branch would call redactSessionTranscript directly.
• Tests: agree, with one change. Snapshot-then-commit (the next commit still covers the same range), the ambiguous caller and the disabled guard are straightforward. For "concurrent snapshot plus commit" I'd test the mechanism rather than race two processes: hold the session lock in the test and assert the snapshot waits and writes nothing until it's released. A real race test would be flaky and could pass by luck.

Suggested order

1. The lock, with the summary skip.
2. The refusal message.
3. The disabled guard and the other-worktree refusal.
4. Subagent fail-closed.
5. The cleanups and the tests.
6. The docs.
7. Snapshot metadata marker last, as its own commit, since it's the one that touches a shared schema.

Should I go ahead, and do you want the metadata marker in this PR or as a follow-up?

Item 7 is about telling the snapshot and the commit that follows it apart, so their shared work isn't counted twice. Here's what I mean.

The problem. A snapshot deliberately leaves the session's checkpoint window alone. So when the agent later commits, that commit's checkpoint covers the same span of work again. Both checkpoints then store the same:

• token usage (the window since the last commit),
• skill events,
• prompts and transcript range.

Nothing in the stored metadata says the first one was a snapshot.

Where this bites. I checked one consumer here: entire tokens profile lists every checkpoint in the store and adds up their token usage (tokens_profile.go:121 then :180). The store's List returns commitless checkpoints too, so a snapshot plus the next commit's checkpoint would count that window's tokens twice. The CLI's session views (session tokens, sessions) aren't affected, because they read the session-wide total from session state instead of adding up checkpoints.

Why it's a bigger change than the other items. The fix itself is one field: something like snapshot: true (with omitempty) in the per-session checkpoint metadata, api/checkpoint/metadata.go, next to Kind. But:

1. Shared format: that struct is the on-disk JSON format of a checkpoint, and it lives in an exported package (github.com/entireio/cli/api/checkpoint). Checkpoints get pushed, and the entire.io side reads the same JSON. I can't see that code from here, so I can't tell you whether the web or server adds up tokens or skill events across checkpoints the way tokens profile does.
2. No effect by itself: an extra field changes nothing until each consumer checks it. Fixing the double count means tokens profile skips snapshots when totalling, and the same goes for anything server-side that aggregates.
3. Product call: someone has to decide what the web shows for a checkpoint with no commit and an overlapping range. Should snapshots appear in the session timeline, be hidden, or be badged? That's not a CLI decision.

What I'd do.

• In this PR: write the marker, and make tokens profile skip snapshots when totalling, with a test. That fixes the double count I can verify and gives every other consumer a reliable signal to use. Adding an omitempty field is backward compatible: old readers ignore it.
• As a follow-up, outside this repo: whoever owns the server and web aggregation checks whether they add up across checkpoints and decides how to display snapshots. Until then they double-count exactly as they would without the marker. The marker makes their fix possible; it doesn't make anything worse.

One alternative avoids the schema change entirely: don't record token usage and skill events in snapshots at all, and leave them only to the commit that follows. That removes the double count for every consumer at once. The cost is that a snapshot no longer shows the usage of the work it captured, and if no commit ever follows, that usage isn't recorded in any checkpoint. I prefer the marker, but the alternative is simpler if snapshots are meant mainly to preserve the transcript.

Yes, you're right, and that breaks what I proposed. "Skip snapshots when totalling" undercounts whenever no commit follows. That isn't an edge case either: a session that never commits is one of the main reasons to want a snapshot. The "don't store tokens in snapshots" alternative has the same flaw, as I noted, so neither works.

Supersession works where skipping doesn't. A snapshot is only redundant once a later checkpoint covers the same work. Because a snapshot never advances the session's window, that later checkpoint is easy to spot:

• Same window start: a snapshot and the next real checkpoint of that session share CheckpointTranscriptStart.
• The later one includes the snapshot: the commit's token usage is the delta since the last condensation, and the snapshot never reset it, so it already contains the snapshot's tokens.

So the rule is: count a snapshot unless a later checkpoint of the same session has the same CheckpointTranscriptStart.

How that plays out:

The marker is still worth having. It keeps the rule from touching regular checkpoints: only snapshots can ever be skipped, and only when something later covers them. And it says the overlap is intentional, so a consumer doesn't have to infer it from matching offsets.

Two things I'd verify before building it:

1. That only snapshots share a window start. If two ordinary commit checkpoints could share one too (say, a second commit with no new transcript), the marker is what keeps the rule from wrongly dropping one of them, so it becomes required rather than nice to have.
2. That every checkpoint in the comparison carries CheckpointTranscriptStart. It's in the metadata today, but older checkpoints may lack it, and those should simply be counted.

The plan changes accordingly:

• In this PR: add the marker and the supersession rule to tokens profile, with tests for the four rows above.
• The server-side follow-up gets the same rule, not "skip snapshots".

Skill events follow the same rule, since they share the window.

Not quite. Today nothing in a snapshot marks it as one, and the session ID alone isn't enough to deduplicate.

What a snapshot is today. It's an ordinary checkpoint, written by the same code a commit's checkpoint uses, with the same layout:

• A checkpoint ID, with a per-session entry under it.
• That entry's metadata, including session_id, created_at, token_usage, skill events, and checkpoint_transcript_start: the line in the transcript where this checkpoint's own part begins. The stored transcript is the full one; that offset marks where the new part starts.
• The transcript itself, redacted.

The only thing that makes it a snapshot is that no commit carries a trailer pointing at it. You can't see that from the checkpoint: you'd have to scan git history for a trailer naming its ID. So today a snapshot can't be identified from its own data at all, which is why the marker matters.

Why the session ID alone doesn't work. One session normally has many legitimate checkpoints, one per commit, each covering a different slice of the transcript. Deduplicating by session would collapse those, which is wrong.

The actual key is session ID plus checkpoint_transcript_start.

• Each commit condensation moves the session's window forward, so a session's commit checkpoints normally all have different window starts.
• A snapshot doesn't move it, so a snapshot and the next checkpoint of that session have the same window start, and the later one covers everything the snapshot did and more.
• So: among checkpoints sharing (session ID, window start), the latest one wins, and earlier ones are covered by it.

Why the marker is still needed.

1. To find snapshots at all, as above.
2. To keep the rule off ordinary checkpoints. checkpoint_transcript_start is omitempty (api/checkpoint/metadata.go:432). A first window starting at line 0 is therefore stored as absent, and so is the field on old checkpoints written before it existed. Without the marker, "same session, same start" could match two unrelated old checkpoints whose start merely reads as 0. With it, the rule only applies when the earlier checkpoint is a snapshot, and new CLI versions write snapshots, so a missing start on a snapshot really does mean 0.

Proposed definition: a snapshot is a checkpoint whose session metadata has snapshot: true. It's covered, and not counted, if a later checkpoint exists with the same session_id and the same checkpoint_transcript_start; otherwise it counts. I still need to confirm whether two ordinary commit checkpoints can ever share a window start (a commit with no new transcript, say). The marker makes that harmless for counting, but I'd want to know before writing the rule into docs.

Yes, I think it should, and it should be what it is today: the session's current window start. The cleanest way to see a snapshot is as a provisional copy of the session's pending checkpoint, meaning the checkpoint the next commit would write, taken early.

The two choices only differ for a session that also commits. For a session that never commits, such as one started outside a repo, the window start is 0 anyway. The snapshot is then the whole session either way.

Why keep the window start:

• Scope matches everything else in the checkpoint. The window start is what scopes a checkpoint's "own" content: the prompts shown for it, the summary, and the token usage (the delta since the last commit, which the snapshot stores). Those are all already window-scoped. A start of 0 alongside window-scoped tokens would be inconsistent.
• It doesn't repeat committed work. With a start of 0, a snapshot taken after three commits would show all of those commits' prompts again as its own. It would overlap every earlier checkpoint of the session, not just the next one.
• Deduplication stays simple. With the window start, a snapshot overlaps exactly one thing: the checkpoint that will eventually be written for the same window. "A later checkpoint with the same start covers it" is then a complete rule. Without a start, a snapshot overlaps all of the session's history, and counting correctly would mean reasoning about the session as a whole (session totals minus committed parts), not a simple pairwise rule.
• The full transcript is stored either way. The start only marks which part is new, so keeping it costs nothing in what's preserved. Anyone wanting the whole session up to the snapshot still has it.

What dropping it would buy: a self-contained "whole session so far" object that doesn't depend on earlier commit history. But that's an export, a different feature from "checkpoint before commit". If it's ever wanted, it would be better as its own command or flag than a reinterpretation of snapshots.

The one rough edge is the omitempty problem from before: a start of 0 isn't written to the metadata, so it can't be told apart from "unknown". The snapshot marker covers that, since a snapshot written by a new CLI with no start can safely be read as 0.

It's a reasonable guard, but it's worth being clear about what it does and doesn't simplify.

What it would settle:

• The window-start question. Every snapshot would start at 0 and cover the whole session, so "snapshot" and "whole session so far" become the same thing.
• No repeated committed work. A snapshot could never re-show work from earlier commits.
• It still covers the main reason for the feature: sessions that haven't committed yet, including ones started outside a repo that never commit.

What it wouldn't fix:

• The double count with the following commit. A snapshot followed by the session's first commit still overlaps it completely: same session, same window starting at 0. So the snapshot marker and the "a later checkpoint covers it" rule are still needed.
• Anything else on the review list. The lock (the race), the summary skip, the refusal message, the disabled guard, subagent fail-closed and the cleanups all stay the same.
• Repeated snapshots. A snapshot doesn't change session state, so the guard can't see earlier snapshots; it only sees real condensations. Repeated snapshots before the first commit would still be allowed, which is fine since the latest covers the earlier ones.

What it costs: a session that has committed once and then works for a long stretch without committing can't snapshot that newer work. That's the "checkpoint before commit" case you started from, for any session past its first commit.

Detecting it is cheap. Real condensations set LastCheckpointID and move CheckpointTranscriptStart forward (doctor and eager condense do, and I'd confirm the PostCommit path before relying on it). So the check is roughly "refuse if LastCheckpointID != "" or CheckpointTranscriptStart > 0". attach also sets LastCheckpointID, so attached sessions would be refused too, which seems right.

My take: it doesn't remove the hard parts, so I wouldn't choose it for simplicity. I would choose it for the asymmetry: the command is hidden and new, and loosening a restriction later is backward compatible, while tightening one breaks whoever started relying on it. Starting with "only sessions that haven't been checkpointed yet" covers the motivating cases, keeps the window question closed for now, and lets you allow later windows once there's a real need.

If you go that way, the refusal should say why and what to do: "this session already has checkpoints; its work is captured when you commit". Then an agent doesn't just retry with a different ID.

Token counting runs on two tracks: a running count in session state, and a per-checkpoint figure written when a checkpoint is created. Readers pick one or the other.

1. Where the numbers come from (each turn end)

At turn end, lifecycle.go:1089 takes the first available source:

1. Counts reported by the agent's own hook (event.TokenUsage). This is the only source for Cursor, whose transcript has no usage fields.
2. Codex's subagent inventory, for Codex.
3. Counting from the transcript: agent.CalculateTokenUsage(transcript, startLine, subagentsDir), which reads the agent's usage fields from the transcript lines since the turn started, plus subagent transcripts where the agent supports that.
4. An out-of-band fallback for Antigravity, whose transcript has no token data: the turn's usage is the current cumulative total minus a baseline captured at turn start.

SaveStep (manual_commit_git.go:125) then adds that turn's usage to two counters in session state:

• TokenUsage: the whole session, never reset.
• CheckpointTokenUsage: usage since the last condensation, cleared each time a checkpoint is written (resetCheckpointWindow, manual_commit_git.go:535).

If a turn ends with no file changes, SaveStep is skipped, but AccumulateSessionTokenUsage (session_state.go:1041) still adds to both counters.

Subagents work differently. Their usage arrives as a total since the session started (each subagent transcript is re-read from the beginning), so it replaces rather than adds to the session counter. The checkpoint's subagent figure is that total minus SubagentTokensBaseline, which is reset at each condensation and never allowed below 0.

2. What a checkpoint stores (at condensation)

CondenseSession recalculates usage from the transcript, from the window start (checkpoint_transcript_start) to the end, in manual_commit_condensation.go:1569. Then resolveCondensedTokenUsage (:1150) adjusts it:

• If that recount finds nothing (for example Antigravity, or Cursor whose usage only came from hooks), it uses CheckpointTokenUsage from session state instead.
• Otherwise it keeps the recount and fills in the subagent part from CheckpointTokenUsage, because the recount deliberately skips subagent transcripts for cost.
• For Copilot only, it also corrects the session-wide total from a shutdown event that lands in the transcript after the hooks have run.

The result goes into that session's checkpoint metadata as token_usage, covering roughly this window's usage. Within one checkpoint that contains several sessions, the store adds their usage together into the checkpoint's top-level summary (persistent.go:931, using types.AddTokenUsage).

3. Who reads what

What this means for snapshots

• Session totals are unaffected. The snapshot never saves session state, so status and session tokens aren't changed or double-counted.
• A snapshot's own number is the same window recount a commit would do: usage from the window start up to now.
• The next commit recounts from the same window start, because the snapshot didn't move it. So the commit's token_usage already includes everything the snapshot recorded, plus anything newer. A snapshot is therefore always covered by the next real checkpoint of its session, which is the basis for the "a later checkpoint covers it" rule. If no commit ever follows, the snapshot's number is the only record of that window, and should be counted.
• Double counting only happens where checkpoints are added together: in the CLI that's tokens profile, plus whatever the server does with pushed metadata, which I can't see from this repo.

One side note: skill events aren't limited to the window. They're extracted from the start of the transcript (ExtractSkillEvents(..., 0)). So they overlap between all of a session's checkpoints, not just a snapshot and its commit, and consumers filter them by checkpoint_transcript_start. Snapshots don't add a new kind of overlap there.

The four reviews are running in parallel:

1. Minimalist cut.
2. What breaks if we cut.
3. Whether the readers we're protecting matter.
4. Whether the feature is the right shape at all, including whether it even serves the outside-repo case.

I'll check their key claims against the code and summarize once they're back.

The minimalist review is back. I'll wait for the other three before summarizing. One claim I already know is wrong: refusing sessions that already have checkpoints would not block repeated snapshots, because a snapshot never changes session state. I'll note that when I report.

Two of the four reviews are back. The feature review makes the sharpest point, and it's one I'd covered in theory but never stated plainly against this PR. As written, checkpoint create refuses the outside-repo case, the one that motivated it: a session started outside the repo has no state here, so the command hits its own "no session state" guard. I'll verify that, and the sweep claim, once the remaining two reviews arrive.

Both are confirmed, and they undercut my own earlier advice.

• tokens profile already discloses overlap (tokens_profile.go:362): "may include overlapping checkpoint history; treat them as checkpoint-observed volume, not guaranteed unique session spend."
• Carry-forward already creates overlap. After a partial commit it resets CheckpointTranscriptStart = 0 on purpose (manual_commit_hooks.go:3771), so ordinary commit checkpoints of one session can share a window start. That answers the open question I raised earlier, and the answer breaks the premise of the supersession rule I proposed.

I'll wait for the last review (what breaks if we cut) before summarizing.

Yes, we were overthinking it, but not uniformly. All four reviews agree the token-counting design was overkill. They also surfaced something more important I'd glossed over: the PR doesn't serve the case that motivated it. I checked each of the claims below against the code.

1. The headline use case isn't served

A session started outside the repo records no state here: its hooks never fire in the repo, or exit when they do. When that agent later runs entire checkpoint create inside the repo, its session is identified from the environment but has no state, so the command refuses (checkpoint_create.go:117). Passing the ID explicitly fails with "session not found". I raised this as a limitation in theory when we discussed enrollment, but never put it plainly against this PR: as written, the command doesn't serve your motivating case.

For sessions inside the repo it adds little. Sessions that end without touching files are already checkpointed when they stop, and ended sessions with uncommitted work are condensed by the background sweep after 24h (session_sweep.go:22, confirmed). What's new is only a mid-session checkpoint plus its ID, and nothing can do much with that ID yet: explain, checkpoint tokens and the hidden checkpoint resume accept one, none of them links it to a commit. The command is also classified "user-owned", which tells agents not to run it unprompted, while the whole point was agents calling it.

session attach already does most of what the outside-repo case needs: it creates state for an untracked session and writes a checkpoint. Its gaps are that it links to the last commit and needs an explicit ID.

2. The marker and dedupe plan was overthinking it

• Overlapping checkpoints already exist. After a partial commit, carry-forward deliberately resets CheckpointTranscriptStart = 0 (manual_commit_hooks.go:3771), so ordinary commit checkpoints of one session already overlap, with no marker. That also breaks the premise of the rule I proposed, because commit checkpoints can share a window start.
• tokens profile already discloses this. It's hidden, experimental, and already prints "may include overlapping checkpoint history… not guaranteed unique session spend" (tokens_profile.go:362).
• One line covers it: a note in the PR description that snapshots overlap the next commit's checkpoint the same way carry-forward does.

So: drop the marker, the supersession rule, the server follow-up and the "refuse if already checkpointed" idea. (One reviewer claimed that rule would block repeated snapshots. It wouldn't, because a snapshot never changes session state, but it's moot now.)

3. What survives on correctness

• The redaction cache race: still real. Every review confirmed the sequence. Odds are low: it needs a transcript of 1MB or more and a concurrent commit of the same session, for example from another shell. But it's the one silent, lasting corruption: later checkpoints of that session keep the duplicated or dropped lines until a CLI upgrade, a redaction-config change or entire clean.
  • Two ways to fix it:
    • The session lock: about 10 lines and scoped to this PR, but a concurrent commit waits for the snapshot to finish.
    • Storing a hash of the payload in the cache entry and checking it on read (falling back to full redaction on mismatch): fixes the class for every writer and doesn't block anything, but it changes code that commit hooks use.
  • My preference: the lock here, and the payload check as separate hardening if you want it.
• Small fixes worth keeping:
  • Drop the guessed session ID from the refusal error.
  • With --json, or whenever output is captured, a disabled repo should print to stderr and exit non-zero, rather than putting prose on stdout with exit 0.
• Already done and correct: failing on redaction errors, and skipping commit attribution.
• Defer or drop: the summary skip (it's opt-in, and post-commit already runs it mid-turn), the subagent redaction behaviour, the other-worktree guard (post-commit already does the same for sessions from other worktrees), the broader cleanups, and most of the docs.

Recommendation

Decide what this PR is for first, because the answer changes everything above:

• If it's for outside-repo sessions: don't merge it as is. The cheap stopgap is letting session attach take the calling session's ID from the environment, maybe without amending a commit. The real fix is making hooks capture sessions started outside the repo.
• If a mid-session snapshot for tracked sessions is worth having on its own: keep it hidden and add only the lock, the refusal-message fix and the disabled-guard fix, plus the one-line overlap note. Then it's done.

I'd also lean towards closing #2632 if the outside-repo case is what you actually need, since its main remaining value is a checkpoint ID nothing can use yet. Which direction do you want?

That notice is just the last review finishing; its findings are already in the summary above. I'm waiting on your call on which direction to take #2632.

There are no review sessions in this repo's local store to check against, so I can't measure the exact timing here. Even so, the review and sharing use case clearly changes which of our earlier concerns matter.

What gets better:

• The ID has a consumer. The adversarial review's "nothing can use the returned ID" point goes away if sharing takes a checkpoint ID.
• Review sessions are tracked. Workers run in the repo, or a managed worktree under .entire/worktrees, with hooks firing. So they have session state, and the "refuses its own use case" problem doesn't apply.
• Review tagging carries over. The snapshot goes through the same write path, which records Kind = agent_review, the review skills and prompt, and has_review from session state (buildCondensationWriteOptions). A snapshotted review is still recognisable as a review.
• The token-overlap question mostly disappears. Reviewers don't commit, so there's usually no later commit checkpoint to overlap with.

What becomes more important:

1. The worktree problem moves up. With --target, review workers run in a managed worktree on the reviewed branch. If the snapshot runs from your own worktree with an explicit session ID, the checkpoint records your branch (GetCurrentBranchName(repo) from the current worktree) and uses your worktree's settings. For a shared review that's a wrong label on exactly the thing being shared. It needs a fix, not a deferral: record the branch from the session's own worktree, or refuse and tell the caller to run it there.
2. It may duplicate a checkpoint that already exists. A reviewer touches no files. If its session ends cleanly, eager condense writes a commitless checkpoint at session stop. A snapshot taken after the review then writes a second checkpoint with the same content. For sharing, the better behaviour is: if the session already has a checkpoint and nothing new has happened since, return that ID instead of writing a new one. That turns the command into "make sure this session has a checkpoint up to now, and give me its ID". It's the deduplication we were designing metadata for, done at the source with no schema change.
3. Pushing. A snapshot is queued for push but only leaves the machine on the next git push. If sharing means "someone else opens this checkpoint", the sharing flow has to push it, or at least say it isn't pushed yet.

Unchanged from the minimal list: the lock (cheap, and a commit can still coincide), dropping the guessed ID from the refusal, and the disabled-repo guard. Most of the mid-turn worries (the summary, the agent snapshotting itself) matter less, because a review is normally snapshotted once it's done.

Three answers would settle the design:

1. When is it taken: after the review finishes, or while workers are still running? If after, does a worker session end cleanly, so eager condense already wrote a checkpoint? Even one real review run, checking a worker's state for Phase, FullyCondensed and LastCheckpointID, would answer this.
2. Who calls it: entire review itself at the end, the user, or the reviewing agent? That decides whether the caller-resolution path matters at all, or whether it's explicit session IDs only.
3. Which PR is the sharing one? I couldn't find one based on this branch: no open PR from anyone, and no remote branch, is stacked on soph/checkpoint-create. I'd want to see how it uses the ID and whether it pushes.

That answers my question, and it's the strongest case for the feature so far.

Today, a session that changes no files never gets a checkpoint. I traced it:

• Turn end: with no file changes, turn end logs "no files modified during session, skipping checkpoint" and skips SaveStep (lifecycle.go:1008). So StepCount stays 0 and no shadow branch is created.
• Session end: PrepareSessionEndCondensation sees no files, no steps and no subagent records, and marks the session FullyCondensed without writing anything (manual_commit_condensation.go, the !hasEagerCondensationContent branch).
• Later: the sweep and doctor only condense sessions that have steps.

So for research, planning and review sessions, a snapshot is the only way to get a checkpoint. The one exception is sessions with subagent records, which do get condensed.

Scoping the command to these sessions removes most of the hard questions. Refuse when the session has pending file changes (FilesTouched non-empty), with a message like "this session has uncommitted file changes; its work is checkpointed when you commit". This is the better-shaped version of your earlier "not when it already has checkpoints" idea:

• No overlap with a commit. A session with no pending files doesn't get condensed by the next commit, so there's no snapshot-plus-commit double count and no metadata marker needed.
• No attribution question. There are no uncommitted agent changes to misattribute; skipping attribution stays harmless.
• No collision with the session-end checkpoint, because session end writes nothing for these sessions.
• Earlier work is fine. A session that changed and committed files before, then switched to research, has no pending files, so it's allowed. Its snapshot window starts after the last commit, which is correct.
• The edge case is acceptable: a session that starts changing files after a snapshot gets a next commit checkpoint that overlaps it. That's the same kind of overlap carry-forward already produces, and tokens profile already discloses it.

Snapshot semantics fit sharing. Since the window isn't moved, each snapshot of a session that hasn't committed starts at 0 and holds the whole session up to that moment. That's what you'd want to share. Repeated snapshots overlap each other, which only affects the hidden, already-caveated tokens profile. If that matters later, "return the previous snapshot's ID when the transcript hasn't grown" is cheap to add, but I'd leave it out for now.

The resulting change list:

1. Refuse sessions with pending file changes (new, and it's what replaces the marker work).
2. Run inside the session lock (the cache race).
3. Drop the guessed session ID from the refusal error.
4. Disabled repo: stderr and a non-zero exit when output is machine-read.
5. Fix the PR description: what it's for (sessions with no file changes have no other path to a checkpoint), plus the overlap note. Update the docs where they say checkpoints happen only at commit.

Still deferred: the other-worktree branch label, subagent redaction failing closed, the summary skip, and the cleanups.

A broader gap, separate from this PR: these sessions lose everything after their last snapshot when they end, because session end writes nothing for them. If research and planning sessions should always be preserved, the real fix is having session end write a checkpoint for sessions with no file changes and a non-empty transcript. That's a product decision with storage cost implications, so I'd raise it separately rather than fold it in here.

Want me to go ahead with steps 1 to 5?

The new description is ready, and I've verified its claims against the code. I'll commit, push and update the PR once mise run check finishes.

Steps 1 to 5 are done and pushed to PR #2632 as f52b6bf4e2, and the PR description is rewritten.

What changed:

1. Pending file changes are refused. checkpoint create now only snapshots sessions with no uncommitted file changes. Otherwise it says "its work is checkpointed when you commit".
2. It runs under the session lock. The snapshot condenses inside MutateSessionState and never saves state back, which closes the redaction cache race.
3. The refusal doesn't print the guessed session ID any more.
4. A disabled repo fails. The notice goes to stderr and the command exits non-zero, so stdout only ever holds the ID or JSON.
5. The PR description now starts with why the command exists: sessions with no file changes have no other way to get a checkpoint. It also covers the overlap note, the product calls, and what's not in this PR.

The docs are updated to match: the snapshot contract in checkpoint-implementation.md, a note on checkpoints without a commit in sessions-and-checkpoints.md, the IsCaller() paragraph in caller-session-resolution.md (now one line per paragraph), and the "written at commit time" line in security-and-privacy.md.

Two tests weren't proving anything, and I fixed both:

• The lock test passed with the lock removed. It waited 200ms, and the snapshot takes over a second here, so it was still running either way. It now checks the actual property: from inside redaction, another writer tries to take the session lock and must time out.
• The attribution test passed with attribution turned back on. With pending files refused, a snapshot has nothing to attribute anyway. It now tests the option directly on a session that does have changes, with a control run that must record attribution.

I removed each guard in turn: the lock, the pending-files check, the attribution opt-out, failing on redaction errors, the disabled-repo change, and the hidden guessed ID. Each removal makes its test fail.

Checks: mise run check failed only on TestOpenCodeSeedRepoPlantsDeps, the same missing local opencode cache as before, which this change doesn't touch. Lint, cli, strategy and the integration tests pass. The canary end-to-end test, which the failure cut short, passes when run on its own.

Trail #1458: it shows no findings, but its status is still "reviewing" for this push, so I'll check again once it's done.

I fixed this one locally; it isn't committed or pushed yet. The finding was correct for most agents, with one gap the suggested fix doesn't close.

What was wrong: only Codex and Antigravity report file edits per tool call. For Claude Code, Cursor and the rest, FilesTouched stays empty until SaveStep at turn end. So an agent that edited a file and then ran checkpoint create in the same turn got past the refusal.

Fix: the guard now uses resolveFilesTouched under the lock, as the review suggested. It falls back to extracting edits from the live transcript when FilesTouched is empty. I checked one risk first: that extraction drops paths outside the worktree (manual_commit_hooks.go:2427). So a planning session writing its plan to ~/.claude/plans is still allowed, and those are exactly the sessions this command is for.

Test: an active session whose live transcript has a Write tool call and whose saved FilesTouched is empty.

• An edit inside the worktree is refused.
• A plan file outside the worktree is allowed, as a control.
• Putting the old FilesTouched-only check back makes the inside-worktree case fail.

Lint is clean and the snapshot tests pass.

Remaining gap: edits made through a shell command (sed, a script, a generator) aren't edit-tool calls. Neither the transcript nor the per-tool-call file hooks see them until turn end, so a snapshot taken in that same turn is still allowed. The consequence is mild: that snapshot overlaps the next commit's checkpoint, and attribution is skipped anyway. Closing it properly would mean a working-tree diff against the state captured at turn start, which is more machinery than this warrants. Refusing any dirty worktree instead would block research in repos that already had uncommitted changes. I've written the gap into the code comment and checkpoint-implementation.md rather than leave it implied.

Should I run mise run check, commit, push, and add that gap to the PR description's "Not in this PR" section?

mise run check is running, and the PR description is updated locally with the current-turn edit handling and the shell-edit gap. I'll commit, push and update the PR when the check finishes.

The fix is committed and pushed to PR #2632 as 47b8596dca. checkpoint create now also refuses a session that edited files earlier in the current turn, not only edits already recorded in session state.

• Checks: mise run check failed only on TestOpenCodeSeedRepoPlantsDeps, the same missing local opencode cache as before, which this change doesn't touch. Lint, cli, strategy and the integration tests pass. The canary end-to-end test, which that failure cut short, passes when run on its own.
• PR description: it now explains how pending file changes are detected and that plan files outside the repo don't count. "Not in this PR" lists the shell-edit gap: edits made with sed or a script aren't seen until the turn ends, so a snapshot in that same turn is still allowed.
• Trail #1458: no findings so far, but it may not have reviewed this push yet. Worth checking again later.

There's nothing new on PR #2632 or trail #1458 since the last push (47b8596dca).

• Trail #1458: no findings, whether open, resolved or dismissed. The "reviewing" label I took as stuck is the trail's own status, not a hung agent review: the agent review on this push completed and found nothing blocking.
• Entire Gates on the current head: passed. Approvals (1 recorded), checks and findings all pass.
• CI: all 17 checks green; the Slack notification was skipped as usual.
• PR comments: none new. The only review thread, Copilot's redaction one, is resolved. Copilot hasn't re-reviewed the later commits, and no human has reviewed on GitHub.
• Merge status: GitHub still shows REVIEW_REQUIRED and is blocking the merge. The approval the Gates check counts is on the trail, not a GitHub review, so the PR needs a GitHub approval before it can merge.

Both PRs from this session are now merged: #2599 (agent-help delegating to plugins) and #2632 (checkpoint create). I've saved two notes to memory:

• The product gap: sessions that change no files get no checkpoint except through checkpoint create, and session end still writes nothing for them.
• A testing lesson: a timing-based lock test passed with the lock removed. Lock tests should probe from inside the locked section, and every guard test is worth checking by removing the guard.

Three things are still open:

1. Should research, planning and review sessions always be kept? Right now a session with no file changes loses everything after its last snapshot when it ends. Keeping them would mean session end writing a checkpoint for any non-empty transcript, which is a product decision with a storage cost.
2. Agent-help listing: you postponed the "External commands" heading in bare entire agent-help.
3. Local cleanup: the soph/checkpoint-create and soph/agent-help-plugin-delegation branches still exist locally and on the remote. I can delete them, or leave that to you.

None of the five candidates is the same problem. They're text-only matches: the Codex rollout scan, a Mantis experiment, test-suite failures, a go-git hash bug, and resumed subagents. So this would be a new item.

I suggest priority 3: research and planning work is lost at session end, but checkpoint create is a workaround, and the fix needs a product and storage-cost decision rather than just code. Is 3 right, or do you want a different priority (1 highest, 5 lowest)?

I shelved it as #DMV8RJ9 (priority 3, seen once), but no checkpoint could be linked. The plugin's entire checkpoint create --json call failed with exit status 1: Error: Invalid usage: unknown flag: --json.

The cause is that the installed entire binary predates #2632, so it doesn't have the create subcommand. The priority plugin already uses entire checkpoint create --json to attach each shelved finding to the session's transcript, so that linking starts working once your installed CLI includes #2632.

link attaches a checkpoint to an existing sighting, so the count stays at 1. Checking its flags.