core

type ACPAcceptedPayload struct {
	WorkerID string `json:"workerId"`
}

type ACPArchiveManifest struct {
	Version    int    `json:"version"`
	SessionID  string `json:"sessionId"`
	SealedAt   string `json:"sealedAt"`
	EventCount int    `json:"eventCount"`
	LastSeq    uint64 `json:"lastSequence"`
}

type ACPAuthority struct {
	ReadOnly       bool     `json:"readOnly"`
	AllowedActions []string `json:"allowedActions"`
}

type ACPBlockerPayload struct {
	Reason string `json:"reason"`
}

type ACPCancelledPayload struct {
	Reason string `json:"reason"`
}

type ACPCheckpointPayload struct {
	Percent      int      `json:"percent"`
	Reason       string   `json:"reason,omitempty"`
	ChangedFiles []string `json:"changedFiles,omitempty"`
	GitHead      string   `json:"gitHead,omitempty"`
}

type ACPCursor struct {
	Version   int    `json:"version"`
	SessionID string `json:"sessionId"`
	WorkerID  string `json:"workerId"`
	Sequence  uint64 `json:"sequence"`
	MessageID string `json:"messageId,omitempty"`
	UpdatedAt string `json:"updatedAt"`
}

type ACPDirectivePayload struct {
	Action string `json:"action"`
	Reason string `json:"reason"`
}

type ACPEnvelope struct {
	Version   string                 `json:"version"`
	MessageID string                 `json:"messageId"`
	SessionID string                 `json:"sessionId"`
	Sequence  uint64                 `json:"sequence"`
	CreatedAt string                 `json:"createdAt"`
	ExpiresAt string                 `json:"expiresAt"`
	Type      ACPMessageType         `json:"type"`
	From      string                 `json:"from"`
	To        string                 `json:"to"`
	Spec      string                 `json:"spec"`
	Task      string                 `json:"task,omitempty"`
	Attempt   int                    `json:"attempt"`
	InReplyTo string                 `json:"inReplyTo,omitempty"`
	Payload   json.RawMessage        `json:"payload"`
	Decision  *OrchestrationDecision `json:"decision,omitempty"`
}

type ACPEvidencePayload struct {
	VerificationRef string   `json:"verificationRef"`
	Summary         string   `json:"summary"`
	ChangedFiles    []string `json:"changedFiles"`
	GitHead         string   `json:"gitHead,omitempty"`
	DurationMs      int64    `json:"durationMs,omitempty"`
	HostTokens      int      `json:"hostTokens,omitempty"`
	HostCost        string   `json:"hostCost,omitempty"`
}

type ACPHeartbeatPayload struct {
	WorkerID string `json:"workerId"`
	Status   string `json:"status"`
}

type ACPLease struct {
	Version          int            `json:"version"`
	SessionID        string         `json:"sessionId"`
	WorkerID         string         `json:"workerId"`
	Spec             string         `json:"spec"`
	Task             string         `json:"task"`
	Attempt          int            `json:"attempt"`
	Status           ACPLeaseStatus `json:"status"`
	AcquiredAt       string         `json:"acquiredAt"`
	HeartbeatAt      string         `json:"heartbeatAt"`
	LeaseUntil       string         `json:"leaseUntil"`
	MessageExpiresAt string         `json:"messageExpiresAt"`
	ReleasedAt       string         `json:"releasedAt,omitempty"`
	// Suspend metadata (R3). All omitempty so a lease that never suspends
	// serializes byte-identically to the pre-resilience shape. SuspendedAt and
	// ResumeDeadline bound the suspension window; the reclaim predicate uses
	// ResumeDeadline (not LeaseUntil) to decide if a suspended lease is dead.
	// SuspendSecondsTotal accumulates requested suspension across repeated
	// suspend calls so the cumulative cap can be enforced.
	SuspendedAt         string `json:"suspendedAt,omitempty"`
	SuspendReason       string `json:"suspendReason,omitempty"`
	ResumeDeadline      string `json:"resumeDeadline,omitempty"`
	SuspendSecondsTotal int    `json:"suspendSecondsTotal,omitempty"`
}

type ACPLeaseStatus string

type ACPMessageType string

type ACPMissionPayload struct {
	DispatchDigest  string                            `json:"dispatchDigest"`
	Role            string                            `json:"role"`
	ContextCommand  string                            `json:"contextCommand"`
	ContextManifest contextpkg.MissionContextManifest `json:"contextManifest,omitempty"`
	Contract        string                            `json:"contract"`
	Files           []string                          `json:"files"`
	Acceptance      string                            `json:"acceptance"`
	VerifyCommand   string                            `json:"verifyCommand"`
	Dependencies    []string                          `json:"dependencies"`
	Authority       ACPAuthority                      `json:"authority"`
}

type ACPProgressPayload struct {
	Percent int    `json:"percent"`
	Message string `json:"message"`
	// LastReport is the server-side write time of this progress record (RFC3339).
	// It is stamped by RecordPinkyProgress from the host clock, never from a
	// worker-supplied value, so it cannot be spoofed into the future. It lets the
	// driver distinguish slow-but-progressing work from a true stall (R6).
	// omitempty keeps pre-resilience progress events byte-stable.
	LastReport string `json:"lastReport,omitempty"`
}

type ACPQueryPayload struct {
	Text string `json:"text"`
}

type ACPResumePayload struct {
	SuspendedSeconds int    `json:"suspendedSeconds"`
	Reason           string `json:"reason,omitempty"`
}

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

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

type AcceptanceGaps struct {
	Unmet  []int    `json:"unmet"`
	Failed []string `json:"failed"`
}

type AdvanceTarget struct {
	Status SpecStatus
	Phase  Phase
}

type Annotation struct {
	Kind     AnnotationKind
	Evidence string // for complete
	Ts       string // for complete
	Reason   string // for blocked
}

type AnnotationKind string

type ArtifactBrief struct {
	Artifact    string   `json:"artifact"`
	Gate        string   `json:"gate"`
	Constraints []string `json:"constraints"`
}

