Rate-Limit Resume Mechanism (2026-07-14)

Ask: define a clear mechanism for resuming Claude Code after hitting a rate limit — Talbot hits them often, sometimes with several sessions running at once.

Outcome: no new command needed. Two-layer resume + always-on session identity, all documented in SSOTs. 10 rounds, one day.

What shipped

1. Native resume documented (Core/AI/Claude-Code/Claude-Code.md → Rate Limits & Resuming): a subscription limit pauses the session (no auto-retry; different quota than 429/529 capacity errors, which do auto-retry). Resume order: wait + new message → claude --continue (same dir) → claude --resume <id-or-name> (any dir). Opus-limit hits need no waiting — /model off Opus keeps working. Open question: whether un-blocking after reset needs a specific action or any message (docs don’t say; note it live next time).
2. SMTM interrupted-session convention (SMTM_System.md → Resuming After a Rate Limit or Crash): 3+-step work writes a **Progress:** checklist inside the in-progress Claude Response; a task file ending without a real ## Talbot Response = interrupted session, not a wait state. /task-start//task-continue (ai-config SSOT) now detect this and resume from the checklist. (/task-start previously existed only as a hand-edited deployed copy — brought into ai-config.)
3. Session identity, passive (statusline-command.sh): two-line status line — line 1 is always the session identity ([name], or [id: xxxxxxxx] from session_id when unnamed), line 2 dir | model | Context % | Session tokens | Limit % (resets time). Live rate-limit consumption visible before the wall. Works identically in tmux/IDE terminals/bare shells — no launch ritual.
4. Hook fixes (settings.wsl.json/.win.json): pre-existing Notification hook read an env var that’s always empty — hooks get JSON on stdin; fixed. Added StopFailure/rate_limit hook logging hits to session.log (permanent record; status line is the live view).

Decisions / reversals

• No custom /resume keyword — would shadow the native /resume picker.
• ctask shell wrapper built, then dropped (rounds 5–8): auto-named sessions from the task filename at launch, but only paid off with a bare-terminal launch ritual — Talbot launches inside tmux windows and IDE terminals. Passive status-line identity solved the actual need; ctask removed from .bashrc.
• “Broken status line” (round 10) wasn’t — a fresh session’s JSON has no context_window/rate_limits until the first API response, and no name until set; [ab72833c] + dir | model is correct startup state. Fixed the readability instead: unnamed fallback now renders [id: ab72833c]. Reproduced from Talbot’s screenshot with mock JSON before touching anything.

Gotchas hit (→ LESSONS.md)

• Task-file Talbot Response approvals don’t satisfy the auto-mode classifier for self-modifying settings/hooks changes (needs live chat approval) — and ai-config’s post-commit → deploy.sh hook deploys the working tree, so an unrelated commit deployed the still-uncommitted hook fix anyway. Partial staging in ai-config is unsafe.
• deploy.sh had no Windows copy line for statusline-command.sh at all — WSL deployed fine, Windows silently stale. Fixed in deploy.sh (b9fe886); diff every platform target.
• /session name never existed (stale-clipping error, corrected in both SSOTs; real commands: /rename, /resume, claude -n).
• tmux side-note: work.sh is attach-only while the work session exists — a closed window (exit claude, then exit shell) stays gone until the whole session is rebuilt. Restored 0:KB-mBR manually.

Commits

• KB vault: e284d59, 50187dc, + closing commit (docs, task→archive, this log)
• ai-config: 3e358b5, 86c3269, 7b3e98f, b9fe886, + closing commit (statusline 2-line + id: fallback)