cli

type APIError struct {
	Status int
	Method string
	Path   string
	Body   string
}

type AnswerOptions struct {
	StoreDir      string
	RunID         string
	InteractionID string
	Answer        string
}

type BenchAsymptoteOptions struct {
	StoreDir          string
	Runs              []string // canonical asymptote subjects (same workflow, N independent sessions)
	VariantRuns       []string // optional: alternative recipe variant for comparison
	Label             string   // primary group label (default: "asymptote")
	VariantLabel      string   // variant group label (default: "variant")
	JudgeNode         string   // IR node ID of the judge whose verdicts we score
	JudgeField        string   // output field name (default "approved")
	LoopName          string   // optional: pin to one loop (default: first observed)
	ApprovalThreshold float64  // default 0.5
	Output            string   // markdown path; "-" or "" → stdout
	Title             string
	IncludePerRun     bool
}

type BotEntry = botregistry.Entry

type BotsCreateOptions struct {
	// Slug is the bundle directory + technical name (botscaffold.SlugRe).
	Slug string
	// Workdir is the workspace root (default: current directory). It
	// anchors both Dest and the catalog refresh, mirroring
	// botinstall.Options.
	Workdir string
	// Dest is the parent directory for the bundle, relative to Workdir
	// unless absolute (default: bots/).
	Dest string
	// Template is a gallery template ID (default: blank).
	Template string

	DisplayName  string
	Description  string
	Instructions string
	Model        string
	Backend      string
	Worktree     *bool
	Sandbox      *bool
}

type BotsListOptions struct {
	// Paths is the list of roots to walk. A path may point to a single
	// .bot file (treated as one entry), a .botz bundle directory, or a
	// directory containing many .bot files / sub-bundles.
	Paths []string

	// Format selects the output rendering: "json" (default), "markdown",
	// or "skill" (a SKILL.md ready to drop in a `<bundle>/skills/`).
	Format string
}

type BudgetOverrides = ir.BudgetOverrides

type BundlePackResult struct {
	Output   string `json:"output"`
	Hash     string `json:"hash"`
	Entries  int    `json:"entries"`
	BytesIn  int64  `json:"bytes_in"`
	BytesOut int64  `json:"bytes_out"`
}

type CheckStatus string

type DiagramOptions struct {
	File string // .bot file path
	View string // "compact" (default), "detailed", or "full"
}

type DiagramResult struct {
	File         string `json:"file"`
	WorkflowName string `json:"workflow_name"`
	View         string `json:"view"`
	Mermaid      string `json:"mermaid"`
}

type DispatchOptions struct {
	ConfigPath string
	StoreDir   string
	Port       int  // overrides cfg.Server.Port if > 0
	NoServer   bool // overrides cfg.Server.Port to disable HTTP
}

type ImportOptions struct {
	// File is the workflow script to import (.js).
	File string
	// Out is the output .bot path. Empty: <workflow-name>.bot next to
	// the source file.
	Out string
	// Name overrides the workflow name (default meta.name, then stem).
	Name string
	// DryRun prints the draft instead of writing it.
	DryRun bool
}

type InspectOptions struct {
	RunID    string
	StoreDir string
	Events   bool // show event log
	Full     bool // show all details

	Node      string
	Branch    string
	Iteration *int // nil = unset; -1 = latest started
	// ExecutionID is the alternative single-string selector
	// ("exec:<branch>:<node>:<iter>"). Mutually exclusive with --node.
	ExecutionID string
	Section     InspectSection
	LogTail     int
	ListNodes   bool
}

type InspectSection string

type IssueBoardInitOptions struct {
	IssueCommonOptions
	From  string // optional path to a board.json
	Force bool
}

type IssueCommonOptions struct {
	StoreDir string
}

type IssueCreateOptions struct {
	IssueCommonOptions
	Title    string
	Body     string
	State    string
	Labels   []string
	Priority int
	Assignee string
	Blockers []string
	Fields   []string // custom-field key=value pairs (Issue.Fields)
	Bot      string   // typed workflow override consumed by the dispatcher
	BotArgs  []string // typed dispatcher var overrides as key=value (Issue.BotArgs)
}