type AuthoringBrief struct {
	EarsForms      []string        `json:"earsForms"`
	DesignSections []string        `json:"designSections"`
	TaskKeys       []string        `json:"taskKeys"`
	Roles          []string        `json:"roles"`
	ReadonlyRoles  []string        `json:"readonlyRoles"`
	Artifacts      []ArtifactBrief `json:"artifacts"`
	Prompt         string          `json:"prompt,omitempty"`
}

type AutoResumeCfg struct {
	Enabled       bool `json:"enabled,omitempty"`
	OnHostStart   bool `json:"onHostStart,omitempty"`
	MaxAgeMinutes int  `json:"maxAgeMinutes,omitempty"`
}

type Badge struct {
	Label string
	Color string
}

type Blocker struct {
	Task   string `json:"task"`
	Reason string `json:"reason"`
	Since  string `json:"since"`
}

type BrainDirective struct {
	SessionID string
	WorkerID  string
	Spec      string
	TaskID    string
	Attempt   int
	Action    string
	Reason    string
	InReplyTo string
}

type CheckCtx struct {
	Root, Slug string
	ReqMd      *string
	Doc        *ParsedTasks
	State      *State
	Cfg        Config
}

type CheckGate func(CheckCtx) (violations, warnings []Violation)

type CheckpointRecord struct {
	Version         int      `json:"version"`
	SessionID       string   `json:"sessionId"`
	Spec            string   `json:"spec"`
	TaskID          string   `json:"taskId"`
	Attempt         int      `json:"attempt"`
	WorkerID        string   `json:"workerId"`
	ProgressPercent int      `json:"progressPercent"`
	ContextManifest string   `json:"contextManifest,omitempty"`
	WorkingNotes    string   `json:"workingNotes,omitempty"`
	ChangedFiles    []string `json:"changedFiles,omitempty"`
	GitHead         string   `json:"gitHead,omitempty"`
	Reason          string   `json:"reason,omitempty"`
	CreatedAt       string   `json:"createdAt"`
}

type CommandMeta struct {
	Command            string                  `json:"command"`
	Category           string                  `json:"category"`
	Description        string                  `json:"description"`
	Usage              string                  `json:"usage"`
	Synopsis           string                  `json:"synopsis"`
	LongDescription    string                  `json:"longDescription"`
	Flags              []FlagMeta              `json:"flags"`
	Positionals        []PositionalMeta        `json:"positionals,omitempty"`
	PhaseCompatibility *PhaseCompatibilityMeta `json:"phaseCompatibility,omitempty"`
	ModeCompatibility  *ModeCompatibilityMeta  `json:"modeCompatibility,omitempty"`
	ExitCodes          []ExitCodeMeta          `json:"exitCodes"`
	Examples           []string                `json:"examples"`
	Hidden             bool                    `json:"hidden,omitempty"`
	RemovedIn          string                  `json:"removedIn,omitempty"`
}

type Commit struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
}

type CommitLink struct {
	SHA     string   `json:"sha"`
	Subject string   `json:"subject"`
	Tasks   []string `json:"tasks"`
}

type CompactionOutcome struct {
	Entry              ContextLedgerEntry
	SummaryFile        string
	PreEstimatedTokens int
}

type CompleteTaskRequest struct {
	Evidence   string
	Unverified bool
	Force      bool
	Idempotent bool
	Tokens     *int
	Cost       *string
}

type CompleteTaskResult struct {
	Status          TaskStatus
	Evidence        string
	AlreadyComplete bool
}

type Config struct {
	Version            int              `json:"version"`
	DefaultVerify      string           `json:"defaultVerify"`
	Report             ReportCfg        `json:"report"`
	Roles              RolesCfg         `json:"roles"`
	PromotionThreshold int              `json:"promotionThreshold"`
	Gates              GatesCfg         `json:"gates"`
	Verify             VerifyCfg        `json:"verify"`
	Orchestration      OrchestrationCfg `json:"orchestration"`
	MCP                MCPConfig        `json:"mcp"`
}

type ConfigDiagnostic struct {
	Path     string `json:"path"`
	Source   string `json:"source,omitempty"`
	Layer    string `json:"layer,omitempty"`
	Field    string `json:"field,omitempty"`
	Severity string `json:"severity"`
	Message  string `json:"message"`
}

type ConfigLoadResult struct {
	Diagnostics []ConfigDiagnostic `json:"diagnostics"`
	ProjectPath string             `json:"projectPath,omitempty"`
	GlobalPath  string             `json:"globalPath,omitempty"`
	Digest      string             `json:"digest"`
	Present     bool               `json:"present"`
}

type ContextLedgerEntry struct {
	StepSequence       uint64 `json:"stepSequence"`
	Phase              Phase  `json:"phase"`
	Action             string `json:"action"` // dispatch | compact | approve | step
	EstimatedTokens    int    `json:"estimatedTokens"`
	HostReportedTokens int    `json:"hostReportedTokens,omitempty"`
	Budget             int    `json:"budget"`
	SoftCeiling        int    `json:"softCeiling"`
	Compacted          bool   `json:"compacted,omitempty"`
	CompactedAt        string `json:"compactedAt,omitempty"`
	Reason             string `json:"reason"` // phase-complete | budget-threshold | manual-clear
}

type ContextManifestTools struct {
	RequiredTools  []string `json:"requiredTools"`
	OptionalTools  []string `json:"optionalTools"`
	ForbiddenTools []string `json:"forbiddenTools"`
}

type CostBrakeLevel string

type Counts struct {
	Pending  int `json:"pending"`
	Running  int `json:"running"`
	Complete int `json:"complete"`
	Blocked  int `json:"blocked"`
	Total    int `json:"total"`
}

type Criterion struct {
	ID      string      // "<req>.<idx>", e.g. "1.2"
	Req     int         // requirement number
	Index   int         // 1-based position within the requirement's acceptance list
	Text    string      // criterion prose
	Line    int         // 1-based line in requirements.md
	Pattern EarsPattern // matched EARS pattern ("" when none matched)
	EarsOK  bool        // whether Text matched an EARS pattern
}

