daemon

type AbortRoleSessionsResult struct {
	Count int
	Err   error
}

type ActivationListResult struct {
	Candidates []activationCandidate
}

type ActivationPollObservation struct {
	AllSatisfied    bool
	FailedRIDs      []string
	EvidenceSummary string
	Reason          string
	Now             time.Time
}

type AssemblyFixerDispatcher func(ctx context.Context, task role.AssemblyFixerTask) (role.AssemblyFixerResult, []string, error)

type AssemblyFixerEventPayload struct {
	Result    role.AssemblyFixerResult
	Coercions []string
}

type BlockedUserPROpenResultEvent struct {
	Results []blockedUserPROpenIssueResult
	At      time.Time
}

type CIRunChecker interface {
	DispatchedWorkflowRunStatus(ctx context.Context, repoSlug, workflowName, ref string, dispatchedAt time.Time) (conclusion string, runID int64, headSHA string, err error)
}

type CPBChildSquashResult struct {
	ChildKey         string
	PlanKey          string
	PlanBranch       string
	RepoSHAs         map[string]string
	FailureKind      CPBSquashFailureKind
	FailureReason    string
	FailureRepo      string
	ConflictingPaths []string
	GateStdout       []byte
	GateStderr       []byte
	// GateExitCode is the failing gate subprocess's exit code, threaded
	// from *github.AssembleGateFailure.ExitCode (SOR-2400 closed the
	// "capture gap" where applyCPBChildSquashResult passed a hardcoded 0
	// to ClassifyGateFailureEnvironment). Populated only on a Gate
	// failure; -1 marks a signal-terminated gate process so the env-class
	// classifier reaches the signal:-1 arm.
	GateExitCode int
	// GateDeadlineKill is true when the gate was killed by its own
	// phase-scoped deadline (cpbPrePushGateTimeout) rather than by an
	// external signal (SOR-2400). Maps from *github.AssembleGateDeadlineKill;
	// drives the CPBSquashFailureGateDeadline routing in
	// applyCPBChildSquashResult.
	GateDeadlineKill bool

	// RerereAutoResolved is true when at least one repo's per-child squash
	// committed via the rerere-fully-resolved branch (the `git merge
	// --squash` exited non-zero, zero unmerged paths remained, and a
	// rerere-staged tree was committed) — the signal threaded up from
	// ChildSquasher / SquashChildIntoPlanBranch. applyCPBChildSquashResult
	// emits a distinct cpb_squash_rerere_autoresolved audit event on the
	// success path when this is set, so a recurring auto-resolved-conflict
	// rate stays observable rather than indistinguishable from a clean
	// squash (SOR-2390). False on a clean exit-zero squash, a
	// resolver-resolved squash, and the net-no-op success.
	RerereAutoResolved bool

	// CircuitBreakerEngaged / CircuitBreakerRejectedPayload are transient
	// signaling fields the main loop sets DURING applyCPBChildSquashResult
	// (not by the off-main squash producer): when
	// dispatchCPBSquashFailureToAssemblyFixer trips the consecutive-
	// validator-rejection circuit-breaker it sets CircuitBreakerEngaged and
	// records the last rejected assembly_fixer payload excerpt here so the
	// caller's refer-back-to-feedback comment can surface what the fixer
	// was trying to say. CircuitBreakerRejectedPayload is populated only
	// when CircuitBreakerEngaged is true (and a payload was recorded).
	CircuitBreakerEngaged         bool
	CircuitBreakerRejectedPayload string

	// FullResolverVerdict carries the FULL untruncated merge-resolver
	// give-up reason threaded out of buildCPBMergeResolverClosure (the best
	// available: the resolver's verbatim FailureReason prose on a genuine
	// give-up, or the trimmed infra error on the infra-transient arm).
	// applyCPBChildSquashResult persists it via captureAndPersistResolverDiagnosis
	// so the durable diagnostic row holds the verbatim verdict the 500-byte
	// cpb_squash_resolver_failed event truncates. Populated only on a
	// CPBSquashFailureConflict result; zero-valued elsewhere.
	FullResolverVerdict string
}

type CPBIntegrationReviewEntry struct {
	// ChildKey is the just-squashed child whose squash created this review
	// point — the integration surface being reviewed.
	ChildKey string `json:"child_key"`
	// Reason is why the surface triggered a review: cpbReviewReasonOverlap (its
	// footprint conflicts with a prior-squashed sibling's) or
	// cpbReviewReasonCadence (the footprint-independent backstop).
	Reason string `json:"reason,omitempty"`
	// Status is the review lifecycle: cpbReviewStatusPending at dispatch,
	// cpbReviewStatusClean / cpbReviewStatusFinding once the verdict returns.
	Status string `json:"status"`
	// SessionID is the interim review session this surface dispatched. The
	// returning verdict is matched back to this entry by session id, so the
	// outcome lands on exactly the surface it reviewed.
	SessionID string `json:"session_id,omitempty"`
	// FindingDetail carries the first substantive concern's detail when the
	// review recorded a finding (cpbReviewStatusFinding); empty otherwise.
	FindingDetail string `json:"finding_detail,omitempty"`
}

type CPBMergeResolverResult struct {
	ChildKey string
	RepoSlug string
	Teardown func()
	Success  bool
	Reason   string
	// HoldNoProvider (SPEC-SOR-3197-v1 R4/R11) is set when the resolver's
	// dispatcher returned a no_provider error mid-retry (PoolExhaustedError /
	// spawn_picker_unavailable — the OAuth pool exhausted before a session could
	// spawn). It signals a HOLD rather than a genuine resolver give-up: when set,
	// applyMergeResolverResult emits the reused pause row and re-dispatches the
	// squash (which the proactive gate holds again while the pool is unavailable)
	// instead of escalating the child through escalateSubject. Zero-valued (false)
	// on every other result, so existing CPBMergeResolverResult literals default
	// to the unchanged give-up path.
	HoldNoProvider bool
}

type CPBSquashFailureKind int

type Cadence struct {
	Active time.Duration // when relevant work is in flight
	Idle   time.Duration // when nothing is in flight (or paused entirely if Idle == 0)
}

type CallCounts struct {
	Implementer   int
	Reviewer      int
	MergeResolver int
	AssemblyFixer int
}

type CapabilityGapParkPayload struct {
	PlanKey             string
	GapIssueKey         string
	CapabilitySignature string
}

type CapabilityGapReleaseProbePlanResult struct {
	PlanKey     string
	GapIssueKey string
	IsDeployed  bool
}

type CapabilityGapReleaseProbeResultPayload struct {
	Results []CapabilityGapReleaseProbePlanResult
}

type ChildActualDiffResolver interface {
	// ComputeChildActualDiff returns the unioned per-repo diff: the
	// sorted set of paths the child's branch touched plus the per-path
	// post-diff content (for anchor resolution). The implementer's
	// repo set is `child.Repos`; the child branch is `child.Branch`
	// (falls back to gh.ChildWorkingBranchName when empty).
	ComputeChildActualDiff(ctx context.Context, child *sm.Issue, planBranch string) (files []string, contents map[string][]byte, err error)
}

type ChildSquasher func(ctx context.Context, repoSlug, planBranch string, child gh.ChildBranchToAssemble) (string, bool, error)

type CommentMutationResult struct {
	ID  int64
	TS  int64
	Err error
}

type CommitVerifier func(ctx context.Context, repo, sha string) (found bool, err error)

