runview

type AlertSettings struct {
	// WebhookURL targets a generic incoming webhook (Slack/Discord
	// shape). Empty disables webhook delivery. Treated as a secret.
	WebhookURL string
	// StallTimeout is the no-activity window for stall alerts. Zero or
	// negative disables stall detection; the caller resolves the default.
	StallTimeout time.Duration
	// BaseURL is the origin used to build /runs/<id> deep links.
	BaseURL string
	// DesktopSink, when non-nil, is added as an extra sink — the desktop
	// app injects a Wails EventsEmit sink here for in-window
	// notifications. Nil in headless server / browser-only mode.
	DesktopSink alert.Sink
}

type AnswerInteractionResult struct {
	RunID         string `json:"run_id"`
	InteractionID string `json:"interaction_id"`
	// Queued is true when the answer was queued for mid-run delivery to
	// the asking node (the run keeps executing).
	Queued bool `json:"queued"`
	// Resumed is true when this answer completed the pending set of an
	// await-paused run and the run was auto-resumed.
	Resumed bool `json:"resumed"`
}

type ArtifactSummary struct {
	Version   int       `json:"version"`
	WrittenAt time.Time `json:"written_at"`
}

type BackendUsage struct {
	Backend   string `json:"backend"`
	Model     string `json:"model,omitempty"`
	NodeCount int    `json:"node_count"`
}

type BumpLoopRequest struct {
	LoopName string `json:"loop_name"`
	Delta    int    `json:"delta"`
	// IssuedBy names the operator for the persisted run_steered event
	// (filled by the HTTP layer from the authenticated identity).
	IssuedBy string `json:"-"`
}

type BumpLoopResponse struct {
	RunID        string `json:"run_id"`
	Loop         string `json:"loop"`
	Delta        int    `json:"delta,omitempty"`
	Extra        int    `json:"extra,omitempty"`
	EffectiveMax int    `json:"effective_max,omitempty"`
	Current      int    `json:"current_iteration"`
	Noop         bool   `json:"noop,omitempty"`
	NoopReason   string `json:"noop_reason,omitempty"`
	// Warning surfaces a non-fatal degradation (applied in-memory but
	// not persisted — a resume would lose the grant).
	Warning string `json:"warning,omitempty"`
}

type BundleSkill struct {
	// Name is the skill identifier — the SKILL.md basename without
	// extension, OR the `name:` frontmatter field when present.
	Name string `json:"name"`
	// Description is the one-line summary parsed from the SKILL.md
	// frontmatter's `description:` field. Empty when the file has no
	// frontmatter (rare) or the field is absent.
	Description string `json:"description,omitempty"`
	// Path is the skill's path relative to the bundle's skills/
	// directory. For a top-level SKILL.md it's just the filename;
	// for skill directories it's the directory name (the SDK reads
	// `<dir>/SKILL.md` inside).
	Path string `json:"path"`
}

type CommitAndFinalizeResponse struct {
	RunID         string              `json:"run_id"`
	FinalCommit   string              `json:"final_commit"`
	FinalBranch   string              `json:"final_branch"`
	MergeStatus   store.MergeStatus   `json:"merge_status"`
	MergedInto    string              `json:"merged_into,omitempty"`
	MergedCommit  string              `json:"merged_commit,omitempty"`
	MergeStrategy store.MergeStrategy `json:"merge_strategy,omitempty"`
	// SourceIssueID is set when the run was dispatcher-spawned. The HTTP
	// handler reads it to fire the merged-issue auto-transition when an
	// auto-FF landed the merge inside finalize (MergeStatus="merged"),
	// without a second LoadRun round-trip. Internal-only — omitted from
	// the JSON wire.
	SourceIssueID string `json:"-"`
}

type DeploymentReport struct {
	// NodeID is the IR node that reported the delivery, so the operator
	// can jump to its output. Empty only for hand-built values.
	NodeID string `json:"node_id,omitempty"`
	// Deployed is the reporting node's claim that the deploy applied.
	Deployed bool `json:"deployed"`
	// Healthy is its claim that the deployed URL answers healthily.
	Healthy bool `json:"healthy"`
	// URL is the public address a human opens. Empty on a failed or
	// blocked deploy — a truthful blocker, never a guessed URL.
	URL string `json:"url,omitempty"`
	// ImageRef is the exact image reference running, e.g.
	// "ghcr.io/owner/repo:<sha>". Empty when none was reported.
	ImageRef string `json:"image_ref,omitempty"`
	// Commit is the source commit the delivery is anchored to (the one
	// the image is expected to name). Empty when the reporter did not
	// state it — the studio then shows no commit rather than borrowing
	// the run's final_commit, which can be a LATER commit than the one
	// deployed.
	Commit string `json:"commit,omitempty"`
	// Notes is the reporter's own prose: what was published, or the
	// concrete blocking error.
	Notes string `json:"notes,omitempty"`
	// Trace is the traceability verdict. Nil when no node ran a
	// traceability gate at all — a distinct fact from a gate that ran
	// and could not establish the facts (Trace.Verifiable == false).
	Trace *DeploymentTrace `json:"trace,omitempty"`
}

type DeploymentTrace struct {
	NodeID string `json:"node_id,omitempty"`
	// Verifiable reports whether the gate could establish the facts.
	// When false, the three booleans below carry no information.
	Verifiable bool `json:"verifiable"`
	// Pushed: the deployed commits are reachable from a remote branch.
	Pushed bool `json:"pushed"`
	// ImageFromRepo: the running image is published under this repo's
	// own registry path (not a stock base image).
	ImageFromRepo bool `json:"image_from_repo"`
	// BuiltFromHead: the image reference names the pushed commit, which
	// is what ties the running artifact to reviewable source.
	BuiltFromHead bool `json:"built_from_head"`
	// Log is the gate's own explanation — the remedy on a failure, the
	// environment fault when unverifiable.
	Log string `json:"log,omitempty"`
}

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