type IssueImportOptions struct {
	IssueCommonOptions
	Forge    string // github | forgejo | gitlab
	Repo     string // owner/name
	TokenEnv string // NAME of the env var holding the forge token (never the value)
	BaseURL  string // forge API base; empty = provider default
	Since    string // RFC3339; empty = full re-sync
	// MinAuthorRole is the trust threshold (gitlab vocabulary; "" →
	// developer) above which an issue author's fresh card is stamped
	// triage:auto instead of parked needs:approval.
	MinAuthorRole string
}

type IssueListOptions struct {
	IssueCommonOptions
	States    []string
	Labels    []string
	Assignee  string
	OnlyClaim bool
	OnlyFree  bool
}

type IssueMoveOptions struct {
	IssueCommonOptions
	IDOrPrefix string
	To         string
}

type IssueRefOptions struct {
	IssueCommonOptions
	IDOrPrefix string
}

type IssueUpdateOptions struct {
	IssueCommonOptions
	IDOrPrefix string
	Title      *string
	Body       *string
	Labels     *[]string
	Priority   *int
	Assignee   *string
	Blockers   *[]string
	Fields     []string // key=value (set or replace)
	ClearField []string
}

type MarketplaceInstallOptions struct {
	StoreDir string
	Slug     string
	Workdir  string
	Force    bool
}

type MarketplaceInstallResult struct {
	Kind   marketplace.Kind
	Bot    *botinstall.Result
	Plugin string
	Entry  *marketplace.Entry
}

type MarketplaceListOptions struct {
	StoreDir string
	Text     string
	Tag      string
	// Kind filters by artifact kind: "" (any), "bot" or "plugin".
	Kind string
}

type MarketplaceSubmitOptions struct {
	StoreDir string
	Source   string // git URL (optionally url#ref) or local path
	Ref      string
	Path     string
	Tags     []string
}

type MarketplaceUninstallOptions struct {
	StoreDir string
	Slug     string
	Workdir  string
}

type MigrateOrgsResult struct {
	ScannedTeams      int
	OrgsCreated       int
	TeamsLinked       int
	OrgMembersCreated int
	OrgsDeleted       int // reverse only
	// Mapping is teamID → orgID for the teams this run created/linked.
	Mapping map[string]string
	// Changes is a human-readable log of every mutation (or would-be
	// mutation under dry-run).
	Changes []string
}

type MigrateRunPathsOptions struct {
	// StoreDir is the run store root; runs live under
	// <StoreDir>/runs/<id>/run.json.
	StoreDir string
	// DryRun reports the changes without writing them.
	DryRun bool
}

type MigrateRunPathsResult struct {
	Scanned int             `json:"scanned"`
	Updated int             `json:"updated"`
	Changes []RunPathChange `json:"changes"`
}

type ModelsOptions struct {
	// Spec is an optional "provider/model-id". When empty the command lists a
	// representative set of known models (model.KnownModelSpecs()).
	Spec string
	// Refresh force-refetches the model-spec cache before resolving.
	Refresh bool
}

type OutputFormat int

type PluginView = plugin.View

type Printer struct {
	W      io.Writer
	Format OutputFormat
}

type PruneOptions struct {
	StoreDir  string
	OlderThan time.Duration
	KeepLast  int
	Statuses  []string
	DryRun    bool
	Now       func() time.Time // test seam; nil = time.Now
}

type PruneResult struct {
	StoreDir     string      `json:"store_dir"`
	AgeField     string      `json:"age_field"`
	OlderThan    string      `json:"older_than"`
	KeepLast     int         `json:"keep_last"`
	Statuses     []string    `json:"statuses"`
	DryRun       bool        `json:"dry_run"`
	Scanned      int         `json:"scanned"`
	Pruned       []PrunedRun `json:"pruned"`
	PrunedCount  int         `json:"pruned_count"`
	SkippedCount int         `json:"skipped_count"`
	// Unreadable lists run dirs whose run.json could not be loaded
	// (partial delete, crash before the first write). They are never
	// deleted — the operator inspects or removes them by hand.
	Unreadable []string `json:"unreadable,omitempty"`
	// TombstonesReaped counts the deletion markers older than the
	// retention horizon that this sweep removed for good.
	TombstonesReaped int `json:"tombstones_reaped,omitempty"`
}

