exec

type AIOptions struct {
	// Schema constrains the answer. When it is set the answer comes back in
	// [Answer.JSON] as well as in [Answer.Text], and a model that could not
	// produce the shape is an error rather than a text answer quietly standing
	// in for a structured one.
	Schema Schema
	// Effort is the reasoning knob, in the provider package's own vocabulary
	// rather than a second spelling of it. The zero value is [provider.EffortNone]
	// — send nothing and let the model use its own default — which is not the
	// same request as [provider.EffortOff].
	Effort provider.Effort
}

type Abandoned struct {
	// After is the watchdog it outlived.
	After time.Duration
}

type Account struct {
	// Files is what the work changed, one row per path, merged across however
	// many times the worker touched it.
	Files []FileChange
	// Checks is what the worker's own verifier ran, as of the last time it ran.
	// It is replaced rather than appended by a repeated verification pass: a
	// suite that ran four times reports the state of the fourth run, and the
	// three before it are history rather than evidence.
	Checks []Check
	// Commands is the bounded list of shell commands the leaf ITSELF ran. It is
	// distinct from Checks, which is the closing photograph's reading of the
	// finished tree: no command here is evidence that anything passed because
	// nothing parsed its output, and Verified does not read this field.
	Commands []string
	// CommandsRun is how many commands the leaf itself ran in total, including
	// the earlier commands omitted from the bounded list above.
	CommandsRun int
	// Final is the last thing the worker said about the whole job, verbatim.
	Final string
	// Unread is why the finished tree could not be read, when something was
	// asked of it and the answer could not be understood — a strategy that
	// would not start a second time, a suite that failed to collect, a command
	// killed at its ceiling before it named a check. Empty when nothing was
	// attempted, and that emptiness is what tells [Account.rows] apart the two
	// worlds an absent Checks list used to collapse. It is
	// Verification.Unread's own sentence, carried rather than recomposed, so
	// the account and the reading cannot come to say different things about the
	// same failure.
	Unread string

	// Range is the two commits this account's change set was measured between,
	// when it was measured from the repository rather than narrated by the
	// worker as it went. See [Range] for why the difference is the whole point.
	Range Range
	// Patch is where the change set's own text lives: a path to the diff, in
	// full, written under the harness's own directory for this node.
	//
	// It is a handle rather than the bytes because a diff is unbounded and
	// every reader downstream is bounded — but it is a handle to CONTENT, which
	// is the thing the file list never was. A judge asked whether the
	// deliverable's account of the change is true can read the change; a method
	// writer handed the goal of describing it can read it instead of inferring
	// it. Empty when nothing was derived, which reads as no claim.
	Patch string

	// Withheld is where this change set actually IS, when it is not in the
	// workspace anybody else can open: the directory of the leaf's own view and
	// the branch its work sits on. Empty is the ordinary case and means the
	// change set is in the shared tree.
	//
	// It exists because a change set has two properties that were being read as
	// one. Whether work was DONE is answered by the repository — files, a range,
	// a diff — and stayed true of a leaf whose delivery gate failed, because the
	// leaf really had written all of it. Whether the work is WHERE ANYBODY CAN
	// SEE IT is a different question with a different answer, and nothing asked
	// it. A measured run finished a complete implementation inside its view,
	// failed the gate, merged nothing, and ended with an empty workspace and no
	// sentence anywhere naming the checkout the work was in: 67% of that run's
	// spend, on files the person never saw.
	Withheld       string
	WithheldBranch string
}

type Answer struct {
	Text string
	// JSON is the structured answer, filled only when [AIOptions.Schema] asked
	// for one. Nil is "nobody asked", never "the model refused" — a refusal is
	// an error.
	JSON json.RawMessage
	// Spend is what this one call cost, in the ledger's own figures. It is
	// returned rather than only journaled so a runner can reason about its own
	// budget without reading back what it just wrote.
	Spend Spend
}

type Artifact struct {
	// Name is what it is called where a person reads it.
	Name string `json:"name"`
	// Path is where it actually is.
	Path string `json:"path"`
	// Note is one line about what it is for, drawn beside it. Nothing renders as
	// nothing.
	Note string `json:"note,omitempty"`
}

type ArtifactChange string

type ArtifactFact struct {
	// Path is workspace-relative, the spelling everything downstream records.
	Path string
	// Claimed is the worker's own statement, through a write tool, that this
	// file is a deliverable of the work.
	Claimed bool
	// Observed is the filesystem's statement, through the before/after diff,
	// that this file moved while the leaf was running.
	Observed bool
	// Change is how it moved, and is empty when Observed is false.
	Change ArtifactChange
}

type AskAnswer struct {
	// Text is what they said — the chosen option, or the words they typed.
	Text string
	// TakingOver means the person is continuing by hand. The run ends as
	// incomplete with their note as its report, whatever Text says.
	TakingOver bool
	// Unanswered means nobody was there and no default was declared. A program
	// that reads this stops; it does not guess.
	Unanswered bool
}

type AskOptions struct {
	// Options are the answers this question offers, if it offers a set. Empty is
	// a free-text question. A surface draws these as chips; a headless run
	// matches a manifest default against them.
	Options []string
	// Default is what an unattended run answers with. EMPTY IS NOT A YES: a
	// question with no default, asked where nobody is, stops the run incomplete
	// at that question rather than choosing for the person.
	Default string
}

type BundleSource interface {
	// Runner loads the head version of one bundle. Not found is (nil, false),
	// which is not an error — it is the next layer's turn.
	Runner(name string) (Runner, bool)
	// Manifests is everything this source can offer, for the lists and the
	// menus. A source that cannot be read answers nothing: a registry is not
	// worth failing a launch over, and a list is not where a person learns their
	// disk is gone.
	Manifests() []Manifest
}

type Check struct {
	Command string
	Kind    string
	Passed  bool
	Known   bool
	Tail    string
}