type Config struct {
	// ProjectRoot is the directory containing .sorcerer/. The daemon
	// reads/writes state.json under it. Required.
	ProjectRoot string
	// BuildCommit is the running daemon binary's embedded build commit SHA
	// (cmd/sorcererd buildProvenance().Commit — the SAME value threaded into
	// recognizer.Config.BuildCommit). The capability-gap park chokepoint
	// (parkPlanOnCapabilityGap) stamps it onto each capability_gap_block record
	// as parked_at_daemon_build, so the operator can tell a deploy-lag park from
	// a live one. Empty when the build is unstamped (an unwired test daemon).
	BuildCommit string
	// BranchPrefix is prepended to the lowered issue key when the
	// supervisor mints an implementer branch. Already normalized by
	// config.applyDefaults to either "" or end-with-slash. Empty =
	// bare issue key.
	BranchPrefix string
	// ProjectLanguage is the managed project's config-sourced primary
	// language (config.ProjectLanguage(cfg)). It is the single signal the
	// product path consults to learn a project's language, keeping
	// language-specific behavior config-sourced rather than assuming Go (the
	// product-self boundary; spec R5). The zero value ("") is treated as Go
	// by every consumer so unwired test daemons keep the Go path.
	ProjectLanguage string
	// ProjectIsForeign reports whether the managed project is foreign (not the
	// sorcerer self-hosting project) — populated from config.ProjectIsForeign(cfg)
	// at daemon start (SPEC-SOR-3317-v1 R2). When true the product-footprint-altitude
	// gate is inert: the refusal that fires for a product-domain issue whose
	// footprint touches no product-engine-source path never fires on a foreign
	// daemon, so a foreign project is no longer subjected to sorcerer-self
	// self-hosting altitude semantics. The zero value (false) is self: it preserves
	// the gate's self-daemon refusal exactly for every unwired test daemon and
	// legacy config (the product-self boundary).
	ProjectIsForeign bool
	// DeclaredLanguages is the managed project's config-sourced DECLARED
	// language SET (config.DeclaredLanguages(cfg)) — the multi-language analog
	// of ProjectLanguage. The traceability-matrix generator consults it to
	// classify each trace target per-file against the declared set and drop a
	// FOREIGN target (a file owned by no declared language) from the regenerated
	// matrix (SOR-3096), so a {rust} project's matrix never references .go
	// targets tracematrix-verify cannot resolve. The zero value (nil/empty)
	// means "no declared-set filtering" — every target passes as native,
	// preserving today's behavior for unwired test daemons and legacy configs.
	DeclaredLanguages []string
	// PropTestRunnerFor resolves the project's config-DECLARED prop_test runner
	// for a language (config.PerLanguageConfig.PropTestRunner), threaded from
	// cmd/sorcererd/start.go. generatePropTestStubUnion feeds the result through
	// langprofile.ResolvePropTestRunner so a language with runner variants
	// (TypeScript) emits the selected runner's stub idiom (SPEC-SOR-3093-v1 R4).
	// It is nil-safe: a nil field (every unwired test daemon / legacy config)
	// means "no declared runner", so selection falls to detection/default and the
	// emitted stub stays byte-identical to today's default-runner output. An empty
	// returned string for a given language means the same.
	PropTestRunnerFor func(lang string) string
	// PrePushGate is the managed project's config-sourced pre-push gate
	// command (config.ProjectPrePushGate(cfg)), mirroring the ProjectLanguage
	// plumbing. cmd/sorcererd/start.go populates it and threads the SAME value
	// into the github.Client (WithPreConfiguredGate) and the pre-push verifier
	// (NewPrePushGateVerifier), so the daemon-resolved managed gate is hermetic
	// and language-native. Empty means "use the language-native auto-detected
	// default" — never a self-asset assumption (the product-self boundary).
	PrePushGate string
	// RelevanceInputsCommand is the project-declared tier-2 build-input
	// closure command (config.ProjectRelevanceInputsCommand(cfg)). When
	// non-empty, the relevance gate runs it OFF the main goroutine and parses
	// its newline-delimited stdout into the declared inputs closure; empty
	// means no declared command, so the tier-3 conservative fallback applies
	// (every main-advance is relevant). Wired from config in cmd/sorcererd;
	// the zero value keeps the conservative fallback so unwired test daemons
	// preserve today's all-advances-relevant behavior.
	RelevanceInputsCommand string
	// DeclaredArtifactPaths is the project's flattened set of declared
	// generated-artifact output paths (the GeneratedFiles of every
	// config.DeclaredGeneratedArtifacts entry, flattened — see
	// cmd/sorcererd/start.go declaredArtifactPaths). It is threaded into the
	// footprint-admission chokepoint (seatPredictedFootprint →
	// footprint.FilterDeclaredArtifactPaths), so a footprint declaring a
	// daemon-generated artifact path is stripped before seating regardless of
	// source. The matching httpapi.Config.PlanDeclaredArtifactPaths threads the
	// same value into the plan validator's proposal-time guard. Empty/nil keeps
	// the matrix-only behavior, so an unconfigured project (and unwired test
	// daemons) preserve the prior guard.
	DeclaredArtifactPaths []string
	// ArtifactVerifyConfigured is true when at least one config-declared generated
	// artifact carries a non-empty VerifyArgv — i.e. the github.Client was wired
	// with a non-nil artifact verifier (runtime.ArtifactVerifierFn(cfg) != nil).
	// The daemon forwards it into invariants.SnapshotInput so the
	// generated-artifact-regenerated-at-seam drift invariant fires only for projects
	// that actually declare a verify command; an unconfigured project (and unwired
	// test daemons) leave it false, so the invariant stays silent.
	ArtifactVerifyConfigured bool
	// MaxConcurrentImplementers is the concurrency cap passed to
	// schedule.Pick. Defaults to 2.
	MaxConcurrentImplementers int
	// MaxActivePlans is the CIPB admission cap on the number of plans in the
	// active integration window (plan_awaiting_children or plan_integrating) at
	// once. A continuous_plan_branch plan approved while the window is full
	// parks in admission_pending until a slot frees, rather than creating its
	// plan branch immediately. Defaults to 3, independent of (and not derived
	// from) MaxConcurrentImplementers.
	MaxActivePlans int
	// EventBufferSize is the events channel capacity. Defaults to 64.
	EventBufferSize int
	// SchedulerDebounce is how long the debouncer waits for the burst to
	// settle. Defaults to 100ms.
	SchedulerDebounce time.Duration
	// FlowStallThreshold is how long the scheduler-pass producer (the
	// Debouncer) may leave a trigger unserviced before the flow-liveness
	// monitor (SOR-2630) judges event flow stalled and self-heals. A
	// ZERO value DISABLES the monitor entirely — the deliberate default
	// for test daemons (no monitor goroutine, no os.Exit risk). Production
	// wires the config-sourced default (~5 min) via start.go; New does
	// NOT default it, so the monitor is strictly opt-in.
	FlowStallThreshold time.Duration
	// FlowStallCheckInterval is the flow-liveness monitor's tick cadence.
	// Ignored when FlowStallThreshold is zero. Production default ~1 min
	// (config-sourced); a zero value with a non-zero threshold disables
	// the monitor (the monitor's Run requires both > 0).
	FlowStallCheckInterval time.Duration
	// FlowStallExitFn is the flow-liveness monitor's process-exit hook,
	// injected so tests capture the exit instead of killing the test
	// process. nil (production) defaults to os.Exit. Mirrors the
	// SignalNotify/SignalStop test-seam pattern.
	FlowStallExitFn func(int)
	// SchedulerPass is invoked after each debounce window. If nil, the
	// daemon uses its own RunSchedulerPass implementation.
	SchedulerPass SchedulerPass
	// Pollers are external-state poll goroutines. The daemon adopts
	// them — Start/Stop is the daemon's responsibility.
	Pollers []*Poller
	// ShutdownGrace bounds how long Run waits for in-flight handlers
	// during shutdown. Defaults to 30s.
	ShutdownGrace time.Duration
	// Logger is optional; nil disables daemon-level logs (events and
	// escalations are persisted to the issuestore regardless).
	Logger Logger

	// SignalNotify / SignalStop inject the os/signal wiring used by
	// installSignalHandler. nil (production) falls through to the real
	// signal.Notify / signal.Stop. Tests inject these to drive the
	// shutdown-on-signal path with a synthetic signal value instead of
	// sending a real SIGTERM to the shared `go test` process: a real
	// self-SIGTERM races the handler install, and any window where the
	// handler is not yet registered reverts SIGTERM to its default
	// disposition, terminating the whole test binary.
	SignalNotify func(c chan<- os.Signal, sig ...os.Signal)
	SignalStop   func(c chan<- os.Signal)

	// ImplementerDispatcher is invoked from the scheduler pass for each
	// ready leaf. nil disables implementer dispatch (Phase 2 daemon).
	ImplementerDispatcher ImplementerDispatcher
	// ReviewerDispatcher is invoked when an issue lands in in_review with
	// a complete PR set.
	ReviewerDispatcher ReviewerDispatcher

	// ImplementerDiscovery / ReviewerDiscovery carry the per-project
	// discovery-phase tuning knobs (config.Roles.*) the supervisor reads at
	// dispatch time to set the discovery dispatch's model/effort override,
	// and at telemetry time to attribute the completion + deviation events
	// and gate the deviation threshold. Zero value preserves today's
	// behavior (frontmatter-default model/effort, 30% threshold).
	ImplementerDiscovery DiscoveryRoleConfig
	ReviewerDiscovery    DiscoveryRoleConfig
	// ImplementerRuntime is the per-project implementer dispatch runtime
	// (config runtime.implementer): "container" routes the implementer
	// claude subprocess through the ContainerRunner, "native" or empty
	// keeps it on the host. dispatchImplementerSession stamps it onto the
	// dispatched task's RuntimeSelector for both the discovery and
	// implementation phases. Empty preserves today's native dispatch.
	ImplementerRuntime string
	// MergeRunner is invoked when an issue transitions to merging.
	MergeRunner MergeRunner
	// MergeOptions are passed to MergeRunner. Strategy defaults to "squash".
	MergeOptions gh.MergeOptions
	// PlanLandingGateRunner runs the FRESH, uncached landing gate for one
	// (repo, plan-branch) pair before the plan PR's MergeSet lands the tree
	// on main (spec SPEC-SOR-3035-v2 R7/R8/R9/R13). It is the authoritative
	// last verification before main — never served from the gate-verdict
	// cache — so a tree that was only ever a cache HIT at an intermediate
	// plan-branch seam still gets a full, fresh gate run here. Wired to
	// (*github.Client).RunPlanLandingGate in cmd/sorcererd/start.go; nil
	// disables the landing gate (test mode / back-compat), in which case
	// dispatchPlanPRMergeSet proceeds straight to MergeRunner as before.
	PlanLandingGateRunner func(ctx context.Context, repoSlug, planBranch, planKey string) error
	// PlanPROpener opens the plan PR for one repo of a `branch_model:
	// plan_branch` planning issue (SOR-1139): a single PR per repo whose
	// head is the long-lived plan branch and whose base is the repo's
	// default branch. dispatchPlanPR calls it once per repo after every
	// plan_branch child's work has landed on the plan branch. Returns the
	// gh-emitted PR URL. Production wiring uses (*github.Client).OpenPlanPR;
	// nil routes a plan_branch plan's PR-open to plan_blocked (the daemon
	// cannot open the plan PR).
	PlanPROpener func(ctx context.Context, repoSlug, planBranch, title, body string) (string, error)

	// PerChildPROpener opens the per-child PR for one repo of a
	// `branch_model: per_child` implementation issue. Daemon-side peer
	// of PlanPROpener: opening the PR moved from the implementer's
	// `gh pr create` into the daemon so the verifier chain gates the
	// open — a red chain leaves no stale PR behind on GitHub.
	// applyImplementerResult's per_child success arm calls it once per
	// repo in iss.Repos AFTER the verifier chain reports green, before
	// the implementing → in_review transition.
	//
	// baseBranch is empty for the common case (gh defaults to the
	// repo's default branch); set when the per_child issue stacks on a
	// sibling's working branch. Production wiring uses
	// (*github.Client).OpenPerChildPR; nil routes a per_child success
	// to blocked_user via the per_child_pr_open_failed escalation
	// (parallel to plan_pr_open_failed).
	PerChildPROpener func(ctx context.Context, repoSlug, headBranch, baseBranch, title, body string) (string, error)

	// Verifiers is the ordered chain of deterministic gates the daemon
	// runs against the implementer's pushed branch on every success-
	// path emit BEFORE the per-branch-model in_review transition. Each
	// Verifier executes against an ephemeral worktree carved off the
	// bare clone pinned to the freshly-fetched tip of the implementer's
	// branch; the chain short-circuits on the first failing verifier
	// and the supervisor routes the issue back through the existing
	// refer-back machinery as synthetic ReviewConcern rows so the next
	// feedback-N dispatch carries the captured output. A nil / empty
	// slice skips the gate entirely (the test-mode + back-compat
	// shape); production wiring assigns
	// `[]Verifier{NewPrePushGateVerifier(cfg.CleanupGoBuildCacheMaxBytes(), sink)}`
	// in cmd/sorcererd/start.go. Forward-looking enforcement of
	// `do-not-do-X` rules plugs in as additional Verifier instances on
	// this slice — the LLM cannot bypass a gate it cannot see.
	Verifiers []Verifier

	// LLMVerifierRunner is the oracle-runner handle threaded onto every
	// VerifierEnv (env.LLMRunner) so the llm_test executor can emit a
	// structured pass/fail verdict for a requirement's traced code. nil
	// (the default + back-compat shape) disables llm_test invocations until
	// that oracle executor ships; the deterministic executors ignore it.
	// Production wiring assigns the clauderunner-backed implementation in
	// cmd/sorcererd/start.go.
	LLMVerifierRunner LLMVerifierRunner

	// GateRuntimeFactory mints a fresh gateruntime.GateRuntime per gate
	// subprocess dispatch — the configured runtime chokepoint every daemon
	// verifier-chain gate spawn routes through (spec R1). Threaded onto every
	// VerifierEnv (env.GateRuntimeFactory). nil (the default + back-compat
	// shape) leaves each spawn site on a fresh &gateruntime.NativeGateRunner{}
	// fallback, reproducing the prior direct host spawn. Production wiring
	// assigns the native factory in cmd/sorcererd/start.go.
	GateRuntimeFactory func() gateruntime.GateRuntime

	// GateRuntimeLabel is the configured gate-dispatch runtime (config
	// runtime.gate: "native" | "container") the verify-chain gate-result
	// audit event carries so the warm-container-vs-native latency-parity
	// comparison can be made from the events table (AC: every gate-result
	// event carries runtime=native|container + duration). It always agrees
	// with GateRuntimeFactory in production (start.go derives both from
	// cfg.Runtime.Gate); empty normalizes to "native" at the emit site.
	GateRuntimeLabel string

	// GateGovernorStat returns the daemon-global gate governor's live running
	// and configured-capacity counts (SPEC-SOR-3122-v2). New wires it into
	// store.State.GateGovernorStat so the gate-concurrency-within-capacity
	// runtime invariant (R12) observes the at-most-K bound live. nil (the
	// test/back-compat shape) leaves State.GateGovernorStat nil — the
	// "no governor wired" sentinel the invariant skips on.
	GateGovernorStat func() (running, capacity int)
	// GateHarnessTimeout is the daemon-authoritative effective harness timeout
	// (the parsed form of config.ProjectGateHarnessTimeout), populated at daemon
	// start and forwarded to the invariants sweep as
	// SnapshotInput.GateHarnessTimeout so the gate-harness-timeout-below-budget
	// runtime invariant (SPEC-SOR-3074-v1 R5) orders it below the gate-subprocess
	// SIGKILL budget (DefaultPrePushGateTimeout). Zero means "no config override
	// set; the gate script's own fallback applies" — the invariant skips on zero.
	GateHarnessTimeout time.Duration
	// GateQueuedGates returns the number of gate dispatches currently blocked
	// waiting for a governor slot. verifierChainStale reads it (nil-safe) to
	// suppress stale-reaping a verifier chain that is merely queued behind
	// running gates rather than genuinely idle (R4 — a queued gate is alive,
	// not stalled). nil (the test/back-compat shape) disables the guard, so
	// staleness reverts to the pure age check.
	GateQueuedGates func() int

	// WorkflowDispatcher dispatches a named GitHub Actions workflow on a ref —
	// the dispatch_workflow primitive the SOR-2503 activation driver fires for a
	// dispatch_workflow-triggered activation criterion (spec R11). Production
	// wiring assigns *github.Client (it satisfies WorkflowDispatcher via
	// DispatchWorkflow). nil disables only the dispatch_workflow firing path (a
	// such-triggered probe defers to pending rather than failing).
	WorkflowDispatcher WorkflowDispatcher

	// ActivationCIChecker is the narrow CI-run-status accessor the activation
	// driver threads into each ci_run probe's ProbeContext (the SOR-2502
	// CIRunChecker). Production wiring assigns *github.Client (it satisfies it
	// via DispatchedWorkflowRunStatus). nil makes a ci_run probe evaluate to
	// pending (CI access not wired) rather than fail.
	ActivationCIChecker CIRunChecker

	// ActivationProbeEvaluator is the activation-driver test seam: when wired it
	// REPLACES the deterministic EvaluateActivationProbe (SOR-2502) so a test can
	// drive firing + polling with fake probe results (no live workflow run / CI
	// query / worktree). nil (the production default) runs the real evaluator.
	ActivationProbeEvaluator func(ctx context.Context, probe *dsl.ActivationProbe, pctx ProbeContext) (string, *role.ProbeEvidence, error)

	// VerifierWorktreeAcquirer carves the ephemeral worktree the
	// implementer post-submit verifier chain runs each Verifier
	// against. Production wiring composes
	// `(*github.Client).AcquireVerifierWorktree`; the returned
	// teardown is invoked synchronously after the chain run completes
	// (success OR failure) so the bare clone's admin metadata stays
	// clean. nil disables the chain entirely (the back-compat shape:
	// no carve = no chain) so a test that wants a chain run with
	// stub verifiers and a hand-built worktree can pass an in-test
	// closure here.
	VerifierWorktreeAcquirer func(ctx context.Context, projectRoot, repoSlug, issueKey, branch, planBranch string) (string, func(), error)

	// PlanPRReadyForReviewMarker flips a draft plan PR to ready-for-review
	// (CIPB Phase A+B audit Fix 5). Called from applyPlanPROpenResults
	// the moment the plan transitions to plan_awaiting_pr_merge: every
	// per-child squash has landed and the cumulative diff is ready for
	// final review. Production wiring uses (*github.Client).MarkPRReadyForReview;
	// nil disables the flip (the PR stays as draft and the final
	// reviewer can flip it manually; the cycle still progresses because
	// CI runs on the draft too).
	PlanPRReadyForReviewMarker func(ctx context.Context, prURL string) error
	// PlanBranchFinalReviewOptionalAtSingleChild mirrors
	// config.PlanBranchFinalReviewOptionalAtSingleChild() (SOR-1139). When
	// true AND a plan_branch planning issue materialized exactly one
	// child, the daemon skips the mandatory final reviewer cycle on the
	// plan PR and merges directly. Defaults to false — the final reviewer
	// always runs.
	PlanBranchFinalReviewOptionalAtSingleChild bool
	// MaxRefererBackCycles caps how many `feedback-N` rounds an issue may
	// go through before escalating to blocked_user. Defaults to 3.
	MaxRefererBackCycles int
	// SessionMaxAges maps role name → wall-clock budget. Sessions that
	// exceed their budget are marked timed_out by the per-session timer.
	SessionMaxAges map[string]time.Duration
	// WorktreeCleanup is called for each (issue, repo) when an issue
	// terminates (merged / abandoned). nil disables cleanup; the
	// production wiring uses internal/github.RemoveWorktree.
	WorktreeCleanup func(projectRoot, issueKey, repoSlug string) error
	// PlanBranchWorktreeCleanup is the per-(plan, child, repo) analog
	// of WorktreeCleanup for `branch_model: plan_branch` issues
	// (SOR-1136). Called for each (plan, child, repo) triple when a
	// plan_branch child issue terminates (merged / abandoned). nil
	// disables plan-branch worktree cleanup; production wiring uses
	// internal/github.RemovePlanChildWorktree.
	PlanBranchWorktreeCleanup func(projectRoot, planKey, childKey, repoSlug string) error
	// WorktreePrep ensures a worktree exists for (issue, repo) on the
	// given branch and returns its absolute path. Called from
	// dispatchImplementer before the goroutine runs. Production wiring
	// composes EnsureBareClone + AddWorktree from internal/github.
	// nil falls back to the canonical WorktreeDir path with no FS
	// preparation — useful for tests that don't actually run an agent.
	WorktreePrep func(ctx context.Context, issueKey, repoSlug, branchName string) (string, error)
	// DeferredChildWorktreePrep is the deferred-integration per-(plan,
	// child, repo) worktree prep for branch_model: plan_branch children:
	// under deferred integration no long-lived plan branch is minted at
	// dispatch, so the child working branch is carved off baseBranch
	// instead — origin's default branch (baseBranch == "") when the child
	// has no sibling dependency, or a sibling dependency's working branch
	// (baseBranch != "") when the child stacks on one. Production wiring
	// composes EnsureBareClone + AddDeferredPlanChildWorktree. childBranch
	// is the per-child working branch (ChildWorkingBranchName). nil falls
	// back to PlanBranchWorktreeDir with no FS preparation — for tests
	// that don't run an agent.
	DeferredChildWorktreePrep func(ctx context.Context, planKey, childKey, repoSlug, childBranch, baseBranch string) (string, error)
	// PlanFixWorktreePrep is the SOR-1329 plan-PR-fix worktree prep.
	// Called from dispatchPlanPRFix before the
	// implementer goroutine runs, once per repo. Production wiring composes
	// EnsureBareClone + EnsurePlanBranch + AddPlanFixWorktree: the worktree
	// is checked out on the plan branch DIRECTLY (no per-child branch), so
	// the fix implementer commits + pushes the plan branch and the open
	// plan PR auto-advances. planBranch is the long-lived plan branch
	// (PlanBranchName). nil falls back to PlanFixWorktreeDir with no FS
	// preparation — useful for tests that don't actually run an agent.
	PlanFixWorktreePrep func(ctx context.Context, planKey, repoSlug, planBranch string) (string, error)
	// PlanFixWorktreeCleanup is the per-(plan, repo) analog of
	// PlanBranchWorktreeCleanup for the SOR-1329 plan-PR-fix worktrees.
	// Called best-effort when a fix dispatch resolves (success or failure)
	// and from the terminal plan-branch cleanup hook. nil disables plan-fix
	// worktree cleanup; production wiring wraps RemovePlanFixWorktree.
	PlanFixWorktreeCleanup func(projectRoot, planKey, repoSlug string) error
	// EphemeralWorktreePruner prunes stale, locked plan-branch ephemeral
	// worktrees (plan-assemble- / cpb-main-merge- / cpb-squash- / verifier-)
	// left on disk when the daemon was killed mid-operation, returning the
	// prune count. Called by the periodic ephemeral-worktree-prune sweep off
	// the main goroutine (pure filesystem + git I/O against the bare clones;
	// touches no d.state). nil disables the sweep — test daemons that don't
	// manage real bare clones leave it unset. Production wiring wraps
	// gh.Client.PruneStaleEphemeralWorktrees with EphemeralWorktreeMaxAge.
	// The pruner emits one ephemeral_worktree_pruned audit event per reaped
	// worktree through the github client's EventSink.
	EphemeralWorktreePruner func(ctx context.Context) (int, error)
	// EphemeralWorktreeLister is the read-only probe behind the
	// worktree-no-leaked-locked-ephemeral runtime invariant. For one
	// daemon-managed bare clone it returns that clone's locked ephemeral
	// worktrees (plan-assemble- / cpb-main-merge- / cpb-squash- / verifier-
	// prefixed) with each one's path, lock reason, and age. Consumed by the
	// invariants-check sweep — wired into invariants.SnapshotInput's
	// WorktreeListProbe so the invariant can flag a leaked, locked ephemeral
	// worktree whose owning operation died before it collides with a later
	// `git worktree add`. Unlike EphemeralWorktreePruner it never mutates the
	// bare clone. Production wiring wraps
	// (*github.Client).ListLockedEphemeralWorktrees via
	// runtime.EphemeralWorktreeListerFn; nil disables the invariant's check
	// (test daemons that don't manage real bare clones leave it unset).
	EphemeralWorktreeLister func(ctx context.Context, bareClone string) ([]invariants.LockedEphemeralWorktree, error)
	// PerIssueWorktreeLister enumerates every top-level per-issue worktree
	// wrapper under <projectRoot>/.sorcerer/worktrees/, returning each one's
	// key basename, absolute path, and mtime age (SOR-2817). Consumed by
	// sweepPerIssueWorktreeGC — the periodic per-issue worktree GC backstop,
	// the self-heal analog of EphemeralWorktreePruner keyed on owning-issue
	// terminal state rather than worktree age. The sweep snapshots the
	// reapable owner-key set from d.state on-main, then runs this lister +
	// the os.RemoveAll reap off-main (the no-main-loop-blocking-call
	// contract). nil disables the GC sweep — test daemons that don't manage a
	// real project tree leave it unset. Production wiring wraps
	// (*github.Client).ListPerIssueWorktrees via runtime.PerIssueWorktreeListerFn.
	PerIssueWorktreeLister func(ctx context.Context) ([]gh.PerIssueWorktreeEntry, error)
	// PlanPRCommenter posts a plain comment on a plan PR (SOR-1329). The
	// autonomous refer-back resolver uses it to record the final
	// reviewer's concerns + rationale on each plan PR so the fix
	// implementer can read them via `gh pr view`. Best-effort: a nil hook
	// or an error is logged and never blocks the fix dispatch (the
	// concerns also ride the implementer envelope's PLAN_PR_REFER_BACK
	// block). Production wiring wraps gh.Client.CommentOnPR.
	PlanPRCommenter func(ctx context.Context, prURL, body string) error
	// PlanPRViewer fetches one plan PR's current state for the SOR-1360
	// pending-CI poller. Returns the full github.PR shape so the poller
	// can read mergeable + mergeable_state + statusCheckRollup at the
	// action boundary (rather than caching upstream from the final
	// reviewer's stale view). Production wiring uses
	// (*github.Client).ViewPR; nil disables the pending-CI poller (plans
	// in plan_pr_merge_pending_ci sit there until an operator intervenes).
	PlanPRViewer func(ctx context.Context, prURL string) (*gh.PR, error)
	// PlanPRBranchDiscoverer looks up the most recent PR (any state —
	// OPEN | CLOSED | MERGED) for the canonical plan branch name on
	// repoSlug (SOR-1375). The runtime + boot-time plan external-merge
	// auto-recovery paths fall back to this when iss.PRURLs is empty —
	// the bridge case for a plan PR opened by the operator after a manual
	// assembly resolution, where the daemon never recorded the URL.
	// Returns (nil, nil) when no PR exists for that branch; the recovery
	// then skips this (plan, repo). Production wiring uses
	// (*github.Client).FindPRByBranchAnyState; nil disables the fallback
	// (PRURLs-populated detection still runs).
	PlanPRBranchDiscoverer func(ctx context.Context, repoSlug, branchName string) (*gh.PR, error)
	// PlanPROpenDiscoverer looks up the OPEN PR for the canonical plan
	// branch name on repoSlug (`gh pr list --head <plan-branch> --state
	// open`). The cpb-pr-url-backfill boot sweep uses it to backfill
	// iss.PRURLs from an already-open plan PR when a restart landed between
	// the PR-open dispatch and its result event — closing the duplicate-
	// PR-open class on the recovery side. Returns (nil, nil) when no open
	// PR exists for that branch; the sweep then skips this (plan, repo).
	// Production wiring uses (*github.Client).FindPRByBranch; nil disables
	// the sweep.
	PlanPROpenDiscoverer func(ctx context.Context, repoSlug, branchName string) (*gh.PR, error)
	// PlanPRMergePendingCITimeout is the wall-clock cap on how long a
	// plan may sit in plan_pr_merge_pending_ci before the poller routes
	// it to plan_blocked with the ci_timeout escalation. Reads
	// config.PlanBranch.PRMergePendingCITimeoutSeconds; defaults to
	// 2 hours in applyDefaults. SOR-1360.
	PlanPRMergePendingCITimeout time.Duration
	// PlanPRMergePendingCIStallBound is the wall-clock bound after which a
	// non-terminal required check in plan_pr_merge_pending_ci is treated as
	// stalled and the daemon recovers it (rung 1 re-dispatch, rung 2 escalate)
	// rather than polling forever — the SOR-2773 never-terminating-check
	// strand. Reads config.PlanBranch.PRMergePendingCIStallBoundSeconds;
	// defaults to 60 minutes in applyDefaults, strictly below the 90-min
	// completed-plan-merge-latency-bounded window so recovery precedes the
	// strand. SOR-3152.
	PlanPRMergePendingCIStallBound time.Duration
	// CompletedPlanProgressWindow is the leader-progress / yield-ceiling
	// window for completedPlanHoldsHeadOfLine: a strictly-older completed
	// plan holds the head-of-line over a ready follower only while its land
	// step is in flight and its last advance is within this window. Reads
	// config.PlanBranch.CompletedPlanProgressWindowSeconds; defaults to
	// 300 seconds in applyDefaults. A zero value falls back to a 5-minute
	// sentinel inside the predicate so an un-wired test daemon still bounds
	// the hold. SOR-2685.
	CompletedPlanProgressWindow time.Duration
	// ActionsRerunner re-requests every failed Actions run on the given
	// (repoSlug, headSHA) pair via gh's REST surface. Returns the
	// number of runs re-requested. The Actions-only flake-retry path
	// uses this exactly once per (check, head-SHA) before falling
	// through to the existing CI-failure refer-back routing.
	// Production wiring uses (*github.Client).RerunFailedActionsRuns;
	// nil disables the flake-retry path (terminal-failure CI routes
	// straight to feedback as it did pre-fix). Tests stub in a fake
	// that records the call.
	ActionsRerunner func(ctx context.Context, repoSlug, headSHA string) (int, error)
	// ActionsWaitTimeout is the per-child `verdict_merge` wall-clock
	// cap on how long the daemon waits for Actions to report terminal-
	// success on the PR's head SHA before routing the issue to
	// blocked_user with escalation reason `actions_wait_timeout`. Reads
	// config.Daemon.ActionsWaitTimeoutSeconds; defaults to 45 minutes
	// in applyDefaults.
	ActionsWaitTimeout time.Duration
	// RoleWorktreeCleanup is the per-(role, session, repo) analog of
	// WorktreeCleanup for the reviewer / planner / plan_reviewer roles.
	// Called best-effort when a role session tears down (clean exit,
	// dispatcher error, ctx-cancel, panic-unwind) and from the boot-time
	// orphan reap. Failures are logged, never fatal. nil disables
	// role-worktree cleanup; production wiring wraps
	// internal/github.RemoveRoleWorktree.
	RoleWorktreeCleanup func(projectRoot, role, sessionID, repoSlug string) error
	// RoleWorktreePrep ensures a private detached worktree exists for a
	// (role, session, repo) triple and returns its absolute path. The
	// reviewer / planner / plan_reviewer roles are read-mostly and never
	// push, so there is no caller-supplied branch. nil falls back to no
	// FS preparation (prepareRoleWorktree returns an empty path + nil
	// error). Production wiring composes EnsureBareClone + a detached
	// worktree. Consumed by the three role dispatch sites.
	RoleWorktreePrep func(ctx context.Context, role, sessionID, repoSlug string) (string, error)
	// PRSetDiscoverer is the GitHub-side hook for PR-set discovery: the
	// supervisor calls this to find the implementer's branch's open PR in
	// every affected repo. SOR-1148: this is the PRIMARY path on the
	// IMPLEMENT_OK success seam — the implementer no longer supplies PR
	// URLs, so the daemon discovers them here (one FindPRByBranch lookup
	// per repo) before transitioning to in_review. It is ALSO the
	// crash-before-marker recovery path (session ended without emitting
	// IMPLEMENT_OK). A complete set means the work is durable; the
	// supervisor writes iss.PRURLs and transitions the issue to
	// in_review. The map's values carry both the PR URL and the head SHA
	// gh reported at discovery time — the blocked_user dedupe sweep
	// reuses the SHA to detect operator commits that should bypass the
	// cooldown. Returns (nil, *recovery.PartialSetError) on partial sets
	// — the supervisor must NOT mark the issue in_review on those.
	// nil disables recovery; on the success seam a nil hook routes the
	// issue to blocked_user (the daemon cannot derive the PR set).
	PRSetDiscoverer func(ctx context.Context, branch string, repos []string) (map[string]DiscoveredPR, error)

	// DefaultBranchResolver resolves repoSlug's default branch (origin's
	// HEAD, e.g. "main") to its short name. The deferred-integration
	// reviewer dispatch calls it once per repo on a branch_model:
	// plan_branch child that has no sibling dependency, to populate
	// ReviewerTask.BaseRef — the ref the child branch was carved off and
	// the reviewer diffs against (`git diff <base>..<child-branch>`). A
	// child that stacks on a sibling dependency uses that sibling's
	// working branch as the base instead and never calls this. Production
	// wiring uses (*github.Client).DefaultBranchName; nil makes the
	// no-sibling-dep plan_branch reviewer dispatch fail. Unused for
	// per_child issues.
	DefaultBranchResolver func(ctx context.Context, repoSlug string) (string, error)

	// MergeResolverDispatcher is the autonomous-resolver dispatch hook
	// the plan-branch assembler's ConflictResolver closure calls when a
	// child's squash conflicts (SOR-1373). When non-nil, the daemon
	// builds a ConflictResolver closure that translates each
	// AssemblyConflictDispatch into a role.MergeResolverTask, dispatches
	// the `merge_resolver` agent, and retries up to
	// mergeResolverMaxRetries (N=2) attempts per conflicting child
	// before falling through to today's `failPlanAssemble` →
	// `plan_blocked` cascade. When nil, the daemon passes nil to
	// AssemblePlanBranch and today's direct-to-plan_blocked path is
	// preserved bit-for-bit. Production wiring uses
	// role.NewMergeResolverDispatcher; the retry budget is not
	// user-tunable.
	MergeResolverDispatcher MergeResolverDispatcher

	// AssemblyFixerDispatcher is the autonomous-fix-up dispatch hook
	// the daemon's plan_auto_fixing follow-on calls when a plan's
	// cumulative dry-run gate (SOR-1443 Fix 1) or real assembly push
	// fails. When non-nil, the daemon renders an AssemblyFixerTask
	// (carrying the captured pre-push gate artifact path + the parked-
	// children cohort) and dispatches the `assembly_fixer` agent; the
	// supervisor applies each emitted action (file_implementation_issue,
	// refer_back_child, escalate_capability_gap) through existing
	// mutation surfaces. The outer-retry budget is M=2 dispatches per
	// plan before the supervisor synthesizes an
	// escalate_capability_gap on exhaustion so the autonomy gap is
	// tracked sorcerer-side regardless. When nil, plan_auto_fixing
	// stays as a pure SM state and the operator must re-arm manually
	// (`sorcerer issue transition <P-key> plan_auto_fixing` is
	// operator-only) — useful for test daemons that don't wire a
	// agentcli. Production wiring uses
	// role.NewAssemblyFixerDispatcher.
	AssemblyFixerDispatcher AssemblyFixerDispatcher

	// EnsurePlanBranchFn is the CIPB Phase B plan-branch creator. For a
	// continuous_plan_branch planning issue that just landed at
	// plan_awaiting_children, dispatchPlanBranchCreate calls it once per
	// affected repo: ensure the canonical plan branch (PlanBranchName)
	// exists in the bare clone AND on origin, cut from origin's current
	// default branch. Production wiring composes EnsureBareClone +
	// EnsurePlanBranch from internal/github. Idempotent — a branch that
	// already exists is a no-op (the implementation short-circuits both
	// the local-ref probe and the ls-remote probe). nil falls back to
	// a no-op skip (test daemons that don't actually run git); the
	// supervisor's follow-on sweep tolerates the absence by leaving
	// PlanCommitSHAs unset for affected repos.
	EnsurePlanBranchFn func(ctx context.Context, repoSlug, planBranch string) error

	// ResetPlanBranchFn resets an existing plan branch back to current
	// main's tip for a re-decomposition, so the new decomposition's
	// children build on a clean base with none of the prior (canceled)
	// decomposition's diverged commits. Production wiring composes
	// (*github.Client).ResetPlanBranchToMain (delete-then-push the captured
	// main SHA — never a force-push). nil falls back to a no-op skip (test
	// daemons that don't run git); the re-decomposition consumption seam
	// tolerates the absence.
	ResetPlanBranchFn func(ctx context.Context, repoSlug, planBranch string) error

	// ClosePlanPRFn closes the prior plan PR for a re-decomposed planning
	// issue. no-op-safe when the PR is already closed, already merged, or
	// absent. Production wiring composes (*github.Client).ClosePlanPR. nil
	// falls back to a no-op skip (test daemons that don't run gh).
	ClosePlanPRFn func(ctx context.Context, repoSlug, prURL string) error

	// ChildActualDiffResolver computes the per-child actual diff used by
	// emitPredictionCheckWithRealDiff (CIPB Phase A+B audit Fix 1). The
	// Phase A/B PRs left the EmitPredictionCheck hook sites passing
	// nil/nil — every event classified every predicted file as
	// over_predicted and emitted zero anchor data, poisoning Phase D's
	// learning loop before it starts. This resolver runs `git diff
	// --name-only` + `git show` in the child's bare clone and feeds the
	// real file list + per-path content into EmitPredictionCheck.
	// Production wiring uses NewChildActualDiffResolver(ghClient,
	// projectRoot, branchPrefix); a nil resolver falls through to the
	// pre-fix EmitPredictionCheck(nil, nil, now) so tests that don't
	// wire git still exercise the emission path.
	ChildActualDiffResolver ChildActualDiffResolver

	// ImplementerCycleDiffStater computes the best-effort git-diff numstat
	// totals (files changed / lines added / lines removed) for an
	// implementer cycle's worktree branch, feeding the
	// implementer_cycle_summary telemetry. Invoked off-main in the
	// dispatch goroutine (never on the single-writer main loop) with the
	// dispatch's per-repo worktree paths. Production wiring uses
	// NewImplementerCycleDiffStater(ghClient, projectRoot); a nil stater
	// leaves the file/line fields zero (the test path, and any cycle whose
	// branch never materialized). Best-effort: an error is logged and the
	// event records zero totals.
	ImplementerCycleDiffStater ImplementerCycleDiffStater

	// PlanBranchHeadResolver probes the current HEAD SHA of a plan branch
	// in the bare clone (CIPB Phase A+B audit fix-up). Called by
	// applyPlanBranchCreateResult AFTER EnsurePlanBranchFn succeeds so
	// the per-repo PlanCommitSHAs entry records the actual commit SHA
	// (not just the branch name). Production wiring uses
	// (*github.Client).PlanBranchHeadSHA; nil falls back to recording the
	// branch name as the sentinel (the pre-audit-fix behavior). The brief
	// (Fix 7) mandates the actual SHA so the field honors its name.
	PlanBranchHeadResolver func(ctx context.Context, repoSlug, planBranch string) (string, error)

	// PlanBranchRemoteRefResolver probes the live state of a plan branch
	// on origin: `git ls-remote origin refs/heads/<planBranch>` in the
	// bare clone. Returns (sha, exists, err): exists==false with a nil
	// err means the ref is genuinely absent on origin; a non-nil err is a
	// probe failure the caller must skip on. Consumed by the
	// invariants_check sweep — wired into invariants.SnapshotInput so the
	// plan-branch existence + tip-consistency invariants can detect a
	// mid-lifecycle plan whose branch was deleted (or whose recorded tip
	// drifted) on origin. Production wiring uses
	// (*github.Client).PlanBranchRemoteRef; nil disables the plan-branch
	// invariants' check (test daemons that don't run git).
	PlanBranchRemoteRefResolver func(ctx context.Context, repoSlug, planBranch string) (string, bool, error)

	// ChildSquasher is the CIPB Phase B per-child squash handler. For a
	// continuous_plan_branch child whose reviewer just returned `merge`,
	// the daemon transitions in_review → merging and spawns the squash
	// session goroutine; the goroutine invokes ChildSquasher once per
	// repo. The squasher carves an ephemeral worktree off the bare
	// clone, checked out to the plan-branch tip, runs `git merge --squash`
	// of the child's working branch, runs the per-push gate, pushes the
	// new plan-branch tip, and returns the new plan-branch HEAD SHA.
	//
	// The trailing resolver argument is the autonomous merge-resolver
	// callback: when the squash conflicts AND resolver is non-nil, the
	// squasher invokes resolver synchronously inside the locked
	// ephemeral worktree; the resolver lands a clean resolution commit
	// and the squasher pushes. A nil resolver routes the conflict
	// directly to *github.AssembleConflict (the daemon then routes the
	// child to feedback). Production wiring uses
	// (*github.Client).SquashChildIntoPlanBranch; nil routes a cpb
	// `merge` verdict's squash to blocked_user (the daemon cannot
	// squash).
	ChildSquasher ChildSquasher

	// ConflictedWorktreeCarver re-materializes a per-child squash conflict in a
	// fresh ephemeral worktree carved off the bare clone so the daemon can
	// dispatch the merge_resolver on its OWN session budget — decoupled from the
	// squash episode (SOR-2739). The squash op (ChildSquasher) returns
	// *github.AssembleConflict and tears down its own worktree without running
	// any resolver; applyCPBChildSquashResult's conflict arm calls this to
	// reproduce the conflict markers for the resolver to edit. The resolver's
	// commit inside the carved worktree auto-records the rerere resolution in the
	// shared rr-cache, which the re-dispatched finalize's re-squash replays.
	// Returns the worktree path, conflicting paths, a teardown closure, and an
	// error. Production wiring uses
	// runtime.ConflictedWorktreeCarverFn(ghClient, projectRoot); a nil carver
	// makes the conflict arm fall through to the legacy assembly_fixer / feedback
	// safety net (test daemons that don't run git).
	ConflictedWorktreeCarver func(ctx context.Context, repoSlug, planBranch, childBranch string) (string, []string, func(), error)

	// PlanMainMerger is the CIPB Phase C main-merge handler. Under the
	// event-triggered model (SOR-2187) the sweepPlanMainMerge tick spawns
	// the off-main origin/<default> tip-change probe; a probed tip that
	// advanced past the recorded one dispatches dispatchPlanMainMerge,
	// which calls this once per repo. The merger carves an ephemeral
	// worktree off the bare
	// clone, runs `git merge --no-ff origin/<default>` against the
	// live plan-branch tip, runs the per-push gate against the merge
	// commit, and pushes the new plan-branch tip with a REGULAR push
	// (NEVER --force, NEVER --force-with-lease — locked by
	// TestMergeDefaultIntoPlanBranch_PushIsNeverForce).
	//
	// The trailing resolver argument is the autonomous merge-resolver
	// callback: when the merge conflicts AND resolver is non-nil, the
	// merger invokes resolver inside the locked ephemeral worktree;
	// the resolver lands a clean resolution commit and the merger
	// pushes. A nil resolver routes the conflict directly to
	// *github.MainMergeConflict (the daemon then routes the failure
	// to the assembly_fixer chain — same Fix 3+4 shape the per-child
	// squash uses).
	//
	// Production wiring uses (*github.Client).MergeDefaultIntoPlanBranch
	// via runtime.PlanMainMergerFnFromClient; nil disables the periodic
	// merge entirely — the sweep emits a `plan_main_merge_skipped`
	// event per candidate and the plan branch may fall behind main
	// indefinitely (test daemons that don't run git).
	PlanMainMerger PlanMainMerger

	// PlanBareCloneRerereResetter clears the bare clone's `rr-cache` for
	// the given (repoSlug) by running `git rerere clear` against the
	// bare clone. Wired in production via
	// runtime.PlanBareCloneRerereResetterFromClient — a closure around
	// gh.Client.GitIn + gh.BareCloneDir. The stale-rerere recovery sweep
	// invokes it once per repo it walks (under the per-(repoSlug,
	// planBranch) plan-branch mutation mutex acquired by the sweep
	// itself, via gh.AcquirePlanBranchMutation). Best-effort + non-
	// fatal: the sweep logs on error and proceeds to the next repo. A
	// nil callback disables the actual rerere clear but the sweep still
	// runs (TOCTOU re-check + plan re-arm); useful for test daemons.
	PlanBareCloneRerereResetter func(ctx context.Context, repoSlug string) error

	// CapabilityGapDeployChecker reports whether potentialAncestor is an
	// ancestor of commit in the bare clone for repoSlug — i.e. whether the
	// running daemon build (commit) includes a merged commit (potentialAncestor),
	// computed via `git merge-base --is-ancestor`. The SOR-3084 deploy-gated
	// release sweep uses it as the deployed != merged predicate: a parked plan's
	// gap fix is DEPLOYED only when its squash SHA is an ancestor of the daemon's
	// OWN build commit. Wired in production via
	// runtime.CapabilityGapDeployCheckerFromClient (a closure around
	// gh.Client.GitInOutput + gh.BareCloneDir). Nil DISABLES the release sweep
	// (test daemons that don't run git, and daemons that simply opt out): the
	// sweep is a no-op and parked plans stay parked.
	CapabilityGapDeployChecker func(ctx context.Context, repoSlug, potentialAncestor, commit string) (bool, error)

	// PlanBranchSHAPusher recreates an externally-deleted plan branch on
	// origin by pushing the recorded plan-branch tip SHA from the daemon's
	// own bare clone (`git push origin <sha>:refs/heads/<planBranch>`).
	// Wired in production via runtime.PlanBranchSHAPusherFn — a closure
	// around (*github.Client).RecreatePlanBranchFromSHA. The daemon-side
	// recreatePlanBranchIfMissing self-heal owns the per-(repoSlug,
	// planBranch) mutex acquire and the withPushRetry wrapping; this
	// callback is the bare push and returns the typed push errors the
	// shared classifier routes on. A nil callback disables the self-heal
	// (recreatePlanBranchIfMissing returns "not needed"); useful for test
	// daemons that don't run git.
	PlanBranchSHAPusher func(ctx context.Context, repoSlug, sha, planBranch string) error

	// RererePreventiveClearCadence is the cadence at which the periodic
	// main-merge handler runs a preventive `git rerere clear` against the
	// daemon's bare clone (inside the per-(repoSlug, planBranch) mutex,
	// before the merge attempt) when the per-(project, repo)
	// last_rerere_clear_at is older than it. Reads
	// config.RererePreventiveClearCadence(); a non-positive value disables
	// the preventive clear (buildPreventiveRerereClearGate returns a nil
	// gate), the path a test daemon takes when it leaves this unwired.
	RererePreventiveClearCadence time.Duration

	// GitHubTokenForceRefresher forces a fresh GitHub App installation
	// token regardless of the cached expiry (SOR-1461). Wired in
	// production to (*github.TokenRefresher).Refresh. The CIPB plan-branch
	// push-auth recovery path calls it before re-dispatching a squash /
	// main-merge that failed with an HTTP 401/403, so the retry pushes
	// with a freshly-minted token rather than waiting for the Client's
	// leeway-based proactive refresh to notice the expiry. nil → the
	// auth-retry path skips the explicit refresh and relies on the
	// Client's own pre-call refresh (test daemons, or deployments without
	// a refresher wired).
	GitHubTokenForceRefresher func(ctx context.Context) error

	// PlanMainMergeSweepCadence is the CIPB Phase C main-merge sweep
	// poll interval. Under the event-triggered model (SOR-2187) the
	// main-merge no longer fires on this cadence — it fires from the
	// daemon's own merge-to-main completion fan-out (immediate) and from
	// the external origin/<default> tip-change probe. This value is the
	// poll interval for that tip-change PROBE, i.e. how often the daemon
	// checks for an external push to main; it is no longer a re-merge
	// interval, so an unchanged tip dispatches nothing. Reads
	// config.Daemon.PlanMainMergeSweepSec; defaults to 5 minutes
	// (applyDefaults), which remains appropriate for external-push
	// detection. Consumed by the poller wiring in cmd/sorcererd/start.go,
	// not by the daemon's sweep handler.
	PlanMainMergeSweepCadence time.Duration

	// PlanBranchInFlightDedupCap is the staleness cap for the three
	// persisted plan-branch in-flight dedup markers
	// (PlanEarlyDraftPROpenInFlightAt / PlanMainMergeInFlightAt /
	// CPBChildSquashInFlightAt). The boot-pass sweep cpb-in-flight-stale-clear
	// clears any non-zero marker older than this cap, and the
	// in-flight-dedup-bounded runtime invariant fires on any non-zero marker
	// older than it. Reads config.PlanBranch.InFlightDedupCapSeconds; a zero
	// value falls back to 2 × planMainMergeRepoTimeout at the read site
	// (planBranchInFlightDedupCap helper) — the default lives there, next to
	// the op-timeout constant, so it tracks it.
	PlanBranchInFlightDedupCap time.Duration

	// OrphanPRDiscoverer scans GitHub for open bot-authored PRs that no
	// in-flight Issue currently claims. Called from a periodic poller;
	// the daemon synthesizes Issue records (with OrphanAdopted=true)
	// for each result so the reviewer + merge gate can pick them up.
	// nil disables orphan-PR adoption.
	OrphanPRDiscoverer func(ctx context.Context, claimed map[string]bool) ([]OrphanPRRef, error)

	// OrphanBranchEnumerator lists every remote branch name on repoSlug
	// ("owner/repo"). The boot-time orphan-branch sweep (SOR-322) calls
	// it once per cfg.Repos repo. Production wiring sets this to
	// gh.Client.ListRemoteBranches; nil disables the sweep (test daemons
	// that don't exercise it).
	OrphanBranchEnumerator func(ctx context.Context, repoSlug string) ([]string, error)
	// OrphanBranchDeleter deletes branchName on repoSlug's remote.
	// Production wiring sets this to gh.Client.DeleteRemoteBranch (a 404
	// is success per that primitive's idempotent contract); nil disables
	// the boot-time orphan-branch sweep.
	OrphanBranchDeleter func(ctx context.Context, repoSlug, branchName string) error
	// DeleteOrphanBranches gates the boot-time orphan-branch sweep
	// (SOR-322). Reads config.CleanupDeleteOrphanBranches(); when false,
	// the sweep does not run at all (no enumeration, no deletion, no
	// events). The config knob defaults to true, so the production
	// wiring passes true unless the operator pinned
	// `cleanup.delete_orphan_branches: false`.
	DeleteOrphanBranches bool

	// WIPPreserver force-pushes the worktree's uncommitted state to
	// wip/<session-id> on GitHub before an issue's terminal-failed
	// transition runs cleanup. Returns the wip branch name on success.
	// nil disables WIP preservation; failed transitions just clean up
	// without saving the diff.
	WIPPreserver func(ctx context.Context, sessionID, repoSlug, worktreePath string) (wipBranch string, err error)

	// RemoteBranchDeleter best-effort deletes branchName on repoSlug's
	// remote. Invoked by the terminal-transition branch-cleanup helper
	// (cleanupTerminalBranches) to reap the WIP branch
	// preserveWIPIfConfigured force-pushed (on both merged and
	// abandoned) and — on abandoned only, when MergeOptions.DeleteBranch
	// is set — the implementer's feature branch. Production wiring uses
	// (*github.Client).DeleteRemoteBranch (idempotent: a 404 returns
	// nil). nil disables terminal-transition branch cleanup.
	RemoteBranchDeleter func(ctx context.Context, repoSlug, branchName string) error
	// LocalBranchDeleter best-effort deletes branchName from the bare
	// clone for repoSlug under projectRoot. SOR-1136: invoked by the
	// plan-branch cleanup helper (cleanupPlanBranchPlanArtifacts) when
	// a planning issue terminates, the per-child cleanup helper
	// (cleanupPlanBranchChildWorktrees) when a plan_branch child reaches
	// a terminal state, and the boot-time plan-branch orphan sweep
	// (sweepOnePlanBranch) when a stale plan or child working branch
	// survives a daemon restart. `git fetch --prune` only touches the
	// default branch's refspec, so a plan-branch ref would otherwise
	// linger in the bare clone. Production wiring uses
	// (*github.Client).DeleteBranch; nil disables local cleanup.
	LocalBranchDeleter func(projectRoot, repoSlug, branchName string, force bool) error
	// LocalBranchProbe reports whether branchName exists in the bare
	// clone for repoSlug under projectRoot. SOR-1136: invoked by the
	// boot-time plan-branch rediscovery sweep (rediscoverPlanBranchState)
	// to learn which plan / child working branches already exist on
	// restart — branch existence lives only in git refs, not the
	// issuestore, so the daemon has no in-memory record after a crash.
	// Read-only: it never creates a ref. Production wiring uses
	// (*github.Client).LocalBranchExists; nil disables the rediscovery
	// sweep (test daemons that don't wire the git surface).
	LocalBranchProbe func(projectRoot, repoSlug, branchName string) (bool, error)

	// PathExistsOnDefaultBranch reports whether path exists on the
	// configured default branch of repoSlug's bare clone under the
	// project root. The forward-referencing-paths predispatch lint
	// consults it once per (repo, path) pair extracted from a per_child
	// standalone issue's AC; a returned (false, nil) is the load-bearing
	// signal that the path is forward-referencing (only resident on a
	// sibling sweep branch of a multi-issue plan, not on the branch the
	// per_child implementer would carve). Production wiring resolves the
	// default branch through the centralized config-sourced chokepoint
	// (config.DefaultBranch) — never the set-once `refs/remotes/origin/HEAD`
	// symbolic ref — and shells out to
	// `git -C <bareclone> cat-file -e refs/heads/<default>:<path>`,
	// treating `git`'s "not a valid object name" exit-1 as (false, nil);
	// any other error (bare clone missing, exec failure) is surfaced so
	// the lint fails open rather than blocking on a flaky probe. nil
	// disables the lint entirely (test daemons that don't wire the git
	// surface stay deterministic).
	PathExistsOnDefaultBranch func(ctx context.Context, repoSlug, path string) (bool, error)

	// RawCloneSweepRunner (SOR-1162) re-runs the boot-time raw-clone-
	// pristine sweep against the project root. Called by the periodic
	// recovery sweep (`raw_clone_drift` kind) so mid-run pollution —
	// an agent's bash session that drifted into the project root and
	// ran a mutator, or a daemon code path that accidentally targeted
	// the project root — is caught at the next recovery tick instead
	// of waiting for daemon restart. Return values: (true, true) when
	// the sweep restored HEAD AND stashed a dirty tree; (true, false)
	// for HEAD-only restore; (false, true) for stash-only; (false,
	// false) for a no-op (already-pristine clone). Production wiring
	// composes runtime.RawCloneSweep with the same audit-sink the
	// boot path uses. nil disables the sweep — the heartbeat row still
	// fires, the per-kind details are empty.
	RawCloneSweepRunner func(ctx context.Context) (headRestored bool, workingTreeStashed bool, err error)

	// RawCloneDriftAttributeProbe (SOR-1162) runs a read-only drift
	// check against the project-root raw clone immediately after a
	// role session tears down. When drift is detected (HEAD off
	// default OR working tree dirty), the probe emits one
	// `raw_clone_drift_attributed` audit event keyed by (role,
	// sessionID) so the operator can attribute the pollution to the
	// agent that caused it. Restorative work is NOT part of this
	// probe — the next recovery-sweep tick (`raw_clone_drift` kind)
	// runs the actual restore via RawCloneSweepRunner. nil disables
	// the probe; the recovery sweep still catches the drift later
	// without per-session attribution.
	RawCloneDriftAttributeProbe func(role, sessionID string)

	// PlannerDispatcher runs one planner task and returns the parsed
	// result. Single-shot per docs/architecture.md.
	PlannerDispatcher PlannerDispatcher
	// PlanReviewerDispatcher runs one plan-review task between the
	// planner's success and the daemon's Linear writes. Reviews the
	// proposed issues for design-quality defects (drift surfaces,
	// scope creep, hypothetical-API deps). On approve, the supervisor
	// proceeds to write Linear; on reject, the planner's plan is
	// discarded and an escalation is filed.
	// nil disables the gate; the supervisor writes directly to Linear.
	PlanReviewerDispatcher PlanReviewerDispatcher
	// SpecDrafterDispatcher runs one spec_drafter task (TASK: draft /
	// amend) on the long-lived spec_drafter conversation and returns the
	// SHAPE-validated draft (spec-driven phase B). nil disables the
	// spec_drafter dispatch — a planning issue parked in spec_drafting is
	// then never picked up. When SpecsEnabled is true and this dispatcher +
	// SpecVerifier are both wired, the request-ingestion cutover
	// (handleRequestArrived) creates /sorcerer-request planning issues
	// directly in spec_drafting and sweepSpecDraftingDispatch drives the
	// initial draft dispatch on the next scheduler pass.
	SpecDrafterDispatcher SpecDrafterDispatcher
	// SpecsEnabled is the per-project spec-driven-workflow cutover switch
	// (config specs.enabled, default false). When true AND
	// SpecDrafterDispatcher + SpecVerifier are wired, a fresh
	// /sorcerer-request planning issue is minted directly in spec_drafting
	// (scoping the spec path to request-originated issues by construction);
	// daemon-internal mints (recognizer / triager / replan / followup) pass
	// plan_waiting explicitly and are never routed regardless of the flag.
	// False keeps every project on the legacy plan_waiting → plan_ready →
	// planning direct path, byte-for-byte unchanged.
	SpecsEnabled bool
	// SpecVerifier runs the SMT verification pipeline (Phase A's
	// internal/spec/verifier) over a parsed spec and returns the structured
	// findings. The seam is injected so the lifecycle wiring is testable
	// without a live Z3 subprocess; production wires verifier.Verify over a
	// shared smt.Driver. nil (alongside a nil SpecDrafterDispatcher)
	// disables the spec lifecycle.
	SpecVerifier SpecVerifier
	// SpecReviewerDispatcher runs one spec_reviewer coherence-judge task
	// (TASK: spec_review) over a SMT-clean spec parked at spec_review and
	// returns the typed coherence verdict. nil disables the coherence-check
	// dispatch — sweepSpecReviewDispatch then never picks up a spec_review
	// issue, leaving the operator `sorcerer spec approve` gate as the only path
	// out of spec_review (the legacy behavior test daemons keep). When wired,
	// applySpecReviewerResult drives the auto-approve / route-back lifecycle.
	SpecReviewerDispatcher SpecReviewerDispatcher
	// StewardDispatcher runs one steward task on the long-lived, resumable
	// steward conversation (SOR-2659). Optional: nil leaves the steward
	// dormant, mirroring the optional SpecDrafterDispatcher above — declared
	// by this daemon-integration-scaffolding child but populated in production
	// only by the go-live child (tests inject a stub). A nil dispatcher keeps
	// the steward inert even once a sibling registers a sub-handler / sweep,
	// because each production steward sweep self-gates on this field.
	StewardDispatcher StewardDispatcher
	// WedgeInvestigatorDispatcher dispatches the wedge_investigator role for a
	// NOVEL wedge (SPEC-SOR-2820-v3 R4), mirroring StewardDispatcher. Optional:
	// nil leaves the investigator dormant — the steward action executor self-gates
	// on nil, so a steward dispatch_wedge_investigator action is a no-op until a
	// dispatcher is wired (cmd/sorcererd/start.go constructs it next to
	// StewardDispatcher).
	WedgeInvestigatorDispatcher WedgeInvestigatorDispatcher
	// StewardEscalationThreshold is the distinct-issue count N per wedge
	// fingerprint within StewardEscalationWindowHours that warrants filing one
	// dogfood structural-root issue (SPEC-SOR-2822-v3 R4). Zero resolves to 3
	// inside applyEscalationPass (config.StewardEscalationThreshold's default);
	// cmd/sorcererd/start.go wires it from cfg.StewardEscalationThreshold().
	StewardEscalationThreshold int
	// StewardEscalationWindowHours is the look-back window (in hours) over which
	// the per-fingerprint distinct-issue escalation count is computed
	// (SPEC-SOR-2822-v3 R4). Zero resolves to 72 inside applyEscalationPass
	// (config.StewardEscalationWindowHours's default); wired from
	// cfg.StewardEscalationWindowHours().
	StewardEscalationWindowHours int
	// StewardRecoveryAttemptCap is the per-(issue, fingerprint) recovery-attempt
	// cap the Cap-3 re-apply suppression gate enforces (SPEC-SOR-2822-v3 R6): a
	// recovery entry whose attempt count has reached this cap is never re-applied.
	// Zero (or negative) resolves to 1 inside applyBlockedCohortRecoveries
	// (config.StewardRecoveryAttemptCap's default — strict R8: a recovery applies
	// once, after which the open entry suppresses further application);
	// cmd/sorcererd/start.go wires it from cfg.StewardRecoveryAttemptCap().
	StewardRecoveryAttemptCap int
	// RequireOperatorApproval, when true, leaves a coherence-clean spec parked
	// at spec_review for the operator `sorcerer spec approve` override. Default
	// false: a clean spec_reviewer verdict auto-transitions spec_review →
	// spec_approved (approved_by="auto"). Sourced from config specs
	// .require_operator_approval.
	RequireOperatorApproval bool
	// PlannerInputs supplies the repos + team-key context that the
	// supervisor injects into PlannerTask. Lifted onto Config because
	// the planner needs project-wide knowledge that lives in config.yaml,
	// not in any single Issue's state.
	PlannerInputs PlannerInputs
	// PRDiffSummarizer returns the per-file diff stat for one OPEN PR,
	// shaped for inclusion in a planner task's ExistingIssue.DiffSummary.
	// Called from dispatchPlanningIssue / dispatchPlanReviewer on the
	// supervisor's main goroutine (same goroutine that calls
	// prepareWorktrees) once per non-terminal issue carrying an open PR
	// in latestPRSnapshots. nil disables the digest — ExistingIssue
	// entries still carry PRURL but no DiffSummary lines.
	PRDiffSummarizer func(ctx context.Context, prURL string) ([]role.DiffStatLine, error)
	// ReviewerConcernPoster posts ONE GitHub PR review (event=COMMENT) at
	// prURL with the supplied body + inline comments — a refer-back's
	// concerns become a single operator-visible review on the PR where
	// the implementer reads them (SOR-1157). The daemon owns this write;
	// the reviewer LLM only emits the concerns, the daemon resolves the
	// slug→URL chain and groups + formats them in postReviewerConcerns
	// before invoking this hook. A non-nil error fires a
	// pr_review_write_failed audit event but never blocks the verdict's
	// state transition — the PR-side comment is best-effort. nil disables
	// the write (test daemons that don't wire a GitHub surface).
	// Production wiring uses (*github.Client).PostPRReview directly as a
	// bound method value.
	ReviewerConcernPoster func(ctx context.Context, prURL, body string, comments []gh.ReviewComment) error
	// PRDiffHunkFetcher returns the per-file new-side `+S,L` hunk ranges
	// for prURL — the set of (path, line) pairs that GitHub's review
	// API will accept as inline comments (SOR-1161). Called by
	// postReviewerConcerns before invoking ReviewerConcernPoster so a
	// concern whose (file, line) is off-diff folds into the review body
	// instead of triggering HTTP 422 on the entire review POST. A
	// non-nil error fires a pr_review_diff_fetch_failed audit event and
	// postReviewerConcerns falls back to the OLD behavior (every
	// (file, line) concern is posted inline; the 422 may still fire, but
	// the failure mode is no worse than today). nil disables the filter
	// (test daemons; the audit event does not fire when the hook is
	// absent). Production wiring uses (*github.Client).FetchPRDiffHunks.
	PRDiffHunkFetcher func(ctx context.Context, prURL string) (map[string][]gh.DiffHunk, error)
	// DedupeDispatcher gates POST /v1/issues operator-create requests
	// against in-flight issues + open PRs. When nil, the dedupe gate is
	// skipped — useful for test daemons that don't wire a clauderunner
	// and don't exercise the gate. Production wiring sets this to
	// role.NewDedupeDispatcher(clauderunner). The dispatcher's verdict
	// is advisory when CreateInput.ForceDedupe is true; the audit event
	// (dedupe_check_ran) fires either way.
	DedupeDispatcher DedupeDispatcher
	// MaxPlannerRevisions is retained for migration safety but unused.
	// Per docs/architecture.md, the planner is single-shot: validation
	// failure escalates rather than retries.
	MaxPlannerRevisions int

	// SubscriptionSnapshotter returns a snapshot of the OAuth-pool
	// (clauderunner picker) state. Used by the status endpoint to surface
	// per-token health (last-used, throttled-until, throttle count, auth-
	// dead reason). nil disables; the status endpoint reports an empty
	// list. Wired by start.go to cRunner.PickerSnapshot.
	SubscriptionSnapshotter func() []SubscriptionSnapshot

	// PoolThrottleState reports whether every OAuth token in the
	// clauderunner pool is currently throttled, plus the soonest reset.
	// RunSchedulerPass consults it before every role-claude-subprocess
	// spawn (SOR-1159): when the whole pool is throttled, the spawn is
	// doomed — the picker returns PoolExhaustedError before exec, the
	// session closes with an error, and three such failures quarantine
	// the role's conversation. The scheduler suspends dispatch and emits
	// one dispatcher_throttle_paused audit event per cooldown window
	// rather than spawning a subprocess that fails and storms the
	// operator inbox with quarantine escalations. nil disables the gate
	// (test daemons without a clauderunner). Wired by start.go to
	// agentcli.Runner.ThrottleState.
	//
	// Deprecated: SOR-1296 superseded this surface with PoolDispatchState,
	// which gates both the throttle case AND the auth-dead-pool case.
	// RunSchedulerPass prefers PoolDispatchState when set; PoolThrottleState
	// is consulted only when PoolDispatchState is nil. Test daemons that
	// want to exercise just the throttle leg may still set this field;
	// production wiring goes through PoolDispatchState.
	PoolThrottleState func() (allThrottled bool, nextReset time.Time)

	// PoolDispatchState is the SOR-1296 successor to PoolThrottleState.
	// It reports the pool's spawn-readiness as two mutually-exclusive
	// pause signals plus the soonest throttle reset:
	//   - throttleHeld: every selectable token is throttled (SOR-1159).
	//     nextReset is the soonest reset; emit dispatcher_throttle_paused.
	//   - authDeadHeld: every token is auth-dead — zero throttled, zero
	//     available. The remediation is operator action (clear the auth
	//     flag on the subscription); the wall-clock cooldown will never
	//     fire. Emit dispatcher_auth_dead_paused.
	// Either pause condition suspends ALL dispatch (ready-leaf loop AND
	// dispatchFollowOns) so no doomed role-claude-subprocess spawn is
	// issued. Both pause cases dedup against Project.LastThrottlePauseEventAt
	// / LastAuthDeadPauseEventAt so a single multi-hour episode cannot
	// re-emit. nil disables the gate (test daemons without a clauderunner).
	// Wired by start.go to agentcli.Runner.PoolDispatchState.
	PoolDispatchState func() (throttleHeld, authDeadHeld bool, nextReset time.Time)

	// WatchdogSnapshotter returns the live claude subprocesses the
	// stuck-bash watchdog should walk on each tick (SOR-37). Wired by
	// start.go to agentcli.Runner.LiveSubprocesses. nil leaves the
	// watchdog goroutine disabled regardless of WatchdogEnabled — a
	// missing snapshotter at construction time is a misconfiguration
	// bug, not a fallback case.
	WatchdogSnapshotter func() []watchdog.Subprocess

	// LiveSessionMetricsFn returns live per-session metering snapshots for the
	// per-issue progress assembly in StatusSnapshot and ProgressByIssue
	// (SOR-2859). Wired by start.go to a closure over
	// agentcli.Runner.LiveSubprocesses() — the same neutral-DTO bridge
	// pattern as WatchdogSnapshotter, so the daemon package takes no
	// clauderunner import. nil disables live metering: a test daemon that
	// constructs no clauderunner serves progress without it, and StatusSnapshot
	// omits the issue_progress block entirely.
	LiveSessionMetricsFn func() []LiveSessionMetrics

	// WatchdogEnabled controls whether the stuck-bash watchdog
	// goroutine starts. Defaults to false (the daemon will not start
	// the goroutine); start.go passes config.WatchdogEnabled() through.
	WatchdogEnabled bool
	// WatchdogInterval is the watchdog's tick cadence. Must be > 0
	// when WatchdogEnabled is true.
	WatchdogInterval time.Duration
	// WatchdogMinStuck is the wall-clock-elapsed window below which
	// the detector never trips. Must be > 0 when WatchdogEnabled is
	// true.
	WatchdogMinStuck time.Duration

	// SessionReaper SIGTERMs (graceful=true) or SIGKILLs
	// (graceful=false) the subprocess tree of the session whose
	// tracked id == sessionID, via the SOR-195 PPID-descendant reaper.
	// Returns true when a live subprocess matched. Wired by start.go to
	// agentcli.Runner.ReapSession so the daemon package stays free
	// of clauderunner-internal coupling (same closure pattern as the
	// watchdog snapshotters). nil → the session-abort / age-reaper
	// paths skip the kill (test-daemon path; the SM transition still
	// runs so scheduler accounting converges).
	SessionReaper func(sessionID string, graceful bool, reason string) bool

	// GitHubTokenStatus returns the current installation token's expiry
	// and owner. Used by the status endpoint. nil disables.
	GitHubTokenStatus func() (owner string, expiresAt time.Time)

	// GitHubBotLogin returns the canonical bot login (e.g.
	// `sorcerer-b3k[bot]`) resolved at boot via the SOR-220
	// `github.bot_login` → JWT-signed /app chain. Surfaced under
	// the `github:` block in /v1/status. nil omits the field
	// (legacy tests without the wire).
	GitHubBotLogin func() string

	// ConversationRecycler, if set, is asked to close (drop and
	// reconstruct) a role's conversation state when its session-
	// failure streak hits QuarantineThreshold. Production wiring (v1
	// shape via clauderunner) currently uses no recycler — sessions
	// are short-lived per-call so there's nothing to recycle.
	ConversationRecycler ConversationRecycler

	// Issuestore is the local SQLite mirror handle. When non-nil, the
	// daemon mirrors every in-process *sm.Issue mutation into the store
	// (state transitions, depends_on / pr_urls / materialized_children
	// updates, freshly-minted Planning Issues) inside the same
	// applyTransition / event-handler scope. Linear remains the source of
	// truth for reads in this PLAN; this is observation-only. When nil,
	// the daemon runs as before — back-compat for tests that don't wire
	// a store.
	//
	// Typed as the issuestore.IssueStore interface (not the concrete
	// *issuestore.Store) so the fault-injection harness in phase 4b can
	// substitute a wrapper. Production wiring (the real daemon boot path)
	// still passes the real *issuestore.Store — it satisfies the interface
	// by construction.
	Issuestore issuestore.IssueStore

	// SweepCooldown is the minimum wall-clock window between successive
	// reviewer dispatches for the SAME `blocked_user` issue whose PR
	// HEADs haven't moved. Reads config.Recovery.SweepCooldownSec.
	// Zero disables the cooldown entirely (legacy behavior); negative
	// values are rejected at config-load time. Defaults to 30 minutes
	// in production.
	SweepCooldown time.Duration

	// VerifierChainStaleMaxAge is the max-age past which a still-in-flight
	// post-submit verifier chain is classified stale by verifierChainStale.
	// Reads config.Recovery.VerifierChainStaleMaxAgeSec via the config
	// resolver (cfg.VerifierChainStaleMaxAge()), so it is always a positive,
	// config-sourced value (30m default) in production — never hard-coded at
	// the classifier. A zero value (e.g. an un-wired test daemon) is not used
	// by any production consumer in this build; tests that exercise
	// verifierChainStale set it explicitly.
	VerifierChainStaleMaxAge time.Duration

	// CommitVerifier verifies that a commit SHA is reachable on the
	// origin/main branch of one of the project's configured repos.
	// Used by the triager Executor before applying any
	// evidence_commit_sha-bearing action (unblock_via_dep_drop,
	// force_converge_to_terminal). The wrapper helper iterates over
	// d.cfg.PlannerInputs.Repos in input order; the first repo that
	// returns found=true wins. Each per-repo call is scoped to a 10s
	// context timeout. Production wiring shells out to
	// `gh api repos/<repo>/commits/<sha>`; tests inject a fake.
	// nil leaves SHA-citing executors in a permanent-reject state
	// (they return ErrSHANotFound / equivalent), so a misconfigured
	// daemon fails closed rather than silently treating every SHA as
	// verified.
	CommitVerifier CommitVerifier

	// PRResolver resolves a PR URL into its repo/state/branch/title/body
	// for the SOR-220 `sorcerer issue adopt-pr` workflow. Production
	// wires this to a closure over gh.Client.ViewPR; tests pass a fake.
	// nil leaves AdoptPR mutations in a permanent-reject state — the
	// daemon refuses the operator call rather than guessing the PR
	// shape.
	PRResolver PRResolver

	// MaxTriagerActionsPerTick caps total throughput of the triager
	// router per tick. The first N actions route per their normal
	// confidence rule; subsequent actions all land as inbox proposals
	// (the operator-approval path) regardless of declared confidence.
	// Defaults to 5 in New when zero; reads config.Triager.MaxActionsPerTick
	// in production wiring.
	MaxTriagerActionsPerTick int

	// ReplanMaxAttempts is the SOR-144 replan circuit-breaker's per-
	// issue attempt cap. When the discovered-prereq replan path would
	// dispatch the (ReplanMaxAttempts + 1)-th attempt for an issue
	// within ReplanWindow without forward progress, the supervisor
	// halts the issue at `blocked_user` / `plan_blocked` with a
	// `replan_loop_halted` event + escalation row instead of firing
	// another replan. Defaults to 3 in New when zero; reads
	// config.Replan.MaxAttempts in production wiring.
	ReplanMaxAttempts int
	// ReplanWindow is the wall-clock window over which the circuit-
	// breaker accumulates attempts before a reset. Defaults to 30
	// minutes in New when zero; reads config.ReplanWindow() in
	// production wiring.
	ReplanWindow time.Duration

	// NarrationRetryBudget is the SOR-227 per-issue retry cap for
	// narration-class session failures (failure_class ∈
	// {narration_only, deadline_expired_first_activity}). The
	// supervisor's Layer-2 branch increments
	// `iss.NarrationFailureCount` on every such failure and re-dispatches
	// the cycle with a retry preamble; on the Nth consecutive failure
	// (where N == NarrationRetryBudget) the issue escalates to
	// blocked_user / plan_blocked with reason
	// `narration_failure_budget_exhausted (count=N)`. Defaults to 3 in
	// New when zero. A single global default is enough for the observed
	// pattern; per-role budgets are out of scope (per the issue body's
	// "out of scope" list).
	NarrationRetryBudget int

	// ThrottleRetryCap is the SOR-1316 per-issue cap on consecutive
	// session_transient_retry events classified as OAuth-pool-exhausted
	// (PoolExhaustedError or the "every OAuth token is throttled"
	// stringified equivalent). When the supervisor's circuit-breaker
	// branch observes the Nth consecutive throttle retry on a single
	// issue (where N == ThrottleRetryCap), the dispatcher stops re-
	// spawning that session and routes the issue to blocked_user with
	// reason `oauth_pool_exhausted_retry_cap_reached`. Defaults to
	// throttleRetryCapDefault (20) in New when zero — matches the
	// SOR-1080 / SOR-1081 production wedges that burned ~6,000
	// dispatches per hour against a single throttled issue before
	// SOR-1316 capped them. Composes with SOR-1241 (the quarantine
	// streak still excludes transient throttle failures) and with
	// SOR-1281 (the structured rate_limit_event classifier is the
	// preferred shape signal; the stringified pool-exhausted text is
	// the defense-in-depth fallback).
	ThrottleRetryCap int

	// SameStateCycleThreshold is the per-issue cap on consecutive
	// returns to a cycle-prone state (waiting / ready / feedback)
	// with the SAME normalized blocking reason before the
	// deterministic same-state-cycle detector force-routes the issue
	// to blocked_user. The detector lives inside applyIssueTransition
	// (the single supervisor entry for in-band issue SM transitions);
	// it increments the per-issue SameStateCycleCount on every return
	// to the recorded SameStateCycleState with a matching normalized
	// reason, and fires when the post-increment count crosses this
	// threshold. The motivating wedge: SOR-1202 on archers cycled
	// `ready → waiting` 157 times over ~78 min before the
	// recognizer's hourly reflective tick noticed (22,294 lint
	// findings emitted). A deterministic per-transition detector is
	// instant, free, and operator-surfacing — orthogonal to the
	// LLM-driven recognizer's "why is it wedging" classification
	// path. Defaults to sameStateCycleThresholdDefault (3) in New
	// when zero. Lowering to 1 turns this into "fail fast on the
	// first re-cycle"; raising tolerates more cycles before blocking.
	SameStateCycleThreshold int

	// AmenderExhaustionThreshold is the SOR-1447 per-issue cap on
	// consecutive scoped_amender `no_amendments` cycles on the same
	// plan-defect signature before the supervisor force-routes the
	// issue from `implementing` to `blocked_user` (with reason prefix
	// `amender_exhausted_on_falsified_premise`) instead of the
	// existing IssueStateWaiting rollback. The counter +
	// last-signature live on the issue row
	// (ConsecutiveNoAmendments + LastPlanDefectSignature, schema
	// migration `issues_amender_exhaustion`); the supervisor's
	// applyScopedACAmendResult.no_amendments branch is the sole
	// increment site. Defaults to amenderExhaustionThresholdDefault
	// (2) in New when zero — the strongest signal we have for an
	// un-fixable defect, since the scoped_amender explicitly returned
	// NoAmendments after reading the body + the implementer's
	// plan_defect report. Routing at N=2 saves one full implementer
	// dispatch (~10-20 min of token spend) versus N=3 and routes the
	// wider-context triager onto the autonomous closure paths.
	AmenderExhaustionThreshold int

	// OversizedDispatchEscalateCeiling is the per-project
	// evidence-derived dispatch-escalate ceiling in predicted cache
	// tokens. A predicted est_cache_tokens value at or above this
	// ceiling triggers the oversized sanity backstop rather than an
	// unconditional dispatch hold. Consumed by the dispatch and
	// proposal gate in the dependent recalibration issue. Production
	// wires cfg.OversizedDispatchEscalateCeiling(); the field is NOT
	// patched in New — the config-layer default is always applied
	// before cmdStart passes the value in.
	OversizedDispatchEscalateCeiling int64

	// HandlerSlowWarnThreshold and HandlerSlowErrorThreshold are the
	// SOR-1347 main-loop slow-handler audit thresholds. The dispatcher
	// (handle()) records every handler's duration and emits an
	// `operator_mainloop_slow_handler` audit event at severity=warn /
	// severity=error when the duration crosses the warn / error tier.
	// Defaults applied in New when zero (6s warn, 10s error); the
	// production wiring routes config.Daemon.SlowHandler values through
	// the corresponding cfg accessors. See ack_timeout.go's threshold
	// comment for the operational rationale.
	HandlerSlowWarnThreshold  time.Duration
	HandlerSlowErrorThreshold time.Duration

	// HandlerKindBudgets is the SOR-2447 per-handler-kind main-loop
	// occupancy-budget table, keyed on the strings handlerKindAndSubject
	// produces. An absent (or non-positive) key falls back to
	// HandlerSlowWarnThreshold, so every dispatched handler kind resolves
	// to a budget (R6). Production wires cfg.SlowHandlerBudgets(); a nil
	// map is fine (every kind uses the warn-threshold default).
	HandlerKindBudgets map[string]time.Duration
	// HandlerSustainedOverrunCount is the number of over-budget firings for
	// the same handler kind within HandlerSustainedOverrunWindow that trips
	// an operator_mainloop_sustained_overrun detection event (R7). Defaults
	// to 3 in New when non-positive.
	HandlerSustainedOverrunCount int
	// HandlerSustainedOverrunWindow is the wall-clock window for the
	// sustained-overrun counter. Defaults to 60s in New when non-positive.
	HandlerSustainedOverrunWindow time.Duration

	// WedgeDetectorEnabled gates the SOR-1356 same-state-cycle detector.
	// When false, the detector is a no-op on every scheduler-pass tick;
	// no audit events, no transitions. Defaults to true in New when the
	// caller leaves the field unset (the zero value is false, so the
	// daemon defaults to enabled only when the test/production wire
	// passes true). Production wires the cfg.WedgeDetectorEnabled()
	// accessor; tests typically leave it false to skip the detector.
	WedgeDetectorEnabled bool
	// WedgeDetectorWindow is the sliding-window length the detector
	// applies when counting state-pair re-entries. Defaults to 30
	// minutes in New when zero.
	WedgeDetectorWindow time.Duration
	// WedgeDetectorCycleThreshold is the per-(issue, state-pair) cycle
	// count that trips the detector. Defaults to 10 in New when zero.
	WedgeDetectorCycleThreshold int
	// WedgeDetectorLowSignalEventKinds is the noise filter the detector
	// applies when extracting the dominant per-issue audit-event
	// signature from the events table (AC2). The set is shared with
	// the recognizer's trend tables so the two surfaces have a single
	// noise definition; production wires cfg.Recognizer.LowSignalEventKinds.
	WedgeDetectorLowSignalEventKinds []string

	// InvariantsCheckEnabled gates the periodic invariants_check recovery
	// sweep kind. When false, the runInvariantsCheck handler short-circuits
	// before any snapshot is built — no events, no work. Defaults to true
	// in New when the caller leaves it unset (the cfg.InvariantsCheck.Enabled
	// nil sentinel maps to true via config.InvariantsCheckEnabled()).
	InvariantsCheckEnabled bool
	// InvariantsCheckTickInterval is the per-N-ticks safety-net cadence
	// the invariants_check handler honors. The recover-sweep ticker fires
	// the handler every tick, but the handler only does the actual check
	// work every Nth call. Defaults to 5 in New when zero (the cadence
	// proposed in docs/structural-coverage/phase-1-invariant-manifest.md
	// § 4.7).
	InvariantsCheckTickInterval int

	// DaemonName is this daemon's registered name (the same value
	// start.go announces to sorcerer-ui). Used as Topology.Self so
	// callers can compare an OwnerOf result against this daemon
	// (SOR-1191). Empty leaves the topology cache's Self field empty.
	DaemonName string
	// UIEndpoint is the sorcerer-ui base URL the topology cache polls
	// (GET <UIEndpoint>/api/daemons) every 60s (SOR-1191). Empty
	// disables the topology cache entirely — no goroutine, no cache.
	UIEndpoint string
	// APIToken is this daemon's HTTP control-plane bearer (the same
	// value passed as httpapi.Config.Token). The cross-daemon forwarder
	// sends it as the Authorization bearer on forwarded POST /v1/issues
	// requests so the receiving peer's dual-auth path (SOR-1214) can
	// hash-match it against the topology. Empty leaves the forwarder
	// unauthenticated — fine for a daemon with no peers, but a forward
	// to an auth-enforcing peer would 401.
	APIToken string
}

