bootstrap

type ActiveVCS struct {
	Template               *vcs.Template
	RepoRoot               string
	TrustedExplicitClasses bool
}

type BootstrapResult struct {
	Home             string         // step 0a
	LaunchDir        string         // launch cwd (item 4 / status overlay)
	ProjectRoot      string         // step 2
	ConfigLayerPaths []string       // step 2 (ordered settings.yaml sources, global-first/project-last; item 10)
	Config           map[string]any // step 3 (composed config)
	VCSTemplate      any            // step 6 (active template; nil when none detected)
	ToolRegistry     any            // step 6c
	Model            any            // step 7 (active model selection; *model.ActiveState)
	Mode             any            // step 7b2 (active interaction mode; *mode.ActiveState)

	// ModelPickerRequired is the path-4 outcome (step 7): a selectable model
	// exists but none was determined, so StartTUI must open the provider-aware model
	// picker once the picker deps are installed. It is distinct from Model holding an empty
	// active state, which alone only means "no active selection".
	ModelPickerRequired bool

	Session           *sessions.Store        // step 7b (active session)
	AgentInstructions []agentinstr.LoadEntry // step 7c (in-memory AGENTS.md load record, for /status + /clear replay)

	// TrustDecision is the step-2b gate's run-fixed outcome, consumed by the interactive
	// project-grant prompt. A headless run retains it from its own non-prompting evaluator.
	TrustDecision trust.Decision

	// WithheldInputs is the structured record of the project inputs a degraded launch did
	// not load, including the reason when the gate could not inspect one.
	WithheldInputs []WithheldInput

	// SettingsLayers holds each admitted settings layer copied independently of Config, so
	// composition's merging and deduplication cannot erase what a layer itself held. A
	// configured project path the trust gate refused is carried as an ignored layer.
	SettingsLayers []securitystate.LayerSnapshot

	// BackgroundPrune marks a launch that must kick off the background
	// retention prune in StartTUI once the active session is installed. Only a fresh
	// launch sets it: pruning is fresh-launch-only. Every resume
	// path — `--resume <id>`, the no-id `--resume` picker, and in-TUI `/resume` —
	// leaves it false, so shared TUI assembly never prunes for a resumed run.
	BackgroundPrune bool

	ResumeLockRelease func()

	// ResumeReplay marks a cold-start resume launch (both `--resume <id>` and the no-id
	// picker form) so StartTUI re-renders the loaded session's prior conversation into
	// the transcript after the launch banner and before the event loop runs. It
	// stays false on a fresh launch, whose empty session has no prior conversation to
	// replay, so fresh-launch transcript behavior is unchanged.
	ResumeReplay bool
}

type ConfigComposition struct {
	Config       map[string]any
	ProjectLayer map[string]any
	// ProjectPresent distinguishes an admitted project layer that exists from one whose
	// file was absent, which ProjectLayer alone cannot: both leave it nil.
	ProjectPresent bool
	// LocalPresent distinguishes an admitted local layer that exists from one whose file was
	// absent, which LocalLayer alone cannot: both leave it nil.
	LocalLayer   map[string]any
	LocalPresent bool
}

type DeniedCall struct {
	Subject string
	Reason  string
	Source  string
}