type CriterionRecord struct {
	Requirement int    `json:"requirement"`
	Criterion   int    `json:"criterion"`
	Status      string `json:"status"` // "pass" | "fail"
	Evidence    string `json:"evidence"`
	RanAt       string `json:"ranAt"`
}

type CustomGateCfg struct {
	Name     string `json:"name"`
	Command  string `json:"command"`
	Severity string `json:"severity"`
	Sandbox  string `json:"sandbox,omitempty"`
}

type CustomGateFinding struct {
	Location string `json:"location"`
	Message  string `json:"message"`
}

type CustomGateInput struct {
	Spec   string              `json:"spec"`
	Root   string              `json:"root"`
	Status string              `json:"status"`
	Tasks  []CustomGateTaskRef `json:"tasks"`
}

type CustomGateOutput struct {
	Violations []CustomGateFinding `json:"violations"`
	Warnings   []CustomGateFinding `json:"warnings"`
}

type CustomGateTaskRef struct {
	ID     string `json:"id"`
	Status string `json:"status"`
	Role   string `json:"role"`
	Wave   int    `json:"wave"`
}

type DagTask struct {
	ID      string
	Wave    int
	Depends []string
	Status  TaskStatus
}

type DriverDispatch struct {
	Decision OrchestrationDecision
	Mission  PinkyMission
}

type DriverEvent struct {
	Event   string
	Session string
	Worker  string
	Task    string
	// Compaction fields are populated only on the "context.compact" event so the
	// host observer can log the token ledger checkpoint and run the real /clear.
	Phase              string
	Reason             string
	CompactionFile     string
	EstimatedTokens    int
	HostReportedTokens int
	Budget             int
}

type DriverObserver func(DriverEvent)

type DriverOptions struct {
	MaxSteps int
	MaxWaits int
	Worker   func(DriverDispatch) error
	Observer DriverObserver
}

type DriverOutcome string

type DriverResult struct {
	Steps   int                   `json:"steps"`
	Outcome DriverOutcome         `json:"outcome"`
	Final   OrchestrationDecision `json:"final"`
}

type EarsIssue struct {
	Line    int
	Message string
}

type EarsPattern string

type ExitCodeMeta struct {
	Code    int    `json:"code"`
	Meaning string `json:"meaning"`
}