type ConversationRecycler interface {
	CloseConversation(role string)
}

type CrashRecoveryPRDiscoveryResultEvent struct {
	IssueKey        string
	Branch          string
	Snaps           map[string]DiscoveredPR
	DiscoveryFailed bool
	Transient       bool
	SessionErrMsg   string
	At              time.Time
}

type CreateMutationResult struct {
	Key string
	Err error
}

type CrossDaemonClient struct {
	// contains filtered or unexported fields
}

type Daemon struct {
	// contains filtered or unexported fields
}

type DaemonInfo struct {
	Name          string
	URL           string
	OwnedRepos    []string
	AuthTokenHash string
}

type Debouncer struct {
	// contains filtered or unexported fields
}

type DedupeDispatcher func(context.Context, role.DedupeTask) (role.DedupeVerdict, error)

type DedupeSnapshotIssue struct {
	Key         string
	Kind        string
	State       string
	Title       string
	Description string
	CreatedAt   int64
	// Repos is the row's affected-repo list (iss.Repos), deep-copied at
	// snapshot time. Used only in-process by buildDedupePayload's
	// relevance ranking (repo-overlap signal) — it is NOT serialized
	// into the LLM payload (the wire struct carries kind/key/title/
	// state/description only).
	Repos []string
}

type DedupeSnapshotPR struct {
	IssueKey string
	Repo     string
	URL      string
	State    string
}

