[bniladridas]

Human overview

The Claude Code channel plan still said a first run's catch-up ends at "the first heartbeat after replay", but a heartbeat is only liveness: the client ends replay at the cursor frame, or at a history_expired that reports the gap and advances to the floor. This corrects that one bullet in planning/claude-code-channel.md so the plan matches the client being shipped in #232. Refs #239.

Human required (optional)

• Merge-order: land after fix(agents): clear the first-run flag when the catch-up completes (#122) #232 merges, so the wording is checked against the implementation that actually reached main.

AI reviewer

Details for agents: what the diff does, invariants, verification, checklist

What the diff does. One paragraph inside one bullet in planning/claude-code-channel.md (design §7.4, the first-run backlog rule). No code, no other file.

The bullet used to say: an event older than started_at - 60s is consumed without a push, and "once the stream has caught up (the first heartbeat after replay)" one kind="backlog" control event is pushed. The heartbeat clause is the stale part. It is replaced with the real boundaries, and the bullet's frame is kept: the same age rule, the same backlog control event, the same "the skill tells the sponsor" ending.

What replaced it.

• "once replay reaches its explicit boundary", so the rule no longer names an event that is not a boundary.
• The cursor frame is the normal boundary.
• A heartbeat is liveness only and does not end replay.
• On history_expired, the client reports the gap and advances to the supplied floor before ending replay. That order is the implementation in fix(agents): clear the first-run flag when the catch-up completes (#122) #232: _gap pushes the gap, advances, then calls _end_replay.
• Server-side emission of history_expired on an out-of-retention reconnect remains unverified. The plan says so rather than promising it.

Invariants. The documented age rule (started_at - 60s) and the backlog control event are unchanged; only the trigger that flushes it moves. First-run resync suppression is not discussed in this bullet and is untouched.

Failure posture. Documentation only: nothing runs differently if this is wrong. The risk is the opposite one, a plan that describes a boundary the client does not use, which is what made #239 worth filing. If the wording still drifts from the code, the next reader trusts the plan over claude_channel.py.

Deferred work. None from this change. #239 closes when this merges.

Verification. macOS, on branch docs/239-replay-boundary at 6259202, based on origin/main 0c96a69:

• npx --yes markdownlint-cli2@0.18.1: 17 files linted, 0 errors. Same command as the docs CI job.
• git diff --stat origin/main: 1 file changed, 6 insertions, 3 deletions.
• No code, so ruff, ty and pytest are unaffected and were not re-run for this branch; the ci job will run them anyway.
• The wording was checked against a50b391 (fix(agents): clear the first-run flag when the catch-up completes (#122) #232), not against main, since fix(agents): clear the first-run flag when the catch-up completes (#122) #232 has not merged. See the merge-order item above.

Checklist (repo-specific)

• uv run ruff format --check and uv run ruff check clean: not applicable, no Python file changed
• uv run ty check src/pepper_cli/ clean: not applicable, no Python file changed
• uv run pytest passes; coverage floor in .claude/maintainerd.json not lowered: not applicable, no code changed
• Server-contract changes: none, no /api/v1 usage, no # MIRROR: comment
• No token or credential is logged, printed, or put in a fixture: not applicable, documentation only
• README and the bundled SKILL.md updated if commands or output changed: not applicable, no command or output changed; this edits the planning doc only

Confidence Score: 5/5

No actionable issue was found beyond the already stated requirement to merge after PR #232.

Summary

Updates the replay description in planning/claude-code-channel.md.

• The replay note ties backlog reports to the cursor boundary, not a heartbeat.

bniladridas states that this wording targets pending PR #232 and should merge afterward. The pending implementation was unavailable for comparison; the known difference from the local client is not reported as a defect.

bniladridas also identifies server emission of history_expired as unverified. The changed paragraph preserves that caveat.

_{Reviews (1) · Last reviewed commit: "docs(planning): describe the replay boun..." · Reviewed by Greptile}

[vycari-review]

Vycari Review

Round 1 on 6259202. The verdict is the Vycari Review check run, and each open finding is an inline thread. Reply on every P0 and P1 thread: Fixed in <sha>, or Disputed: with a reason. P2s are the author's call: fix one, or reply Deferred: #<issue> (the PR's one follow-up issue) or Declined: with a reason, and VR stops re-raising it. From round 2 on, VR raises no new P2s: it checks the fixes and looks for P0s and P1s.

Open: P0 0 · P1 0 · P2 1 · disputed 0 · confirmed fixed 0 · withdrawn 0

Hand-off: Greptile requested on 6259202.

No open P0 or P1 findings this round.

P2s, judge's notes and closed findings

Open P2 findings

• P2 · VR-59583025 · Plan states the replay boundary as shipped behaviour, but the client on main flushes the backlog on heartbeats and not on the cursor frame · planning/claude-code-channel.md lines 334–340

P2s with no reply yet

• P2 · VR-59583025 · Plan states the replay boundary as shipped behaviour, but the client on main flushes the backlog on heartbeats and not on the cursor frame · planning/claude-code-channel.md lines 334–340

Judge's notes

This PR only changes the planning doc. The one finding is a P2: the new wording describes the client in #232, not the one on main, so the plan is only wrong if it merges before #232. The PR's merge-order item already asks to land it after #232.

[chatgpt-codex-connector]

Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-11-12T03:41:19.119066Z	6259202	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[vycari-review]

@greptileai review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6259202f37

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[allenhutchison]

Thank you for this, and for filing #239. Since a ping really is the end of replay (details on #232), the plan's current wording is correct, so we'll close this one. Thanks for pushing the docs and code to agree.

---

Generated by Claude Code