type FlagMeta struct {
	Name        string   `json:"name"`
	Type        string   `json:"type"`
	Description string   `json:"description,omitempty"`
	Enum        []string `json:"enum,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Default     string   `json:"default,omitempty"`
}

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

type FrontierEvent struct {
	Spec     string   `json:"spec"`
	Revision int      `json:"revision"`
	Status   string   `json:"status"`
	Frontier []string `json:"frontier"`          // runnable task IDs, wave/ordinal order
	Added    []string `json:"added,omitempty"`   // entered the frontier since last event
	Removed  []string `json:"removed,omitempty"` // left the frontier since last event
	At       string   `json:"at"`
}

type Gate string

type GatesCfg struct {
	Traceability string `json:"traceability"`
	Acceptance   string `json:"acceptance"`
	// Scope is the diff-scope gate severity: "off"/""/"*" = no-op, else
	// "warn"/"error". It flags verify-time changed files outside a task's
	// declared `files:` contract.
	Scope string `json:"scope"`
	// ContextBudget is the opt-in context-budget gate severity:
	// "off"/""/"*" = no-op (default), else "warn"/"error". When enabled it builds
	// the active spec's context manifest and flags it when the required-item token
	// estimate exceeds the effective budget, naming the heaviest items.
	ContextBudget string `json:"contextBudget"`
	// MaxContextTokens optionally caps the gate's effective budget (mirrors the MCP
	// capabilities.specd.maxContextTokens host hint). 0 = use the derived budget.
	MaxContextTokens int `json:"maxContextTokens"`
	// ModeCapability is the opt-in mode-capability gate severity:
	// "off"/""/"*" = no-op (default), else "warn"/"error". When enabled it flags a
	// spec recorded as orchestrated while the project lacks orchestration
	// capability (orchestration.enabled absent/false). Off by default keeps Base
	// projects clean.
	ModeCapability string `json:"modeCapability"`
	// Custom lists external, declarative custom gates run after the core
	// pipeline. Each is an ordinary subprocess (no Go plugin, no network).
	Custom []CustomGateCfg `json:"custom"`
}

type GlobalConfigScaffoldResult struct {
	Path    string `json:"path"`
	Created bool   `json:"created"`
}

type HandshakeActiveSpecMode struct {
	Slug   string `json:"slug"`
	Status string `json:"status"`
	Phase  string `json:"phase"`
	Mode   string `json:"mode"`
	Origin string `json:"origin"`
	Gate   string `json:"gate"`
}

type HandshakeBootstrap struct {
	Version     int                       `json:"version"`
	Root        string                    `json:"root"`
	Load        []HandshakeLoadItem       `json:"load"`
	Commands    HandshakeCommandSummary   `json:"commands"`
	Config      HandshakeConfigSummary    `json:"config"`
	Health      HandshakeHealthSummary    `json:"health"`
	Modes       []HandshakeActiveSpecMode `json:"modes"`
	NextActions []string                  `json:"nextActions"`
}

type HandshakeCommandSummary struct {
	SchemaCommand string        `json:"schemaCommand"`
	Digest        string        `json:"digest"`
	Count         int           `json:"count"`
	Schema        []CommandMeta `json:"schema,omitempty"`
}

type HandshakeConfigSummary struct {
	Path                  string               `json:"path"`
	Digest                string               `json:"digest"`
	Roles                 HandshakeRolesConfig `json:"roles"`
	Orchestration         HandshakeOrchConfig  `json:"orchestration"`
	VerifySandbox         string               `json:"verifySandbox"`
	GateSeverities        map[string]string    `json:"gateSeverities"`
	ConfigFilePresent     bool                 `json:"configFilePresent"`
	EffectiveConfigSource string               `json:"effectiveConfigSource"`
}

type HandshakeHealthCheck struct {
	Name    string   `json:"name"`
	OK      bool     `json:"ok"`
	Missing []string `json:"missing"`
	Message string   `json:"message,omitempty"`
}

type HandshakeHealthSummary struct {
	OK     bool                   `json:"ok"`
	Checks []HandshakeHealthCheck `json:"checks"`
}

type HandshakeLoadItem struct {
	Path      string `json:"path"`
	Mode      string `json:"mode"`
	Rationale string `json:"rationale"`
}

type HandshakeMCPExposure struct {
	Expose               string   `json:"expose"`
	EssentialTools       []string `json:"essentialTools,omitempty"`
	IncludeMeta          bool     `json:"includeMeta"`
	IncludeOrchestration *bool    `json:"includeOrchestration,omitempty"`
}

type HandshakeOrchConfig struct {
	Enabled        bool   `json:"enabled"`
	ApprovalPolicy string `json:"approvalPolicy"`
	WorkerMode     string `json:"workerMode"`
}

type HandshakePolicy struct {
	Version              int                  `json:"version"`
	Root                 string               `json:"root"`
	SubagentMode         string               `json:"subagentMode"`
	OrchestrationEnabled bool                 `json:"orchestrationEnabled"`
	ApprovalPolicy       string               `json:"approvalPolicy"`
	WorkerMode           string               `json:"workerMode"`
	MaxWorkers           int                  `json:"maxWorkers"`
	MaxRetries           int                  `json:"maxRetries"`
	TimeoutSeconds       int                  `json:"timeoutSeconds"`
	VerifySandbox        string               `json:"verifySandbox"`
	GateSeverities       map[string]string    `json:"gateSeverities"`
	MCPExposure          HandshakeMCPExposure `json:"mcpExposure"`
	ConfigDigest         string               `json:"configDigest"`
	ConfigFilePresent    bool                 `json:"configFilePresent"`
	DigestMatch          *bool                `json:"digestMatch,omitempty"`
	ExpectedConfigDigest string               `json:"expectedConfigDigest,omitempty"`
	Spec                 *HandshakeSpecPolicy `json:"spec,omitempty"`
	Diagnostics          []ConfigDiagnostic   `json:"diagnostics"`
	Violations           []string             `json:"violations"`
	Recommendations      []string             `json:"recommendations"`
}

type HandshakeRolesConfig struct {
	SubagentMode string `json:"subagentMode"`
}

type HandshakeSpecPolicy struct {
	Slug            string `json:"slug"`
	SpecMode        string `json:"specMode"`
	ModeOrigin      string `json:"modeOrigin"`
	BrainAllowed    bool   `json:"brainAllowed"`
	BaseLoopAllowed bool   `json:"baseLoopAllowed"`
	Recommended     string `json:"recommendedCommandFamily"`
	NextCommand     string `json:"nextCommand"`
	PolicyViolation string `json:"policyViolation,omitempty"`
}

type InitAction struct {
	Kind        string `json:"kind"`
	Target      string `json:"target"`
	Description string `json:"description"`
	Destructive bool   `json:"destructive"`
	Required    bool   `json:"required"`
	Template    string `json:"template"`
	Content     string `json:"-"`
}

type InitAgentResults struct {
	Detected   []string `json:"detected"`
	Configured []string `json:"configured"`
	Manual     []string `json:"manual"`
}

type InitExecutor struct {
	WriteFile   func(path, content string) error
	MergeAgents func(path, content string, force bool) error
	MkdirTemp   func(dir, pattern string) (string, error)
	Rename      func(oldPath, newPath string) error
	RemoveAll   func(path string) error
}

type InitFileResults struct {
	Written []string `json:"written"`
	Updated []string `json:"updated"`
	Skipped []string `json:"skipped"`
	Failed  []string `json:"failed"`
}

type InitNextAction struct {
	Kind string `json:"kind"`
	Text string `json:"text"`
}

type InitOptions struct {
	Root           string   `json:"root"`
	Force          bool     `json:"force"`
	Repair         bool     `json:"repair"`
	Refresh        bool     `json:"refresh"`
	DryRun         bool     `json:"dryRun"`
	Interactive    bool     `json:"interactive"`
	AgentSelection []string `json:"agentSelection"`
	Scope          string   `json:"scope"`
}

type InitPlan struct {
	Root     string        `json:"root"`
	Mode     string        `json:"mode"`
	DryRun   bool          `json:"dryRun"`
	Fresh    bool          `json:"fresh"`
	Actions  []InitAction  `json:"actions"`
	Warnings []InitWarning `json:"warnings"`
}

type InitResult struct {
	SchemaVersion int                    `json:"schemaVersion"`
	Status        string                 `json:"status"`
	Root          string                 `json:"root"`
	Mode          string                 `json:"mode"`
	Files         InitFileResults        `json:"files"`
	Agents        InitAgentResults       `json:"agents"`
	Verification  InitVerificationResult `json:"verification"`
	Warnings      []InitWarning          `json:"warnings"`
	NextAction    InitNextAction         `json:"nextAction"`
}

type InitVerificationResult struct {
	MCP             string `json:"mcp"`
	ProtocolVersion string `json:"protocolVersion"`
	ToolCount       int    `json:"toolCount"`
}

type InitWarning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type LoadedSpec struct {
	State *State
	Doc   ParsedTasks
}

type MCPConfig struct {
	Expose               string   `json:"expose"`               // "all" (default) | "essential"
	EssentialTools       []string `json:"essentialTools"`       // commands/intents kept under expose:"essential"
	IncludeMeta          bool     `json:"includeMeta"`          // include install-mutating tools (update/uninstall/schema)
	IncludeOrchestration *bool    `json:"includeOrchestration"` // nil => derive from orchestration.enabled
}

type MidreqSummary struct {
	Turn   int
	Impact string
	Input  string
}

type ModeCompatibilityMeta struct {
	Modes                           []string `json:"modes,omitempty"`
	RequiresOrchestrationCapability bool     `json:"requiresOrchestrationCapability,omitempty"`
}

type ModeRecommendation struct {
	Recommended string      `json:"recommended"` // "simple" | "orchestrated"
	Confidence  string      `json:"confidence"`  // "neutral" | "suggest" | "strong"
	Signals     ModeSignals `json:"signals"`
	Rationale   string      `json:"rationale"`
	UserDecides bool        `json:"userDecides"`
}

type ModeSignals struct {
	TaskCount       int `json:"taskCount"`
	MaxWaveWidth    int `json:"maxWaveWidth"`
	DistinctRoles   int `json:"distinctRoles"`
	CrossSpecEdges  int `json:"crossSpecEdges"`
	EstimatedTokens int `json:"estimatedTokens"`
}

type NextResult struct {
	Kind     NextResultKind `json:"kind"`
	ID       string         `json:"id,omitempty"`
	Blocked  []string       `json:"blocked,omitempty"`
	Blocking []string       `json:"blocking,omitempty"`
}

type NextResultKind string

type OrchestrationAction string

type OrchestrationAuthoring struct {
	WorkID   string   `json:"workId"`   // reserved authoring ID (A1/A2/A3)
	Artifact string   `json:"artifact"` // e.g. "requirements.md"
	Gate     string   `json:"gate"`     // gate the artifact must clear
	Role     string   `json:"role"`     // worker role for the mission
	Issues   []string `json:"issues"`   // current `specd check`-shaped reasons
}

type OrchestrationCfg struct {
	Enabled                  bool    `json:"enabled"`
	ApprovalPolicy           string  `json:"approvalPolicy"`
	WorkerMode               string  `json:"workerMode"`
	MaxWorkers               int     `json:"maxWorkers"`
	MaxRetries               int     `json:"maxRetries"`
	SessionTimeoutMinutes    int     `json:"sessionTimeoutMinutes"`
	HostReportedCostLimitUSD float64 `json:"hostReportedCostLimitUSD"`
	// CompactionPolicy / CompactionBudgetThreshold drive stage-aware context
	// compaction (none|phase|budget|both; threshold in [0,1]). omitempty keeps
	// pre-compaction config files byte-identical.
	CompactionPolicy          string       `json:"compactionPolicy,omitempty"`
	CompactionBudgetThreshold float64      `json:"compactionBudgetThreshold,omitempty"`
	Transport                 TransportCfg `json:"transport"`
	Program                   ProgramCfg   `json:"program"`
	// Resilience holds opt-in checkpoint/auto-resume policy. Pointer + omitempty
	// keeps existing config.json byte-identical when the block is absent.
	Resilience *ResilienceCfg `json:"resilience,omitempty"`
}

type OrchestrationCheckpointSnapshot struct {
	TaskID          string `json:"taskId"`
	Attempt         int    `json:"attempt"`
	ProgressPercent int    `json:"progressPercent"`
}

type OrchestrationDecision struct {
	Version int                 `json:"version"`
	Action  OrchestrationAction `json:"action"`
	Spec    string              `json:"spec"`
	TaskID  string              `json:"taskId,omitempty"`
	Attempt int                 `json:"attempt,omitempty"`
	// Artifact is set on dispatch-authoring / advance-phase decisions: the
	// planning artifact (e.g. "design.md") the decision concerns.
	Artifact       string                  `json:"artifact,omitempty"`
	Reason         string                  `json:"reason"`
	IdempotencyKey string                  `json:"idempotencyKey"`
	Escalation     OrchestrationEscalation `json:"escalation"`
}

type OrchestrationEscalation struct {
	Code    OrchestrationEscalationCode `json:"code"`
	Message string                      `json:"message"`
}

type OrchestrationEscalationCode string

type OrchestrationFailure struct {
	TaskID    string `json:"taskId"`
	Attempt   int    `json:"attempt"`
	Kind      string `json:"kind"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable"`
}

