Create a new StateManager instance.
When true, state is held only in memory and never read from or written to disk. Useful for unit tests that need isolated state without side effects. Defaults to false (normal persistent mode).
Add closed PRs to storage, deduplicating by URL. Entries with URLs that fail parseGitHubUrl are dropped before persistence (read-side filters in dashboard-data already skip them, but this prevents the bad data from reaching disk in the first place).
Closed PRs to add (duplicates by URL are ignored)
OptionalcommentsFetchedAt?: stringWhen the raw review-comment bundle for this PR was last fetched (#867).
OptionallearningsExtractedAt?: stringWhen the host last ran LLM extraction over this PR's comment bundle (#867).
count of entries added vs. dropped (invalid URL)
Track a new issue. No-op if the issue URL is already tracked.
The issue to track
Add merged PRs to storage, deduplicating by URL. Entries with URLs that fail parseGitHubUrl are dropped before persistence (read-side filters in dashboard-data already skip them, but this prevents the bad data from reaching disk in the first place).
Merged PRs to add (duplicates by URL are ignored)
OptionalcommentsFetchedAt?: stringWhen the raw review-comment bundle for this PR was last fetched (#867).
OptionallearningsExtractedAt?: stringWhen the host last ran LLM extraction over this PR's comment bundle (#867).
count of entries added vs. dropped (invalid URL)
Add a repository to the trusted projects list. No-op if already trusted.
Repository in "owner/repo" format
Execute multiple mutations as a single batch, deferring disk I/O until the
batch completes. Nested batch() calls are flattened — only the outermost saves.
The function containing mutations to batch
Push current state to Gist (async). Call at well-defined moments (end of daily, after claim).
Remove excluded repos/orgs from trusted projects.
Repository names to exclude
Organization names to exclude
Remove a manual status override for a PR.
The PR URL
true if an override was removed, false if none existed
Tombstone the guidelines file for repo so subsequent reads return null.
Throws when not in Gist mode.
Dismiss an issue's notifications. Auto-resurfaces on new activity.
The issue URL to dismiss
ISO timestamp of dismissal
true if newly dismissed, false if already dismissed
Returns all stored closed-without-merge PRs (sorted by close date descending via addClosedPRs).
OptionalcommentsFetchedAt?: stringWhen the raw review-comment bundle for this PR was last fetched (#867).
OptionallearningsExtractedAt?: stringWhen the host last ran LLM extraction over this PR's comment bundle (#867).
Returns the most recent close date, used as a watermark for incremental fetching.
Read the per-repo guidelines for repo (#867). Returns null when in
local mode, when no file exists, or when the file is empty (tombstoned).
Returns repos above the score threshold.
OptionalminScore: numberMinimum score (default: config.minRepoScoreThreshold)
Get the timestamp when an issue was dismissed, or undefined if not dismissed.
The issue URL to check
Returns repos below the score threshold.
OptionalmaxScore: numberMaximum score (default: config.minRepoScoreThreshold)
Returns all stored merged PRs (sorted by merge date descending via addMergedPRs).
OptionalcommentsFetchedAt?: stringWhen the raw review-comment bundle for this PR was last fetched (#867).
OptionallearningsExtractedAt?: stringWhen the host last ran LLM extraction over this PR's comment bundle (#867).
Returns the most recent merge date, used as a watermark for incremental fetching.
Get the score record for a repository.
Repository in "owner/repo" format
Read-only score record, or undefined if not tracked
Returns repository names that have at least one merged PR.
Returns repository names with open PRs but no merged PRs yet.
Returns cached starred repository names.
Get the current state as a read-only snapshot.
Returns a staleness marker when the in-memory state diverged from the
canonical Gist (refresh failure or degraded bootstrap), or null when
state is current. Commands surface this via their --json warnings
envelope (#1193).
Returns aggregate contribution statistics (merge rate, PR counts, repo breakdown).
Get the status override for a PR, auto-clearing if new activity has occurred.
The PR URL
OptionalcurrentUpdatedAt: stringPR's current updatedAt timestamp for staleness check
The override if still valid, undefined otherwise
Increment the closed-without-merge PR count.
Repository in "owner/repo" format
Increment the merged PR count for a repository.
Repository in "owner/repo" format
Initialize state with sensible defaults for zero-config onboarding. No-op if setup is already complete.
Whether the Gist is in degraded mode (using local cache fallback).
Whether this StateManager is backed by a Gist.
Whether per-repo guidelines (#867) are available. True iff the Gist store is initialized — in local-only mode, guidelines are unavailable and write operations would throw GuidelinesNotAvailableError.
Check if a PR is currently shelved.
The PR URL to check
true if the PR is shelved
Check if initial setup has been completed.
Returns true if starred repos cache is older than 24 hours.
List repos with non-empty guidelines stored in the Gist.
Stamp commentsFetchedAt on the merged or closed PR matching url (#867).
No-op when no PR with that URL is stored.
Stamp learningsExtractedAt on the merged or closed PR matching url (#867).
No-op when no PR with that URL is stored.
Mark a repository as hostile (score zeroed).
Repository in "owner/repo" format
Mark setup as complete and record the completion timestamp.
Re-fetch state from the backing Gist (if in Gist mode). Throttled to once per 30 seconds by GistStateStore. Returns true if state was refreshed.
Re-read state from disk if the file has been modified since the last load/save. Returns true if state was reloaded, false if unchanged or in-memory mode.
Persist the current state to disk, creating a timestamped backup of the previous
state file first. In in-memory mode, only updates lastRunAt without any file I/O.
In Gist mode, writes to a local cache file (not the main state file) so the Gist
remains the source of truth. Use checkpoint() to push state to the Gist.
Local-file mode uses optimistic compare-and-swap: if another process has
written state.json since we last loaded/saved, saveState throws
ConcurrencyError. See issue #1030.
ConcurrencyError (local file mode only) when the on-disk state
was modified externally between this StateManager's last load/save
and now. Callers that tolerate silent merge can set
{ allowReloadAndLoseMutation: true } to downgrade the error into a
warning — but note that doing so abandons any in-memory mutation
made since the last load. Fail-loud (the default) is preferred.
Persist per-repo guidelines for repo. Throws when not in Gist mode or
when content exceeds the byte budget.
Store the latest daily digest and update the digest timestamp.
The daily digest to store
Persist the timestamp of the most recent strategy snapshot embedded
in a daily run output (#1270). Called from the daily pipeline after
computeStrategy() succeeds; the cadence gate in
shouldComputeStrategy reads this on the next run.
Update the local repository cache.
Local repository cache mapping repo names to paths
Update monthly closed PR counts for dashboard display.
Monthly closed PR counts keyed by YYYY-MM
Update monthly merged PR counts for dashboard display.
Monthly merged PR counts keyed by YYYY-MM
Update monthly opened PR counts for dashboard display.
Monthly opened PR counts keyed by YYYY-MM
Update the cached starred repositories and timestamp.
Repository names in "owner/repo" format
Set a manual status override for a PR. Auto-clears when the PR has new activity.
The PR URL
The overridden status
ISO timestamp of PR's last activity when override was set
Shelve a PR URL, hiding it from daily digest and capacity.
The PR URL to shelve
true if newly shelved, false if already shelved
Restore a dismissed issue to notifications.
The issue URL to undismiss
true if undismissed, false if not currently dismissed
Unshelve a PR URL, restoring it to daily digest.
The PR URL to unshelve
true if removed from shelf, false if not shelved
Merge partial config updates into the current configuration.
Partial config object to merge
Update scoring data for a repository.
Repository in "owner/repo" format
Partial score fields to merge
StaticcreateAsync factory that creates a StateManager backed by a GitHub Gist.
The regular constructor is synchronous (for backwards-compat), but Gist bootstrapping requires network calls, so this factory is async.
GitHub personal access token with gist scope
Core module exports Re-exports all core functionality for convenient imports