type PrunedRun struct {
	ID           string    `json:"id"`
	Name         string    `json:"name,omitempty"`
	WorkflowName string    `json:"workflow_name,omitempty"`
	BundleName   string    `json:"bundle_name,omitempty"`
	Status       string    `json:"status"`
	AgeSeconds   int64     `json:"age_seconds"`
	Timestamp    time.Time `json:"timestamp"`
	Deleted      bool      `json:"deleted"`
}

type QuestionsOptions struct {
	StoreDir string
	RunID    string
}

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

type RemoteConfig struct {
	BaseURL string `json:"base_url"`
	Token   string `json:"token"`
	Email   string `json:"email,omitempty"`
	// TeamID / OrgID are the default tenant scope for team-/org-scoped
	// commands. Persisted by `iterion remote teams|orgs switch`; a
	// per-command --team/--org flag or ITERION_REMOTE_TEAM/_ORG wins.
	TeamID string `json:"team_id,omitempty"`
	OrgID  string `json:"org_id,omitempty"`
}

type RemoteIssueFields struct {
	Title    string
	Body     string
	State    string
	Labels   []string
	Priority int
	Assignee string
	Bot      string
	BotArgs  map[string]string
}

type RemoteIssuesListOptions struct {
	States   []string
	Labels   []string
	Assignee string
}

type RemoteMe struct {
	User struct {
		ID           string `json:"id"`
		Email        string `json:"email"`
		Name         string `json:"name"`
		IsSuperAdmin bool   `json:"is_super_admin"`
	} `json:"user"`
	ActiveOrgID  string `json:"active_org_id"`
	ActiveTeamID string `json:"active_team_id"`
	Teams        []struct {
		TeamID   string `json:"team_id"`
		TeamName string `json:"team_name"`
		OrgID    string `json:"org_id"`
		Role     string `json:"role"`
	} `json:"teams"`
}

type RemoteRunsFilesOptions struct {
	Path     string
	Mode     string // "uncommitted" | "branch" (server-side default applies)
	Diff     bool
	Content  bool
	EditFile string // local file whose bytes replace the remote path (PUT)
}

type RemoteRunsLaunchOptions struct {
	FilePath      string // local .bot file; read and sent inline as source
	BotID         string // catalog bot id (alternative to FilePath)
	Vars          map[string]string
	Preset        string
	Timeout       string
	Backend       string
	Compress      string
	Permission    string
	ReviewMode    string
	MergeInto     string
	BranchName    string
	MergeStrategy string
	AutoMerge     bool
	// Attach maps attachment name -> local file path; each is uploaded
	// to /api/runs/uploads first and referenced by upload id.
	Attach             map[string]string
	ModelOverridesJSON []byte // raw model_overrides array (from @file)
	CallbackURL        string
	CallbackToken      string
	Follow             bool
	FollowInterval     time.Duration
}

type RemoteRunsListOptions struct {
	Status   string
	Workflow string
	Repo     string
	Since    string // RFC3339, passed through verbatim
	Limit    int
}

type RemoteRunsResumeOptions struct {
	AnswersFile string // JSON map of answers (@file semantics handled by caller)
	FilePath    string // optionally push a modified workflow
	Force       bool
	Timeout     string
}

type ReportOptions struct {
	RunID    string
	StoreDir string
	Output   string // output file path (empty = stdout)
}

