Design #91 — responsive session startup: render first, reconcile after

1. Summary

Today /session-init takes roughly ten minutes to produce a prioritized list. The instinct is to blame the network — three gh searches, a project-board query, a GraphQL Ideas sweep. The measurements say otherwise. Every network call the init makes, run cold and serially, totals about 4 seconds; with the cache the workspace already maintains, it totals 2 milliseconds. Essentially the entire ten minutes is language-model work: a subagent spawn, a digest, per-idea triage reasoning, and the synthesis of a fresh list.

That reframes the problem. You cannot reach a 10-second bar by making the API calls faster, batching them harder, or fanning them out — they are already noise. You reach it only by removing generated tokens from the critical path.

The design is therefore render first, reconcile after, in three tiers:

• Tier 0 — render (target ≤ 5 s). A deterministic script prints the list the previous wrapup already wrote down. No synthesis, no judgment, no subagent. This is the thing that has to be fast, and it is the deliverable @jwildfire sees.
• Tier 1 — mechanical reconciliation (target ≤ 10 s total). The same script annotates that list from a pre-warmed GitHub delta cache: carried items GitHub shows closed or merged get struck; items that appeared since the hand-off get appended. String matching, not judgment.
• Tier 2 — the judgment pass (async, minutes). The delta subagent and the ideas-inbox triage run after the list is on screen and revise it in place. The session is already working by then.

The enabling insight is that the machinery for Tiers 0 and 1 already exists and is tested: obot.agent/tools/session-hub/lib/collect.mjs ships collectScratchpad(), collectNextSession(), and collectGhSweep() — exactly the three hand-off sources plus the cached delta. What is missing is a terminal-shaped, non-LLM entry point over them.

2. What “responsive” means here

The bar is time-to-first-actionable-output: from @jwildfire typing /session-init to a usable, link-bearing, prioritized list being on screen. Under 10 seconds.

Three clarifications the target needs to survive contact with reality:

• The first paint may be provisional, and must say so. A list stamped “carried from the 2026-07-30 wrapup; delta cache 4 minutes old; judgment pass running” is honest and useful. A list that silently omits something that changed overnight is not.
• The clock stops at the first paint, not at the last revision. Tier 2 continues afterwards and is allowed to take minutes; it just is not allowed to block.
• This tightens obot.agent#29 rather than replacing it. The ~2-minute end-to-end budget and the “well under 10% of context” budget from #29 still hold for the whole init including Tier 2. The new number is a latency bar on the first paint.

3. Where the time actually goes

Measured on @jwildfire's Mac, 2026-07-31, against the live workspace. Every row marked measured is a real wall-clock timing of the exact command the skill runs today; rows marked estimated are attribution by subtraction and remain to be instrumented.

So: the entire data-gathering surface of /session-init is ~4 seconds cold and ~0 warm. Against a ~10-minute observed init, that is under 1% of the time. The other 99% is model work — spawning, digesting, triaging, and writing prose. Optimizations aimed at the network are rounding error; the only lever that moves the number is what the model is asked to generate before @jwildfire sees anything.

4. The design: three tiers

5. Pre-warming the delta cache

Tier 1 is 2 ms warm and 4 s cold, and the cache TTL is 5 minutes — so at a typical session start the cache is cold and the whole latency budget goes to one gh project item-list call. Three ways to keep it warm, in increasing order of infrastructure:

The pragmatic answer is C now, B if the pause is still felt — C is already built, and the cache write is best-effort and self-healing either way. A GitHub Action writing a committed snapshot is deliberately not proposed: the sweep is derived state and the session-hub design already ruled that it is never committed.

6. What leaves the critical path — and what that costs

The honest cost: with the judgment pass deferred, the first list @jwildfire sees can be wrong in one specific way — an item whose meaning changed without its state changing (a PR that went red, a review comment that reframes the work). Tier 1 catches state; only Tier 2 catches meaning. The freshness header is what keeps that from being a silent failure.

7. What this means for --auto

An unattended session has no human to present to, so the latency bar does not apply to it — but the tiering still helps, because an --auto run currently spends its first minutes on the same delta agent before it can select an increment.

The rule should be asymmetric and explicit: an interactive session presents at Tier 1 and lets Tier 2 revise; an --auto session waits for Tier 2 before selecting. Selection eligibility depends on judgment the mechanical tier cannot supply — whether a design is signed off, whether a repo is inside the grant matrix, whether an item is gated on @jwildfire. Selecting from a provisional list would let an unattended session start work on something that closed overnight. The tiering makes --auto's init no slower and no faster; it just stops it from being the design's driving constraint.

8. Relationship to #127 (/oneoff)

#127 proposes a separate lane that skips session startup entirely for quick bounded work, and its own Business Requirement names this issue as the tension: “if /session-init were genuinely fast, some of this need would shrink.”

If Tier 0 lands, most of it does shrink. A 3-second render of a list @jwildfire was going to want anyway is not a tax worth building a bypass around. What survives of #127 is the other half of its ask — a durable trace for work done outside a full session — which is about the closing bookend, not the opening one.

9. Instrumentation and the acceptance test

The requirement asks for per-step timing before any optimization merges. §3 satisfies part of that for the mechanical steps; three gaps remain, and they are exactly the steps this design moves off the critical path:

• Delta-subagent round trip (spawn → digest returned).
• Inbox triage, correlated against pending-thread count.
• Prioritize-and-present generation time, and its context cost against the #29 ~10% budget.

The implementation should emit a small timing ledger per init — one JSON line per step to .claude/session-hub/cache/init-timings.jsonl, appended, never committed — so the claim “first paint under 10 seconds” is a fact the next session can check rather than a target nobody re-measures. Suggested acceptance test, run three times on a warm workspace and three times cold:

t0  /session-init typed
t1  first paint (Tier 0 + Tier 1 rendered)     — assert t1 - t0 < 10 s
t2  Tier 2 revision posted (or "no changes")   — assert t2 - t0 < 2 min  (obot.agent#29)
    context consumed at t2                     — assert < 10% (obot.agent#29)

10. Decisions for @jwildfire

11. Risks and non-goals

• A provisional list read as final. The mitigation is the freshness header and nothing else; if the header is dropped for tidiness the design becomes a liability. It is load-bearing.
• Tier 2 quietly never running. A deferred pass that nobody notices missing is worse than a slow one that always runs. The timing ledger plus an explicit “no changes” line are the backstop.
• Wrapup quality becomes the latency budget. Render-first makes the first paint only as good as the last wrapup's list. That is the correct incentive — it is the lean-bookends contract — but it does mean a session that ends without a wrapup starts slow, via the fallback path.
• Non-goal: claude CLI process boot, MCP server startup, and machine-level factors stay out of scope, unchanged from the requirement's assumption 1.
• Non-goal: no change to what the wrapup writes. This design consumes the existing hand-off format; if the durable-todo-list work changes that format, this render follows it rather than the reverse.

12. Rollout

This design document was drafted by Claude Code using Opus 5 and reviewed by @jwildfire.