AppDeps
Defined in: src/server.ts:151
Properties
Section titled “Properties”activity?
Section titled “activity?”
optionalactivity?:object
Defined in: src/server.ts:186
Last-emitted activity signal per running session, for client bootstrap; absent in tests that skip it.
snapshot()
Section titled “snapshot()”snapshot():
Record<string,SessionActivity>
Returns
Section titled “Returns”Record<string, SessionActivity>
autoMerge?
Section titled “autoMerge?”
optionalautoMerge?:object
Defined in: src/server.ts:331
Full-auto merge train snapshot; absent in tests that don’t exercise it.
snapshot()
Section titled “snapshot()”snapshot():
Promise<AutoMergeStatus[]>
Returns
Section titled “Returns”Promise<AutoMergeStatus[]>
backlog?
Section titled “backlog?”
optionalbacklog?:Pick<CountsService,"counts">
Defined in: src/server.ts:267
Backlog counts service; absent in tests that don’t exercise it.
claudeAlive?
Section titled “claudeAlive?”
optionalclaudeAlive?:object
Defined in: src/server.ts:190
Last-swept claude-process liveness per session (does a claude process still
live in the worktree?), for client bootstrap; updates flow via the
session:claude-alive event. Absent in tests that skip it.
snapshot()
Section titled “snapshot()”snapshot():
Record<string,boolean>
Returns
Section titled “Returns”Record<string, boolean>
diagnostics?
Section titled “diagnostics?”
optionaldiagnostics?:Pick<DiagnosticsService,"current"|"check"|"fix">
Defined in: src/server.ts:166
environment-readiness diagnostics (issue #623); absent in tests that don’t wire it.
distiller?
Section titled “distiller?”
optionaldistiller?:object
Defined in: src/server.ts:276
Learning distiller — manual trigger for the proposal pass over a repo’s transcripts. Optional so environments/tests that don’t wire it still type-check; the route no-ops the trigger when absent. Wired to the real DistillerService in index.ts.
distillNow
Section titled “distillNow”distillNow: (
repoPath) =>void
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”void
health?
Section titled “health?”
optionalhealth?: () =>object
Returns
Section titled “Returns”object
consecutiveFailures
Section titled “consecutiveFailures”consecutiveFailures:
number
lastFailure
Section titled “lastFailure”lastFailure: {
at:number;reason:string;repoPath:string; } |null
ok:
boolean
docAgent?
Section titled “docAgent?”
optionaldocAgent?:object
Defined in: src/server.ts:309
PR-gated AI doc agent (issue #882). Optional + flag-gated (config.docAgentEnabled); the route 404s when the flag is off or the service is unwired. Wired to DocAgentService in index.ts.
consider
Section titled “consider”consider: (
repoPath) =>Promise<DocAgentResult>
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”Promise<DocAgentResult>
drain?
Section titled “drain?”
optionaldrain?:object
Defined in: src/server.ts:317
Self-draining work queue snapshot; absent in tests that don’t exercise it.
approveEpicNext()
Section titled “approveEpicNext()”approveEpicNext(
repoPath):void
Operator approves the next epic-attended spawn for the given repo.
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”void
buildEpic()
Section titled “buildEpic()”buildEpic(
repoPath,run):Promise<Epic|null>
Assemble the live Epic for a repo’s running epic (server routes + pump).
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”Promise<Epic | null>
queue()
Section titled “queue()”queue(
repoPath):Promise<QueuedItem[]>
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”Promise<QueuedItem[]>
retainClaim()
Section titled “retainClaim()”retainClaim(
id):void
One-shot: keep ACTIVE_LABEL on the next session:archived for this id (a
relaunch is not a retire — the actively-worked issue stays claimed).
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
snapshot()
Section titled “snapshot()”snapshot():
Promise<DrainStatus[]>
Returns
Section titled “Returns”Promise<DrainStatus[]>
tick()
Section titled “tick()”tick():
Promise<void>
Drive one pump cycle across all drain-enabled repos.
Returns
Section titled “Returns”Promise<void>
events
Section titled “events”events:
EventHub
Defined in: src/server.ts:154
githubOwnersRunner?
Section titled “githubOwnersRunner?”
optionalgithubOwnersRunner?:GhOutRunner
Defined in: src/server.ts:340
Injectable stdout gh runner for GET /api/github/owners. Absent in production
(listGithubOwners falls back to the real gh runner); tests inject a fake so the
owner-enumeration route can be exercised without hitting GitHub.
githubReposRunner?
Section titled “githubReposRunner?”
optionalgithubReposRunner?:GhOutRunner
Defined in: src/server.ts:344
Injectable stdout gh runner for GET /api/github/repos. Absent in production
(listGithubRepos falls back to the real gh runner); tests inject a fake so the
repo-enumeration route can be exercised without hitting GitHub.
gitignoreAdopter?
Section titled “gitignoreAdopter?”
optionalgitignoreAdopter?:object
Defined in: src/server.ts:313
Open a PR adding Shepherd’s managed .shepherd-* ignore block to a repo’s .gitignore.
adopt: (
repoPath) =>Promise<AdoptResult>
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”Promise<AdoptResult>
herdDigest?
Section titled “herdDigest?”
optionalherdDigest?:object
Defined in: src/server.ts:258
Herd Rundown digest — the daily cross-session attention synthesis. Absent in tests
that don’t exercise it. snapshot is the latest stored digest (null when none yet);
currentFingerprint re-derives the herd’s live attention surface so the GET route can
compute staleCount (drift since the digest was generated); regenerate forces a
fresh spawn.
currentFingerprint()
Section titled “currentFingerprint()”currentFingerprint():
Record<string,string[]>
Returns
Section titled “Returns”Record<string, string[]>
regenerate()
Section titled “regenerate()”regenerate():
Promise<"error"|"started"|"empty"|"in-flight">
Returns
Section titled “Returns”Promise<"error" | "started" | "empty" | "in-flight">
snapshot()
Section titled “snapshot()”snapshot():
HerdDigest|null
Returns
Section titled “Returns”HerdDigest | null
herdr?
Section titled “herdr?”
optionalherdr?:Pick<HerdrDriver,"list">
Defined in: src/server.ts:176
Herdr driver (for liveness checks). Absent in some tests; gate fails open.
herdrUpdates?
Section titled “herdrUpdates?”
optionalherdrUpdates?:Pick<HerdrUpdateService,"current"|"apply">
Defined in: src/server.ts:164
herdr-version tracker + applier; absent in environments where it isn’t wired.
hooks?
Section titled “hooks?”
optionalhooks?:object
Defined in: src/server.ts:215
Phase-0 hook ingest ring buffer (issue #704); absent in tests/envs that skip it.
record is observe-only here — it forwards to signals only when Task 3 wires
onSignal (the hooksSignals flag).
allSubagentsSnapshot()
Section titled “allSubagentsSnapshot()”allSubagentsSnapshot():
Record<string,SubagentEntry[]>
Every tracked session’s sub-agent roster, keyed by sessionId (Phase 3, #710);
served at GET /api/subagents for a global bootstrap, mirror of activity.
Returns
Section titled “Returns”Record<string, SubagentEntry[]>
record()
Section titled “record()”record(
id,ev):void
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
snapshot()
Section titled “snapshot()”snapshot(
id):HookEvent[]
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”mergeSuggest?
Section titled “mergeSuggest?”
optionalmergeSuggest?:object
Defined in: src/server.ts:298
Background merge-suggestion pass — manual per-repo trigger (“Suggest merges now”). Optional so tests that don’t wire it still type-check; route no-ops when absent.
mergeNow
Section titled “mergeNow”mergeNow: (
repoPath) =>void
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”void
newProjectGhRunner?
Section titled “newProjectGhRunner?”
optionalnewProjectGhRunner?:GhRunner
Defined in: src/server.ts:336
Injectable gh CLI runner for the POST /api/projects remote step. Absent in
production (createProject falls back to the real gh runner); tests inject a
fake so the route’s partial-success mapping can be exercised WITHOUT creating
real GitHub repos.
optimizer?
Section titled “optimizer?”
optionaloptimizer?:object
Defined in: src/server.ts:287
Learning optimizer — operator-triggered LLM rewrite pass over flagged (“not working”) rules. Optional so tests that don’t wire it still type-check; routes no-op when absent. Wired to the real OptimizerService in index.ts.
health?
Section titled “health?”
optionalhealth?: () =>object
Returns
Section titled “Returns”object
consecutiveFailures
Section titled “consecutiveFailures”consecutiveFailures:
number
lastFailure
Section titled “lastFailure”lastFailure: {
at:number;reason:string;repoPath:string; } |null
ok:
boolean
optimizeAllFlagged
Section titled “optimizeAllFlagged”optimizeAllFlagged: (
repoPath) =>void
Parameters
Section titled “Parameters”repoPath
Section titled “repoPath”string
Returns
Section titled “Returns”void
optimizeOne
Section titled “optimizeOne”optimizeOne: (
id) =>void
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”void
ownsPr?
Section titled “ownsPr?”
optionalownsPr?: (s,headSha) =>boolean|null
Defined in: src/server.ts:184
Whether a name-matched terminal PR’s head commit belongs to the session’s branch — same guard the poller injects, so the on-demand git endpoint can’t flip GitRail to a false MERGED on a reused-name collision. Absent → unguarded (tests).
Parameters
Section titled “Parameters”headSha
Section titled “headSha”string
Returns
Section titled “Returns”boolean | null
planGate?
Section titled “planGate?”
optionalplanGate?:object
Defined in: src/server.ts:235
Trigger an adversarial plan review for a session on demand (the /review-plan route). Wired to PlanGateService.consider in index.ts; absent in tests that don’t exercise it.
consider()
Section titled “consider()”consider(
session):Promise<PlanReviewTrigger>
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”Promise<PlanReviewTrigger>
dismiss()?
Section titled “dismiss()?”
optionaldismiss(session):void
Reset the plan-gate round WITHOUT re-delivering findings (dismiss the quota block).
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”void
resume()?
Section titled “resume()?”
optionalresume(session):boolean
Reset the plan-gate round so the quota block clears, re-delivering findings to the agent.
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”boolean
planGateCache?
Section titled “planGateCache?”
optionalplanGateCache?:object
Defined in: src/server.ts:229
Snapshot of plan-gate verdicts keyed by session id (+ in-flight reviewer ids); absent in tests that skip it. The parallel of reviewCache for the pre-execution plan gate.
reviewing()?
Section titled “reviewing()?”
optionalreviewing():string[]
Returns
Section titled “Returns”string[]
snapshot()
Section titled “snapshot()”snapshot():
Record<string,PlanGate>
Returns
Section titled “Returns”Record<string, PlanGate>
poller?
Section titled “poller?”
optionalpoller?:Pick<StatusPoller,"acknowledgeStall"|"ingestActivity"|"ingestNotification">
Defined in: src/server.ts:211
Status poller; used to manually dismiss a stall flag (acknowledgeStall) and, when
hooksSignals is on, as the Phase-1 signal sink the index.ts onSignal closure feeds
push events to (ingestActivity / ingestNotification — issue #704). The route
itself never calls the ingest methods; the onSignal closure in index.ts does.
prCache?
Section titled “prCache?”
optionalprCache?:PrCache
Defined in: src/server.ts:179
In-memory PR-status cache surfaced in the list overview; absent in tests that don’t exercise it.
presence?
Section titled “presence?”
optionalpresence?:Pick<Presence,"set"|"drop">
Defined in: src/server.ts:206
Active-window tracker fed by /events presence frames; gates push suppression.
preview?
Section titled “preview?”
optionalpreview?:object
Defined in: src/server.ts:197
Live preview port per session, for client bootstrap; absent until PreviewService is wired (Task 2+).
session:preview events are emitted via PreviewService.onChange in index.ts.
snapshot()
Section titled “snapshot()”snapshot():
Record<string,SessionPreviewState>
Returns
Section titled “Returns”Record<string, SessionPreviewState>
previewServe?
Section titled “previewServe?”
optionalpreviewServe?:object
Defined in: src/server.ts:202
Tailscale serve registration status per session slot; absent when auto-serve is disabled or tailscale is unavailable. Merged into /api/preview responses.
snapshot()
Section titled “snapshot()”snapshot():
Record<string,"ok"|"failed">
Returns
Section titled “Returns”Record<string, "ok" | "failed">
promoter?
Section titled “promoter?”
optionalpromoter?:object
Defined in: src/server.ts:303
Promote a curated rule into the repo’s CLAUDE.md via an auto-opened PR, or a cross-repo recurrence rule into the user-global ~/.claude/CLAUDE.md directly (#872).
promote
Section titled “promote”promote: (
id) =>Promise<PromoteResult>
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<PromoteResult>
promoteGlobal
Section titled “promoteGlobal”promoteGlobal: (
rule) =>Promise<PromoteResult>
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<PromoteResult>
optionalpush?:Pick<PushService,"publicKey"|"subscribe"|"unsubscribe">
Defined in: src/server.ts:204
Web Push delivery; absent in tests that don’t exercise notifications.
recap?
Section titled “recap?”
optionalrecap?:object
Defined in: src/server.ts:252
Force-regenerate a session recap on demand (the /recap/regenerate route).
regenerate()
Section titled “regenerate()”regenerate(
session):Promise<"error"|"started"|"empty">
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”Promise<"error" | "started" | "empty">
recapCache?
Section titled “recapCache?”
optionalrecapCache?:object
Defined in: src/server.ts:250
Snapshot of session recaps keyed by session id; absent in tests that skip it.
snapshot()
Section titled “snapshot()”snapshot():
Record<string,Recap>
Returns
Section titled “Returns”Record<string, Recap>
refreshBacklog?
Section titled “refreshBacklog?”
optionalrefreshBacklog?: (repoDir) =>Promise<void>
Defined in: src/server.ts:272
Force-refresh one repo’s backlog counts (bypassing the read-TTL) and push the rebuilt overview to every client. Fired after a mutation that changes a repo’s open issue/PR counts (e.g. a merge) so the counters + headline drop the item immediately instead of lingering until the next warm poll. Absent in tests.
Parameters
Section titled “Parameters”repoDir
Section titled “repoDir”string
Returns
Section titled “Returns”Promise<void>
refreshUsage?
Section titled “refreshUsage?”
optionalrefreshUsage?: () =>Promise<UsageLimits>
Defined in: src/server.ts:158
Force a /usage re-scrape (calibration) and return fresh limits; absent in tests that
don’t wire the live calibrator (the route then falls back to the current snapshot).
Returns
Section titled “Returns”Promise<UsageLimits>
resolveForge?
Section titled “resolveForge?”
optionalresolveForge?: (repoDir) =>GitForge|null
Defined in: src/server.ts:160
Resolve the git forge for a repo dir; null when none is configured.
Parameters
Section titled “Parameters”repoDir
Section titled “repoDir”string
Returns
Section titled “Returns”GitForge | null
reviewCache?
Section titled “reviewCache?”
optionalreviewCache?:object
Defined in: src/server.ts:223
Snapshot of critic verdicts keyed by session id (+ in-flight run ids); absent in tests that skip it.
reviewing()?
Section titled “reviewing()?”
optionalreviewing():string[]
Returns
Section titled “Returns”string[]
snapshot()
Section titled “snapshot()”snapshot():
Record<string,ReviewVerdict>
Returns
Section titled “Returns”Record<string, ReviewVerdict>
reviewTrigger?
Section titled “reviewTrigger?”
optionalreviewTrigger?:object
Defined in: src/server.ts:244
Operator-initiated critic review (the POST /review-pr route). Wired to ReviewService.forceReview in index.ts; absent in tests that don’t exercise it.
clearStallState()?
Section titled “clearStallState()?”
optionalclearStallState(session):void
Reset escalation counters WITHOUT re-triggering a review (dismiss the quota block).
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”void
force()
Section titled “force()”force(
session,git):Promise<ReviewOutcome>
Parameters
Section titled “Parameters”session
Section titled “session”Returns
Section titled “Returns”Promise<ReviewOutcome>
service
Section titled “service”service:
SessionService
Defined in: src/server.ts:153
starPrompt?
Section titled “starPrompt?”
optionalstarPrompt?:object
Defined in: src/server.ts:169
GitHub-star nudge: tracks first-use + the operator’s choice, stars the repo via gh. Absent in tests that don’t exercise it.
dismiss()
Section titled “dismiss()”dismiss():
StarPromptStatus
Returns
Section titled “Returns”snooze()
Section titled “snooze()”snooze():
StarPromptStatus
Returns
Section titled “Returns”star()
Section titled “star()”star():
Promise<StarPromptStatus>
Returns
Section titled “Returns”Promise<StarPromptStatus>
status()
Section titled “status()”status():
StarPromptStatus
Returns
Section titled “Returns”store:
SessionStore
Defined in: src/server.ts:152
updates?
Section titled “updates?”
optionalupdates?:Pick<UpdateService,"current"|"apply"> &Partial<Pick<UpdateService,"applyState">>
Defined in: src/server.ts:162
Self-update tracker; absent in environments where it isn’t wired.
usageLimits
Section titled “usageLimits”usageLimits:
Pick<UsageLimitsService,"limits">
Defined in: src/server.ts:155
verifyKey?
Section titled “verifyKey?”
optionalverifyKey?: () =>Promise<VerifyKeyResult>
Defined in: src/server.ts:265
Verify the configured api-key authenticates end-to-end (the /settings/verify-key route); absent in environments where it isn’t wired. Returns only {ok,reason?,detail?} — no key/path.
Returns
Section titled “Returns”Promise<VerifyKeyResult>
workingBlocked?
Section titled “workingBlocked?”
optionalworkingBlocked?:object
Defined in: src/server.ts:194
Sessions herdr reports blocked whose TUI shows a live turn spinner
(working-while-blocked display flag), for client bootstrap; updates flow via
the session:working-blocked event. Absent in tests that skip it.
snapshot()
Section titled “snapshot()”snapshot():
Record<string,boolean>
Returns
Section titled “Returns”Record<string, boolean>