type ResumeOptions struct {
	RunID       string
	StoreDir    string
	AnswersFile string            // path to JSON answers file
	Answers     map[string]string // --answer key=value overrides
	LogLevel    string            // log level (default: "info", env: ITERION_LOG_LEVEL)
	Force       bool              // allow resume despite workflow hash change
	// ForceStale auto-promotes a status=running run to failed_resumable
	// IFF its events.jsonl mtime is older than forceStaleStaleAfter.
	// The server-boot sweep (pkg/store.PromoteStaleOrphans) covers the
	// common case automatically; this flag is the operator's escape
	// hatch when they spot an orphan in a long-running session, or want
	// to bypass waiting for the next server restart.
	ForceStale bool
	Executor   runtime.NodeExecutor
	// Background marks this invocation as a managed-runner subprocess
	// spawned by the studio server. The CLI writes a .pid file so the
	// server can detect liveness across its own restart.
	Background bool
	// Budget carries CLI overrides for the workflow's budget: block,
	// mirroring `iterion run`. The documented "budget exceeded → raise the
	// budget + resume" recovery relies on this. Non-zero wins; zero
	// inherits. See applyBudgetOverrides.
	Budget BudgetOverrides
	// Permission overrides the tool-permission gate on resume. Adding an
	// allow rule here is how an operator authorizes a call the run paused
	// on (`permission: ask`): the rule lands in the resolved policy, the
	// agent re-issues the call, and it proceeds. See docs/permissions.md.
	Permission      string
	PermissionAllow []string
	PermissionAsk   []string
	PermissionDeny  []string
	// ModelFor / BackendFor re-apply the launch-time per-node/-group model+
	// backend overrides on resume (repeatable --model / --backend,
	// "selector=value" or bare "value"). Resume does NOT persist the original
	// run's overrides, so a run launched with e.g. `--model 'judge=...'` falls
	// back to the node's DSL model unless the same flags are passed again here.
	// Parsed via model.ParseModelOverrides in buildResumeExecutor.
	ModelFor   []string
	BackendFor []string
	// AutoResume is the bounded run-level auto-resume budget N
	// (`--auto-resume`, env ITERION_AUTO_RESUME; default 0 = off). Mirrors
	// RunOptions.AutoResume so `iterion resume` can itself keep re-driving a
	// transient-failing run without a human in the loop. See auto_resume.go.
	AutoResume int
}