type Completer interface {
	CompleteWithMessages(ctx context.Context, messages []ai.Message, options ...ai.Option) (*ai.Response, error)
}

type ControlAction string

type DocumentProvider interface {
	ParseDocument(context.Context, provider.DocumentRequest) (*provider.DocumentResponse, error)
}

type Env interface {
	// AI is one model call. promptRef NAMES A PROMPT ASSET IN THE BUNDLE and is
	// never an inline string: prompts are files under prompts/ so they can be
	// diffed, reviewed, revised into a new version, and — later — carry their
	// own accepted-output cache per call site. A program that could inline its
	// prompt would put the one thing worth improving somewhere nothing can
	// improve it.
	AI(ctx context.Context, promptRef string, input any, opts AIOptions) (Answer, error)

	// Tool calls one belt tool, filtered by the manifest's whitelist, through
	// the same consent doors any tool call goes through. A tool not on the
	// whitelist is refused here; a tool not on the session's belt is absent, and
	// the two are told apart in the error because they are different facts about
	// what the person can fix.
	Tool(ctx context.Context, name string, args map[string]any) (ToolResult, error)

	// Ask puts a question to the person and waits for the answer. WHAT IT MEANS
	// WITH NOBODY THERE IS DECLARED PER GATE, never assumed: a headless run
	// either takes the answer the manifest defaulted or stops incomplete and
	// says which question it stopped at. The old bridge's auto-approving gate
	// (internal/subharness/exec_model.go) is the anti-pattern this signature
	// exists to make unnecessary — it was kept honest only by writing "nobody was
	// there to ask, so it carried on" into the trail afterwards.
	Ask(ctx context.Context, question string, opts AskOptions) (AskAnswer, error)

	// Remember keeps one note in this subharness's OWN memory — its file in its
	// own bundle, not the session's. A program that has learned that this
	// company's brief always arrives as a PDF has learned something about its
	// domain and nothing about this conversation.
	Remember(ctx context.Context, note string) error

	// Recall reads that memory back. An empty query is everything it has kept.
	Recall(ctx context.Context, query string) ([]Note, error)

	// Log raises one visible progress row into the run's journal, in the
	// program's own words. IT IS THE ONE DOOR TO A PERSON'S ATTENTION that costs
	// nothing, and the vocabulary law reaches it: work is running, finishing,
	// done, incomplete, or your call.
	Log(ctx context.Context, status string) error
}

type Event struct {
	NodeID  int
	Title   string
	State   plan.State
	Detail  string
	Elapsed time.Duration
}

type Executor interface {
	Subharness() string
	Run(ctx context.Context, task Task) (*Outcome, error)
}

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

type Field struct {
	Name        string
	Type        string
	Title       string
	Description string
	Required    bool
	// Default is what the schema says to use when nobody says otherwise, in its
	// own JSON. It is nil when the schema named none, which the card draws as
	// nothing rather than as a guessed blank.
	Default json.RawMessage
	Enum    []string
}

type FileChange struct {
	Path    string
	Change  string
	Added   int
	Removed int
}

type Governor struct{}

type Guard struct {
	Kind GuardKind `json:"kind"`
	// File, Tool and Field name what is being looked at, one per kind.
	File  string `json:"file,omitempty"`
	Tool  string `json:"tool,omitempty"`
	Field string `json:"field,omitempty"`
	// Pattern is what a [GuardField] field has to match. It is a plain substring
	// test in the checker the runtime lane writes; a regular expression in a
	// manifest is a program a person did not know they were writing.
	Pattern string `json:"pattern,omitempty"`
	// Question is the whole of a [GuardJudgement]: one question, one word back.
	Question string `json:"question,omitempty"`
	// Because is what this check is FOR, in a person's words — "this one needs
	// the brief in the repository". It is the sentence the fallback line is
	// built from, and a guard without one falls back silently rather than
	// explaining itself in machinery vocabulary.
	Because string `json:"because,omitempty"`
}

type GuardKind string

type Input struct {
	Title     string
	Result    string
	Artifacts []string
	// Whole says Result above is the producer's material and not an account of
	// it: the files were read back and their text is in the block. It exists
	// because the sentence under that block is an instruction either way, and
	// the two instructions are opposites — "read them if you need the full
	// detail" is an invitation to go and get what the leaf is already holding.
	// False is the older and weaker claim, and is what every caller that does
	// not set this keeps.
	Whole bool
}

type Journal interface {
	Write(entry JournalEntry) error
}

type JournalEntry struct {
	// Seq counts from one within a run, so a reader can order entries without a
	// clock. Two entries written in the same millisecond are still in order.
	Seq int       `json:"seq"`
	At  time.Time `json:"at"`
	// Call is which door was used: "ai", "tool", "ask", "remember", "recall" or
	// "log". The constants are below, and they are spelled the way the program
	// spells them so a person reading a journal and a person reading the bundle
	// are reading one vocabulary.
	Call string `json:"call"`
	// Ref is what the call was about, in one string: the prompt asset an ai()
	// named, the tool a tool() asked for, the question an ask() put, the note a
	// remember() kept. It is what a compact progress row is drawn from.
	Ref string `json:"ref,omitempty"`
	// Input and Output are the call's two halves as JSON. THEY ARE NOT CLIPPED
	// HERE: clipping is a decision about a surface, and a journal that had
	// already thrown the material away could not be the resume point it is also
	// meant to be. A writer with a size law of its own applies it on the way to
	// disk and says so.
	Input  json.RawMessage `json:"input,omitempty"`
	Output json.RawMessage `json:"output,omitempty"`
	// Spend is what this one call cost. Summed across a run's entries it is the
	// run's whole ledger, which is the only reason the ledger and the journal
	// can never disagree.
	Spend Spend `json:"spend,omitzero"`
	// Note is the one line a person reads for this row, in a person's words. It
	// is where a log() status lands, and it is what a surface draws when it has
	// room for one line and not for a call.
	Note string `json:"note,omitempty"`
	// Err is what went wrong, when something did. A call that failed is still a
	// call that happened and still costs what it spent before it failed.
	Err     string        `json:"err,omitempty"`
	Elapsed time.Duration `json:"elapsed,omitempty"`
}