type OrchestrationLeaseSnapshot struct {
	WorkerID   string `json:"workerId"`
	TaskID     string `json:"taskId"`
	Attempt    int    `json:"attempt"`
	LeaseUntil string `json:"leaseUntil"`
	// Suspended marks a lease that is rate-limited/away but within its resume
	// window (R3). It is still in-flight (counts toward MaxWorkers) but is not a
	// heartbeating active worker. omitempty keeps non-suspended snapshots
	// byte-identical to the pre-resilience shape.
	Suspended bool `json:"suspended,omitempty"`
}

type OrchestrationPolicy struct {
	ApprovalPolicy           string  `json:"approvalPolicy"`
	MaxWorkers               int     `json:"maxWorkers"`
	MaxRetries               int     `json:"maxRetries"`
	SessionTimeoutSeconds    int     `json:"sessionTimeoutSeconds"`
	HostReportedCostLimitUSD float64 `json:"hostReportedCostLimitUSD"`
	// CompactionPolicy selects automatic context compaction: none|phase|budget|
	// both. Empty is treated as none. omitempty keeps existing session.json
	// byte-identical.
	CompactionPolicy string `json:"compactionPolicy,omitempty"`
	// CompactionBudgetThreshold is the fraction of the manifest budget at which
	// budget-driven compaction fires, in [0,1]. omitempty keeps the zero value
	// (no budget trigger) out of byte-stable session.json.
	CompactionBudgetThreshold float64 `json:"compactionBudgetThreshold,omitempty"`
	// CheckpointEnabled mirrors resilience.checkpointEnabled into the policy so
	// the pure (snapshot, policy) decision path can gate resume-from-checkpoint
	// without reading config. omitempty keeps existing session.json byte-stable
	// when the resilience block is absent.
	CheckpointEnabled bool `json:"checkpointEnabled,omitempty"`
}