type RunOptions struct {
	File          string               // .bot file path or .botz bundle path
	Recipe        string               // recipe JSON file path (alternative to File)
	Vars          map[string]string    // --var key=value overrides
	Preset        string               // --preset <name>: applies an in-source named preset before --var
	RunID         string               // explicit run ID (auto-generated if empty)
	Source        *store.RunSource     // originating-action provenance stamped on the run (schedule launches)
	StoreDir      string               // explicit store override; empty uses store.ResolveStoreDir anchored at the workflow project
	Timeout       time.Duration        // maximum run duration (0 = no limit)
	LogLevel      string               // log level (default: "info", env: ITERION_LOG_LEVEL)
	NoInteractive bool                 // disable interactive TTY prompting on human pause
	Executor      runtime.NodeExecutor // pluggable executor (nil = stub)
	// Background marks this invocation as a managed-runner subprocess
	// spawned by the studio server. The CLI writes a .pid file so the
	// server can detect liveness across its own restart, and forces
	// NoInteractive (no TTY in the spawned process).
	Background bool
	// 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 (must match currently-checked-out).
	MergeInto string
	// BranchName overrides the default storage branch
	// `iterion/run/<friendly>` created on the worktree's HEAD. The
	// branch is always created (GC guard); on collision a numeric
	// suffix is appended.
	BranchName string
	// MergeStrategy selects how the run's commits are landed on the
	// merge target when AutoMerge is on: "squash" (default) collapses
	// into one commit; "merge" fast-forwards (preserves history).
	MergeStrategy string
	// AutoMerge toggles whether the engine performs the merge at end
	// of run. CLI default is true (preserves prior behaviour); the
	// studio sets false by default to defer merge to a UI action.
	AutoMerge bool
	// Sandbox is the run-level override for the sandbox activation
	// mode ("", "none", "auto"). "" inherits the global default
	// (ITERION_SANDBOX_DEFAULT, else "auto" — sandbox-by-default, see
	// runtime.ResolveGlobalSandboxDefault). The workflow's own
	// `sandbox:` block is the next layer of precedence; per-node
	// overrides win above all. See pkg/sandbox.
	Sandbox string
	// SandboxDefaultImage overrides the image ref used by `sandbox: auto`
	// when no .devcontainer/devcontainer.json is found in the workspace.
	// Empty inherits ITERION_SANDBOX_DEFAULT_IMAGE then the built-in
	// default (`ghcr.io/socialgouv/iterion-sandbox-slim:<iterion-version>`).
	SandboxDefaultImage string
	// SandboxHostState controls whether the host's `~/.iterion` (run
	// store) and `~/.claude` (Claude Code OAuth + sessions) are
	// auto-mounted into the sandbox so persistent memory survives
	// across runs. Values: "", "auto", "none". Empty inherits
	// ITERION_SANDBOX_HOST_STATE then the built-in default "auto".
	SandboxHostState string
	// Compress is the run-level command-output-compression override
	// ("", "on", "ultra", "off"). "" inherits the workflow/node `compress:`
	// DSL then the ITERION_COMPRESS env default. It is the 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"). "" inherits the workflow/node
	// `permission:` DSL then the ITERION_PERMISSION env default.
	// PermissionAllow/Ask/Deny are run-level rules, additive to the
	// workflow-level lists. See docs/permissions.md.
	Permission      string
	PermissionAllow []string
	PermissionAsk   []string
	PermissionDeny  []string
	// Budget carries CLI overrides for the workflow's budget: block
	// (--max-cost-usd / --max-tokens / --max-duration / --max-iterations /
	// --max-parallel-branches). Non-zero fields win over the DSL/recipe
	// budget; zero fields inherit. See applyBudgetOverrides.
	Budget BudgetOverrides
	// ReviewMode is the run-level override for bi-model review-loop bots'
	// mono/dual topology ("", "auto", "mono", "dual"). Only bots that
	// declare a review_mode var are affected. "" / "auto" resolves from
	// detected provider credentials at launch (pkg/reviewtopology);
	// "mono"/"dual" force the topology. See docs on review topology.
	ReviewMode string
	// ModelFor / BackendFor are launch-time per-node/-group model+backend
	// overrides (repeatable --model / --backend flags), each a
	// "selector=value" (or a bare "value" targeting every LLM node). They win
	// over the node's DSL model:/backend: so a run can re-target the bot per
	// node-group without editing the .bot. Parsed via model.ParseModelOverrides
	// in buildRunExecutor. See model_override.go.
	ModelFor   []string
	BackendFor []string
	// AutoResume is the bounded run-level auto-resume budget N
	// (`--auto-resume`, env ITERION_AUTO_RESUME; default 0 = off). When the
	// run exits failed_resumable with a retryable cause, the CLI waits
	// (capped exponential backoff) and re-invokes resume in-process up to N
	// times, re-using this run's exact overrides. See auto_resume.go.
	AutoResume int
	// SkipMCPHealth downgrades a failing MCP startup health-check from a
	// fatal error to a warning: the check still runs (its diagnostics are
	// logged) but a failure no longer aborts the run. Set by --skip-mcp-health
	// or a truthy ITERION_SKIP_MCP_HEALTH env var. Useful when the project
	// .mcp.json declares a server that is unreachable/unauthorized in this
	// environment (e.g. an HTTP-OAuth MCP) but the run does not depend on it.
	SkipMCPHealth bool
}

type RunPathChange struct {
	RunID string `json:"run_id"`
	Field string `json:"field"`
	From  string `json:"from"`
	To    string `json:"to"`
}

type SandboxCheck struct {
	Name        string      `json:"name"`
	Status      CheckStatus `json:"status"`
	Detail      string      `json:"detail,omitempty"`
	Remediation string      `json:"remediation,omitempty"`
}

type SandboxDoctorOptions struct {
	// Strict turns on the pre-run validation battery (driver liveness,
	// image resolvability, k8s compatibility, network syntax, …) and
	// makes the command exit non-zero on any failure.
	Strict bool
	// File is an optional workflow (.bot/.botz/dir) whose sandbox:
	// block is resolved and validated. Empty runs host-level checks only.
	File string
	// Sandbox / SandboxDefaultImage / SandboxHostState mirror the
	// `iterion run` flags so the doctor validates the EXACT spec a run
	// with the same flags would use.
	Sandbox             string
	SandboxDefaultImage string
	SandboxHostState    string
	// Target selects the check battery: "auto" (follow the selected
	// driver, default), "cloud" (force the kubernetes/host-independent
	// battery — validate a cloud workflow from a laptop), or "local"
	// (force docker).
	Target string
}