type Layer int

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

type LivenessMark func() func()

type Manifest struct {
	// SubharnessInfo is the identity and the COST SHAPE, unchanged and in the
	// same spelling every existing caller reads: the name, the one line of
	// purpose, the capacity ruler the sizing pass quotes, and the three fields
	// [SubharnessInfo.Deadline] turns into a leaf's hang backstop. The PRD names
	// this pair — prior anchors plus deadline shape — as the manifest's cost
	// shape and says to keep the linearInfo form. Embedding is how it is kept:
	// there is no second spelling of a budget anywhere in this file.
	SubharnessInfo

	// Cues are the trigger vocabulary a match is made against — the words that
	// mean this work, written down at design time and PERSISTED with the
	// program. Their absence from disk is a real hole in the old system, named
	// at internal/session/harness_build.go where a designed harness's cues die
	// with the session that designed them and the page it saved carries none.
	// A manifest with no cues is found by being NAMED and by nothing else, which
	// is a quieter subharness rather than a broken one.
	Cues []string `json:"cues,omitempty"`

	// Input is the typed front door: a JSON Schema with defaults and optional
	// fields, which the intake card draws field by field and chat fills from the
	// conversation. A Go runner may derive it by reflection over a struct; a
	// bundle declares it. Both arrive here as the same bytes.
	Input Schema `json:"input,omitempty"`

	// Output is the PROMISE, and it is the machine-checkable finish line the old
	// one-string program form never had. A run that ends without producing this
	// shape is INCOMPLETE — never done with a strange message — and that
	// sentence is enforceable only because the shape is written down here.
	Output Schema `json:"output,omitempty"`

	// Whitelist is the belt tools this subharness may call through [Env.Tool].
	// It is a ceiling and not a grant: a tool named here that the session does
	// not have is simply not there, and every call still goes through the same
	// consent doors an ordinary tool call goes through. An empty whitelist is a
	// subharness that spends only on the model.
	Whitelist []string `json:"whitelist,omitempty"`

	// Guards are the cheap preconditions checked before a run — a file that has
	// to exist, a tool that has to be on the belt, an input field that has to
	// look a certain way. A FAILED GUARD IS NOT A FAILED RUN: the run falls back
	// to the general worker with the same input, and the person is told the step
	// needed a closer look. See [Guard] for the vocabulary law that governs what
	// they are allowed to say.
	Guards []Guard `json:"guards,omitempty"`

	// Provenance is where this subharness was found: shipped in the binary,
	// written by the person, or committed into the repository they are standing
	// in. It is drawn as a dim mark on the list and it is the one field a person
	// reads that this file spells in words rather than in a code.
	//
	// PROVENANCE IS STAMPED, NEVER AUTHORED. A manifest.json on disk does not get
	// to claim it is built in; the registry writes this field from the layer the
	// bundle was actually loaded out of ([Layer.Provenance]), which is why
	// [Manifest.Validate] neither requires it nor objects to it.
	Provenance Provenance `json:"provenance,omitempty"`
}

type MediaProvider interface {
	GenerateImage(context.Context, provider.ImageRequest) (*provider.ImageResponse, error)
	Speak(context.Context, provider.SpeechRequest) (*provider.SpeechResponse, error)
	// GenerateMusic is its own lane and not Speak with a music model in it.
	// This tool sent composition briefs to /audio/speech for as long as it has
	// existed, and that endpoint has no music behind it — the router composes
	// through streaming chat completions instead
	// (internal/provider/music.go). Every call generate_music made failed.
	GenerateMusic(context.Context, provider.MusicRequest) (*provider.MusicResponse, error)
	GenerateVideo(context.Context, provider.VideoRequest) (*provider.VideoResponse, error)
}

type MediaTools struct {
	Provider    MediaProvider
	Catalog     ModalityCatalog
	ImageModel  string
	SpeechModel string
	MusicModel  string
	VideoModel  string
	VisionModel string
	// VisionClient is a direct completion client. The selected VisionModel is
	// applied per request so capability resolution can stay live at leaf start.
	VisionClient Completer
	// DocumentClient owns the explicit OpenRouter file-parser completion. It is
	// separate from ordinary model turns so every request names its cost rung.
	DocumentClient DocumentProvider
	// DocumentEngine is auto, local, free, or ocr. Empty is auto for embedders
	// that construct MediaTools directly.
	DocumentEngine string
	// VideoPrice is the catalog's fixed per-request price when advertised.
	// Zero means the catalog had no trustworthy estimate; the rail still runs.
	VideoPrice   float64
	WorkingModel string
	BeforeSpend  func(context.Context, float64) error

	// ResolveModel reads a media tool's optional model argument against the
	// live catalog: "best" for the modality's strongest advertised model, or a
	// name to resolve inside that modality. The returned error is already
	// user-facing prose. Nil means the slot default is the only choice, which
	// is what an embedder without a catalog gets.
	ResolveModel func(modality, word string) (string, error)
}

type Meter struct {
	// Name is the bound in one word, for a reader and for a grep. The bounds the
	// loop writes have constants because two files spell them and one of them
	// decides whether the figures are re-read at land time: see MeterCost.
	Name string `json:"name,omitempty"`
	// Reached and Allowed are the bound's own two numbers, in the bound's own
	// unit. Zero Allowed means the bound has no figure worth printing (a
	// structural detector rather than a ceiling).
	Reached int `json:"reached,omitempty"`
	Allowed int `json:"allowed,omitempty"`
	// Unit is what those numbers count, so a line can be composed without the
	// reader having to know which bound spells its allowance in what: "tokens",
	// "turns", "prompt tokens sent".
	Unit string `json:"unit,omitempty"`
}