type FreshSteps struct {
	// ResolveHome resolves the user's home directory (step 0a).
	ResolveHome func() (home string, err error)
	// RunFirstRun reports ran=true when global settings were absent and first-run
	// generation ran (step 0); RunFresh then exits before step 1.
	RunFirstRun func(home string) (ran bool, err error)
	// LoadGlobalSettings loads ~/.codemeld/global/settings.yaml (step 1).
	LoadGlobalSettings func(home string) (global map[string]any, err error)
	// ResolveProjectRoot walks for the project root from the launch cwd and returns
	// the project-side settings.yaml layer paths discovered there (at most one, per
	// config.LocateProjectRoot); RunFresh prepends the global path to build the
	// global-first/project-last /status source list (step 2).
	ResolveProjectRoot func(cwd string, global map[string]any) (projectRoot string, projectLayers []string, err error)
	// GateTrust decides whether the repository at projectRoot may contribute its settings
	// layer to this run (step 2b), prompting and recording the answer on an interactive
	// launch. It runs before the layer paths are published and before composition, so an
	// untrusted repository's settings reach neither.
	GateTrust func(home, projectRoot, launchDir string) trust.Decision
	// ScaffoldProjectIgnore scaffolds the commented <project-root>/.codemeld/codemeldignore
	// template, creating it only when absent. It runs immediately after
	// project-root resolution and before config/VCS/tool setup (step 2.5) so the project
	// .codemeld directory and starter file exist before any later step reads the project
	// tree. The production step is best-effort (it never aborts the launch).
	ScaffoldProjectIgnore func(projectRoot string) error
	// RecoverJournals puts back the writes of a child agent whose codemeld process was killed
	// before it could unwind them, for the project folder being opened (step 2.6). It returns
	// nothing because recovery must never block a launch: what it could not do is reported and the
	// launch continues.
	RecoverJournals func(home, projectRoot string)
	// ComposeConfig composes the config layers (step 3).
	ComposeConfig func(global map[string]any, projectRoot string) (composition ConfigComposition, err error)
	// LoadVCSTemplates loads built-in and project VCS templates (step 4). projectLayer is
	// step 3's verified project settings map (nil when none was composed), carried here so
	// vcs.preferred source attribution reuses it rather than reading the file again.
	// approved is the launch's trust outcome; the step derives no trust of its own.
	LoadVCSTemplates func(home, projectRoot string, projectLayer map[string]any, approved bool) (templates any, err error)
	// ValidatePreferredVCS cross-reference-validates vcs.preferred (step 5).
	ValidatePreferredVCS func(composed map[string]any, templates any) error
	// DetectVCS runs auto-detection, returning the active template or nil (step 6).
	DetectVCS func(cwd string, composed map[string]any, templates any) (active any, err error)
	// BuildToolRegistry builds the tool registry (step 6c).
	BuildToolRegistry func(active any) (registry any, err error)
	// DetermineModel determines the active model (steps 7/7a) through the config→
	// model bridge: it builds a config.Cache from the composed config, the project
	// root, and the global-first/project-last layer paths (using global to attribute
	// each path-4 provider diagnostic to its source settings file), calls
	// model.DetermineSelection, and returns the run-scoped *model.ActiveState. It also
	// reports pickerRequired=true for the path-4 selectable-model outcome (a
	// model picker must open) and returns the path-4 *NoSelectableModelError
	// when no model is installed.
	DetermineModel func(composed, global map[string]any, projectRoot string, layerPaths []string) (selection any, pickerRequired bool, err error)
	// EnsureFreshSession ensures the sessions dir, mints the id, and writes the
	// folder file (step 7b).
	EnsureFreshSession func(home, projectRoot string) (session *sessions.Store, err error)
	// FlushSessionTitle persists a caller-supplied session name (codemeld run --title)
	// as soon as the session exists and before any launch record is appended, so an
	// interrupt anywhere in the rest of the launch still leaves the session named on
	// disk. It returns nothing because losing the name must not kill the run: the
	// headless adapter routes a write failure through the metadata-notice path and
	// discards it. nil for launches that carry no title, which is every interactive one.
	FlushSessionTitle func(ctx context.Context, session *sessions.Store)
	AcquireLock       func(sessionPath, id string) (release func(), err error)
	// AppendLaunchBegan appends exactly one launch_began event, source: fresh
	// (step 7b1) — after session creation and before AGENTS.md load.
	AppendLaunchBegan func(ctx context.Context, session *sessions.Store) error
	// InitMode resolves mode.default from the composed config, appends the
	// session-start interaction_mode{trigger:"launch"} durably (same write-failure
	// policy as launch_began), and returns the run-scoped *mode.ActiveState (step
	// 7b2) — after launch_began and before AGENTS.md load. The active mode is never
	// inherited from a prior session: launch always starts from mode.default.
	// projectRoot/layerPaths feed the config.Cache mode.default is read
	// from, the same source the model and AGENTS.md steps use.
	InitMode func(ctx context.Context, session *sessions.Store, composed map[string]any, projectRoot string, layerPaths []string) (modeState any, err error)
	// LoadAgentInstructions discovers AGENTS.md files, replays one
	// agent_instructions_loaded event per file into the session stream, flushes so
	// the records are durable, and returns the in-memory load record (step 7c). The
	// walk anchor is launchDir (the launch CWD), not projectRoot: the AGENTS.md loader
	// always walks from the launch directory to the filesystem root, independent of
	// discovery.boundary, so the resolved project root must not be substituted here.
	// composed/projectRoot/layerPaths feed the config.Cache the per-file size cap is
	// read from. The returned record is surfaced on BootstrapResult so the /status
	// overlay and /clear replay reuse it without re-walking the disk.
	LoadAgentInstructions func(ctx context.Context, session *sessions.Store, home, launchDir string, composed map[string]any, projectRoot string, layerPaths []string) ([]agentinstr.LoadEntry, error)
	// StartTUI starts the TUI (step 8).
	StartTUI func(ctx context.Context, result *BootstrapResult) error
}

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