type EventSubscription struct {
	C <-chan *store.Event
	// contains filtered or unexported fields
}

type ExecStatus string

type ExecutionState struct {
	ExecutionID         string     `json:"execution_id"`
	IRNodeID            string     `json:"ir_node_id"`
	BranchID            string     `json:"branch_id"`
	LoopIteration       int        `json:"loop_iteration"`
	Status              ExecStatus `json:"status"`
	Kind                string     `json:"kind,omitempty"` // node kind (Agent / Judge / Router / ...)
	StartedAt           *time.Time `json:"started_at,omitempty"`
	FinishedAt          *time.Time `json:"finished_at,omitempty"`
	LastArtifactVersion *int       `json:"last_artifact_version,omitempty"`
	CurrentEventSeq     int64      `json:"current_event_seq"`
	Error               string     `json:"error,omitempty"`
	// FirstSeq / LastSeq mark the persisted event range that produced
	// this execution row, allowing clients to scrub directly to the
	// segment of events.jsonl describing this execution.
	FirstSeq int64 `json:"first_seq"`
	LastSeq  int64 `json:"last_seq"`
}

type ExecutorSpec struct {
	// Ctx is captured by the store-backed event hooks for AppendEvent
	// calls during execution. Filesystem stores ignore it; cloud
	// (Mongo) stores honor it for cancellation/timeout.
	Ctx      context.Context
	Workflow *ir.Workflow
	Vars     map[string]string
	Store    model.EventEmitter // typically *store.RunStore
	RunID    string
	Logger   *iterlog.Logger
	StoreDir string
	// SourceIssueID is the ticket that owns this run (dispatcher / pipeline
	// launch). Empty for ad-hoc runs. Used to auto-stamp parent_id when the
	// bot creates child tickets via board.create.
	SourceIssueID string
	// ExtraHooks are merged into the store-backed event hooks. Pass
	// the prometheus exporter's hooks here (cli does this); the HTTP
	// service can pass nothing or a future broker-side hook chain.
	ExtraHooks []model.EventHooks
	// EventObservers (ADR-046) fire on every event the backend-hook
	// layer persists — the stall-heartbeat seam for high-frequency tool
	// events that bypass the runtime engine's WithEventObserver. The
	// dispatcher-via-service path sets these so it can observe the same
	// store-level event stream the direct path's heartbeatStore saw,
	// WITHOUT wrapping the store (which would shadow its optional
	// capabilities — PlanWriter / RunFilesStore / … — against the probes
	// below). Engine-level events reach the same observers through
	// runtime.WithEventObserver; the two event sets are disjoint.
	EventObservers []func(store.Event)
	// Inbox, when non-nil, wires the operator chatbox plumbing into
	// the claw backend so queued messages are delivered between
	// agent-loop iterations. Nil disables the inbox (CLI mode +
	// runs that opted out).
	Inbox model.InboxBinder
	// AsyncAsk, when non-nil, backs the ask_user_async / await_answers
	// tools of interaction: async nodes (ADR-081). Nil = the tools
	// error explicitly if a node resolves them.
	AsyncAsk model.AsyncAskBinder
	// Backend, when non-empty, takes precedence over the workflow's
	// `default_backend:` for this run only. Node-level explicit
	// `backend:` still wins (it's the most specific level in the
	// resolution chain). Used by the studio launch UI to A/B a
	// workflow against different backends without editing the .bot.
	Backend string
	// ModelOverrides are launch-time per-node/-group backend+model+provider
	// overrides (studio Launch dropdowns, CLI --model/--backend selector=spec).
	// Unlike Backend (a run-level default below node DSL), these target nodes
	// explicitly and win over the node's DSL backend:/model:, so a run can
	// re-target the bot per node-group without editing the .bot. Empty = no-op.
	ModelOverrides model.ModelOverrides
	// BotID is the stable bundle/bot identifier used to qualify
	// structured visibility=bot memory. Empty falls back to Workflow.Name.
	BotID string
	// MemoryStore overrides the workspace-memory backend. nil → the
	// local filesystem store. Cloud runners pass the Mongo store so
	// shared knowledge persists in the tenant's document store.
	MemoryStore knowledge.MemoryStore
	// BoardRegister mints a per-node board MCP run token (C082, server
	// path): it registers the node's board caps with the server's token
	// registry and returns the token. nil (CLI) leaves sandboxed
	// board-emit disabled.
	BoardRegister func(caps []string, sourceIssueID string) string
	// Compress is the run-level command-output-compression override ("",
	// "on", "ultra", "off"), forwarded to the executor as the highest-priority
	// input to rewrite.Resolve (above node/workflow DSL and ITERION_COMPRESS).
	Compress string

	// Permission is the run-level tool-permission-gate mode override
	// ("", "off", "ask", "deny"), highest-priority input to the gate's
	// mode precedence (above node/workflow DSL and ITERION_PERMISSION).
	// PermissionAllow/Ask/Deny are run-level rules, additive to the
	// workflow lists. See docs/permissions.md.
	Permission      string
	PermissionAllow []string
	PermissionAsk   []string
	PermissionDeny  []string

	// LocalSecrets + LocalSealer are the local (desktop / CLI / non-cloud
	// studio) secret store and its AES-GCM sealer. When both are set and the
	// ctx does not already carry resolved Credentials (the cloud runner path),
	// BuildExecutor resolves the workflow's declared `secrets:` names from the
	// store and stamps them into ctx via secrets.WithCredentials — the
	// in-process equivalent of the cloud runner's injectCredentials. Nil on
	// the cloud path (credentials arrive pre-resolved in ctx).
	LocalSecrets secrets.GenericSecretStore
	LocalSealer  secrets.Sealer
}

