feat: link mid-task background-subagent commits to their session

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/1077

The incident

Background Claude Code subagents run git commit between the parent session's turns. tryAgentCommitFastPath (the prepare-commit-msg fast path) only trusted ACTIVE sessions; between turns the session is IDLE, so the fast path declined, and the slow content-detection path then found no evidence linking the commit to the session (the subagent's work wasn't in the parent's shadow baseline). The commit shipped with no Entire-Checkpoint trailer at all. On a real subagent-driven feature branch, six of seven commits went unlinked this way.

The design (after merging #2032's durable-record model)

1. Trigger (idle + task content). tryAgentCommitFastPath now treats a session as eligible when it's ACTIVE or IDLE with a fresh task record (idleWithTaskContent, strategy/manual_commit_hooks.go). A record counts whether it's still in flight or completed-but-unmaterialized — the same HasTaskContent() shapes condensation keys on — and each record is bounded by its own StartedAt against activeSessionInteractionThreshold (24h), so a subagent that dies without ever sending SubagentStop/SessionEnd doesn't leave the session a trailer candidate forever. The same predicate feeds shouldCondenseWithOverlapCheck's overlap-check bypass, so the trigger and the condensation trust share one rule.
2. Content (the condensation materializer). The base branch (feat(claude-code): capture background subagent work durably (SubagentStop + task records) #2032, issue Subagent data does not survive condensation — durable storage for subagent transcripts #2058) made session.TaskRecord a durable ledger: condensation materializes each record's transcript-so-far into the checkpoint's tasks/<tool-use-id>/{agent-<agent-id>.jsonl, task.json} subtree, live records survive for the next condensation, and every checkpoint is self-contained. That means the trailer this PR adds is backed by content by construction: the very condensation the trailer triggers stores the subagent's transcript-so-far. The earlier revision of this PR pre-wrote a commit-time transcript snapshot (captureInFlightTaskCommitSnapshot / captureInFlightTasksForCommit) gated on headHasCheckpointTrailer to keep the trailer from dangling — all of that is now removed as redundant, along with its tests and post-commit wiring.

Overlap-trust scoping

idleWithTaskContent is deliberately scoped to PhaseIdle only, not PhaseEnded. An earlier version leaked the overlap-check bypass to ended sessions too; that shape was empirically reproduced and fixed (fe2aa5fdb), with a regression test pinning that an ended session with a lingering record still declines — its records belong to its own final condensation, not this fast path.

The trade-off

Because eligibility is keyed off a no-TTY commit plus a fresh task record, the trust window spans the entire lifetime of a background task — including raw-mode TUI git clients (lazygit, gitui, tig) that spawn git commit without a real terminal. This means an unrelated no-TTY commit made while a background task happens to still be running could get mislinked. We accept this: a mislink is recoverable (and rare — it requires a fresh record plus an unrelated no-TTY commit in the same narrow window), while a silent unlink is not. Records are genuine evidence of live agent work, not a guess. The window is also narrower than it used to be: the base branch's dead-owner sweep completes a crashed agent's records, so orphaned records no longer linger for the full 24h in the common case.

Non-regression pins

• An ordinary commit made while IDLE with no task records stays exactly as before: no trailer (TestSubagentCheckpoints_IdleCommitNoMarkers_NoTrailer).
• Record-less behavior (foreground tasks, ACTIVE-session commits) is byte-identical to pre-PR behavior — the new eligibility branch is additive.
• The end-to-end arbiter, TestSubagentCheckpoints_CommitWhileIdleWithLiveMarker_LinksAndCondensesContent, drives the real prepare-commit-msg + post-commit hook chain and now asserts the strong guarantee: the mid-task commit's condensed checkpoint contains tasks/<id>/agent-<id>.jsonl with the subagent's real transcript content (stronger than the previous revision, which could only check the pre-written shadow-side snapshot).

Known gaps / follow-ups

1. Pre-existing orphan-prune gap. Fixed by feat(claude-code): capture background subagent work durably (SubagentStop + task records) #2032. findSessionsForWorktree's orphan sweep now spares record-bearing sessions (!state.HasTaskContent() in the prune predicate), so an idle session whose only activity is one open task record survives to prepare-commit-msg — a first-turn background commit links. The integration test's read-only seed-task workaround has been removed accordingly.
2. Sweep-finalize follow-up. Fixed by feat(claude-code): capture background subagent work durably (SubagentStop + task records) #2032. finalizeExitedSessions now completes a dead-owner session's live records (sweepCompleteLiveTaskRecords, session_finalize.go) before ending it, exactly as a clean SessionEnd does — preserving transcripts and closing the trust-window trade-off from the other end.
3. Identity/ancestry discovery (linking a commit to a session by content/authorship signals beyond records) composes into the same fast-path loop later, via feat(strategy): link commits to sessions by process identity #2013. Out of scope here.

Trailer eligibility is bounded; condensability is not

A session's task records make it condensable with no freshness bound — that is deliberate, and it is what keeps a stale record's transcript-so-far from being stranded unmaterialized. Claiming a commit is bounded separately: only a record within idleWithTaskContent's 24h window may mint a trailer. Without that split, an IDLE session whose only content was a >24h record got a trailer from the slow path and was then refused by PostCommit, leaving Entire-Checkpoint pointing at a checkpoint nothing ever wrote — on an unrelated human commit. Two reviewers reproduced it end to end; staleRecordIsOnlyContent closes it, and PostCommit now warns whenever a trailer is minted and no session condenses into it, so any future divergence is visible rather than silent.

An earlier revision of this PR also exempted record-bearing sessions from PostCommit's read-only skip. That is reverted: the skip only fires when another session's files are in the commit, and PostCommit hands one checkpoint ID to every condensing session, so that other session fills the trailer anyway. The exemption prevented no dangling trailer and only let a record-bearing session condense into someone else's commit.

Test plan

• mise run fmt && mise run lint — clean
• mise run test:ci — unit + integration green, Vogon canary + roger-roger E2E 4/4

🤖 Generated with Claude Code

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1408af6. Configure here.}

[Copilot]

Pull request overview

This PR fixes missing session linkage for background subagent git commits that occur between parent-session turns by expanding the prepare-commit-msg fast-path eligibility to include IDLE sessions with a “live” in-flight task marker, and by adding a post-commit commit-snapshot capture so any newly added Entire-Checkpoint trailer is backed by condensible content.

Changes:

• Extend tryAgentCommitFastPath + PostCommit condensation trust rules to treat IDLE sessions with live in-flight task markers as linkable.
• Add a post-commit trailer gate (headHasCheckpointTrailer) and commit-snapshot capture path to persist in-flight task snapshot content before strategy.PostCommit runs.
• Add unit + integration tests and architecture docs covering the idle+marker linkage and its scoping/regression boundaries.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/architecture/sessions-and-checkpoints.md	Documents the idle+marker commit linkage and the commit-snapshot backstop.
cmd/entire/cli/strategy/phase_postcommit_test.go	Adds an end-to-end-ish strategy-level test asserting condensation behavior for idle+marker commit-snapshots and a regression for ENDED+marker scope.
cmd/entire/cli/strategy/manual_commit_hooks.go	Implements idle+marker eligibility + overlap-check bypass and shares logic via idleWithLiveMarker.
cmd/entire/cli/strategy/condense_skip_test.go	Adds fast-path eligibility regression tests for idle-with-marker vs idle-without-marker vs ended vs stale-marker.
cmd/entire/cli/lifecycle.go	Adds commit-snapshot capture for in-flight tasks to back trailer-bearing commits.
cmd/entire/cli/lifecycle_test.go	Adds unit tests for commit-snapshot capture behavior (files present, read-only, dedup/no-op).
cmd/entire/cli/integration_test/subagent_commit_in_turn_test.go	Adds full hook-chain integration coverage for idle+marker linkage + condensation, plus the “idle no markers” guard.
cmd/entire/cli/integration_test/subagent_checkpoints_test.go	Adds requireSessionState helper for safer integration assertions.
cmd/entire/cli/hooks_git_cmd.go	Adds post-commit trailer gate + invokes commit-snapshot capture before strategy PostCommit.
cmd/entire/cli/hooks_git_cmd_test.go	Adds unit tests for the HEAD trailer gate helper.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Soph]