type ModalityCatalog interface {
	Supports(modelID, direction, modality string) bool
}

type Mutator interface {
	// Mutates reports that this worker's deliverable is a change to the
	// workspace. It is a property of the worker and never of one run.
	Mutates() bool
}

type NotWired struct{ Call string }

type Note struct {
	Text string
	// At is when it was kept, as an RFC 3339 string rather than a time, because
	// this is what a bundle's memory.md carries and a program reads it as text.
	At string
}

type Opening struct {
	// Reading is the project's own account of whether it still works, read
	// while the tree was still pristine.
	Reading verify.Reading
	// Moved says THE JOB HAS CHANGED FILES SINCE THIS READING WAS TAKEN, and it
	// is what the second reading is bought with. See verify.TreeState.
	//
	// This field carried "did this leaf inherit a reading" when it was first
	// written, and that was the wrong question in the way #460 measured: every
	// leaf after the first inherits, so a job whose leaves were ordered to
	// change nothing bought a whole second reading at every one of them — four
	// of them, two minutes each, over a tree that never moved. Inheriting is a
	// fact about a lookup; this is a fact about the tree, and the tree is what
	// the reading is of.
	Moved bool
	// Base is the commit the repository was standing on at that moment, and it
	// is the only one of the three that cannot be recovered later — by the time
	// a leaf lands, HEAD is wherever the leaf left it. Empty for every root that
	// is not a git work tree, which reads downstream as no claim.
	Base string
}