type ForkResult struct {
	NewRunID    string            `json:"new_run_id"`
	ParentRunID string            `json:"parent_run_id"`
	ForkAnchor  *store.ForkAnchor `json:"fork_anchor,omitempty"`
}

type ForkSpec struct {
	// RunID is the parent run to fork from.
	RunID string
	// NodeID identifies the anchor node (i.e. the node the new run
	// will re-execute from). Required.
	NodeID string
	// TurnIndex selects the per-(node, iter) turn checkpoint to
	// rehydrate from. Negative means "latest available turn for this
	// node". For claude_code the index is always 0 (one TurnCheckpoint
	// per delegate call).
	TurnIndex int
	// RewindCode controls the worktree state of the child run:
	//   - false (default): the child's worktree starts at the parent's
	//     current HEAD (inherit current files).
	//   - true: the child's worktree is reset to the snapshot ref
	//     recorded at (NodeID, iter) — `git reset --hard` semantics
	//     against the per-node snapshot.
	// Phase 2 wires per-node refs; per-turn refs are a Phase 5 polish.
	RewindCode bool
	// ForkName, when non-empty, overrides the auto-generated child
	// name. Cosmetic — the child's id is always a fresh UUID.
	ForkName string
	// NewInputs, when non-nil, replaces the child run's Inputs map
	// (merged onto the parent's). Useful for "fork with a different
	// prompt vars" workflows from the studio's ForkDialog JSON editor.
	NewInputs map[string]any
}

type HandleSnapshot struct {
	RunID  string
	Cancel context.CancelFunc
	Done   <-chan struct{}
	PID    int // 0 for in-process; >0 for detached subprocess
}

type LaunchPublisher interface {
	// SubmitLaunch persists the run as queued in the cloud store
	// and publishes a RunMessage. Returns the 1-based queue position
	// at submission time.
	SubmitLaunch(ctx context.Context, runID string, spec LaunchSpec, wf *ir.Workflow, hash string) (int, error)
	// CancelRun signals the runner pool to abort the run. Idempotent —
	// flips the Mongo doc to cancelled regardless of whether a runner
	// is currently holding the lease.
	CancelRun(ctx context.Context, runID string) error
	// SubmitResume republishes a RunMessage with ResumeSpec set so
	// the runner picks the run back up.
	SubmitResume(ctx context.Context, spec ResumeSpec, wf *ir.Workflow, hash string) error
}

type LaunchResult struct {
	RunID string
	// Done is closed when the run goroutine exits (success or
	// failure). Callers that want to wait can `<-result.Done`. Cloud-
	// mode launches return a Done channel that is already closed —
	// the runner pod owns the lifecycle, not this server.
	Done <-chan struct{}
	// QueuePosition is the 1-based position on the cloud queue at
	// the moment of submission. Zero when launching in-process.
	QueuePosition int
}

