RecapService
Defined in: src/recap.ts:201
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new RecapService(
deps):RecapService
Defined in: src/recap.ts:229
Parameters
Section titled “Parameters”Returns
Section titled “Returns”RecapService
Methods
Section titled “Methods”considerForArchive()
Section titled “considerForArchive()”considerForArchive(
session):Promise<"error"|"started"|"empty"|"skip">
Defined in: src/recap.ts:351
Archive-hook entry point. Unlike sweep()/considerSession, this fires for EVERY
finishing session — including auto/drain — with NO debounce and NO auto-skip,
so every session gets a durable recap row for the Done lens (the live-sweep’s
skip of auto sessions would otherwise starve drained sessions of a recap).
Head-keyed dedup: if a recap already exists for the current HEAD we return “skip” (the common case — the live sweep usually already generated one), so we never double-spawn. Otherwise we generate synchronously.
Does NOT throw: a git/worktree-unavailable rev-parse failure self-heals to “error” rather than throwing out of the archive hook.
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”Promise<"error" | "started" | "empty" | "skip">
generate()
Section titled “generate()”generate(
session,knownHead?):Promise<"error"|"started"|"empty">
Defined in: src/recap.ts:394
Spawn a recap agent for session. Shared by sweep (auto) and regenerate (on-demand).
Returns: “empty” — diff had no files; an empty row is written and onChange is fired. “started” — spawn launched; a generating row is written. “error” — git (rev-parse/diff) failed, or herdr.start failed; any tmpdir is cleaned and no row is left so a later auto-settle can retry.
Does NOT throw — git/diff rejections are caught and surface as “error” — so callers
(incl. the bare-void sweep loop) need not guard it.
A synchronous in-flight guard prevents double-spawn if regenerate races sweep.
Parameters
Section titled “Parameters”session
Section titled “session”knownHead?
Section titled “knownHead?”string
Returns
Section titled “Returns”Promise<"error" | "started" | "empty">
onArchived()
Section titled “onArchived()”onArchived(
sessionId):void
Defined in: src/recap.ts:375
Slim archive cleanup: frees ONLY the per-session debounce entry. Without this the
debounce Map would leak entries for archived sessions (they never re-enter the
sweep’s active-session list to be cleared).
Deliberately does NOT reapGenerating — an in-flight spawn must be allowed to finish (it’s worktree-independent once launched, and tick() finalizes it post-archive) — and does NOT dropRecap — the row must persist for the Done lens.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”string
Returns
Section titled “Returns”void
regenerate()
Section titled “regenerate()”regenerate(
session):Promise<"error"|"started"|"empty">
Defined in: src/recap.ts:614
Force a fresh recap for ANY session, regardless of existing row / debounce / drain. Returns “empty” | “started” | “error”.
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”Promise<"error" | "started" | "empty">
snapshot()
Section titled “snapshot()”snapshot():
Record<string,Recap>
Defined in: src/recap.ts:622
Returns
Section titled “Returns”Record<string, Recap>
sweep()
Section titled “sweep()”sweep():
Promise<void>
Defined in: src/recap.ts:319
Periodic auto-fire. For each active session, debounce the settled-idle window then generate a recap once per idle episode (head-keyed).
Returns
Section titled “Returns”Promise<void>
tick()
Section titled “tick()”tick():
Promise<void>
Defined in: src/recap.ts:520
Finalize any generating recap whose verdict file is ready or that has timed out. Restart-safe: reads from the DB, not memory.
Returns
Section titled “Returns”Promise<void>