type Outcome struct {
	Text      string
	Artifacts []string
	Turns     int
	ToolCalls int
	Decayed   int // observations faded to stubs, a measure of how much context was reclaimed
	// Folded counts the leaf's own aged assistant turns retired to pointers. It
	// is separate from Decayed because the two say different things about a run:
	// decay means the work produced more raw material than fits, fold means the
	// work produced more of its own prose than fits, and only the second is
	// evidence that a leaf was talking to itself.
	Folded int
	// Steered counts the user's mid-flight lines this run actually read. It is
	// the difference between a redirection delivered to a mailbox and one
	// delivered to a mind, and it is zero on every leaf nobody steered.
	Steered int
	Usage   Usage
	// PerTurn is Usage with its shape kept: one row per turn, summing to Usage
	// exactly. See meter.go for why a summed row alone cannot answer the
	// question anybody asks of it. Executors that do not meter turns leave it
	// empty, which reads as "no shape recorded" rather than as a leaf with no
	// turns.
	PerTurn []TurnUsage
	// Meter is the bound that actually landed this leaf, with its own two
	// numbers.
	//
	// THREE CEILINGS PRODUCED ONE SENTENCE. A leaf could be landed by its cost
	// grant, by an undiscounted token ceiling three times that grant, or by a
	// cumulative bound on prompt sent — and all three set Exhausted to
	// StopBudget, so the journal said "it ran out of its tokens" and the surface
	// printed the grant, which in the ink run of 2026-08-29 was a number the
	// leaf never came near. An autopsy could not tell which ceiling had fired,
	// and the first three readings of that run each blamed a different one.
	//
	// A MEASUREMENT THAT WAS NOT TAKEN IS A FACT ABOUT THE RUN (FAILSAFE.md's
	// sixth failure) and so is a measurement whose meter nobody can name. Empty
	// on a leaf that was not landed by a bound.
	Meter Meter
	Stop  StopReason
	// Exhausted is what ran out, when something did. It is separate from Stop
	// because the two answer different questions and the common case makes them
	// disagree: a leaf whose budget runs out is told to land, it lands, and it
	// ends StopDone — truthfully, because it did stop asking for tools. Reading
	// that as an ordinary finish was how the whole continuation subsystem came
	// to be dead on its designed path, and how a truncated partial posted as a
	// finished deliverable. Stop stays the honest answer to "how did the loop
	// end"; Exhausted answers "was it still working when it was told to stop",
	// which is what continuation and rating both actually need. Empty means
	// nothing ran out.
	Exhausted StopReason
	Elapsed   time.Duration
	// Mode names the shape the loop actually ran in, when it ran in one that is
	// not the open loop. It is written so a benchmark can assert that a fold
	// fired rather than inferring it from a turn count that any well-behaved
	// leaf might also have produced. Empty is the ordinary loop.
	Mode string
	// Promote is the executor's explicit verdict that a reflex needs the normal
	// compiled path. Text remains the useful partial discovered before stopping.
	Promote bool
	// SplitRequest is the leaf's own finding that it is holding more than one
	// agent's job, and its account of how the job divides. It is for the
	// settlement path that grows the graph: nil — every leaf that never asked,
	// which is every leaf outside swarm mode — is what keeps that path unentered
	// and this field free.
	//
	// It is separate from Promote because the two say opposite things about the
	// work. Promote says "this is bigger than the shape I was given, run it
	// again properly"; this says "this is several things, and here they are" —
	// the difference between an escalation and a division. Text remains the
	// partial the leaf produced before it stopped, and the parts consume it.
	SplitRequest *SplitRequest
	// ServiceRequests are live ownership leases requested through job.keep.
	// The resident must adopt or stop every lease before settling the leaf.
	ServiceRequests []ServiceRequest

	// Verdict is the same ending seen from the other side. Stop is written for a
	// person reading the run; Verdict is written for whatever learns from it, and
	// the two part company in exactly the case that matters — a leaf that
	// produced text and stopped because it was out of budget reads as "budget"
	// and grades as a failure.
	Verdict provider.Reading

	// Ran is the tail of what the leaf actually did: the last calls it made,
	// in order, with the arguments clipped. ToolCalls already counted them and
	// a count settles nothing — the question a reader of a finished job
	// actually has is whether the check the deliverable claims to have run
	// appears anywhere in the run. The trace file answers that too, but it is
	// a file in the workspace holding every turn's prose; this is the same
	// evidence in memory, bounded, and already beside the text it is used to
	// check. It is a tail and not a transcript: absence in it is evidence, not
	// proof, and whatever reads it must say so.
	Ran []string
	// Commands is the bounded tail of shell commands this leaf issued itself,
	// in the order it issued them, with each command clipped so a pasted heredoc
	// cannot ride into a judge's context. Ran cannot answer this question: it is
	// a tail of ALL calls, so forty edits can displace a check that ran first,
	// and parsing its JSON here would create a second answer to the question the
	// shell tool already answers.
	Commands []string
	// CommandsRun is how many shell commands this leaf issued in total. It says
	// when Commands was cut, so a bounded list can never read as the whole run.
	CommandsRun int
	// Standing is what this leaf's own closing photograph found and the leaf
	// still held when it landed. It is empty after the leaf settles its finding
	// and whenever that reading found nothing.
	Standing []SelfCloseFinding

	// Baseline is what was already broken before this work began: the checks
	// that came back red, and were red in exactly the same places before the
	// leaf touched the workspace.
	//
	// It exists because the delivery gate was reading a suite's absolute state
	// as a verdict on the change, and a repository with one pre-existing red
	// test therefore convicted every correct patch that passed through it — a
	// measured, repeated way of throwing finished work away (audit-notes
	// §14.4.1). A worker that can tell the difference owes the judge the
	// difference in words, because the judge cannot rerun anything. Only a
	// worker that actually photographs the repository before it starts fills
	// this in; every other leaf leaves it empty, which reads as "no claim".
	Baseline []string

	// Regressed names the project's own checks that passed before this work and
	// fail after it.
	//
	// It exists because a leaf's own new tests are the ONE signal that
	// structurally cannot see a regression: the leaf wrote them, so they test
	// what the leaf was thinking about and nothing else. Three graded runs in
	// the 2026-08-28 sweep shipped patches that deleted attributes their
	// repositories already had, every hidden test failed on setup, and from
	// inside the run there was no signal at all — one of them ran its own tests
	// thirty-three times and scored zero. Test COUNT correlates with nothing.
	// Two measured runs of the project's own command, before and after, are the
	// only thing that can see it, and that is what fills this in.
	//
	// NIL MEANS NO CLAIM — nobody looked, because the project declares no
	// verification entrypoint, or the leaf's wall could not afford the reading,
	// or the command would not run, or the tree never changed. Empty-non-nil is
	// not a distinction anything downstream needs and nothing writes one: this
	// field is nil or it is populated. A populated one is a finding the gate
	// raises itself, with no citation to weigh, because the person never had to
	// ask for their repository to keep working (docs/design/gate/SETTLEMENT.md
	// §4, FAILSAFE.md clause 2).
	Regressed []string

	// OwnFailing names the red checks that FIRST APPEARED AFTER THE BASELINE:
	// the ones this run wrote itself, and did not get passing.
	//
	// It is what Regressed used to swallow. A leaf whose own new checks are red
	// has not finished; a leaf that turned somebody else's check red has broken
	// the repository, and calling the first one the second is how happy-dom's
	// nemotron n1 run was failed for breaking checks it had written that hour
	// while the grader scored the same tree 9 of 9.
	//
	// Nil on every worker that cannot take two readings of the tree, which reads
	// as no claim.
	OwnFailing []string

	// Removed names the PUBLIC names this work deleted: a name the tree spelled
	// before the job's first change that the finished tree does not, in the
	// files the run's own record says it changed.
	//
	// It is Regressed's other half and it is the half a suite cannot see. A
	// check proves something is exercised; it never proves nothing else exists.
	// igel s11 deleted eight public class attributes off `Igel` and its own
	// reading of the finished tree came back BETTER — named 2 → 14, red 2 → 0 —
	// while all twenty-four hidden tests failed at setup on `Igel.results_path`.
	//
	// Nil on every worker that cannot take two readings of the tree, which reads
	// as no claim and never as nothing removed. See verify.Surface.
	Removed []string

	// Unbound names what this work READS that nothing in the tree binds: an
	// attribute a class reaches for and no code assigns, a binding an import
	// asks an in-tree module for that the module does not define.
	//
	// It is the question one step further back than Removed. That one compares
	// two readings and reports a name that USED to be there; this needs only the
	// tree as it stands, and it is the one measurement a run gets on a project
	// with no baseline at all. igel s14 imported `temp_post_req_data_path` from
	// a module it had just stopped binding it in, all twenty-four hidden tests
	// failed on `ImportError`, and the only thing the run could say was that its
	// own checks were red. See verify.UnboundReferences.
	//
	// Nil on every worker with no workspace to read, which reads as no claim.
	Unbound []string

	// Verification is the whole photograph the two readings above came out of:
	// the entrypoint that was run, the budget it was run on, and both readings'
	// complete rosters rather than only their red halves.
	//
	// Regressed is one subtraction over it. The delivery gate needs the other
	// two. WHICH CHECKS EXIST answers whether anything at all exercises a
	// behaviour the request asked for, and WHICH CHECKS STOPPED EXISTING is the
	// one thing that catches a worker deleting the test that was failing it —
	// neither question can be asked of a list of failures. The Taken flag is
	// what keeps the gate honest about a project that declares no verification:
	// nobody looked and nothing may be concluded, which is a different fact from
	// a suite that came back clean. See docs/design/gate/ACCEPTANCE.md.
	//
	// A zero value is a photograph nobody took, which is what every worker that
	// cannot take two readings leaves here.
	Verification verify.Reading

	// Account is the worker's structured account of the work itself: the files
	// it changed, the commands it issued itself, and the checks the closing
	// photograph ran with what each one found. See [Account] for why a leaf that
	// reports only prose is expensive.
	//
	// It is a pointer and it is usually nil. Only a worker that can observe its
	// own change set and run its own verifier has anything to put here; every
	// other leaf leaves it unset, which reads as "no claim" — the same silence
	// Baseline uses, and for the same reason.
	Account *Account

	// Calibration is what the worker noticed about its own fit for this job:
	// free-text sentences, in the worker's own voice, about whether the work sat
	// comfortably inside its envelope, under it, or at the top of it.
	//
	// It is deliberately prose rather than a number or an enum. The only reader
	// is the recalibration call that rewrites a subharness's three anchor
	// examples, and that reader is a model reading evidence — a "fit: 0.3" would
	// have to be invented at one end and interpreted at the other, and both
	// halves would be fiction. Nothing branches on it and nothing may; the
	// generalist emits none of it, so every existing profile record and every
	// existing prompt is exactly what it was.
	//
	// A worker writes these about ITSELF. "This sat under my envelope" is a fact
	// this executor is uniquely placed to observe; "the other worker should have
	// had it" is a judgement it is not, and the note says the first thing.
	Calibration []string
}