type LaunchSpec struct {
	FilePath string // absolute .bot path; sandbox check is the caller's job
	// Source carries the .bot source verbatim. Used by cloud-mode
	// callers when the server pod has no local copy of the workflow
	// (the studio SPA uploads the source inline). When non-empty it
	// takes precedence over FilePath for parsing; FilePath is still
	// retained for display and for the runner to recompile against
	// the same logical workflow.
	Source string
	Vars   map[string]string // --var-style overrides
	// Preset is the name of an in-source preset (presets: block) to
	// apply before Vars. Unknown name → launch error. Empty means no
	// preset.
	Preset  string
	RunID   string        // optional explicit ID; auto-generated when empty
	Timeout time.Duration // 0 disables
	// MergeInto controls the worktree-finalization fast-forward target
	// for `worktree: auto` runs. "" or "current" → FF the user's
	// currently-checked-out branch (default); "none" → skip FF;
	// <branch-name> → FF that branch (only honoured when it matches
	// the currently-checked-out branch).
	MergeInto string
	// BranchName overrides the default storage branch
	// `iterion/run/<friendly>` created on the worktree's HEAD.
	BranchName string
	// MergeStrategy selects how the run's commits are landed on the
	// merge target: "squash" (default — collapse into one commit) or
	// "merge" (fast-forward, preserve history). Persisted on run.json
	// so the deferred-merge UI can pre-fill the same choice.
	MergeStrategy store.MergeStrategy
	// AutoMerge captures the launch-time intent. When true, the engine
	// applies MergeStrategy synchronously at end of run; when false the
	// engine creates the storage branch only and leaves merge_status
	// pending for the UI to drive via POST /api/runs/{id}/merge.
	AutoMerge bool
	// AttachmentPromote, when set, is invoked after CreateRun and
	// before the engine starts. It is expected to materialise every
	// attachment declared in `attachments:` into the run-scoped store
	// (typically by promoting uploads from a staging area). Errors
	// abort the launch.
	AttachmentPromote runtime.AttachmentPromoteFunc
	// Backend, when non-empty, overrides the workflow's `default_backend:`
	// for this run. Node-level explicit `backend:` declarations still
	// win — this is a soft default override, not a hard force. Empty
	// preserves the resolver chain. NOTE: the detached runner path
	// (ITERION_RUNS_DETACHED=1) does not yet honor this field; the
	// service layer logs a warning and ignores it there.
	Backend string
	// Compress is the run-level command-output-compression override
	// ("", "on", "ultra", "off") from the studio Launch toggle. ""
	// inherits the workflow/node `compress:` DSL then ITERION_COMPRESS. Highest
	// priority input to rewrite.Resolve. See docs/plugins.md.
	Compress string
	// Permission is the run-level tool-permission-gate mode override
	// ("", "off", "ask", "deny") from the studio Launch toggle. ""
	// inherits the workflow/node `permission:` DSL then
	// ITERION_PERMISSION. See docs/permissions.md.
	Permission string
	// ReviewMode is the run-level mono/dual review-topology override
	// ("", "auto", "mono", "dual") from the studio Launch toggle /
	// dispatcher. Only affects bots that declare a review_mode var. ""
	// / "auto" resolves from detected provider credentials at launch;
	// "mono"/"dual" force it. See pkg/reviewtopology.
	ReviewMode string
	// ModelOverrides are launch-time per-node/-group backend+model overrides
	// (studio Launch dropdowns). Each entry targets nodes by selector (node id,
	// id glob, or kind keyword agent|judge) and wins over the node's DSL
	// backend:/model:. Empty applies nothing. Composes with ReviewMode. See
	// model_override.go.
	ModelOverrides []ModelOverrideEntry
	// Budget carries launch-time budget-cap overrides for the workflow's
	// `budget:` block — the HTTP equivalent of the CLI --max-cost-usd /
	// --max-tokens / --max-duration / --max-iterations /
	// --max-parallel-branches flags. Applied to the compiled workflow after
	// recipe/preset resolution and before the executor snapshots Budget
	// (non-zero field wins, zero inherits — see ir.ApplyBudgetOverrides).
	// The detached path forwards it as the CLI flags; the queued cloud path
	// does not support it yet and rejects a non-zero Budget explicitly.
	Budget *ir.BudgetOverrides
	// ParentRunID, ShardIndex, ShardCount, ShardLabel are set when a
	// parent run dispatches this as a shard child (see Cap. 3 in
	// docs/security-bots-distributed.md). The cloudpublisher copies
	// them onto the persisted Run document AND onto the published
	// RunMessage so the runner pod that picks up the work knows it's
	// part of a sharded set.
	ParentRunID string
	ShardIndex  int
	ShardCount  int
	ShardLabel  string
	// CallbackURL, when set, is an http/https endpoint the engine POSTs
	// a run-completion webhook to when the run terminates (see
	// pkg/notify). Lets a programmatic caller (chat adapter, CI bridge)
	// be told the run finished without polling. Empty for CLI / studio.
	CallbackURL string
	// CallbackToken is an opaque value echoed back verbatim in the
	// completion payload so the receiver can correlate the callback to
	// the originating request (e.g. a chat thread id) without state.
	CallbackToken string
	// CallbackAnswerNode optionally names the node whose latest artifact
	// holds the run's user-facing answer (the "final_answer" field).
	// Empty → the notifier scans all artifact nodes for "final_answer".
	CallbackAnswerNode string
	// RepoURL / RepoRef, when set, propagate onto the published
	// RunMessage so a cloud runner clones the repo before sandboxing.
	// Used by webhook-launched runs (inbound MR review) where the
	// operator has no local checkout.
	RepoURL string
	RepoRef string
	// ProjectPath is the stable forge slug ("group/project") the run
	// targets, persisted on the run so the studio can filter/group runs
	// by repository. Set by inbound-webhook launches; empty otherwise.
	ProjectPath string
	// BotID is the bot bundle name (e.g. "review-pr") this run launches.
	// The cloud publisher uses it to resolve bot-secret bindings during
	// credential sealing. Empty for plain .bot launches.
	BotID string
	// KeyOverrides pins a specific BYOK key per LLM provider for this run
	// (provider name → api_key id), overriding the org/user default in
	// secrets.Resolve. Set by webhook launches that carry per-webhook key
	// bindings; empty for normal launches. See docs/byok.md.
	KeyOverrides map[string]string
	// SecretOverrides pins a stored secret per workflow-secret name (name ->
	// secret id) for this run, overriding the org bot-secret binding. Set by
	// webhook launches carrying per-webhook secret bindings. See docs/byok.md.
	SecretOverrides map[string]string

	// WorkDir overrides the service-level working directory for this launch
	// (runtime.WithWorkDir). The dispatcher sets it to the per-issue isolated
	// worktree so `${PROJECT_DIR}` in bot var defaults expands to that
	// worktree, not the daemon's cwd. Empty inherits WithWorkDir.
	WorkDir string
	// ExtraObservers are per-launch event observers fired on EVERY run
	// event — both the engine-level events runtime.WithEventObserver sees
	// AND the high-frequency tool_started/tool_called events the backend
	// hook layer emits (which bypass the engine callback) — matching the
	// dispatcher's stall-heartbeat semantics. The dispatcher wires one that
	// advances its last-event watermark for stall detection. Empty adds
	// none. Delivered through TWO disjoint seams — runtime.WithEventObserver
	// for engine events + ExecutorSpec.EventObservers for backend-hook
	// events — so no store wrapper is interposed (a wrapper would shadow the
	// store's optional capabilities against the executor/sandbox type-probes;
	// ADR-046).
	ExtraObservers []func(store.Event)
	// DailyCap, when non-nil, overrides the service-level per-(store, UTC-day)
	// spend-cap guard for this launch (runtime.WithDailyCap). The dispatcher
	// builds it from its SINGLETON SpendStore so every concurrent dispatched
	// run writes the one ledger, serialising on a single mutex. Nil inherits
	// the service's dailyCap.
	DailyCap *runtime.DailyCapGuard
	// SourceRef stamps who originated this run onto the run record
	// (runtime.WithSource); the studio RunHeader links back to it. The
	// dispatcher sets it to the kanban issue that triggered the dispatch. Nil
	// leaves Source unset (CLI / studio / fork launches).
	SourceRef *store.RunSource
	// OnOutcome, when set, is invoked once with the run's terminal Go error
	// (nil on success, runtime.ErrRunPaused/ErrRunPausedOperator on a pause,
	// the failure error otherwise) just before the run goroutine closes
	// LaunchResult.Done. It is the return-path completion of the four data
	// fields above: a blocking caller (the dispatcher's EngineRunner routing
	// through this launch authority) reads the SAME typed error the direct
	// engine.Run would have returned, so its retry / park / sandbox-backoff
	// logic stays byte-identical. Nil for fire-and-forget CLI / studio /
	// webhook launches. Not honoured on the cloud-queue or detached paths.
	OnOutcome func(error)
}