type HeadlessExperiment struct {
	ExtraTools []HeadlessExtraTool
	DenyCall   func(call turn.AssembledToolCall) (reason string, deny bool)
}

type HeadlessExtraTool struct {
	Definition provider.ToolDefinition
	Handle     func(ctx context.Context, arguments string) (turn.ToolResult, error)
}

type HomeResolveError struct{ Err error }

type PromptDisplay struct {
	// Action is the prompt's action header ("Create file" / "Edit file" /
	// "Run command" / "Run tool"), produced by dispatch from the subject kind and tool.
	Action string
	// For shell subjects, Subject is effective source text, not MatchRequest.Subject.
	Subject string
	// Body is the payload shown verbatim with no truncation and nothing added: the file
	// content for a create, an old→new snippet for an edit, the full structured-tool
	// call for any other tool. It is empty for a shell subject (the whole command is the
	// Subject).
	Body string
	// OutOfRootFileWrite marks a structured edit/create prompt whose resolved target lies
	// outside the project root. It is copied verbatim from
	// dispatch.PromptDisplay and mapped onto tui.PromptRequest so the prompt offers the
	// folder option for that out-of-root write only; false for every other prompt.
	OutOfRootFileWrite bool
	// OutOfRootReadScope marks a read-only navigation tool prompt whose resolved scope lies
	// outside the project root. It is copied verbatim from dispatch.PromptDisplay and
	// mapped onto tui.PromptRequest so the prompt offers the folder option for that out-of-root
	// read-only scope too; false for every other prompt.
	OutOfRootReadScope bool
	// GrantStoredSubject is the capability subject (write/read*) a grant should store when this
	// structured-tool prompt is approved with a grant-creating option. It is copied verbatim
	// from dispatch.PromptDisplay and mapped onto tui.PromptRequest, where the grant-creating choice
	// returns it as the stored subject so the grant folds the sibling member tools. Empty for every
	// prompt whose grant should store the concrete request subject.
	GrantStoredSubject string
	// Pipeline mirrors dispatch.PromptDisplay.Pipeline: the full pipeline source text carried through
	// for a direct pipeline-stage prompt so the prompt can show the approved stage is one stage of a
	// larger pipeline. Empty for a single direct command, a literal route, and every structured tool. It
	// is display-only, never consulted for matching, and mapped straight onto tui.PromptRequest.Pipeline
	// by buildPromptRequest.
	Pipeline string
	// WholeCommand mirrors dispatch.PromptDisplay.WholeCommand: true on a literal-route prompt to mark a
	// whole-command approval (the Subject is the entire command, not one stage of a direct pipeline).
	// Display-only and mapped straight onto tui.PromptRequest.WholeCommand by buildPromptRequest.
	WholeCommand bool
	// RequestedTarget mirrors dispatch.PromptDisplay.RequestedTarget and feeds only the prompt
	// summary; it is never a matching or grant input.
	RequestedTarget string
	// ProjectRoot is the resolved project root shown alongside the run folder.
	ProjectRoot string
	// LaunchDir is the resolved directory codemeld was launched in; with Boundary
	// and WouldCreateSettingsFile it gates the launch-dir-only cross-mode notice.
	LaunchDir string
	// Boundary is the resolved discovery boundary mode ("launch-dir-only" or
	// "project-root").
	Boundary string
	// FolderSettingsPath is the absolute path a folder grant would be written to,
	// shown for the folder option.
	FolderSettingsPath string
	// FolderCoverage is the one-line statement of what the folder grant covers.
	FolderCoverage string
	// WouldCreateSettingsFile reports whether persisting a folder grant would newly
	// create the project settings file.
	WouldCreateSettingsFile bool
	// ProjectUntrusted is !BootstrapResult.TrustDecision.Trusted, fixed for the run. It must
	// come from that decision and never be inferred from the config layers: a project with no
	// settings file has the same layer shape as an untrusted one and is trusted.
	ProjectUntrusted     bool
	HostRequest          string
	DirectHTTPFallback   bool
	ExceptionalAuthority string
}

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

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