type SandboxStrictReport struct {
	Host   string         `json:"host"`
	Target string         `json:"target,omitempty"`
	Driver string         `json:"driver,omitempty"`
	Mode   string         `json:"mode"`
	Source string         `json:"source,omitempty"`
	Image  string         `json:"image,omitempty"`
	Checks []SandboxCheck `json:"checks"`
}

type ScheduleAddOptions struct {
	ScheduleCommonOptions
	Name          string
	Cron          string
	Bot           string
	Workdir       string
	StoreDir      string
	Sandbox       string
	Timeout       string
	VarFlags      []string
	Description   string
	Disabled      bool
	Overlap       string
	MaxConcurrent int
	Guard         string
	GuardTimeout  string
	GuardVar      string
	StaleAfter    string
}

type ScheduleAuditOptions struct {
	ScheduleCommonOptions
	Name    string // filter: schedule name/id ("" = all)
	Surface string // filter: host-cron|trigger|cloud ("" = all)
	Since   string // filter: Go duration lookback ("" = all)
	Tail    int    // keep only the last N matching rows (0 = all)
}

type ScheduleCommonOptions struct {
	ManifestPath string // --manifest; "" → resolveScheduleManifestPath
}

type ScheduleEntry struct {
	Name        string            `yaml:"name"`
	Cron        string            `yaml:"cron"`
	Bot         string            `yaml:"bot"`
	Workdir     string            `yaml:"workdir,omitempty"`
	StoreDir    string            `yaml:"store_dir,omitempty"`
	Sandbox     string            `yaml:"sandbox,omitempty"`
	Timeout     string            `yaml:"timeout,omitempty"`
	Vars        map[string]string `yaml:"vars,omitempty"`
	Description string            `yaml:"description,omitempty"`
	Disabled    bool              `yaml:"disabled,omitempty"`

	// Overlap policy + pre-launch guard (pkg/schedgate). Overlap
	// defaults to "skip": a tick whose previous run is still live is
	// skipped (and audited) instead of piling up concurrent runs.
	// Guard is an optional `sh -lc` snippet run before any launch —
	// exit 0 fires the run with its stdout in vars[guard_var],
	// non-zero skips the tick. See docs/scheduling.md#overlap-policy.
	// Overlap "keepalive" runs the bot always-on at the cron cadence (host
	// crontab floors at 1 minute — sub-minute keepalive needs the resident
	// scheduler): a stale run silent past StaleAfter is relaunched.
	Overlap       string `yaml:"overlap,omitempty"`
	MaxConcurrent int    `yaml:"max_concurrent,omitempty"`
	Guard         string `yaml:"guard,omitempty"`
	GuardTimeout  string `yaml:"guard_timeout,omitempty"`
	GuardVar      string `yaml:"guard_var,omitempty"`
	StaleAfter    string `yaml:"stale_after,omitempty"`
}

type ScheduleInstallOptions struct {
	ScheduleCommonOptions
	Print bool   // render the managed block to stdout; don't touch the crontab
	TZ    string // crontab CRON_TZ; "" → UTC
}

type ScheduleManifest struct {
	Version   int             `yaml:"version"`
	Schedules []ScheduleEntry `yaml:"schedules"`
}

type ScheduleRefOptions struct {
	ScheduleCommonOptions
	Name string
}

type ScheduleRunOptions struct {
	ScheduleCommonOptions
	Name   string
	DryRun bool
}

type SecretOptions struct {
	Name     string
	FromEnv  string
	Project  bool
	Hosts    []string
	HostsSet bool // whether --hosts was explicitly passed (distinguish "clear" from "leave")
	StoreDir string
}

type SeedOptions struct {
	// Paths are bundle source roots to index (e.g. ["bots"]). Resolved
	// relative to Workdir when not absolute. Whatever bots the target
	// repo ships under these paths become the seeded entries — the
	// mechanism is repo-agnostic; it never assumes a specific layout.
	Paths []string
	// Workdir is the base for relative Paths (default: current dir).
	Workdir string
}

type SkillOptions struct {
	Name     string
	From     string // file to read the skill body from (add); empty = stdin
	Project  bool
	StoreDir string
	Dir      string // export destination dir
}