type ListFilter struct {
	Status   store.RunStatus // exact match
	Workflow string          // exact match on WorkflowName
	Repo     string          // exact match on ProjectPath (cloud repo slug)
	// Bundle filters runs to those whose resolved bundle name (persisted
	// BundleName, falling back to basename(BundlePath) minus ".botz" —
	// see resolveBundleName) matches case-insensitively. Wire name: ?bot=.
	Bundle string
	Since  time.Time // UpdatedAt >= Since
	Limit  int       // 0 = no limit
	// Node filters runs to those whose persisted events include at
	// least one node_started for this IR node ID. Used by the studio
	// to surface "this node was touched by N runs" without scanning
	// every run on the client. Scanning happens at request time —
	// fine for hundreds of runs; wire an inverted index later if the
	// store grows past low thousands.
	Node string
}

type LogSlice struct {
	BestEffort bool      `json:"best_effort"`
	StartTime  time.Time `json:"start_time"`
	EndTime    time.Time `json:"end_time"`
	StartByte  int64     `json:"start_byte,omitempty"`
	EndByte    int64     `json:"end_byte,omitempty"`
	Truncated  bool      `json:"truncated,omitempty"`
	Notes      []string  `json:"notes,omitempty"`
	Body       string    `json:"body,omitempty"`
}

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

type MergeConflictsResponse struct {
	Files []runtime.ConflictFile `json:"files"`
	// PendingMessage is the squash commit message that was passed to
	// the original merge attempt — preserved so the finalize path can
	// reuse it without recomputing (the user can still override).
	PendingMessage string `json:"pending_message,omitempty"`
	// PendingMergeInto is the target branch the original merge
	// targeted; finalize must run with the same target.
	PendingMergeInto string `json:"pending_merge_into,omitempty"`
}

type MergeRequest struct {
	// Strategy is "squash" (default when empty) or "merge".
	Strategy store.MergeStrategy
	// MergeInto is the target branch override:
	//   ""        → currently-checked-out branch (default)
	//   "current" → same as default
	//   <branch>  → that branch (must equal currently-checked-out)
	MergeInto string
	// CommitMessage overrides the squash commit message. Ignored for
	// "merge" strategy. Empty falls back to a generated message that
	// lists each squashed commit.
	CommitMessage string
}

type MergeResponse struct {
	MergedCommit  string              `json:"merged_commit"`
	MergedInto    string              `json:"merged_into"`
	MergeStrategy store.MergeStrategy `json:"merge_strategy"`
	MergeStatus   store.MergeStatus   `json:"merge_status"`
	// SourceIssueID is set when the run was dispatcher-spawned (i.e.
	// Run.Source is non-nil). The HTTP handler reads it to fire the
	// post-merge auto-transition without a second LoadRun round-trip.
	// Internal-only — omitted from the JSON wire.
	SourceIssueID string `json:"-"`
}

type ModelOverrideEntry struct {
	Selector string `json:"selector"`
	Backend  string `json:"backend,omitempty"`
	Model    string `json:"model,omitempty"`
	Provider string `json:"provider,omitempty"`
}

type PipelineConcurrencyStatus struct {
	// Enabled is true when a finite cap is configured. When false the
	// other fields are zero and the board's TODO lane only holds
	// not-yet-launched native tasks.
	Enabled bool `json:"enabled"`
	Max     int  `json:"max"`
	Active  int  `json:"active"`
	Waiting int  `json:"waiting"`
}

type QueueMessageOption func(*queueMessageConfig)

type RaiseBudgetRequest struct {
	Budget   ir.BudgetOverrides `json:"budget"`
	IssuedBy string             `json:"-"`
}

type RaiseBudgetResponse struct {
	RunID      string         `json:"run_id"`
	Applied    map[string]any `json:"applied,omitempty"`
	Effective  map[string]any `json:"effective,omitempty"`
	Noop       bool           `json:"noop,omitempty"`
	NoopReason string         `json:"noop_reason,omitempty"`
	Warning    string         `json:"warning,omitempty"`
}

type ResumeSpec struct {
	RunID    string
	FilePath string // .bot file (loaded fresh; must match the run's WorkflowHash unless Force)
	// Source mirrors LaunchSpec.Source: cloud-mode callers can supply
	// the .bot contents inline so the server pod does not need to
	// resolve FilePath against a local filesystem.
	Source  string
	Answers map[string]any // answers for human nodes; ignored for failed_resumable
	Force   bool           // skip workflow hash check
	Timeout time.Duration  // 0 disables
}