type OrchestrationSession struct {
	Version      int                        `json:"version"`
	SessionID    string                     `json:"sessionId"`
	Spec         string                     `json:"spec"`
	Owner        string                     `json:"owner"`
	Status       OrchestrationSessionStatus `json:"status"`
	Policy       OrchestrationPolicy        `json:"policy"`
	CreatedAt    string                     `json:"createdAt"`
	UpdatedAt    string                     `json:"updatedAt"`
	ExpiresAt    string                     `json:"expiresAt"`
	LastSequence uint64                     `json:"lastSequence"`
	// ContextLedger is the persistent token-accounting trail (R1). LastCompactionStep
	// is the snapshot revision at which the most recent compaction fired, guarding
	// the phase-boundary trigger from re-emitting. PeakTokens is the high-water mark
	// across estimated and host-reported entries. All omitempty so pre-ledger
	// session.json round-trips byte-identical.
	ContextLedger      []ContextLedgerEntry `json:"contextLedger,omitempty"`
	LastCompactionStep uint64               `json:"lastCompactionStep,omitempty"`
	PeakTokens         int                  `json:"peakTokens,omitempty"`
}

type OrchestrationSessionStatus string

type OrchestrationSnapshot struct {
	Version          int                          `json:"version"`
	SessionID        string                       `json:"sessionId"`
	Spec             string                       `json:"spec"`
	Revision         int                          `json:"revision"`
	Status           SpecStatus                   `json:"status"`
	Phase            Phase                        `json:"phase"`
	Gate             Gate                         `json:"gate"`
	HumanOnlyGate    bool                         `json:"humanOnlyGate"`
	Runnable         []OrchestrationTaskSnapshot  `json:"runnable"`
	ActiveLeases     []OrchestrationLeaseSnapshot `json:"activeLeases"`
	RecentFailures   []OrchestrationFailure       `json:"recentFailures"`
	SessionExpiresAt string                       `json:"sessionExpiresAt"`
	// Authoring is the planning-phase frontier: present when the spec is in a
	// planning status (requirements/design/tasks) and the phase artifact is
	// absent or fails `specd check`. It is the authoring counterpart of
	// Runnable for the execution DAG. PlanningReady is true when the spec is in
	// a planning status and the current artifact already passes its gate (the
	// phase is ready to advance).
	Authoring     *OrchestrationAuthoring `json:"authoring,omitempty"`
	PlanningReady bool                    `json:"planningReady"`
	// AccumulatedCostUSD is the sum of host-reported cost across the session's
	// evidence events. It is hostReported and untrusted — it never gates
	// completion — but it drives the advisory cost-limit escalation (GAP-4).
	AccumulatedCostUSD float64 `json:"accumulatedCostUSD"`
	// SessionExpired is true when the session's fixed wall-clock deadline
	// (session.ExpiresAt, set at start from sessionTimeoutSeconds) has passed.
	// It forces a terminal escalation rather than relying on lease expiry alone.
	SessionExpired bool `json:"sessionExpired"`
	// LastCompactionStep, LedgerEstimatedTokens, and LedgerBudget carry the
	// compaction inputs DecideOrchestration needs without breaking its pure
	// (snapshot, policy) signature: they are read from the persisted session's
	// ledger tail in SenseOrchestration. omitempty keeps snapshots without a
	// session (plain-controller mode) byte-identical to the pre-compaction shape.
	LastCompactionStep    uint64 `json:"lastCompactionStep,omitempty"`
	LedgerEstimatedTokens int    `json:"ledgerEstimatedTokens,omitempty"`
	LedgerBudget          int    `json:"ledgerBudget,omitempty"`
	// Checkpoints carries the mid-task checkpoints that survive on disk for this
	// session, projected so DecideOrchestration can prefer resume-from-checkpoint
	// over a fresh dispatch while staying a pure (snapshot, policy) function.
	// SenseOrchestration populates it only when resilience.checkpointEnabled is
	// set; omitempty keeps snapshots byte-identical to today when the feature is
	// off or no checkpoint exists.
	Checkpoints []OrchestrationCheckpointSnapshot `json:"checkpoints,omitempty"`
	// MostRecentProgressAt is the newest server-side progress-report time among
	// the session's in-flight workers (those holding an active lease). The driver
	// reads it to weight stall waits: a worker progressing within
	// resilience.progressTimeoutSeconds does not advance the consecutive-wait
	// counter (R6). It enters via SenseOrchestration, never via a clock read in
	// the pure decision. omitempty keeps snapshots byte-identical when no in-flight
	// worker has reported.
	MostRecentProgressAt string `json:"mostRecentProgressAt,omitempty"`
}

type OrchestrationStepResult struct {
	Snapshot   OrchestrationSnapshot `json:"snapshot"`
	Decision   OrchestrationDecision `json:"decision"`
	Event      *ACPEnvelope          `json:"event,omitempty"`
	Compaction *CompactionOutcome    `json:"compaction,omitempty"`
}

type OrchestrationTaskSnapshot struct {
	ID       string     `json:"id"`
	Wave     int        `json:"wave"`
	Status   TaskStatus `json:"status"`
	Attempt  int        `json:"attempt"`
	Role     string     `json:"role"`
	Depends  []string   `json:"depends"`
	Verified bool       `json:"verified"`
}

type PRSummary struct {
	Spec       string          `json:"spec"`
	Title      string          `json:"title"`
	Status     string          `json:"status"`
	GatesOK    bool            `json:"gatesOk"`
	TasksDone  int             `json:"tasksDone"`
	TasksTotal int             `json:"tasksTotal"`
	Waves      []PRSummaryWave `json:"waves"`
	Violations []Violation     `json:"violations"`
	Warnings   []Violation     `json:"warnings"`
	Commits    []CommitLink    `json:"commits,omitempty"`
}

type PRSummaryTask struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	Status string `json:"status"`
	Role   string `json:"role"`
}

type PRSummaryWave struct {
	Wave  int             `json:"wave"`
	Tasks []PRSummaryTask `json:"tasks"`
}

type ParsedTask struct {
	ID         string
	Title      string
	Wave       int
	Checked    bool
	Meta       map[string]string
	Annotation *Annotation
	Line       int
}

type ParsedTasks struct {
	Title string
	Tasks []ParsedTask
}

type Phase = spec.Phase