type DedupeSnapshotResult struct {
	Issues []DedupeSnapshotIssue
	PRs    []DedupeSnapshotPR
	Err    error
}

type DiffStatTotals struct {
	FilesModified int
	LinesAdded    int
	LinesRemoved  int
}

type DiscoveredPR struct {
	URL     string
	HeadSHA string
}

type DiscoveryRoleConfig struct {
	// Model is the per-project full model id for this discovery phase (e.g.
	// claude-opus-4-8); "" → the daemon omits --model for the dispatch.
	// Threaded verbatim from the discovery role's triple (config.Roles.TripleFor).
	Model string
	// Effort is the per-project effort override (low|medium|high|xhigh);
	// "" → the daemon omits --effort. Threaded verbatim from the discovery
	// role's triple (config.Roles.TripleFor).
	Effort string
	// DeviationThresholdPct is the resolved files-edited-not-cited percentage
	// at/above which the role's *_phase_discovery_deviation event fires.
	// Already defaulted to 30 by config.Roles.DeviationThresholdPctFor at
	// boot; an explicit 0 is honored.
	DeviationThresholdPct int
}

type DispatchOutcome string

type DispatchSituation string

type DuplicateEntry = httpapi.DuplicateEntry

type DuplicateError = httpapi.DuplicateError