type Provenance string

type Range struct {
	Base, Head string
}

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

type Result struct {
	Content string
	IsError bool

	// Followup carries multimodal content that must reach the next model turn.
	// The ordinary text result is still emitted first so tool-call pairing
	// remains valid on every OpenAI-compatible backend.
	Followup []ai.ContentPart
	Usage    Usage
	// contains filtered or unexported fields
}

type RunResult struct {
	// Output is the typed answer, matching the manifest's output schema. A run
	// that ends with nothing here has not finished, and [RunResult.Finished] says
	// so without anybody having to remember the rule.
	Output json.RawMessage `json:"output,omitempty"`

	// Report is the short prose a person reads: what happened, in the
	// vocabulary law's words. It is not a summary of the output — the output is
	// rendered from its own schema — it is the account of the run.
	Report string `json:"report,omitempty"`

	// Artifacts are the files the run made, if it made any.
	Artifacts []Artifact `json:"artifacts,omitempty"`

	// Incomplete is WHY it did not finish, in a person's words, and empty when
	// it did. Out of budget, out of time, a question nobody was there to answer,
	// a step that could not produce its shape: all of them end here, all of them
	// say what ran out. "incomplete" is one of the five sanctioned words for the
	// state of work, and nothing may reach a person calling this a failure.
	Incomplete string `json:"incomplete,omitempty"`

	// FellBack is set when the work was done the long way — the program's guards
	// did not pass, or it broke partway, and the general worker finished the job
	// with the original input. IT IS NOT A FAILURE AND MUST NOT BE DRAWN AS ONE:
	// the person is told the step needed a closer look and was handled the long
	// way. The value is the person-facing half of that sentence, drawn from the
	// guard's own Because line where it had one.
	FellBack string `json:"fell_back,omitempty"`

	// Spend is the whole run's ledger, which is the sum of its journal's
	// entries and can be nothing else.
	Spend Spend `json:"spend,omitzero"`
}

type Runner interface {
	// Manifest is everything true about this subharness before it runs. It
	// answers the name too, which is why there is no second Name method: a
	// runner whose name and whose manifest could disagree is a registry entry
	// filed under something it does not describe.
	Manifest() Manifest

	// Run does the work. The input is JSON matching the manifest's input schema;
	// the Env is the whole capability surface (env.go) and the only way to
	// spend. AN ERROR IS A RUN THAT COULD NOT BE MADE TO HAPPEN — a broken
	// bundle, a dead context — and is what the deoptimization path catches. A
	// run that HAPPENED and did not finish returns a [RunResult] with its
	// Incomplete reason set and no error at all.
	Run(ctx context.Context, input json.RawMessage, env Env) (RunResult, error)
}

type Scheduler struct {

	// Budget bounds the whole run's token spend, in prompt+completion tokens.
	// Zero means unbounded — each leaf still has its own budget. When the
	// cumulative spend passes it, no new node is launched; whatever is in
	// flight lands (mirroring the per-leaf landing reserve), never-started
	// nodes are marked, and Run reports the stop reason.
	Budget int

	// Escalations is how many times a failed leaf may be re-run on a stronger
	// model. Zero — the default — is exactly today's behaviour: a leaf that
	// fails, fails. It is only worth setting when there is somewhere stronger to
	// go, so the caller sets it from the panel rather than the scheduler
	// assuming one exists.
	//
	// Only verdicts that a better model could plausibly fix count: running out
	// of budget, running out of turns, returning nothing at all. A provider
	// failure is weather and a rate limit is not cured by spending more.
	Escalations int

	// NodeTimeout is the watchdog on a single node. The executor has its own
	// deadline, so this only fires when an executor is wedged past every
	// deadline it was given — a hung pipe, a stuck transport. The ending is
	// recorded as an [Abandoned] rather than letting one stuck goroutine freeze
	// the run silently and forever, and what that ending MEANS is decided in
	// [Scheduler.apply]: a node with a record goes back on the queue, and a node
	// that reached nothing is failed. Zero disables it.
	NodeTimeout time.Duration

	// BeforeLaunch applies process policy immediately before a leaf starts.
	// Returning an error stops new launches while already-running leaves land.
	BeforeLaunch func(context.Context) error

	// OnEvent reports state changes as they happen. A run is long and mostly
	// invisible; without this the only feedback is silence followed by a graph.
	OnEvent func(Event)
	// contains filtered or unexported fields
}

type Schema json.RawMessage

type SelfCloseFinding struct {
	// Kind is one of the four constants above.
	Kind string
	// Names is what the finding is ABOUT, in the reading's own words. A kind
	// alone sends a worker off to run a suite; the name is the diagnosis.
	Names []string
	// Fact is the finding without an instruction addressed to a worker that may
	// already have stopped. A handover needs this clause on its own, while
	// Sentence composes it with the move offered to a leaf still standing.
	Fact string
	// Sentence is the finding put to the leaf in the person-facing register: a
	// fact, then the one move that settles it, then the honest alternative —
	// because a measurement can be right about the tree and wrong about the
	// request, and a leaf told to obey a measurement it disagrees with will
	// invent work rather than say so.
	Sentence string
}