type PhaseCompatibilityMeta struct {
	Statuses []string `json:"statuses,omitempty"`
	Phases   []string `json:"phases,omitempty"`
}

type PinkyBlockerReport struct {
	SessionID string
	WorkerID  string
	Spec      string
	TaskID    string
	Attempt   int
	Reason    string
}

type PinkyClaim struct {
	Mission PinkyMission `json:"mission"`
	Lease   ACPLease     `json:"lease"`
}

type PinkyEvidenceResult struct {
	Event      ACPEnvelope        `json:"event"`
	Completion CompleteTaskResult `json:"completion"`
}

type PinkyInbox struct {
	SessionID  string        `json:"sessionId"`
	WorkerID   string        `json:"workerId"`
	Directives []ACPEnvelope `json:"directives"`
}

type PinkyMission struct {
	Version         int                               `json:"version"`
	SessionID       string                            `json:"sessionId"`
	WorkerID        string                            `json:"workerId"`
	Spec            string                            `json:"spec"`
	TaskID          string                            `json:"taskId"`
	Attempt         int                               `json:"attempt"`
	Deadline        string                            `json:"deadline"`
	HeartbeatEvery  int                               `json:"heartbeatEverySeconds"`
	Role            string                            `json:"role"`
	Title           string                            `json:"title"`
	ContextCommand  string                            `json:"contextCommand"`
	ContextManifest contextpkg.MissionContextManifest `json:"contextManifest"`
	Contract        string                            `json:"contract"`
	Files           []string                          `json:"files"`
	Acceptance      string                            `json:"acceptance"`
	VerifyCommand   string                            `json:"verifyCommand"`
	Dependencies    []string                          `json:"dependencies"`
	Requirements    []int                             `json:"requirements"`
	Authority       ACPAuthority                      `json:"authority"`
	DispatchDigest  string                            `json:"dispatchDigest"`
	// Resume, when present, carries the prior mid-task checkpoint a worker is
	// being handed so it continues from recorded progress instead of restarting
	// (R1, R4). It is omitempty and excluded from the dispatch digest, so a
	// fresh-dispatch and a resume mission for the same (task, attempt) share a
	// digest and a non-resume mission stays byte-identical to today.
	Resume *PinkyResume `json:"resume,omitempty"`
}

type PinkyProgressReport struct {
	SessionID string
	WorkerID  string
	Spec      string
	TaskID    string
	Attempt   int
	Percent   int
	Message   string
}

type PinkyQueryReport struct {
	SessionID string
	WorkerID  string
	Spec      string
	TaskID    string
	Attempt   int
	Text      string
}

type PinkyResume struct {
	ProgressPercent int      `json:"progressPercent"`
	WorkingNotes    string   `json:"workingNotes,omitempty"`
	ChangedFiles    []string `json:"changedFiles,omitempty"`
	GitHead         string   `json:"gitHead,omitempty"`
	PriorManifest   string   `json:"priorManifest,omitempty"`
	// ContextDelta, when present, is the per-file reference/reload verdict from
	// diffing the latest context snapshot against the working tree (R2). It lets
	// the resumed worker reload only what changed. nil when snapshots are off or
	// none exist, so a resume without snapshots renders identically to before.
	ContextDelta *contextpkg.SnapshotDiff `json:"contextDelta,omitempty"`
}

type PinkyTerminalReport struct {
	SessionID       string
	WorkerID        string
	Spec            string
	TaskID          string
	Attempt         int
	VerificationRef string
	Summary         string
	ChangedFiles    []string
	GitHead         string
	DurationMs      int64
	HostTokens      int
	HostCost        string
}

type PositionalMeta struct {
	Name        string `json:"name"`
	Required    bool   `json:"required"`
	Repeatable  bool   `json:"repeatable,omitempty"`
	Description string `json:"description,omitempty"`
}

type PreflightItem struct {
	Kind    string `json:"kind"`    // "workspace" | "steering" | "spec"
	Message string `json:"message"` // human-readable reason
	Remedy  string `json:"remedy"`  // the `specd` command that fixes it
}

type ProgramCfg struct {
	MaxConcurrentSpecs int `json:"maxConcurrentSpecs"`
}

type ProgramChildLease struct {
	Version         int                     `json:"version"`
	ParentSessionID string                  `json:"parentSessionId"`
	ChildSessionID  string                  `json:"childSessionId"`
	Slug            string                  `json:"slug"`
	Status          ProgramChildLeaseStatus `json:"status"`
	AcquiredAt      string                  `json:"acquiredAt"`
	LeaseUntil      string                  `json:"leaseUntil"`
	ReleasedAt      string                  `json:"releasedAt,omitempty"`
	EscalatedAt     string                  `json:"escalatedAt,omitempty"`
}

type ProgramChildLeaseStatus string

type ProgramChildRuntime struct {
	Active         bool
	Escalated      bool
	ChildSessionID string
}

type ProgramChildSnapshot struct {
	Slug           string     `json:"slug"`
	Status         SpecStatus `json:"status"`
	Wave           int        `json:"wave"`
	Depends        []string   `json:"depends"`
	Complete       bool       `json:"complete"`
	Blocked        bool       `json:"blocked"`
	Active         bool       `json:"active"`
	Escalated      bool       `json:"escalated"`
	ChildSessionID string     `json:"childSessionId,omitempty"`
}

type ProgramChildStep struct {
	Slug      string                  `json:"slug"`
	SessionID string                  `json:"sessionId"`
	Result    OrchestrationStepResult `json:"result"`
}

type ProgramCounts struct {
	Total     int `json:"total"`
	Complete  int `json:"complete"`
	Active    int `json:"active"`
	Blocked   int `json:"blocked"`
	Escalated int `json:"escalated"`
}

type ProgramDecision struct {
	Version int                   `json:"version"`
	Action  ProgramDecisionAction `json:"action"`
	Specs   []string              `json:"specs,omitempty"`
	Reason  string                `json:"reason"`
}

type ProgramDecisionAction string

type ProgramDriverDispatch struct {
	Slug           string
	ChildSessionID string
	Dispatch       DriverDispatch
}

