PlanGateService
Defined in: src/plan-gate.ts:192
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new PlanGateService(
deps):PlanGateService
Defined in: src/plan-gate.ts:244
Parameters
Section titled “Parameters”Returns
Section titled “Returns”PlanGateService
Methods
Section titled “Methods”adoptOrphans()
Section titled “adoptOrphans()”adoptOrphans():
Promise<void>
Defined in: src/plan-gate.ts:418
Re-adopt plan reviews that were in flight when the server last stopped. The inflight
map is in-memory only, so a restart mid-review used to orphan the reviewer forever: its
verdict was never read, the gate never advanced, and the planning agent sat idle waiting
for a re-review that would never come. This rebuilds those entries from the persisted
reviewer_spawns rows so the normal tick() finalizes them — reading the verdict the
reviewer already wrote, or timing the run out. Call once at boot, before the tick loop.
An orphan is a plan_gate spawn that never completed AND whose disposable worktree still
exists — finalize() reaps that worktree, so a surviving one means finalize never ran.
Returns
Section titled “Returns”Promise<void>
consider()
Section titled “consider()”consider(
session):Promise<PlanReviewTrigger>
Defined in: src/plan-gate.ts:268
Decide whether session’s current plan warrants a fresh adversarial review, and start one.
Returns "started" iff a reviewer actually spawned, "skipped" for a no-op (not planning,
in flight, no/unchanged plan, already approved), or "error" if a spawn was attempted but
failed. The on-demand “Review plan now” route relays this so the UI can tell a real review
from a silent dedupe — and a genuine failure from either — instead of just blinking the button.
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”Promise<PlanReviewTrigger>
dismiss()
Section titled “dismiss()”dismiss(
session):void
Defined in: src/plan-gate.ts:675
Operator “dismiss” for a plan stalled at the adversarial-review cap: reset the round
budget WITHOUT re-delivering findings (unlike resume, no steer is sent). The block
clears on the next poll tick once quotaBlockReason re-derives from the reset row.
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”void
forget()
Section titled “forget()”forget(
sessionId):void
Defined in: src/plan-gate.ts:702
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”string
Returns
Section titled “Returns”void
gcStaleReviewWorktrees()
Section titled “gcStaleReviewWorktrees()”gcStaleReviewWorktrees():
void
Defined in: src/plan-gate.ts:467
Reap stale plan-review worktrees left on disk by a prior run — e.g. the older of two
same-session orphans that adoptOrphans() left behind when it adopted the newer (#631). A
persisted, not-yet-finalized plan_gate spawn whose disposable worktree still exists but is
NOT in the live inflight set has no owner: nothing will ever read its verdict or remove it.
Two safety conditions make this sound:
(a) it MUST run once at boot AFTER adoptOrphans() has repopulated inflight, so every
genuinely-live orphan is already adopted (its worktree is in the inflight set below) and
only the truly ownerless duplicates remain to reap;
(b) the load-bearing invariant that begin() calls recordReviewerSpawn AFTER inflight.set —
so any persisted not-yet-finalized plan_gate row implies its run is already in inflight
(or it finalized, and finalize already removed the worktree). A future reorder putting
recordReviewerSpawn BEFORE inflight.set would let this GC reap a live spawning run, so
that ordering must not be changed.
Returns
Section titled “Returns”void
inflightWorktrees()
Section titled “inflightWorktrees()”inflightWorktrees():
string[]
Defined in: src/plan-gate.ts:651
Worktree paths of plan reviews currently owned in-memory — the GC sweep must spare these (a re-adopted #631 orphan’s tick() still needs its worktree).
Returns
Section titled “Returns”string[]
reapReviewer()
Section titled “reapReviewer()”reapReviewer(
sessionId):void
Defined in: src/plan-gate.ts:687
Reap any in-flight plan reviewer for a session WITHOUT dropping its persisted gate. Used when a planning session advances to execution (manual-steer-then-PR): the reviewer must stop, but the gate’s verdict + blocks stay reachable read-only for the life of the session. dropPlanGate is deferred to forget() at archive.
Parameters
Section titled “Parameters”sessionId
Section titled “sessionId”string
Returns
Section titled “Returns”void
resume()
Section titled “resume()”resume(
session):boolean
Defined in: src/plan-gate.ts:661
Operator “resume” for a plan stalled at the adversarial-review cap: reset the round budget so the at-cap stall clears, and re-deliver the outstanding findings so the planning agent revises. The normal consider() driver re-reviews once the revised plan changes its hash. Returns whether the steer reached the live pane (false if there’s nothing to resume or the pane was unreachable).
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”boolean
reviewingIds()
Section titled “reviewingIds()”reviewingIds():
string[]
Defined in: src/plan-gate.ts:645
Session ids with a plan review currently in flight (for client bootstrap).
Returns
Section titled “Returns”string[]
snapshot()
Section titled “snapshot()”snapshot():
Record<string,PlanGate>
Defined in: src/plan-gate.ts:640
Returns
Section titled “Returns”Record<string, PlanGate>
tick()
Section titled “tick()”tick():
Promise<void>
Defined in: src/plan-gate.ts:486
Finalize any in-flight plan review whose verdict file is ready or that timed out.
Returns
Section titled “Returns”Promise<void>
hashPlan()
Section titled “hashPlan()”
statichashPlan(plan):Promise<string>
Defined in: src/plan-gate.ts:259
sha256 of the plan text — dedups re-reviews of an unchanged plan.
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<string>