type SelfCloseRoom struct {
	// Turns, Tokens and Wall are what is left on each meter that BOUNDS this
	// belt. A belt that does not meter one of them leaves it at zero and says
	// so through the flag below rather than reading as exhausted — a belt with
	// no turn cap and no token ceiling reads zero on both, and reading that as
	// "out of turns" would silently switch the mechanism off for a whole belt.
	Turns  int
	Tokens int
	Wall   time.Duration
	// Left says every meter that bounds this leaf still has something on it.
	Left bool
	// Why is the meter that said no, for the record. Empty when Left.
	Why string
}

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

type ServiceRequest struct {
	JobID      int
	Name       string
	Command    string
	Dir        string
	Health     store.ServiceHealth
	LogPath    string
	PID        int
	StartedAt  time.Time
	LeafNodeID string
	// contains filtered or unexported fields
}

type Spend struct {
	// Model is what answered, as the PROVIDER reported it, and it is empty when
	// two calls disagreed — a run whose steps pinned models of their own is not
	// a run one name describes, and choosing one of them would be this package
	// stating a fact nobody gave it.
	Model string `json:"model,omitempty"`
	// Calls is every request made, the intermediate rounds of a tool loop
	// included. A call the provider reported no usage for is still counted: a
	// missing count is not a call that did not happen.
	Calls int `json:"calls,omitempty"`
	// Input and Output are the provider's token counts, with cache reads beside
	// the prompt count rather than inside it — the session's own accounting
	// keeps them in exactly this shape.
	Input  int `json:"input,omitempty"`
	Output int `json:"output,omitempty"`
	// CacheRead and CacheWrite are the prompt-cache accounting.
	CacheRead  int `json:"cache_read,omitempty"`
	CacheWrite int `json:"cache_write,omitempty"`
	// CostUSD is the provider's OWN figure, summed. Zero is "the provider did not
	// say", which is not the same fact as free — and under the emptiness law a
	// surface that cannot tell them apart draws nothing rather than $0.00.
	CostUSD float64 `json:"cost_usd,omitempty"`
	// contains filtered or unexported fields
}

type SplitPart struct {
	Title   string
	Summary string
	Brief   string
}

type SplitRequest struct {
	// Parts are the jobs the leaf believes it is holding, in no particular
	// order — a division exists to be run at the same time, and parts that have
	// an order are a sequence somebody has mislabelled.
	Parts []SplitPart
	// Evidence is what the leaf actually read or discovered that revealed the
	// division: the file it opened, the count it found, the shape of the thing
	// in front of it. It is here because a division decided from the assignment
	// alone is the division the build already made and refused; what makes this
	// one worth a round is that it was made against what is really there, and a
	// planner handed the request without the finding cannot tell the two apart.
	Evidence string
}

type StagedAttachments struct {
	// Documents and Images are workspace-relative, which is the spelling the
	// leaf's own tools take: read_document and view_image both address the
	// workspace.
	Documents []string
	Images    []string
	// ImageFiles are the same images as absolute paths, for the turn content a
	// model with eyes receives directly.
	ImageFiles []string
}

type StopReason string

type SubharnessInfo struct {
	Name    string `json:"name"`
	Purpose string `json:"purpose,omitempty"`
	// PriorAnchors is the capacity ruler in the style of plan/size.go's three
	// worked examples: comfortably atomic, borderline, oversized. A saved
	// program that measures differently from the generalist says so here.
	PriorAnchors string `json:"prior_anchors,omitempty"`

	// DeadlineFloor and the scaling pair are the budget shape. A leaf's hang
	// backstop is not a policy about patience, it is a claim about how long
	// this kind of work legitimately takes. Zero values fall back to the
	// generalist's shape, so a registration that says nothing about time is
	// served rather than refused.
	DeadlineFloor     time.Duration `json:"deadline_floor,omitempty"`
	DeadlineStep      time.Duration `json:"deadline_step,omitempty"`
	DeadlinePerTokens int           `json:"deadline_per_tokens,omitempty"`
}