type ErrRefactorPlanAborted struct {
	// contains filtered or unexported fields
}

type Event struct {
	Kind EventKind
	At   time.Time

	// EventSessionResult / EventSessionTimeout / EventSessionCrashed
	SessionID    string
	SessionError error // nil on success

	// SessionCrashMessage is the watchdog's last-known forensic line
	// for an EventSessionCrashed event (e.g. role + pgid). Empty for
	// other event kinds.
	SessionCrashMessage string

	// EventSessionLifecycle payload. SessionPhase is "starting" or
	// "running"; SessionStateDir is the runner's per-session state dir
	// (so the heartbeat watchdog can locate <dir>/heartbeat). Empty for
	// other event kinds.
	SessionPhase    string
	SessionStateDir string

	// EventSessionSpawnFailed payload. nil for other event kinds.
	SpawnFailure *SpawnFailureEvent

	// EventSessionInitFailed payload. nil for other event kinds.
	SessionInitFailure *SessionInitFailureEvent

	// EventRequestArrived
	RequestPath string

	// EventOperatorCommand
	Command      string
	CommandReply chan<- error // optional: caller blocks until handler ack

	// EventGitHubPRsPolled payload: freshly-fetched PR state per issue
	// and repo. The handler calls ApplyGitHubPoll with this slice.
	PRSnapshots []PRSnapshot

	// PRDiffSummaries carries pre-computed per-PR-URL diff-summary strings,
	// keyed by PR URL. Populated by the github-prs poller goroutine
	// alongside PRSnapshots (one gh diff-stat call per OPEN PR, off the
	// main goroutine); written to d.prDiffSummaryCache by the
	// EventGitHubPRsPolled handler on the main goroutine. Nil on
	// synthetic/test events — the handler treats a nil map as empty
	// (no cache writes for absent entries; eviction on MERGED/CLOSED still
	// runs off the PRSnapshots slice).
	PRDiffSummaries map[string]string

	// EventSessionResult typed payloads. Exactly one is populated per
	// event (matching the Session's Role); they coexist on Event because
	// the alternative (per-role event kinds) would explode the dispatch
	// table without buying clearer code.
	ImplementerResult   *role.ImplementerResult
	ReviewerVerdict     *role.ReviewerVerdict
	MergeResults        []gh.MergeSetResult
	PlanReviewerVerdict *role.PlanReviewerVerdict

	// LandingGateTail / LandingGateClass carry the captured fresh-landing-gate
	// failure tail and its flake-vs-real classification from the off-main
	// dispatchPlanPRMergeSet closure to the on-main applyPlanPRMergeResults
	// handler (SPEC-SOR-3238-v1 R12/R13/R16/R17). Set ONLY on the merge-result
	// Event a failed landing gate submits (via NewMergeResultEventWithTail);
	// LandingGateTail is nil and LandingGateClass is "" on every success path and
	// on a non-*PlanLandingGateFailure plumbing error (no tail to capture). The
	// handler reads them to enrich the plan_pr_merge_failed message with the
	// failing-test identity instead of the generic "no merge results returned"
	// string, and to emit the landing_gate_flake_detected audit event when the
	// class is flake.
	LandingGateTail  *LandingGateTail
	LandingGateClass GateFailureClass

	// ImplementerCycleDiffStat carries the best-effort git-diff numstat
	// totals (files changed / lines added / lines removed) for an
	// implementer cycle, computed off-main in the dispatch goroutine from
	// the cycle's worktree branch. Set on EventSessionResult for
	// implementer sessions whose stat computation succeeded; nil (→ zero
	// totals in the implementer_cycle_summary event) on the no-stater /
	// no-branch / git-error path and on the panic / boot-recovery paths.
	ImplementerCycleDiffStat *DiffStatTotals

	// ImplementerEditedFiles carries the off-main `git diff --name-only`
	// union of repo-relative paths the implementer cycle actually edited,
	// computed in the dispatch goroutine (submitImplementerResult) alongside
	// ImplementerCycleDiffStat. Feeds the implementer_phase_discovery_deviation
	// metric's "actually edited" set, compared against the discovery
	// artifact's "## Files to touch" prediction. nil on the no-stater /
	// git-error / panic / boot-recovery paths (→ the deviation metric sees
	// zero edited files; it still won't fire unless a discovery section was
	// cited, so an empty list is benign).
	ImplementerEditedFiles []string

	// PlanPRFixTipSHAs carries the post-fix origin plan-branch tip SHA per
	// repo, probed OFF the main goroutine in the dispatchPlanPRFix session
	// goroutine after the autonomous plan-PR-fix implementer returns success
	// (the fix force-with-lease-pushes the plan branch, advancing the origin
	// tip; role.ImplementerResult carries no SHA, so the daemon probes
	// origin). applyPlanPRFixResult records it into planIss.PlanCommitSHAs
	// via recordPlanBranchTip so the recorded SHA tracks the live tip by
	// construction (plan-branch-tip-consistency). Set only on a successful
	// continuous_plan_branch plan-PR-fix result whose probe succeeded; nil on
	// every other EventSessionResult (the standard implementer path, legacy
	// plan_branch fixes, the no-resolver / probe-error / panic / boot-recovery
	// paths). recordPlanBranchTip no-ops on an empty SHA, so a nil/partial map
	// never clobbers a previously-good recorded tip.
	PlanPRFixTipSHAs map[string]string

	// PlanPRResults carries the per-repo plan-PR-open outcomes for a
	// "plan_pr_open" session (SOR-1139). Set on EventSessionResult when
	// the session role is "plan_pr_open"; applyPlanPROpenResults reads
	// it to record iss.PRURLs and transition the planning issue to
	// plan_awaiting_pr_merge.
	PlanPRResults []PlanPROpenResult

	// PlannerResult is the planner's typed result (proposal id + any
	// in-process echoes of the envelope). Set on EventSessionResult
	// when the session role is "planner". Under the v2 proposals
	// lifecycle, the production path populates only ProposalID — the
	// envelope's children live in the issuestore and are read back
	// when the supervisor needs to project them.
	PlannerResult *role.PlannerResult
	// PlannerValidationErrors carries validator errors that survived
	// all revision attempts. nil on success.
	PlannerValidationErrors []string
	// PlannerNewIssueKeys carries the Linear keys created from the
	// planner's output, in input order. Populated when the writer ran
	// successfully (in part or in full).
	PlannerNewIssueKeys []string
	// PlannerOriginIssue is set when the planner ran on a replan
	// trigger (TriggerDiscoveredPrereq). It identifies the issue that
	// raised the discovered-prereq escalation; applyPlannerResult uses
	// it to attach the new prereqs to the origin issue's DependsOn.
	PlannerOriginIssue string

	// SpecDrafterResult is the spec_drafter's SHAPE-validated draft (the
	// extracted spec YAML + parsed *dsl.Spec). Set on EventSessionResult
	// when the session role is "spec_drafter"; applySpecDrafterResult runs
	// the verification pipeline over it and drives the spec lifecycle.
	SpecDrafterResult *role.SpecDrafterResult
	// SpecDrafterTaskKind is the dispatched task flavor ("draft" / "amend")
	// the spec_drafter ran. applySpecDrafterResult reads it to emit
	// spec_drafted vs spec_amended and to chain previous_version_id.
	SpecDrafterTaskKind string

	// SpecReviewerVerdict is the spec_reviewer's validated coherence verdict.
	// Set on EventSessionResult when the session role is "spec_reviewer";
	// applySpecReviewerResult reads it to auto-approve a coherent spec or route
	// a drift verdict back through the bounded revise loop.
	SpecReviewerVerdict *role.SpecReviewerVerdict

	// EventOrphanPRsDiscovered payload.
	OrphanPRs []OrphanPRRef

	// IssueKey is the subject issue key for events that carry one
	// (currently EventOperatorIssueMutation; previously also Linear-push
	// grace / mirror-check, both removed). Most events use Mutation.IssueKey
	// instead; this top-level field is retained for callers that route
	// only an issue key without a full Mutation payload.
	IssueKey string

	// EventOperatorIssueMutation payload: the typed mutation +
	// reply chan. The dispatcher reads Mutation.Kind to route to
	// the right per-mutation handler.
	Mutation *Mutation

	// EventSteward payload (SOR-2659). StewardSubKind selects which
	// init()-registered steward sub-handler handleStewardEvent invokes.
	// Empty for every other event kind.
	StewardSubKind string

	// EventRecoverySweep payload. The handler dispatches the requested
	// recovery sweeps on the main goroutine and sends the response
	// envelope back through Recover.Reply.
	Recover *RecoverEvent

	// EventForceConvergeForTest payload. See ApplyForceConvergeForTest
	// for the full rationale; the handler runs (*sm.Issue).ForceConverge
	// on the main goroutine and signals the caller via Done.
	ForceConvergeForTest *ForceConvergeForTestPayload

	// EventTriagerActionApply payload. See ApplyTriagerAction in
	// triager_executors.go for the call shape. The handler dispatches
	// on TriagerAction.Kind to one of the per-action SM mutations
	// (drop dep, force-converge to terminal, archive session, requeue
	// issue, mark blocked, cascade orphan proposal) on the main
	// goroutine and signals the caller via Reply with the outcome.
	TriagerActionPayload *TriagerActionApplyPayload

	// PlanKey identifies the planning issue a plan-branch event targets.
	// Shared by the CIPB event family (plan-branch create, child squash,
	// main-merge, plan-PR, stale-rerere sweep, assembly_fixer).
	PlanKey string

	// GateReadSet is the EventGateReadSetObserved payload (SPEC-SOR-2773 tier
	// 1): the worktree-relative file-read set a plan-branch gate observed for
	// the plan named by PlanKey. applyGateReadSetObserved writes it into
	// d.state.PlanInputsReadSets[PlanKey]. Nil for other event kinds.
	GateReadSet []string

	// EventPlanPRPendingCIObserved payload (SOR-1360). PendingCIObservation
	// carries the typed classification + per-PR diagnostic string the
	// pending-CI poller derived for the plan; applyPlanPRPendingCIObserved
	// routes per the classification. Nil for other event kinds.
	PendingCIObservation *PlanPRPendingCIObservation

	// EventActivationPollObserved payload (SOR-2503). ActivationPollObservation
	// carries the activation driver's aggregate poll verdict for one plan;
	// applyActivationPollObserved routes per AllSatisfied / FailedRIDs. Nil for
	// other event kinds.
	ActivationPollObservation *ActivationPollObservation

	// EventAssemblyFixerResult payload (SOR-1443 Fix 4). AssemblyFixer
	// carries the typed result + any liberal-parser coercions the
	// dispatcher emitted; AssemblyFixerErr carries any transport /
	// conversation / validator-exhausted error. Nil for other event
	// kinds.
	//
	// AssemblyFixerRawPayload (SOR-1476) carries the raw JSON the agent
	// submitted on the validator-reject path. Populated only when the
	// dispatcher's err is a *role.AssemblyFixerParseError (i.e. the role
	// returned a payload but ParseAssemblyFixerResult rejected it). Empty
	// on success AND on transport errors that produced no payload to
	// inspect. applyAssemblyFixerResult emits the secondary
	// assembly_fixer_payload_rejected audit event only when this field is
	// non-empty.
	AssemblyFixer           *AssemblyFixerEventPayload
	AssemblyFixerErr        error
	AssemblyFixerRawPayload json.RawMessage

	// AssemblyFixerSessID is the id of the tracked assembly_fixer session
	// dispatchAssemblyFixer opened + attached for this cycle (empty for
	// legacy / test events that synthesize the result without a session).
	// applyAssemblyFixerResult routes it through terminateSession for every
	// outcome so the plan's iss.SessionID is cleared the moment the result
	// is applied — closing the plan_auto_fixing re-dispatch storm by
	// construction (the pass.go follow-on guard keys off iss.SessionID).
	AssemblyFixerSessID string

	// AssemblyFixerTriggeringChildKey is the key of the parked child P
	// whose per-child squash failure dispatched this assembly_fixer cycle.
	// Populated only on the CPB-squash dispatch path
	// (dispatchCPBSquashFailureToAssemblyFixer); empty on the main-merge
	// (dispatchPlanMainMergeFailureToAssemblyFixer) and follow-on
	// re-dispatch (pass.go) paths, which carry no triggering child. The
	// apply site (applyAssemblyFixerAction) uses it to strip a
	// file_implementation_issue corrective child's self-dependency on P —
	// any proposed depends_on edge that reaches P directly or transitively
	// — before the child persists, closing the SOR-2321 ↔ SOR-2338
	// cross-graph deadlock by construction. Empty here makes the strip a
	// no-op, so a legitimate dependency on the main-merge path is never
	// dropped.
	AssemblyFixerTriggeringChildKey string

	// AssemblyFixerResolverDiagnosis is the formatted merge-resolver verdict
	// dispatchAssemblyFixer loaded from the plan's latest persisted
	// merge_resolver_diagnostics row on a conflict-triggered dispatch. It
	// rides the result event to the apply site, where the
	// file_implementation_issue arm injects it verbatim into the corrective
	// child's body as a `## Resolver diagnosis` section so the downstream
	// implementer starts with the files + port direction the resolver named.
	// Empty on gate-only + main-merge-non-conflict + follow-on dispatches,
	// making the body injection a no-op there.
	AssemblyFixerResolverDiagnosis string

	// EventCapabilityGapPark payload (SPEC-SOR-2923-v1 R2, SOR-3083).
	// CapabilityGapPark carries the (plan, gap issue, capability signature) the
	// site-3 filing goroutine resolved; applyCapabilityGapParkEvent parks the
	// plan through parkPlanOnCapabilityGap. Nil for other event kinds.
	CapabilityGapPark *CapabilityGapParkPayload

	// EventCapabilityGapReleaseProbeResult payload (SOR-3084). CapabilityGapReleaseProbe
	// carries the off-main git-ancestry probe's per-plan deployed verdict;
	// applyCapabilityGapReleaseProbeResult drives the release / re-park /
	// circuit-break disposition from it. Nil for other event kinds.
	CapabilityGapReleaseProbe *CapabilityGapReleaseProbeResultPayload

	// EventPlanBranchCreateResult payload (CIPB Phase B). PlanKey
	// identifies the planning issue; PlanBranchCreate carries the
	// aggregate per-repo result. Nil for other event kinds.
	PlanBranchCreate *PlanBranchCreateResult

	// EventCPBChildSquashResult payload (CIPB Phase B). CPBChildSquash
	// carries the typed per-child-per-repo squash outcome. Nil for other
	// event kinds.
	CPBChildSquash *CPBChildSquashResult

	// EventCPBMergeResolverResult payload (CIPB Phase B, SOR-2739).
	// CPBMergeResolver carries the off-budget merge_resolver dispatch
	// outcome. Nil for other event kinds.
	CPBMergeResolver *CPBMergeResolverResult

	// EventPlanMainMergeResult payload (CIPB Phase C).
	// PlanMainMergeData carries the typed per-repo periodic-main-merge
	// outcome — populated on EventPlanMainMergeResult, nil for every
	// other event kind. PlanKey at the top-level Event identifies the
	// planning issue the merge sweep targeted.
	PlanMainMergeData *PlanMainMergeResultEvent

	// EventPlanMainMergeTipProbeResult payload (CIPB Phase C, SOR-2187).
	// PlanMainMergeTipProbeData carries the off-main origin/<default> tip
	// probe's per-repo result — populated on EventPlanMainMergeTipProbeResult,
	// nil for every other event kind. No PlanKey: a single probe covers the
	// union of every in-flight CIPB plan's repos, and the result handler maps
	// changed repos back to the plans that cover them.
	PlanMainMergeTipProbeData *PlanMainMergeTipProbeResultEvent

	// EventMainMergeRelevanceResult payload (CIPB Phase C, SOR-2876).
	// MainMergeRelevanceData carries the off-main-computed per-plan relevance
	// verdict for one interim main-merge trigger (the completion fan-out or the
	// tip-change probe, discriminated by the payload's Trigger field) —
	// populated on EventMainMergeRelevanceResult, nil for every other event
	// kind. No top-level PlanKey: a single relevance pass covers every eligible
	// in-flight CIPB plan, and the handler maps relevant / deferred keys back to
	// the plans.
	MainMergeRelevanceData *MainMergeRelevanceResultEvent

	// EventPlanPRReadyFlipResult payload (CIPB Phase C AC6).
	// PlanPRReadyFlipResults carries the per-repo flip outcome; nil
	// for other event kinds. PlanKey at the top-level Event
	// identifies the planning issue. The reused
	// PlanPROpenResult-shaped slice is shared with the legacy plan-
	// PR-open session shape because the per-repo outcome surface
	// (Repo / URL / Err) is identical — only the meaning differs
	// (URL on success is the still-set existing PR URL, not a
	// newly-opened one).
	PlanPRReadyFlipResults []PlanPROpenResult

	// PlanBranchRecreateResults carries the per-repo outcome of the
	// recovery-walk plan-branch self-heal dispatch
	// (maybeDispatchRecreatePlanBranch). Set on EventPlanBranchRecreateResult;
	// nil for other event kinds. PlanKey at the top-level Event identifies
	// the planning issue.
	PlanBranchRecreateResults []PlanBranchRecreateRepoResult

	// PerChildPROpenResults carries the per-repo outcome of a
	// "per_child_pr_open" session: the daemon-side per-child PR-open
	// the verifier chain gates AFTER the implementer pushes the branch
	// (the load-bearing reason for moving `gh pr create` into the
	// daemon — a red chain leaves no stale PR behind on GitHub).
	// Reuses the PlanPROpenResult shape (Repo / URL / Err) because the
	// per-repo outcome surface is identical to the plan-PR-open case;
	// applyPerChildPROpenResults differentiates by the session role.
	PerChildPROpenResults []PlanPROpenResult

	// PerChildPRSummary is the implementer-supplied summary the
	// daemon-side per-child PR-open propagates from the
	// `dispatchPerChildPROpen` call site to the `applyPerChildPROpenResults`
	// main-loop handler so the in_review transition comment renders the
	// same `### Summary` section it used to under the LLM-driven
	// PR-open shape. Set on the EventSessionResult emitted by the
	// per_child_pr_open session; ignored for every other event kind.
	PerChildPRSummary string

	// PerChildRequirementTraceJSON is the implementer's raw
	// requirement_trace JSON the daemon-side per-child PR-open propagates
	// from the `dispatchPerChildPROpen` call site to the
	// `applyPerChildPROpenResults` main-loop handler so the in_review
	// transition seats the structured requirement→code trace on the issue
	// row (IssueTransitionEffects.SetRequirementTrace). Set on the
	// EventSessionResult emitted by the per_child_pr_open session; empty /
	// ignored for every other event kind and for issues that traced
	// nothing.
	PerChildRequirementTraceJSON string

	// PerChildVerifiedSpecVersion is the plan's current spec-version ID the
	// daemon-side per-child PR-open propagates from the
	// `dispatchPerChildPROpen` call site to the `applyPerChildPROpenResults`
	// main-loop handler so the in_review transition seats the re-gate stamp
	// on the issue row (IssueTransitionEffects.SetVerifiedAgainstSpecVersion,
	// SPEC-SOR-2945-v3 R9). The stamp is resolved on the main goroutine at
	// dispatch time (currentPlanSpecVersion reads d.state) and captured in
	// the session closure. Set on the EventSessionResult emitted by the
	// per_child_pr_open session; empty / ignored for every other event kind
	// and for a child with no spec-bearing planning parent.
	PerChildVerifiedSpecVersion string

	// VerifyChain is the EventImplementerVerifyChainResult payload —
	// the aggregate outcome of running the implementer verifier chain
	// off-main. Nil for other event kinds.
	VerifyChain *ImplementerVerifyChainResult

	// ForwardRefLint is the EventForwardRefLintResult payload — the
	// aggregate outcome of running the forward-referencing-paths
	// predispatch lint off-main. Nil for other event kinds.
	ForwardRefLint *ForwardRefLintResult

	// SpecVerificationResult is the EventSpecVerificationResult payload —
	// the outcome of running the spec SMT verification off-main. Nil for
	// other event kinds.
	SpecVerificationResult *SpecVerificationResultEvent

	// BlockedUserPROpenResult is the EventBlockedUserPROpenResult payload —
	// the per-issue outcome of running the blocked_user PR-open probes
	// off-main. Nil for other event kinds.
	BlockedUserPROpenResult *BlockedUserPROpenResultEvent

	// CrashRecoveryPRDiscoveryResult is the EventCrashRecoveryPRDiscoveryResult
	// payload — the outcome of running the crash-before-marker PR-set recovery
	// discovery off-main. Nil for other event kinds.
	CrashRecoveryPRDiscoveryResult *CrashRecoveryPRDiscoveryResultEvent

	// PickResult is the EventPickResult payload — the outcome of running the
	// scheduler Pick (dependency-graph build + ready-leaf selection) off-main.
	// Nil for other event kinds.
	PickResult *PickResultEvent
}