type RefreshOutcome int

type RefreshResult struct {
	ProviderID string
	Outcome    RefreshOutcome
}

type ResumeSteps struct {

	// ResolveHome resolves the user's home directory (step 0a), mirroring the fresh
	// path's first step. RunResumeWithID / RunResumePicker wrap a failure here in a
	// HomeResolveError so the CLI renders the step-0a stderr line.
	ResolveHome func() (home string, err error)
	// RunFirstRun reports ran=true when global settings were absent and first-run
	// generation ran (step 0); the resume entry points then exit before listing or
	// resolving, exactly as RunFresh exits before step 1.
	RunFirstRun func(home string) (ran bool, err error)
	// LoadGlobalSettings loads ~/.codemeld/global/settings.yaml and the keys the
	// resume paths need (discovery.boundary, sessions.retention_days) (step 1).
	LoadGlobalSettings func(home string) (global map[string]any, err error)

	// ListAndSelect renders the listing (after the tty/skipped-id
	// preflight) and reports the chosen session id. picked is false when the user
	// dismisses without selecting, in which case the caller exits normally without
	// entering the resume sub-sequence. No retention prune runs on this path: pruning
	// is fresh-launch-only.
	ListAndSelect func(home, cwd string, global map[string]any) (id string, picked bool, err error)

	// ResolveResume resolves <id> to its session file and runs the
	// folder-file check and the CWD-match check. A failure
	// here fires before the record stream is available, so it is stderr-only and
	// emits no event (the returned error's text is the exact stderr line).
	ResolveResume func(id, cwd, home string) (sessionPath string, sess *sessions.Session, err error)
	// AcquireLock takes the per-session advisory lock on the session file's sidecar
	// (sub-step 1) and returns the release held for the lifetime of the
	// run. A failure here is also pre-stream and stderr-only.
	AcquireLock func(sessionPath, id string) (release func(), err error)
	// AppendLaunchBegan appends the launch_began (source: resume) event as the first
	// event of this launch (sub-step 2) and flushes. The record
	// stream is available at this point because resolve and lock have completed.
	AppendLaunchBegan func(ctx context.Context, store *sessions.Store) error
	// RefreshUpdatedAt refreshes the loaded session's updated_at and flushes
	// (sub-step 3). A write failure here fires after the record stream is
	// available, so the step routes it through the per-turn write-failure protocol
	// and the run continues; it returns a non-nil error only for a fatal
	// condition (e.g. context cancellation), which aborts the launch.
	RefreshUpdatedAt func(ctx context.Context, store *sessions.Store) error

	// ResolveProjectRoot walks for the project root from the launch cwd and returns
	// the project-side settings.yaml layer paths discovered there (step 2), mirroring
	// the fresh path's contract so a resumed launch shows the same global-first/
	// project-last /status config sources (item 10).
	ResolveProjectRoot func(cwd string, global map[string]any) (projectRoot string, projectLayers []string, err error)
	// GateTrust decides whether the repository at projectRoot may contribute its settings
	// layer (step 2b), mirroring the fresh path: it runs before the layer paths are
	// published and before composition.
	GateTrust func(home, projectRoot, launchDir string) trust.Decision
	// ScaffoldProjectIgnore scaffolds the commented <project-root>/.codemeld/codemeldignore
	// template, creating it only when absent. It runs immediately after project-root
	// resolution and before config/VCS/tool setup (step 2.5), mirroring the fresh path so a
	// cold-start resume scaffolds the project starter file too. The production step is
	// best-effort (it never aborts the launch).
	ScaffoldProjectIgnore func(projectRoot string) error
	// RecoverJournals puts back the writes of a child agent whose codemeld process was killed
	// before it could unwind them, for the project folder being opened (step 2.6), mirroring the
	// fresh path: a resumed launch is a launch for that folder too. It returns nothing because
	// recovery must never block a launch.
	RecoverJournals func(home, projectRoot string)
	// ComposeConfig composes the config layers (step 3), mirroring the fresh path.
	ComposeConfig func(global map[string]any, projectRoot string) (composition ConfigComposition, err error)
	// LoadVCSTemplates loads built-in and project VCS templates (step 4), mirroring the fresh
	// path: projectLayer is step 3's verified project settings map (nil when none was
	// composed) and approved is the launch's trust outcome.
	LoadVCSTemplates func(home, projectRoot string, projectLayer map[string]any, approved bool) (templates any, err error)
	// ValidatePreferredVCS cross-reference-validates vcs.preferred (step 5).
	ValidatePreferredVCS func(composed map[string]any, templates any) error
	// DetectVCS runs auto-detection, returning the active template or nil (step 6).
	DetectVCS func(cwd string, composed map[string]any, templates any) (active any, err error)
	// BuildToolRegistry builds the tool registry (step 6c).
	BuildToolRegistry func(active any) (registry any, err error)
	// DetermineModel determines the active model (steps 7/7a) through the same config→
	// model bridge as the fresh path, taking the composed config, the global layer
	// (to attribute path-4 provider diagnostics to their source settings file), the
	// project root, and the global-first/project-last layer paths. On a resumed run it
	// follows step 1 (recover from the loaded record stream) before the fresh
	// paths 2–4, so it also takes the loaded store. It returns the run-scoped
	// *model.ActiveState, reports pickerRequired=true for the path-4
	// selectable-model outcome, and returns the path-4 *NoSelectableModelError when no
	// model is installed.
	DetermineModel func(composed, global map[string]any, projectRoot string, layerPaths []string, store *sessions.Store) (selection any, pickerRequired bool, err error)
	// InitMode resolves mode.default from the composed config, durably appends the
	// session-start interaction_mode{trigger:"resume"}, and returns the run-scoped
	// *mode.ActiveState (step 7b2). A resumed session starts from mode.default, never
	// from the mode active when the prior session ended, so this mirrors
	// the fresh path's InitMode with a "resume" trigger. It runs after step 7's model
	// determination — so a path-4 no-selectable-model abort suppresses it —
	// and before AGENTS.md load, since the composed config (step 3) it reads is not
	// available until after the resume sub-sequence's launch_began.
	InitMode func(ctx context.Context, store *sessions.Store, composed map[string]any, projectRoot string, layerPaths []string) (modeState any, err error)
	// LoadAgentInstructions discovers AGENTS.md files, replays one
	// agent_instructions_loaded event per file into the resumed store, flushes so
	// the records are durable, and returns the in-memory load record for the live
	// system prompt, /status, and /clear replay (step 7c). The walk anchor is the launch CWD on a
	// resumed run, which the CWD-match check has already proven equal to
	// metadata.folder. composed/projectRoot/layerPaths feed the config.Cache the
	// per-file size cap is read from.
	LoadAgentInstructions func(ctx context.Context, store *sessions.Store, home, launchDir string, composed map[string]any, projectRoot string, layerPaths []string) ([]agentinstr.LoadEntry, error)
	// StartTUI starts the TUI (step 8). It blocks for the lifetime of the run, so
	// the resume lock acquired above stays held until it returns.
	StartTUI func(ctx context.Context, result *BootstrapResult) error
}

type WithheldCategory string

type WithheldInput struct {
	Category WithheldCategory
	Path     string
}