type StudioOptions struct {
	Port      int
	Bind      string // bind address (default "127.0.0.1"); use "0.0.0.0" to expose on LAN
	Dir       string // working directory (for examples)
	StoreDir  string // explicit store override; empty uses store.ResolveStoreDir anchored at Dir
	NoBrowser bool   // skip opening browser
	// NoBrowserPane disables every Browser-pane code path: the
	// preview proxy, the CDP WS endpoint, and the Chromium runner.
	// Useful for emergency lockdown (security incident) or for
	// shaving startup latency when the operator never needs the
	// pane. Defaults to false (pane enabled).
	NoBrowserPane bool

	// OnReady, when non-nil, is invoked once the HTTP listener is up and
	// the server has accepted its bind address. The argument is the actual
	// host:port the listener is bound to (useful when Port=0 / random).
	// Invoked from a goroutine; callers must be ready for it to fire
	// concurrently with their own Run loop.
	OnReady func(addr string)

	// Mode, when set, advertises the deployment context in
	// /api/server/info and tunes upload defaults ("desktop" raises
	// the per-file cap to 1 GB; "" / "local" / "web" keep the 50 MB
	// cap). The server's Config.Mode owns the same field.
	Mode string

	// MaxUploadSize / MaxTotalUploadSize / MaxUploadsPerRun /
	// AllowUploadMime override the server's upload limits. Zero
	// values fall through to mode-specific defaults applied by
	// pkg/server.applyUploadDefaults.
	MaxUploadSize      int64
	MaxTotalUploadSize int64
	MaxUploadsPerRun   int
	AllowUploadMime    []string

	// MaxConcurrentPipelines caps how many ROOT pipelines run at once
	// (0 = unlimited). Over the cap, launches wait in the pipeline
	// board's Todo lane. Threaded into server.Config →
	// runview.WithMaxConcurrentPipelines.
	MaxConcurrentPipelines int

	// OnForceRefresh, when non-nil, is forwarded to the server and fires
	// before /api/backends/detect?force=1 invalidates its cache. The
	// desktop host uses this to re-source ~/.iterion/env so dotenv
	// edits (including key deletions) are picked up without a restart.
	OnForceRefresh func()

	// BotsPaths configures where the /api/v1/bots endpoint walks to
	// discover bots for the Board ticket form's bot picker. Empty
	// falls back to <Dir>/bots, <Dir>/examples, <Dir>/.botz.
	BotsPaths []string

	// DesktopAlertSink, when non-nil, is wired as the run-health alert
	// desktop delivery sink (the desktop app injects a Wails
	// EventsEmit-backed sink for native OS notifications). It is honoured
	// only when desktop alerts are enabled (ITERION_ALERTS_DESKTOP_ENABLED
	// / alerts.desktop.enabled). The headless CLI and the --server-only
	// daemon leave it nil — they have no Wails runtime to emit through.
	DesktopAlertSink alert.Sink
}

type SuperviseOptions struct {
	RunID    string
	Session  string // raw Claude Code session: cwd or session id (mutually exclusive with RunID)
	Name     string
	Model    string
	System   string   // inline policy text, or @path to read from a file
	Nodes    []string // node ids to watch (empty = whole run)
	Monitors []string // pre-declared monitors as "key=val,key=val" specs
	Cooldown time.Duration
	MaxEvals int
	StoreDir string
}

type ValidateResult struct {
	File               string   `json:"file"`
	Valid              bool     `json:"valid"`
	WorkflowName       string   `json:"workflow_name,omitempty"`
	NodeCount          int      `json:"node_count,omitempty"`
	EdgeCount          int      `json:"edge_count,omitempty"`
	BundleName         string   `json:"bundle_name,omitempty"`
	BundleVersion      string   `json:"bundle_version,omitempty"`
	ParseDiagnostics   []string `json:"parse_diagnostics,omitempty"`
	CompileDiagnostics []string `json:"compile_diagnostics,omitempty"`
	// BundleDiagnostics holds manifest↔workflow consistency findings
	// (bundlelint, C2xx). Kept separate from CompileDiagnostics so the
	// studio can distinguish DSL-level from manifest-level issues.
	BundleDiagnostics []string `json:"bundle_diagnostics,omitempty"`
}