type EventKind int

type FailedPlanPRCheck struct {
	Repo         string
	PRURL        string
	CheckName    string
	WorkflowName string
	HeadSHA      string
}

type FlowLivenessMonitor struct {
	// contains filtered or unexported fields
}

type ForceConvergeForTestPayload struct {
	IssueKey string
	ToState  sm.IssueState
	Actor    string
	Reason   string
	Now      time.Time
	// Done is closed by the handler once ForceConverge has been
	// applied. The caller waits on this channel so the test goroutine
	// resumes only after the mutation is visible on the main loop.
	Done chan struct{}
}

type ForwardError struct {
	// StatusCode is the peer's HTTP status, or 0 for a transport-level
	// failure (connection refused, timeout, DNS).
	StatusCode int
	// Body is the (truncated) peer response body, or the transport
	// error text when StatusCode is 0.
	Body string
	// contains filtered or unexported fields
}

type ForwardRefLintResult struct {
	IssueKey string
	Missing  []string
	ProbeErr error
}

type ForwardRequiredError = httpapi.ForwardRequiredError

type GateFailureClass string

type ImplementerCycleDiffStater interface {
	// CycleDiffStat runs `git diff --numstat origin/<default>...HEAD` in
	// each worktree (keyed repo→dir) and returns the summed totals. A
	// per-repo failure contributes zero and the loop continues; a
	// fully-failed computation returns zero totals with a non-nil error
	// the caller logs.
	CycleDiffStat(ctx context.Context, worktreePaths map[string]string) (DiffStatTotals, error)
	// CycleDiffNameOnly runs `git diff --name-only origin/<default>...HEAD`
	// in each worktree and returns the union of edited repo-relative paths
	// (the name-only sibling of CycleDiffStat). Feeds the implementer_phase_
	// discovery_deviation metric's "actually edited" set. Same best-effort
	// contract: a per-repo failure contributes nothing and the loop
	// continues; a fully-failed computation returns nil with a non-nil error.
	CycleDiffNameOnly(ctx context.Context, worktreePaths map[string]string) ([]string, error)
}