Reviewed at b7ed75fe1. One item, and I'm taking it off your plate.

warnDanglingCheckpointTrailer fires on amend, cherry-pick, and revert — I'll land it separately, please drop these hunks.

manual_commit_hooks.go:1090, plus anyCondensed at :1022 and the void→bool change on postCommitProcessSessionLocked.

The doc says the condition is "never a routine outcome, so it warns." It's routine:

• handleAmendCommitMsg (:562) deliberately preserves or restores the trailer. A message-only amend has no new content, so hasNew is false, shouldCondenseWithOverlapCheck short-circuits, and handler.condensed stays false for every session — it's only assigned at :713 and :742, both behind shouldCondense. Warn fires.
• Same for cherry-pick and revert, which isGitSequenceOperation (:319) covers via CHERRY_PICK_HEAD/REVERT_HEAD. The rebase branch skips phase transitions, not condensation, so a cherry-picked range emits one WARN per commit.

In all of those the trailer isn't dangling — its checkpoint was written by the original commit. Verify: git commit --amend -m on any trailered commit, then grep .entire/logs/ for trailer left dangling.

It's worth having, though: guarded properly it catches the IDLE + empty-FilesTouched dangling-trailer shape, which I have a repro for. It also needs a test — nothing in the PR references anyCondensed or the warn. Since it doesn't depend on your predicate and applies to main as-is, I'll open it off main with the sequence-operation guard, an inherited-trailer check against state.LastCheckpointID, and coverage. Drop it here and your rebase gets smaller.