type RunArtifactSummary struct {
	NodeID    string    `json:"node_id"`
	Version   int       `json:"version"`
	Labels    []string  `json:"labels,omitempty"`
	Title     string    `json:"title,omitempty"`
	WrittenAt time.Time `json:"written_at"`
}

type RunHeader struct {
	ID string `json:"id"`
	// Name is the deterministic, human-friendly label for the run.
	// Empty for legacy runs persisted before this field existed.
	Name         string `json:"name,omitempty"`
	WorkflowName string `json:"workflow_name"`
	WorkflowHash string `json:"workflow_hash,omitempty"`
	FilePath     string `json:"file_path,omitempty"`
	// BundleName mirrors the .botz manifest's `name` field captured
	// at launch (e.g. "feature-dev"). The studio RunHeader pairs it
	// with WorkflowName so the operator can distinguish bundles whose
	// internal workflow name was customised. Empty for plain .bot
	// runs.
	BundleName string `json:"bundle_name,omitempty"`
	// BundleDisplayName mirrors the manifest's `display_name` (e.g.
	// "Nexie"). When set, the studio RunHeader leads the bot chip
	// with this persona name + a ✨ icon so dispatcher-spawned runs
	// belonging to a named bot read at a glance.
	BundleDisplayName string          `json:"bundle_display_name,omitempty"`
	Status            store.RunStatus `json:"status"`
	Inputs            map[string]any  `json:"inputs,omitempty"`
	// PermissionMode is the workflow-declared tool-permission gate mode
	// ("off"|"ask"|"deny"); empty when the gate is off/unset. The studio
	// badges ask/deny. See docs/permissions.md.
	PermissionMode string `json:"permission_mode,omitempty"`
	// ModelOverrides are the launch-time per-node/-group model/backend
	// pins captured on the run, surfaced so the studio Overview can show
	// what the run was launched with. Empty when none were set.
	ModelOverrides []store.RunModelOverride `json:"model_overrides,omitempty"`
	// Budget is the effective budget cap set captured at launch (after
	// overrides + cloud ceiling clamp), surfaced so the studio Overview
	// draws budget meters with a denominator. Nil when the workflow
	// declared no budget: block. See store.RunBudget.
	Budget     *store.RunBudget  `json:"budget,omitempty"`
	CreatedAt  time.Time         `json:"created_at"`
	UpdatedAt  time.Time         `json:"updated_at"`
	FinishedAt *time.Time        `json:"finished_at,omitempty"`
	Error      string            `json:"error,omitempty"`
	Checkpoint *store.Checkpoint `json:"checkpoint,omitempty"`
	// WorkDir is the absolute filesystem path the run executed in
	// (per-run worktree when Worktree is true, otherwise inherited cwd).
	// Empty for runs created before this field was persisted; the studio
	// hides the modified-files panel in that case.
	WorkDir string `json:"work_dir,omitempty"`
	// ProjectPath is the stable forge slug ("group/project") the run
	// targets — the cloud run's repo identity (WorkDir is a runner-pod
	// path there). Empty for local and repo-less runs.
	ProjectPath string `json:"project_path,omitempty"`
	// Worktree is true when WorkDir was created by `worktree: auto`.
	Worktree bool `json:"worktree,omitempty"`
	// WorktreeAvailable is true when WorkDir still exists on THIS server's
	// filesystem — i.e. the inline file-editor + uncommitted/live diff
	// surfaces can be served without a 409. It is false for a cloud run
	// (whose worktree lives on the runner pod) and for a finalized/gc'd
	// local run (whose worktree was torn down). The studio gates the
	// Monaco file-editor affordances on it so the operator never clicks an
	// Edit button that then 409s. Mirrors the /files/content endpoint's own
	// gate (resolveRunWorktreePath).
	WorktreeAvailable bool `json:"worktree_available"`
	// Worktree finalization summary (only populated for `worktree:
	// auto` runs that reached a clean exit). The studio uses these to
	// surface the persistent branch and FF status in the run header.
	FinalCommit      string              `json:"final_commit,omitempty"`
	FinalBranch      string              `json:"final_branch,omitempty"`
	FinalBranchError string              `json:"final_branch_error,omitempty"`
	MergedInto       string              `json:"merged_into,omitempty"`
	MergedCommit     string              `json:"merged_commit,omitempty"`
	MergeStrategy    store.MergeStrategy `json:"merge_strategy,omitempty"`
	MergeStatus      store.MergeStatus   `json:"merge_status,omitempty"`
	AutoMerge        bool                `json:"auto_merge,omitempty"`
	// LocAdded / LocDeleted aggregate the three-dot numstat of the
	// run's commits against its fork point (merge-base of the merge
	// target and FinalCommit), computed server-side with a cache.
	// POINTERS on purpose: nil renders "—" (refs unresolvable — branch
	// deleted, commit GC'd), a zero literal renders "0" (diff resolved
	// and empty). Absent for runs without a FinalCommit.
	LocAdded   *int `json:"loc_added,omitempty"`
	LocDeleted *int `json:"loc_deleted,omitempty"`
	// ActiveDurationMs is the wall-clock the run actually consumed —
	// the sum of run_started/resumed → paused/failed/cancelled/
	// interrupted/finished windows derived from events. Excludes time
	// the run sat paused waiting for human input or sat failed_resumable
	// between a crash and a resume.
	ActiveDurationMs int64 `json:"active_duration_ms"`
	// CurrentRunStart anchors the currently-accruing window. Non-nil
	// while the run is actively executing; nil once it pauses, fails,
	// is cancelled, is interrupted, or finishes. The frontend adds
	// (now - CurrentRunStart) to ActiveDurationMs to drive the live
	// timer and freezes the value once this clears.
	CurrentRunStart *time.Time `json:"current_run_start,omitempty"`
	// QueuePosition is the 1-based position of a queued cloud run on
	// the NATS queue. Populated only while Status == "queued"; absent
	// otherwise. Computed server-side (Mongo aggregation in T-17/T-31).
	// The studio's QueuedBanner uses it to render the "3rd in queue"
	// copy. See cloud-ready plan §F (T-03, T-15, T-31).
	QueuePosition int `json:"queue_position,omitempty"`
	// Source records who originated the run (dispatcher → issue back-
	// reference today; CLI / studio launches leave it nil). The studio
	// RunHeader reads it to render a link back to the kanban ticket
	// that triggered the dispatch.
	Source *store.RunSource `json:"source,omitempty"`
	// Run-tree shard tuple (T4b, refs #125): the child←parent edge plus
	// the shard coordinates mirrored from the queue message. ParentRunID
	// points UP at the run that spawned this shard/child; ShardIndex /
	// ShardCount / ShardLabel describe this run's slot in its parent's
	// fan-out. All empty for a top-level (non-sharded) run. The studio
	// projects these to render a run's shard/child subtree.
	ParentRunID string `json:"parent_run_id,omitempty"`
	// ParentNodeID is the IR node id of the subbot node in the parent
	// workflow that spawned this child run; empty for root runs and
	// non-subbot children. See store.Run.ParentNodeID.
	ParentNodeID string `json:"parent_node_id,omitempty"`
	ShardIndex   int    `json:"shard_index,omitempty"`
	ShardCount   int    `json:"shard_count,omitempty"`
	ShardLabel   string `json:"shard_label,omitempty"`
	// WatchedIssueIDs is the server-authoritative set of native-kanban
	// issue IDs this run subscribed to (MVP3b). The studio's whats-next
	// WatchPanel reads it as the primary watch-list source, falling back
	// to its event-derived list for legacy runs that predate the field.
	WatchedIssueIDs []string `json:"watched_issue_ids,omitempty"`
	// BackendsUsed summarizes the distinct (backend, model) pairs the
	// run's LLM/delegate nodes actually executed against, derived by
	// folding node_finished events (each stamps _backend / _model on its
	// output). Auto-detected backends report their RESOLVED value, not
	// "auto". Nil for runs with no LLM nodes (tool/compute-only) so the
	// studio RunHeader renders no chip. See the studio BackendsUsed row.
	BackendsUsed []BackendUsage `json:"backends_used,omitempty"`
	// Loops is the run-level "real loops" indicator: one entry per
	// declared named loop (e.g. "review_loop"), reporting the SEMANTIC
	// iteration counter (matching the runtime's `node#N` log label and
	// review_loop.iteration), NOT the count of node executions — a
	// resume re-runs a mid-loop iteration, so the physical execution
	// count drifts above the true loop counter. Current is the max
	// iteration observed across the loop's node_started events
	// (iteration_path); Max is the declared bound (0 = unbounded /
	// expression cap / unknown). Absent for runs with no named loops.
	Loops map[string]RunLoopProgress `json:"loops,omitempty"`
	// Deployment is the run's delivery outcome — the live URL, the image
	// actually running, and the traceability verdict — folded from any
	// node whose structured output carries the deployment-report keys
	// (see recordDeployment). Nil for the overwhelming majority of runs,
	// which deploy nothing; the studio then renders no deployment row.
	Deployment *DeploymentReport `json:"deployment,omitempty"`
}

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

