git:20260614.d46202b to git:20260830.448ec5d

- # checkpoint-backlog — checkpoint the queued (ended) sessions

- When a session ends, subrosa's `SessionEnd` hook queues it in `pending-checkpoint.log` (in the subrosa data dir, `~/.claude/subrosa/` by default) for checkpointing. This skill processes that backlog now, **in-session** — no background daemon, no headless `claude` run. It's the same memory procedure as the checkpoint skill, applied to each *past* session instead of the current conversation.

- Follow the checkpoint skill's rules (the four memory types — user / feedback / project / reference — the exclusion list, and the leaf → `subrosa fact upsert` → `subrosa generate` flow). Read `${CLAUDE_PLUGIN_ROOT}/skills/checkpoint/SKILL.md` if you need the detail. Apply these overrides.

- When the queue spans **more than one project**, the slow part — reading each session dump to judge what's durable — runs in parallel, one sub-agent per project. A single-project queue stays sequential and behaves exactly as it always has. The split is safe because each project has its own `MEMORY.md`: separate projects never race, but two sessions in the *same* project would race the regenerate and the dedup, so same-project work always stays serial.

- 1. **List the backlog:** `subrosa pending`. Each line is `<timestamp>\t<session-id>`, oldest first. Collect the unique ids.

- If it's empty, say "no backlog" and stop.

- 2. **Cap the work** at the 5 most recent queued sessions (newest is last in the file). If there are more,

- process those 5 and tell the user to run `/subrosa:checkpoint-backlog` again for the rest. This keeps session startup from stalling.

- 3. **Find each session's project (cheap probe).** For each id, run `subrosa session <id> | head -2`. The pipe stops the

- command after the two header lines, so this never dumps the whole session — it works on any recent binary:

- - line 1 — `# session <id> project=<project> cwd=<cwd> <first>..<last>` → take the `project=` value.

- - line 2 — `# memdir: <path>` → take the memdir path.

- If instead it prints `[subrosa] no archived turns for session <id>` (the session was never ingested), there is nothing

- to extract: run `subrosa checkpoint-drop <id>` now and count it as a skip. Don't pass it to a lane.

- 4. **Group the surviving ids by project, then pick a branch.** If none survive, skip to the report.

- ### Branch A — one project (the common case)

- Process the sessions one at a time, inline in this conversation — byte-identical to the old behavior. For each id, oldest first:

- - `subrosa session <id>` — read the flattened turns.

- - Pull durable facts per the checkpoint skill's rules (four types, exclusion list, be conservative — a borderline

- candidate is a skip, because `MEMORY.md` is byte-budgeted and low-signal facts crowd out good ones).

- - Check existing memory first: `subrosa fact list --memdir "<memdir>"` and `subrosa search "<keyword>"`. Update a fact

- in place rather than create a near-duplicate.

- - Write each leaf into the `<memdir>` from the probe, then register it:

- `subrosa fact upsert --memdir "<memdir>" --leaf <name>.md --hook "<one-line hook>" --origin-session <id>`

- - Rebuild that project's index: `subrosa generate --memdir "<memdir>"`

- - Clear it from the queue: `subrosa checkpoint-drop <id>`

- ### Branch B — more than one project (parallel)

- Fan out **one sub-agent per project**, launched in a single batch with the Agent tool (general-purpose type) so they

- run at the same time. Parallelize *across* projects; keep each project's sessions *serial* inside its own lane.

- - For each project group, launch one sub-agent with the **sub-agent prompt** below, filling in `{{PROJECT}}`,

- `{{MEMDIR}}`, `{{SESSION_IDS}}` (that project's ids, oldest first, space-separated), and `{{PLUGIN_ROOT}}`

- (the real value of `${CLAUDE_PLUGIN_ROOT}`).

- - The sub-agents read, extract, and write facts for their own project only. They do **not** drop anything from the

- queue and never touch another project's memdir.

- 5. **Drop the queue entries yourself — Branch B only, after every sub-agent has returned.** Each sub-agent reports the

- ids it finished (`FINISHED_IDS:`). For every finished id, run `subrosa checkpoint-drop <id>` one at a time, here in the

- orchestrator — never inside a sub-agent — so the shared `pending-checkpoint.log` has a single writer. Any id a sub-agent

- did **not** report (it failed, or found nothing it could finish) stays in the queue and is retried on the next backlog.

- That is safe and self-healing: `checkpointed_seq` in the database is the real done-marker, the log is just a to-do list.

- 6. **Do NOT** run `subrosa checkpoint-clear` (it wipes the whole queue, including sessions you didn't reach), and

- do NOT run the staleness archive pass — both stay with the interactive checkpoint skill.

- Launch one sub-agent per project, all in one batch. Use this exact prompt, with the four placeholders filled in:

- You are saving durable memory from one or more ended Claude Code sessions that all belong to ONE project. This is the

- same memory procedure as subrosa's `checkpoint` skill, applied to past sessions. Read

- {{PLUGIN_ROOT}}/skills/checkpoint/SKILL.md if you want the full detail — the load-bearing rules are inlined below.

- Process the ids IN ORDER, one at a time. Do not parallelize within this lane — these sessions share one MEMORY.md and

- would race each other. For each id:

- 1. `subrosa session <id>` — read the flattened turns.

- 2. Pull out durable facts. Match each to one of four types:

- - user — role, preferences, knowledge, working context

- - feedback — corrections ("don't do X") and confirmed-good approaches; always include the why

- - project — ongoing work, deadlines, motivations, who is doing what and why

- - reference — pointers to external systems, dashboards, ticket projects

- 3. Apply the exclusion list strictly. Do NOT save: code patterns, conventions, file paths, architecture; git history,

- commit hashes, blame, PR numbers; debugging recipes (the fix is in the code, the why is in the commit message);

- anything already in CLAUDE.md; ephemeral state (in-progress task details, the current investigation chain, bare

- ticket numbers without context); routine activity logs. Only save what was surprising or non-obvious.

- 4. Be conservative. This writes straight into the always-loaded MEMORY.md with no human review, so when a candidate is

- borderline, skip it — the index is byte-budgeted and low-signal facts crowd out good ones.

- 6. Check existing memory first so you update instead of duplicating: `subrosa fact list --memdir "{{MEMDIR}}"` and

- `subrosa search "<keyword>"`. Similar fact exists and is correct → skip; exists but stale → update in place; none → new.

- 7. Write each leaf file into {{MEMDIR}} with frontmatter (name, description, type). For feedback and project facts, use

- the **Why:** / **How to apply:** structure in the body — the why is what lets a future reader judge edge cases. Link

- related leaves with [[their-name]].

- 9. Rebuild this project's index after EACH session: `subrosa generate --memdir "{{MEMDIR}}"`. Regenerating per session

- (not once at the end) means a failure partway through still leaves the earlier sessions saved.

- - NEVER run `subrosa checkpoint-drop` or `subrosa checkpoint-clear` — the orchestrator owns the queue.

- - If `subrosa session <id>` prints "no archived turns", there is nothing to extract — count that id finished and move on.

- <id>: saved <n>, updated <n>, skipped <n> — <very short note>

- Add up the work across both branches (the inline Branch A sessions, every sub-agent's `TOTALS`, and the no-turns skips

- from step 3). Then re-run `subrosa pending` and count the unique ids left — that is the authoritative `M`, not a guess.

- Keep it short so it doesn't bury the user's actual task:

- If you ran this at session start, finish it, then turn straight to whatever the user asked for.