type Task struct {
	NodeID int
	// NodeKey is the identity everything this leaf writes is filed under: its
	// artifact bucket, its flight recorder, its spilled observations, its
	// background job logs.
	//
	// It exists because NodeID is not always unique. A headless run's NodeID is
	// its plan node's number, which is unique within the graph — that path sets
	// nothing here and keeps the numeric spelling it has always written. The
	// resident surface has no such number: it holds a store node, whose creation
	// sequence belongs to the whole splice, so a four-part job handed four
	// workers one bucket, one recorder and one set of spill names. Siblings run
	// concurrently by construction, so that is not a naming inelegance — it is
	// one worker's spilled observation overwritten by another's while a stub in
	// its context still points at the file.
	//
	// Empty falls back to NodeID, which is what keeps every existing headless
	// path byte-identical. See [Task.leafKey].
	NodeKey string
	// StoreNodeID is the durable provenance anchor used when a background job
	// requests promotion. One-shot execution leaves it empty.
	StoreNodeID string
	Title       string
	Goal        string // the whole plan's goal, for orientation
	Brief       string // the self-contained instruction: what the job is
	Contract    string // the working method: how this kind of job is done well
	// Spec is the same job as the object the planner authored, carried whole.
	// Brief and Contract above are two of its fields and remain what this
	// executor reads; the object is here for the worker that can be handed a
	// spec directly instead of prose reassembled at the boundary. An empty
	// Spec renders to the empty string and changes nothing.
	Spec   plan.Spec
	Inputs []Input
	// OutputHint is where a file goes if this work needs one. It is an
	// address, never an instruction: what a leaf owes is its final message,
	// and a path offered as though a document were expected is how a job came
	// to leave 07-pr-482-code-review.md, 70-read-diff.md and 144-synthesis.md
	// in a person's own directory.
	OutputHint string
	// Intermediate says this leaf's result is consumed by later work rather
	// than read by the person who asked. Its handoff is its final message, so
	// it is offered no deliverable path at all — OutputHint, when it carries
	// anything, names the run's own scratch.
	Intermediate bool
	// ImagePaths are user-supplied inputs attached to the initial leaf turn.
	ImagePaths []string
	// DocumentPaths are user-supplied documents already staged in the
	// workspace. The brief names them; this is the same fact in structural
	// form, and it is what arms the document reader before turn 1 instead of
	// making the leaf spend a turn asking for a tool it demonstrably needs.
	DocumentPaths []string
	// Reflex constrains the general loop to one obvious micro-action and gives
	// it an explicit promotion verdict when the assignment is larger than it
	// first appeared.
	Reflex bool

	// Fold says this leaf's material is entirely in Inputs above, whole, and
	// that its job is to assemble it — so the loop runs it as a fold: one model
	// call, and a second only if the first asked for a tool or produced nothing
	// deliverable. See foldTurns.
	//
	// It is set by whatever assembled this task, from two structural facts it
	// can check and this package cannot: that the plan gives this node nothing
	// to go and find (plan.Folds), and that every dependency arrived pushed
	// rather than clipped to a handle. The second is what makes the first safe —
	// a node told to assemble material it was only handed a pointer to has to go
	// and get it, whatever its plan says.
	Fold bool

	// Subharness names the worker this leaf was routed to. It is carried on the
	// task rather than looked up again at dispatch because the choice was made
	// once, upstream, and journaled: the scheduler's job is to honour it, not to
	// re-decide it. Empty is the generalist, which is nearly every leaf.
	Subharness string

	// Skills is the ordered list of skill names attached to this leaf's brief:
	// the plan composed them from the shelf (pinned first), and the brief
	// renders them beside the working method. Empty renders nothing.
	Skills []string

	// Steer, when set, is polled between turns for mid-flight guidance from
	// the user. Each returned line lands in the transcript as a user message
	// before the next model call, so a running worker can be redirected
	// without being killed. Nil (the default, and the whole one-shot path)
	// costs nothing.
	Steer func() []string
	// Share, when set, gives the worker a one-line channel to the rest of its
	// job: a discovery about the material, a pitfall, a decision siblings must
	// match. It is nil for a job with no siblings, so a single-worker errand
	// never pays the schema for a channel with nobody on the other end.
	Share func(line string) error
	// Board is the reading side of Share: polled at the same between-turn
	// boundary as Steer, it returns lines other workers on this job shared.
	// They land in the transcript in their own voice, never the user's — a
	// sibling's discovery is testimony, not instruction.
	Board func() []string
	// Control is polled at the same between-turn boundary as Steer. It is
	// deliberately cooperative: a model/tool turn already in flight lands,
	// then the claim owner releases through the store CAS path.
	Control func() ControlAction

	// Progress is within-node visibility: where the work has got to, said in a
	// way that replaces the last thing it said rather than adding to it.
	//
	// It exists for the leaf that is long and whose insides are not nodes. A
	// linear leaf is a turn loop nobody watches and passes nil; a saved program
	// that runs a pipeline for forty minutes would otherwise be a spinner, and
	// the two alternatives to this are both worse — splicing its stages into
	// the graph would put work in the plan that nobody planned, and posting
	// them as thread messages would spend the person's attention on a running
	// pipeline. phase is the coarse thing being done, done/total are a count
	// when there is one, and latest is the short right-hand side. Nil-safe and
	// ignored when nil, so no existing caller pays anything for it.
	Progress func(phase string, done, total int, latest string)

	// Fault carries a recovered panic out to whoever can write it down.
	//
	// It exists because guard.Note's whole record is a line in a log file, and a
	// caught fault is a fact about the run that changes what the person watching
	// should expect. In the crashed run of 2026-08-28 a leaf faulted, was
	// escalated two seconds later, and the headless stream said `still waiting`
	// for eleven minutes; the operator read it as a hang. The surface that owns
	// the journal is the one that can journal it, so the leaf-running code
	// reports and the surface records. Nil-safe and ignored when nil, so a
	// caller with nowhere to write pays nothing.
	Fault func(error)
	// contains filtered or unexported fields
}

type TaskInput struct {
	// Brief is the self-contained instruction and the one required field. A leaf
	// with no brief has been handed nothing to do.
	Brief string `json:"brief"`
	// Goal is the whole plan's aim, for orientation. Empty where there is no
	// wider plan, which is every direct invocation.
	Goal string `json:"goal,omitempty"`
	// Contract is the working method — how this kind of job is done well.
	Contract string `json:"contract,omitempty"`
	// Title is what the work is called on a roster row.
	Title string `json:"title,omitempty"`
}

type TaskOutput struct {
	Result    string   `json:"result"`
	Artifacts []string `json:"artifacts,omitempty"`
}

type ToolResult struct {
	Text string
	JSON json.RawMessage
	// Spend is what the call cost where a tool spends model tokens of its own.
	// Most tools spend nothing and leave it zero.
	Spend Spend
}

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

type TranscriptJournal interface {
	RecordTranscript(nodeID, model string, entries []store.TranscriptEntry) error
}

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

type TranscriptSink interface {
	Record(entry store.TranscriptEntry)
	Flush()
}

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

type TurnUsage struct {
	// Turn is the leaf's own turn number, counting from one.
	Turn int `json:"turn"`
	// Usage is this turn's whole bill, model call and tools together.
	Usage
	// Sent is in_k: what this turn's own model call put on the wire, the whole
	// prompt including the part the provider served from cache. Summed across
	// turns it is the leaf's cumulative context pressure — the quantity a
	// per-turn window bound cannot see because no single turn is large, and a
	// cache-discounted spend meter cannot see because most of it was cheap.
	Sent int `json:"sent"`
}

type UnwiredEnv struct{}

type Usage struct {
	Calls            int     `json:"calls"`
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	CachedTokens     int     `json:"cached_tokens"`
	Cost             float64 `json:"cost"`
}

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

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