type RunLogSubscription struct {
	C <-chan runLogChunk
	// contains filtered or unexported fields
}

type RunLoopProgress struct {
	Current int `json:"current"`
	Max     int `json:"max,omitempty"`
}

type RunSnapshot struct {
	Run        RunHeader        `json:"run"`
	Executions []ExecutionState `json:"executions"`
	LastSeq    int64            `json:"last_seq"`
}

type RunSummary struct {
	ID string `json:"id"`
	// Name is the deterministic, human-friendly label for the run.
	// Empty for legacy runs persisted before this field existed.
	Name         string `json:"name,omitempty"`
	WorkflowName string `json:"workflow_name"`
	// BundleName is the bot/bundle label (e.g. "docs-refresh"). Sourced
	// from the persisted Run.BundleName; falls back server-side to
	// basename(BundlePath) (stripped of `.botz`) for legacy runs.
	// Empty for plain .bot runs with no bundle.
	BundleName string `json:"bundle_name,omitempty"`
	// BundleDisplayName is the bot's persona label (e.g. "Nexie") from
	// the bundle manifest. Empty for plain runs; the studio falls back
	// to BundleName then WorkflowName. Carried so the run list can
	// render readable bot-filter chips without a per-run fetch.
	BundleDisplayName string `json:"bundle_display_name,omitempty"`
	// SourceKind classifies how the run was triggered, for list filtering /
	// grouping: "manual" | "webhook" | "dispatcher" | "fork" | "shard".
	// Derived server-side from the run's source/owner; never persisted.
	SourceKind string          `json:"source_kind,omitempty"`
	Status     store.RunStatus `json:"status"`
	FilePath   string          `json:"file_path,omitempty"`
	CreatedAt  time.Time       `json:"created_at"`
	UpdatedAt  time.Time       `json:"updated_at"`
	FinishedAt *time.Time      `json:"finished_at,omitempty"`
	Error      string          `json:"error,omitempty"`
	// Active reports whether the run is currently held by this
	// process's manager. A run with status "running" but Active=false
	// belongs to another process or to a previous boot — Cancel won't
	// reach it from here.
	Active bool `json:"active"`
	// Worktree finalization summary (only populated for `worktree:
	// auto` runs that reached a clean exit). See store.Run for the
	// full semantics.
	FinalCommit      string              `json:"final_commit,omitempty"`
	FinalBranch      string              `json:"final_branch,omitempty"`
	FinalBranchError string              `json:"final_branch_error,omitempty"`
	MergedInto       string              `json:"merged_into,omitempty"`
	MergedCommit     string              `json:"merged_commit,omitempty"`
	MergeStrategy    store.MergeStrategy `json:"merge_strategy,omitempty"`
	MergeStatus      store.MergeStatus   `json:"merge_status,omitempty"`
	AutoMerge        bool                `json:"auto_merge,omitempty"`
	// WorkDir / RepoRoot locate where a local run executed: WorkDir is
	// the absolute exec dir (worktree path or inherited cwd), RepoRoot
	// the main git repo it was forked from. The studio uses these to
	// offer a "by folder" run filter in desktop/local mode. Empty for
	// cloud runs (which carry ProjectPath instead) and legacy runs.
	WorkDir  string `json:"work_dir,omitempty"`
	RepoRoot string `json:"repo_root,omitempty"`
	// ProjectPath is the stable forge slug ("group/project") for
	// cloud webhook-launched runs, powering the "by repo" filter.
	// Empty in local mode.
	ProjectPath string `json:"project_path,omitempty"`
	// QueuePosition is set only for cloud-mode runs whose Status is
	// "queued"; nil otherwise. 1 means "next to be picked up". Computed
	// by the server (Mongo aggregation), not persisted on the run doc.
	// See cloud-ready plan §F (T-03, T-31).
	QueuePosition *int `json:"queue_position,omitempty"`
	// Run-tree shard tuple (T4b, refs #125): the child←parent edge plus
	// the shard coordinates mirrored from the queue message. Empty for a
	// top-level (non-sharded) run. Carried so the run list / children
	// endpoint can project a run's shard/child subtree without a per-run
	// fetch. See store.Run.
	ParentRunID string `json:"parent_run_id,omitempty"`
	// ParentNodeID is the IR node id of the subbot node in the parent
	// workflow that spawned this child run; empty for root runs and
	// non-subbot children. See store.Run.ParentNodeID.
	ParentNodeID string `json:"parent_node_id,omitempty"`
	ShardIndex   int    `json:"shard_index,omitempty"`
	ShardCount   int    `json:"shard_count,omitempty"`
	ShardLabel   string `json:"shard_label,omitempty"`
}