type ProgramDriverOptions struct {
	MaxSteps int
	MaxWaits int
	Worker   func(ProgramDriverDispatch) error
	Observer DriverObserver
}

type ProgramDriverResult struct {
	Steps   int             `json:"steps"`
	Outcome DriverOutcome   `json:"outcome"`
	Final   ProgramDecision `json:"final"`
}

type ProgramGraph struct {
	Specs   []SpecNode
	Dag     []DagTask
	Orphans []struct{ Spec, Dep string }
	Cycle   []string
}

type ProgramManifest struct {
	Version   int                 `json:"version"`
	DependsOn map[string][]string `json:"dependsOn"`
}

type ProgramSession struct {
	Version         int                        `json:"version"`
	ParentSessionID string                     `json:"parentSessionId"`
	Status          OrchestrationSessionStatus `json:"status"`
	CreatedAt       string                     `json:"createdAt"`
	UpdatedAt       string                     `json:"updatedAt"`
}

type ProgramSnapshot struct {
	Version      int                          `json:"version"`
	Children     []ProgramChildSnapshot       `json:"children"`
	Capacity     int                          `json:"capacity"`
	ActiveCount  int                          `json:"activeCount"`
	Cycle        []string                     `json:"cycle"`
	Orphans      []struct{ Spec, Dep string } `json:"orphans"`
	CriticalPath []string                     `json:"criticalPath"`
}

type ProgramState struct {
	Version         int                   `json:"version"`
	ParentSessionID string                `json:"parentSessionId"`
	ChildSessions   map[string]string     `json:"childSessions"`
	InflightKeys    []string              `json:"inflightKeys"`
	ChildStatus     map[string]SpecStatus `json:"childStatus"`
	UpdatedAt       string                `json:"updatedAt"`
}

type ProgramStatusReport struct {
	Session    ProgramSession       `json:"session"`
	Snapshot   ProgramSnapshot      `json:"snapshot"`
	Decision   ProgramDecision      `json:"decision"`
	Counts     ProgramCounts        `json:"counts"`
	Frontier   []string             `json:"frontier"`
	Waves      []ProgramWaveSummary `json:"waves"`
	Escalation []string             `json:"escalation"`
}

type ProgramStepResult struct {
	Snapshot ProgramSnapshot     `json:"snapshot"`
	Decision ProgramDecision     `json:"decision"`
	Started  []ProgramChildLease `json:"started"`
	Stepped  []ProgramChildStep  `json:"stepped"`
	Leases   []ProgramChildLease `json:"leases"`
}

type ProgramWaveSummary struct {
	Wave     int      `json:"wave"`
	Specs    []string `json:"specs"`
	Complete int      `json:"complete"`
	Active   int      `json:"active"`
}

type ReportCfg struct {
	Format             string `json:"format"`
	AutoRefreshSeconds int    `json:"autoRefreshSeconds"`
}

type ReportData struct {
	State        *State
	Requirements *string
	Design       *string
	Tasks        *string
	Decisions    *string
	Memory       *string
	MidReqs      *string
}

type ResilienceCfg struct {
	// CheckpointEnabled gates proactive checkpoint/resume behavior (R1, R4).
	CheckpointEnabled bool          `json:"checkpointEnabled,omitempty"`
	AutoResume        AutoResumeCfg `json:"autoResume,omitempty"`
	// MaxSuspendSeconds caps the cumulative time a worker may keep a task
	// suspended (rate-limited) before it is treated as dead (R3). 0 = use the
	// built-in default (600s); omitempty keeps configs without the field
	// byte-identical.
	MaxSuspendSeconds int `json:"maxSuspendSeconds,omitempty"`
	// ContextSnapshotEnabled gates per-turn context-snapshot writing (R2).
	// Default false; omitempty keeps configs without the field byte-identical.
	ContextSnapshotEnabled bool `json:"contextSnapshotEnabled,omitempty"`
	// ProgressTimeoutSeconds is the window within which an in-flight worker's
	// last progress report keeps a driver wait from counting toward the stall
	// limit (R6). Recommended 300. 0/unset disables progress weighting, keeping
	// today's behavior; omitempty keeps configs without the field byte-identical.
	ProgressTimeoutSeconds int `json:"progressTimeoutSeconds,omitempty"`
}

type ResumableSession struct {
	SessionID    string                     `json:"sessionID"`
	Spec         string                     `json:"spec"`
	Status       OrchestrationSessionStatus `json:"status"`
	UpdatedAt    string                     `json:"updatedAt"`
	PausedSince  string                     `json:"pausedSince,omitempty"`
	LastDecision string                     `json:"lastDecision,omitempty"`
	// Program marks a program-parent session: one that orchestrates a DAG of
	// child specs and must be resumed via `brain resume --program`, not the
	// single-spec path (cross-spec recovery). ChildrenComplete/ChildrenTotal give
	// the host the parent's frontier progress at a glance. omitempty keeps
	// single-spec entries byte-identical to the pre-program shape.
	Program          bool `json:"program,omitempty"`
	ChildrenComplete int  `json:"childrenComplete,omitempty"`
	ChildrenTotal    int  `json:"childrenTotal,omitempty"`
}

type RolesCfg struct {
	SubagentMode string `json:"subagentMode"`
}

type ScaffoldAsset struct {
	Template string         `json:"template"`
	Target   string         `json:"target"`
	Policy   ScaffoldPolicy `json:"policy"`
	Required bool           `json:"required"`
	Refresh  bool           `json:"refresh"`
}

type ScaffoldPolicy string

type SessionTimelineEvent struct {
	At         string `json:"at,omitempty"`
	Sequence   uint64 `json:"sequence"`
	Type       string `json:"type"`
	Spec       string `json:"spec,omitempty"`
	Task       string `json:"task,omitempty"`
	Action     string `json:"action,omitempty"`
	Reason     string `json:"reason,omitempty"`
	Escalation string `json:"escalation,omitempty"`
	Detail     string `json:"detail,omitempty"`
}