type ImplementerDispatcher func(ctx context.Context, task role.ImplementerTask) (role.ImplementerResult, error)

type ImplementerVerifyChainResult struct {
	IssueKey    string
	Result      role.ImplementerResult
	Results     []VerifierResult
	FailingRepo string
	Passed      bool
}

type IssuePRClosedRecovery struct {
	IssueKey  string
	FromState sm.IssueState
	// ClosedRepos lists the repos whose PR snapshot was CLOSED, sorted
	// for deterministic event-message ordering.
	ClosedRepos []string
}

type IssuePRDraftConverted struct {
	IssueKey  string
	Repo      string
	PRURL     string
	FromState sm.IssueState
}

type IssueTransitionEffects struct {
	To            sm.IssueState
	Actor         string
	Reason        string
	Force         bool
	PreserveWIP   string
	ClearSession  bool
	EventKind     string
	EventMessage  string
	Comment       string
	CleanWorktree bool
	Escalation    *store.Escalation

	// AttachSessionID is the mirror image of ClearSession: when non-empty,
	// the chokepoint sets iss.SessionID = AttachSessionID AFTER the SM
	// mutation and BEFORE persistTransitionHistory, so the attach lands in
	// the same issuestore transaction as the state write (and rolls back
	// with it on a persist error — the transitionFieldSnapshot already
	// captures sessionID). It is the in-band caller's way to satisfy the
	// session-attached-on-transition-in invariant: a transition INTO a
	// session-required state (sm.IsSessionRequiredState) must atomically
	// attach a session. Callers that already opened a session set this so
	// open+attach+transition is one atomic unit (dispatchImplementer's
	// ready-entry arm, applyImplementerDiscoveryResult). The full-row
	// re-projection in persistTransitionHistory is safe here because
	// session-required states are implementation-issue states only — never
	// planning issues, whose mid-construction child junctions are what the
	// narrow attachIssueSession UPDATE exists to protect. AttachSessionID
	// and ClearSession are mutually exclusive on one edge.
	AttachSessionID string

	// EventPayload is the typed event a caller built via a generated
	// store.New<Kind> constructor (events.gen.go). When non-zero
	// (EventPayload.Kind != ""), the chokepoint emits it verbatim —
	// layering the post-transition NewState + Timestamp on top — and
	// ignores EventKind / EventMessage. Callers migrating off the
	// untyped literal seat the constructor's output here; the legacy
	// EventKind / EventMessage path stays in place for kinds whose
	// schema entry has not yet shipped.
	EventPayload store.Event

	// BlockedReason, TriagerBlockedAt, TriagerBlockedReason are the
	// post-transition metadata fields the chokepoint writes onto *iss as
	// part of the atomic step that runs before persistTransitionHistory's
	// mirror commit. Optional/zero-value semantics: an empty string / zero
	// time.Time means "leave the field unchanged", matching today's
	// behavior at call sites that never pre-mutated the fields. When set,
	// the chokepoint writes the value AFTER the SM mutation (Transition /
	// ForceConverge) so a non-empty BlockedReason wins over the SM's
	// auto-derived BlockedReason on blocked_user / plan_blocked targets;
	// callers who want the SM's auto-write to stand simply leave Effects.
	// BlockedReason at its zero value. The cluster-1 rollback covers these
	// fields via transitionFieldSnapshot, so a persist failure leaves them
	// at their pre-call values along with State / PlanState.
	BlockedReason        string
	TriagerBlockedAt     time.Time
	TriagerBlockedReason string

	// ReviewerReferBackConcerns is the JSON-encoded []role.ReviewConcern
	// buffer the verdict-refer-back path writes onto *iss BEFORE the
	// in_review → feedback transition so the next feedback-N implementer
	// dispatch threads the concerns onto the REVIEW_FEEDBACK envelope
	// block. Same zero-value semantic as BlockedReason: empty means leave
	// unchanged. Covered by the cluster-1 rollback via transitionFieldSnapshot.
	ReviewerReferBackConcerns string

	// From is the IssueState the issue was in before queueTransition
	// performed the in-place SM mutation. Set ONLY by queueTransition so
	// applyTransitionEffects can build a history row with the correct
	// from_state column; ignored by applyIssueTransition (which reads
	// iss.State directly before its own mutation). Zero-value is fine
	// for the applyIssueTransition path — the helper does not consume
	// this field.
	From sm.IssueState

	// CommentRow is an optional issuestore.Comment that callers want
	// committed inside the same transaction as the issue-row mirror +
	// history row. Used by the operator-mutate cancel path so the
	// derived cancel comment lands atomically with the SM transition.
	// Nil means no comment to write (the common case).
	CommentRow *issuestore.Comment

	// SetDiscoveryMarkdown / SetReviewDiscoveryMarkdown (phased-dispatch
	// foundation), when non-empty, write the discovery artifact onto
	// iss.DiscoveryMarkdown / iss.ReviewDiscoveryMarkdown AFTER the snapshot
	// and BEFORE the persist, so the forward phased transitions
	// (discovering → implementing carries the discovery result;
	// in_review → review_judging carries the review-discovery result)
	// persist the column atomically with the state change. Empty leaves the
	// column unchanged. The future discovery-result handler seats the
	// markdown here rather than mutating *iss directly so the write lands
	// inside the cluster-1 snapshot/restore bracket — a failed persist rolls
	// the column back to its pre-transition value alongside State.
	SetDiscoveryMarkdown       string
	SetReviewDiscoveryMarkdown string

	// ClearDiscoveryMarkdown / ClearReviewDiscoveryMarkdown (phased-dispatch
	// foundation), when true, zero iss.DiscoveryMarkdown / iss.Review
	// DiscoveryMarkdown on *iss AFTER the snapshot and BEFORE the persist,
	// so the operator-recovery edges (implementing → discovering,
	// review_judging → in_review) discard the stale discovery artifact
	// atomically with the state change. The cluster-1 rollback covers the
	// columns via transitionFieldSnapshot, so a failed persist leaves the
	// column at its pre-clear value alongside State. Zero-value (false)
	// leaves the column unchanged — the common case for every other edge.
	// A Set and a Clear for the same column never coexist on one edge; if
	// both were set, the Clear wins (applied last).
	ClearDiscoveryMarkdown       bool
	ClearReviewDiscoveryMarkdown bool

	// ClearDiscoveringHold (SOR-2891), when true, zeros the five durable
	// held-discovering hold columns (DiscoveringHoldFootprint /
	// DiscoveringHoldMarkdown / DiscoveringHoldSince / DiscoveringHoldBlockerKey
	// / DiscoveringHoldReason) on *iss in the post-snapshot / pre-persist window,
	// so the durable hold record is cleared ATOMICALLY with the discovering →
	// implementing release transition — the exact inverse of the write-gate hold
	// that set them (supervisor_result_implementer.go). Without this the released
	// issue would carry a stale durable record indefinitely: `sorcerer issue show`
	// would render a false "held" bullet on an actively-implementing issue,
	// rehydrateDiscoveringFootprintHeld would resurrect a phantom registry entry
	// after a restart, and the stale non-zero DiscoveringHoldSince would mask the
	// strand-detection invariant's implementing leg. The cluster-1 rollback covers
	// the five columns via transitionFieldSnapshot, so a failed persist restores
	// the pre-clear hold record alongside State / SessionID. Zero value (false)
	// leaves the columns unchanged — the common case for every edge except the
	// hold-release transition in dispatchHeldDiscoveringIssue.
	ClearDiscoveringHold bool

	// SetPredictedFootprint (CIPB Phase E Option D), when non-nil,
	// replaces iss.PredictedFootprint with the pointed-to value in the
	// post-snapshot / pre-persist window so the in_review footprint
	// backfill commits atomically with the in_review transition (and
	// rolls back with it on a persist error — transitionFieldSnapshot
	// captures the column). Nil leaves the column unchanged — the common
	// case for every edge except the three in_review callers that compute
	// a backfill for an exploration / legacy-empty footprint. The
	// computed footprint sets Backfilled=true so subsequent in_review
	// re-entries refresh it.
	SetPredictedFootprint *footprint.PredictedFootprint

	// SetRequirementTrace, when non-nil, replaces iss.RequirementTrace with
	// the pointed-to value in the post-snapshot / pre-persist window so the
	// implementer-emitted structured requirement→code trace commits
	// atomically with the in_review transition (and rolls back with it on a
	// persist error — transitionFieldSnapshot captures the column). Nil
	// leaves the field unchanged — the common case for every edge except
	// the result-handler in_review callers that decode a non-empty
	// requirement_trace from the implementer result. Seated by
	// applyIssueEffectsFootprintFields alongside SetPredictedFootprint.
	SetRequirementTrace *spectrace.RequirementTrace

	// SetVerifiedAgainstSpecVersion, when non-empty, writes iss.SpecAmend
	// VerifiedSpecVersion (the durable re-gate stamp added by the
	// bounded-recovery child's migration) in the post-snapshot / pre-persist
	// window so the spec version a child last gated against commits
	// atomically with the post-verify in_review transition (and rolls back
	// with it on a persist error — transitionFieldSnapshot.specAmend
	// VerifiedSpecVersion captures the column). The fan-out point
	// applyImplementerResultPostVerifier computes the plan's current spec id
	// once and threads it onto each branch-model in_review seat, mirroring
	// how SetRequirementTrace is threaded. Empty leaves the column
	// unchanged — the common case for every edge except a spec-driven
	// child's gate-pass (and for a child with no spec-bearing planning
	// parent, where the empty stamp is the correct "never gated" value).
	SetVerifiedAgainstSpecVersion string

	// SetReviewDiscoveryFootprint, when non-nil, replaces
	// iss.ReviewDiscoveryFootprint with the pointed-to value in the
	// post-snapshot / pre-persist window so the reviewer-discovery cited
	// path-set commits atomically with the review_discovering → review_judging
	// transition (and rolls back with it on a persist error —
	// transitionFieldSnapshot.reviewDiscoveryFootprint captures the column).
	// The reviewer-side peer of SetPredictedFootprint: applyReviewerDiscoveryResult
	// extracts the typed per_ac_mapping path-set once and seats it here so
	// emitReviewerDiscoveryDeviation reads the structured field, not a re-parse
	// of the derived ReviewDiscoveryMarkdown (spec R8). Nil leaves the column
	// unchanged — the common case for every edge except the one discovery-result
	// seat.
	SetReviewDiscoveryFootprint *footprint.PredictedFootprint

	// BackfillAuditEvent (CIPB Phase E Option D), when its Kind is
	// non-empty, is emitted AFTER persistTransitionHistory succeeds —
	// alongside (not in place of) EventPayload / EventKind. It carries the
	// predicted_footprint_backfilled audit row paired with a
	// SetPredictedFootprint mutation; the emit is gated on persist success
	// so a rolled-back transition never logs a phantom backfill. Zero value
	// (Kind == "") means no backfill event — the common case.
	BackfillAuditEvent store.Event
}

type LLMVerifierRunner interface {
	RunVerification(ctx context.Context, specID, requirementID, statement string, tracedTargets []tracedcode.ResolvedTarget) (result, rationale string, err error)
}

type LandingGateTail struct {
	FailingTest string
	Diagnostic  []string
}

type LiveSessionMetrics struct {
	SessionID          string
	IssueKey           string   // empty until populated by JoinLiveMetrics
	OutputTokens       int      // cumulative output tokens
	InputTokens        int      // cumulative input + cache-read tokens
	Turns              int      // assistant-frame turn count
	LatestSalientLine  string   // most recent salient activity line
	RecentSalientLines []string // bounded ≤5 ring, oldest first
}

type LivenessSessionWriteback struct {
	// contains filtered or unexported fields
}

type Logger interface {
	Printf(format string, args ...any)
}

type LoopHarness struct {
	// contains filtered or unexported fields
}