type RunTerminalError struct{ Status store.RunStatus }

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

type ServiceOption func(*Service)

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

type SteerCommand struct {
	// CommandID is minted by the sender (ULID/UUID); the runner dedups
	// on it so a retried publish cannot double-apply.
	CommandID string              `json:"command_id"`
	Kind      SteerCommandKind    `json:"kind"`
	LoopName  string              `json:"loop_name,omitempty"`
	Delta     int                 `json:"delta,omitempty"`
	Budget    *ir.BudgetOverrides `json:"budget,omitempty"`
	IssuedAt  time.Time           `json:"issued_at"`
	// IssuedBy names the operator for the persisted run_steered event.
	IssuedBy string `json:"issued_by,omitempty"`
}

type SteerCommandKind string

type SteerError struct {
	// Code: "unknown_loop" | "invalid" | "no_budget" | "terminal" |
	// "not_active" | "engine_stalled" | "internal".
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

type SteerReply struct {
	CommandID  string         `json:"command_id"`
	RunID      string         `json:"run_id"`
	Applied    map[string]any `json:"applied,omitempty"`
	Effective  map[string]any `json:"effective,omitempty"`
	Noop       bool           `json:"noop,omitempty"`
	NoopReason string         `json:"noop_reason,omitempty"`
	Warning    string         `json:"warning,omitempty"`
	Err        *SteerError    `json:"error,omitempty"`
	RunnerID   string         `json:"runner_id,omitempty"`
}

type WireEdge struct {
	From       string `json:"from"`
	To         string `json:"to"`
	Condition  string `json:"condition,omitempty"`
	Negated    bool   `json:"negated,omitempty"`
	Expression string `json:"expression,omitempty"`
	Loop       string `json:"loop,omitempty"`
}

type WireNode struct {
	ID              string            `json:"id"`
	Kind            string            `json:"kind"`
	Description     string            `json:"description,omitempty"`
	Model           string            `json:"model,omitempty"`
	Backend         string            `json:"backend,omitempty"`
	ReasoningEffort string            `json:"reasoning_effort,omitempty"`
	OutputFields    []WireSchemaField `json:"output_schema,omitempty"`
	Source          string            `json:"source,omitempty"`
	Isolated        bool              `json:"isolated,omitempty"`
}

type WireSchemaField struct {
	Name       string   `json:"name"`
	Type       string   `json:"type"`
	EnumValues []string `json:"enum_values,omitempty"`
}

type WireWorkflow struct {
	Name string `json:"name"`
	// Entry is the first node ID the runtime picks. Useful so the
	// frontend can mark it specially and start its layout from there.
	Entry string     `json:"entry"`
	Nodes []WireNode `json:"nodes"`
	Edges []WireEdge `json:"edges"`
	// StaleHash signals that the .bot source on disk no longer matches
	// the hash captured at run launch. The frontend can warn the user
	// that the IR they are viewing may diverge from what was executed.
	StaleHash bool `json:"stale_hash,omitempty"`
}