friend

type ActivityLimits struct {
	Files int
	Time  time.Duration
}

type Agent struct {
	Friend, Harness, Dir, Session string
	Adapter, DeliveryDir          string   // explicit Codex folder route; session remains the real harness session
	StateDir                      string   // the daemon's state files, when not the default under Home
	Binary                        string   // this tool, by absolute path
	Copy                          CopyFile // places a removable-volume binary under Home; nil refuses it
	Redis, Server                 string   // the bus store and the sprint server
	Home, Path                    string   // the environment the agent runs in
	LaunchdLog                    string   // launchd's own stdout and stderr path, off the friend's volume
	// Secrets are the names of the secrets the daemon needs in its environment
	// (never values); with any, the command is wrapped in nova-secrets exec as
	// the seat Seat, with SecretsTool and Sops by absolute path, the store under
	// Home/nova-bench/secrets and the key under Home/.config/nova-secrets.
	Secrets                 []string
	Seat, SecretsTool, Sops string
	// Coordinator, SilentStop and BrokenAfter are the daemon's flags of the
	// same names, written only when set and not the default.
	Coordinator string
	SilentStop  time.Duration
	BrokenAfter int
	// ConfigDir is the friend's harness config directory (CLAUDE_CONFIG_DIR),
	// the daemon's --config-dir, written only when set.
	ConfigDir string
	// Pronouns are the friend's pronouns (the row's pronouns setting), the daemon's --pronouns,
	// written only when set.
	Pronouns string
	// DenySelf is the coordinator's self the daemon's lane wall never writes inside, the
	// daemon's --deny-self, written only when set (the daemon's default, DefaultDenySelf,
	// stands when it is not).
	DenySelf string
	// WallReads is what the harness reads inside the lane's wall beyond the system roots and its
	// own directory (a pinned harness shim under the home), the daemon's --wall-reads, written only
	// when set.
	WallReads string
	// Command, when set, is what the agent runs in place of the daemon: this tool's
	// own verb and flags, after Binary.
	Command []string
	// Sleep is how Install waits between two looks at the old service after the
	// bootout (ReleasePoll); nil is time.Sleep. A test passes its own clock.
	Sleep func(time.Duration)
}

type AgentAPIRefusal string

type Antigravity struct {
	Dir, Session string
	Run          Exec
	Out          io.Writer                  // the daemon's record, when set
	Home         string                     // the user's home ($HOME when empty): app data under Home/.gemini/antigravity
	User         string                     // daemon's username (current process user when empty)
	FS           fs.FS                      // rooted at Home (os.DirFS(Home) when nil): the mailbox is read through it
	Wait         func(context.Context) bool // one poll interval; false once ctx has ended (real time when nil)
	Now          func() time.Time           // the daemon's clock, every time in the ledger (time.Now when nil)
	State        string                     // the daemon's state directory: the ledger's file (AntigravityLedgerFile); "" keeps it in memory
	// contains filtered or unexported fields
}

type AntigravityDelivery struct {
	ID           string    `json:"id"`
	Conversation string    `json:"conversation"`
	DeliveredAt  time.Time `json:"delivered_at"`
	ReadAt       time.Time `json:"read_at,omitzero"`
	ResentTo     string    `json:"resent_to,omitempty"`
	Text         string    `json:"text,omitempty"`
}

type AntigravityLedger struct {
	Followed   string                `json:"followed,omitempty"`
	From       string                `json:"from,omitempty"`
	Since      time.Time             `json:"since,omitzero"`
	Deliveries []AntigravityDelivery `json:"deliveries"`
}

type AskedRead struct {
	ID     string
	Epoch  string
	Gen    int // the read card's generation as the queue carries it (0: a queue before it); a stop-return names it
	Packet ReadPacket
	Col    string // its column on the reader queue (asked, reading)
	Lane   int    // the read lane the server says holds it (take --as reader-<friend> --lane <n>); 0 none
}

type BeatWords struct {
	StopReturns int
}

type BusFacts struct {
	Friend    string `json:"friend"`
	RealSince int    `json:"real_since"`
	LastReal  string `json:"last_real"` // RFC3339 or "-"
}

type Card struct {
	ID     string `json:"id"`
	Brief  string `json:"brief"`
	Outbox string `json:"outbox"`
	// Lane, ServerEpoch and ServerGen are what the server's answer to a lane's ask named
	// (lane_take.go): the lane that holds the card, the epoch and the generation it holds it
	// at. A card a lane holds is reported by these, never by its directory's name.
	Lane        int    `json:"lane,omitempty"`
	ServerEpoch string `json:"server_epoch,omitempty"`
	ServerGen   int    `json:"server_gen,omitempty"`
}

type CardRunner interface {
	Deliverer
	// RunCard runs card c to its end: its exit, and an error naming what the
	// outbox lacks when the run wrote no REPORT.md or RESULT.md there.
	RunCard(ctx context.Context, c Card) (LaneTurn, error)
	// Refusal is why no card can run now, with its remedy; empty when one can.
	Refusal() string
}

type CardUsage interface {
	Tokens(ctx context.Context) (Tokens, error)
}

type CheckReport struct {
	Friends []FriendCheck `json:"friends"`
	Summary CheckSummary  `json:"summary"`
}

type CheckResult struct {
	Harness string        `json:"harness"`
	Nonce   string        `json:"nonce"`
	Stage   string        `json:"stage,omitempty"`
	Why     string        `json:"why,omitempty"`
	Took    time.Duration `json:"took"`
}

type CheckSeams struct {
	Now         func() time.Time
	Home        string
	Launchctl   Launchctl
	ReadStatus  func(friend string) (Status, bool, error)
	ReadHook    func(friend string) (HookRecord, error) // her nova-hook record; nil reads none
	ReadLog     func(friend string) ([]string, error)
	BusLog      func(ctx context.Context, friend string, since time.Time) (realCount int, lastReal time.Time, err error)
	ReadWork    func(friend string, dir string) (inboxCount, outboxCount int, newestName string, newestAt time.Time, err error)
	ListFriends func() ([]string, error)
	HarnessDir  func(friend string) (harness, dir string, err error)
}

type CheckSummary struct {
	Friends int `json:"friends"`
	OK      int `json:"ok"`
	Broken  int `json:"broken"`
	Down    int `json:"down"`
	Untrue  int `json:"untrue"`
}

type Claude struct {
	Stub
	Friend, Dir string
	// ConfigDir is the friend row's config_dir as the daemon last read it;
	// nil or empty refuses every card.
	ConfigDir func() string
	Run       Exec
	Program   string           // "claude" when empty
	Out       io.Writer        // where the run's output goes, when set: the daemon's record
	Now       func() time.Time // time.Now when nil: the clock a limit's reset is read against
	// TokenCap is the friend row's per-card token cap as the daemon last read
	// it (TokenCapOf; 0 none); nil is DefaultTokenCap (tokencap.go).
	TokenCap func() int64
	// contains filtered or unexported fields
}

type ClaudeWake struct {
	Dir, Name string
	Now       func() time.Time // time.Now when nil
	Out       io.Writer        // the daemon's record, when set
}

type Conformance struct {
	Friend, Harness string
	Deliver         Deliverer
	Store           bus.Store
	Within          time.Duration
	Now             func() time.Time
	Wait            func(ctx context.Context) bool // one CheckPoll; false once ctx has ended
	Nonce           func() string
	Text            func(nonce string) string // the session check as the session reads it (SessionCheckText)
}

type CopyFile func(src, dst string) error

type Courier struct {
	// Bus is the bus every send goes on; Open, when set, dials one for each
	// send instead (the server's way: one connection per note) and its
	// failure is watched like a send's.
	Bus   *bus.Bus
	Open  func(ctx context.Context) (*bus.Bus, func(), error)
	Watch *bus.Watch
	Now   func() time.Time
}

type DSH struct {
	Dir, Session string
	Run          Exec
	Program      string    // DSHProgram when empty
	Sessions     string    // the sessions root; DSH_HOME/sessions, else ~/.dsh/sessions, when empty
	Out          io.Writer // where the turn's output goes, when set: the daemon's record
	// contains filtered or unexported fields
}

type Daemon struct {
	Friend, Harness, Dir string
	// Pro holds the friend's pronouns (the row's pronouns setting): every text the daemon
	// writes about the friend says them through d.say. Nil is they/them.
	Pro              *PronounsRef
	Notices          *Notices
	Store            bus.Store
	Deliver          Deliverer
	Beat             func(ctx context.Context, active time.Time) error // one beat to the sprint server, carrying the session's last activity (zero: none known)
	StepBeatForTests bool                                              // deterministic fake-clock seam; production has one independent beat caller
	// Activity is the newest write of the session's files, read by the
	// independent beat cadence at most once an ActivityEvery and carried on
	// each beat; nil knows no write.
	Activity func() time.Time
	Now      func() time.Time
	// Pause waits between lane steps while the independent beat continues.
	Pause  func(ctx context.Context, d time.Duration)
	Record func(line string) // one line per delivery, to the daemon's log
	// MachineStopped says the machine's word, as the owner last read it off the beat's
	// answer (ParseMachine), is STOPPED: the lanes cancel what runs, owe and send
	// stop-returns, and start nothing (stop.go). nil: never stopped.
	MachineStopped func() bool
	// StopReturn sends one stop-return (StopReturnArgv) to the sprint server; nil sends it
	// through Sprint.
	StopReturn func(ctx context.Context, argv []string) error

	// Limited is the harness's limit now: its kind and reset, and whether there is one
	// (Limits.Limited, Limits.Kind); nil: none. While there is one the status says
	// session=limited with them, and the turns the Gate defers stay pending.
	Limited func() (kind string, until time.Time, limited bool)
	// Status receives the daemon's state whenever it changes, and every
	// StatusEvery (WriteStatus over the state files).
	Status func(Status) error
	// SilentStop is how long a running turn may print nothing before it is
	// stopped (DefaultSilentStop when zero); BrokenAfter how many turns in a
	// row the provider refuses the same way before the session is broken
	// (DefaultBrokenAfter when zero); Coordinator who is told of a broken
	// session when the sprint server names no seat.
	SilentStop  time.Duration
	BrokenAfter int
	Coordinator string
	// Row is the friend's nova-config row as the daemon last read it (from
	// its beat): her delivery mode (ModeBatch or ModeOneShot) and width,
	// read every step so a change takes effect without a restart; nil, or
	// empty answers, deliver in batch, and a width of 0 runs no lane: the width
	// is nova-config's alone, answered by the server (row).
	Row func() (mode string, width int)
	// Pacing is the row's pacing as the daemon last read it: the fraction of each
	// subscription window the lanes may spend, read every step; nil, or out of
	// (0, 1], is DefaultPacing (pacing.go). No beat carries the row's pacing yet,
	// so nova-friend leaves it nil.
	Pacing func() float64
	// LaneCaps is the row's wall cap of a lane's card by its tier as the daemon last read
	// it (ParseLaneCaps off its beat), read every step; nil, or a tier it names none for,
	// is DefaultLaneCaps (lane_cap.go).
	LaneCaps func() map[string]time.Duration
	// LoadLanes and SaveLanes let tests carry lane state between loop instances.
	// Production keeps that state in memory; the sprint server owns lane records.
	LoadLanes func() (LaneState, error)
	SaveLanes func(LaneState) error
	// CardDone is the one bus line a lane's session sends when its card is
	// done (nova-bus send by path, as this friend, to the coordinator).
	CardDone func(card, to string) string
	// Progress stamps progress on the cards whose lane turn printed (ProgressArgv to the
	// sprint server); nil stamps none.
	Progress func(ctx context.Context, cards []Card) error
	// Finish sends one finish verb to the sprint server: a lane's card whose run ended with
	// no REPORT.md (FinishArgv, lane_end.go), and every working card on her row whose job's
	// REPORT.md says a verdict, whoever wrote its brief (OutboxFinishArgv, outbox.go). Nil,
	// or a finish not answered, leaves it to friend sync, which reads the same REPORT.md.
	Finish func(ctx context.Context, argv []string) error
	// Take sends one take to the sprint server (LaneTakeArgv), its refusal an
	// error: a lane starts a card only once the server has it working on her row (lane_take.go).
	// Nil (a test's world) takes nothing, and a lane runs any card on her row as before.
	Take func(ctx context.Context, argv []string) (string, error)
	// The lanes' parity with the runner scripts they replace (lane_parity.go); Rules nil
	// turns every one off. Rules is her row's lane rules as her beat last answered them,
	// Load the machine's one-minute load (nil: no load rule), Tokens a session's tokens
	// from opencode's database (nil: no cost and no token cap), Route the store's route row
	// for her model and Model its name, LaneHold the pause marker's line (the lanes held
	// down by a provider failure until a person clears it) and LaneHoldDown writes it: her
	// beat then says her down with its message (PauseBeat).
	Rules        func() LaneRules
	Load         func() float64
	Tokens       func(ctx context.Context, session string) (LaneTokens, error)
	Route        func() RoutePrice
	Model        string
	LaneHold     func() string
	LaneHoldDown func(ctx context.Context, message string) error
	// Fault is the lane's provider-refusal fault report in the state directory
	// (ReadLaneFault), and FaultWrite records or clears it (WriteLaneFault): the
	// loop's poll sees a fault it holds whose file a person cleared and releases
	// the lanes, and a stale file a restart cleared. The friend's main wires it
	// to the state directory; nil (a test's world) leaves the fault in memory
	// only, cleared by a restart (docs/SPEC-FRIEND.md, the lanes).
	Fault      func() string
	FaultWrite func(report string) error
	// FaultExternal is a lane fault the limit detector counted itself (lanes
	// failing alike): the loop adopts it as the same record a provider's refusal
	// writes, then clears it. The friend's main wires it to the detector; nil:
	// no such fault.
	FaultExternal func() string
	// FaultDown marks her row down until until with reason: the same harness fault
	// FaultRepeats times within FaultWithin on her lanes (lane_parity.go); her beat says
	// her down with them until then (friend beat --until --reason). Nil: her lanes are
	// held here alone.
	FaultDown func(until time.Time, reason string)
	// RefusalDown marks her row down until until with reason: a server that refused one
	// of her verbs RefusalRepeats times in a row (inbox.go, "A refused verb"). RefusalUp
	// clears it when the server answers again. Nil: the refusal is said, never beaten down.
	RefusalDown func(until time.Time, reason string)
	RefusalUp   func()
	// Prove runs the harness's cheapest no-tool turn and answers its terminal reason
	// (harness_proof.go): "" when the harness can answer, the reason when it cannot. Nil
	// proves nothing (every harness can answer; a test's world). Until it answers, the
	// daemon takes no card, beats down with the reason, tells the coordinator once, and
	// re-proves every ServedEvery (docs/SPEC-FRIEND.md, "A lane proves its harness").
	Prove func(ctx context.Context) string
	// Held is every card on her row as the sprint server says it (HeldVia: friend cards
	// <friend>, else the worker view), asked once an InboxEvery; her inbox is reconciled with
	// the answer (SyncInbox, inbox.go). Nil leaves her inbox to friend sync alone.
	Held func(ctx context.Context) (Row, error)
	// Sprint sends one verb to the sprint server and answers what it printed: the reader row's
	// queue, begin, verdict and return (read_lanes.go). Nil runs no reads. ReadSlots is the
	// row's read slots, read each step (nil: DefaultReadSlots), and ReadModel the model of a
	// read's tier ("": the harness's own).
	Sprint    func(ctx context.Context, argv []string) (string, error)
	ReadSlots func() int
	ReadModel func(tier string) string
	// Stage stages a held work card's job (Stager.Stage: jobs/<job>/repo and its JOB.md) and
	// answers the commit staged (stage.go); nil stages none, and a lane is handed a card with
	// its brief alone.
	Stage func(ctx context.Context, p Packet) (string, error)
	// Prune removes finished jobs' worktrees past FinishedJobsKept (Stager.Prune), given the
	// jobs that are live (held on her row, run by a lane, being staged), after each inbox
	// cleanup, and answers the jobs it removed; nil prunes none.
	Prune func(ctx context.Context, live map[string]bool) ([]string, error)
	// Tip is origin's tip of a branch of a repository (owner/name), "" when origin has no
	// such branch (Stager.Tip: one git ls-remote): a report's LAND finishes only at that tip,
	// as nova-sprint collect's does (outbox.go). Nil reads none, and a LAND finishes at its
	// Head.
	Tip func(ctx context.Context, repo, branch string) (string, error)
	// Running is the beat's running list as the sprint server last said it, every friend's:
	// a card id or job to the friend whose lane runs it. A lane is never started for a card
	// it names another friend running, and a lane whose card left her row names its friend
	// on the job's lane mark (one_lane.go). Nil says none; the lane marks still hold.
	Running func() map[string]string
	// Holders reads the server's current card-to-holder map (view cards), once
	// per outbox pass that finds a report outside her row. Nil uses Running's
	// known holders; an error refuses with the explicit unknown-holder remedy.
	Holders func(ctx context.Context) (map[string]string, error)
	// Seat is the coordinator seat holder as the sprint server says it: who the
	// daemon tells (coordinator), else Coordinator. An error, an empty name or a
	// nil Seat is the seat unknown.
	Seat func(ctx context.Context) (string, error)
	// contains filtered or unexported fields
}

type DaemonFacts struct {
	Friend   string `json:"friend"`
	Agent    string `json:"agent"`    // loaded, not-loaded, none
	PID      string `json:"pid"`      // numeric string or "-"
	Status   string `json:"status"`   // the daemon's status file: ok, stale, none
	Hook     string `json:"hook"`     // the hook record's state (none, armed, proven, unhooked, ...), or "-" when not read
	Since    string `json:"since"`    // how long it has been in it, e.g. "4m", or "-"
	Answer   string `json:"answer"`   // the age of her model's last answer to a challenge, or "-"
	Misses   int    `json:"misses"`   // challenges in a row left unanswered
	Presence string `json:"presence"` // up while the record proves her there, else down
	Reason   string `json:"reason"`   // why the record reads down, or "-"
}

type Deferred struct{ Reason, Remedy string }

type Deliverer interface {
	Deliver(ctx context.Context, text string) (exit int, err error)
}

type Entry struct {
	Kind   string // KindDir, KindFile, KindSymlink or KindMissing
	Target string // a symlink's target
}

type Evidence struct {
	DaemonUp    bool       // the daemon's status file is fresh; shown, never deciding up
	Hook        HookRecord // her nova-hook record: the one truth of whether she is there
	Limit       string     // the limit's name, when the provider said one
	LimitUntil  time.Time  // the limit's reset; zero, or past, is no limit
	Undelivered int        // messages waiting on the friend's stream; negative is not counted
	BusBlocked  string     // why the bus cannot deliver to the friend; empty when it can
	LastResult  time.Time  // the end of the last turn; zero is none yet
	LastExit    int        // that turn's exit
}

type Exec func(ctx context.Context, dir, name string, args []string, stdin string) (stdout string, exit int, err error)

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

type Folder struct {
	Dir, Session, Friend, WorkDir string
}

type FriendCheck struct {
	Friend  string       `json:"friend"`
	Daemon  DaemonFacts  `json:"daemon"`
	Harness HarnessFacts `json:"harness"`
	Bus     BusFacts     `json:"bus"`
	Work    WorkFacts    `json:"work"`
	Verdict VerdictFacts `json:"verdict"`
}

type GUIWindow struct {
	Bundle    string
	Run       Exec
	Permitted func(ctx context.Context) (bool, error)
}

type Gemini struct {
	Dir, Session string
	Run          Exec
	Program      string    // "gemini" when empty
	Out          io.Writer // where the turn's output goes, when set: the daemon's record

}

type Grok struct {
	Dir  string    // the friend's directory: the session's cwd
	Wake string    // the wake file, when named; else the one the session's monitor tails
	Run  Exec      // runs ps
	Out  io.Writer // the daemon's record, when set
	Home string    // the grok home, ~/.grok when empty
	// contains filtered or unexported fields
}

type HarnessFacts struct {
	Friend         string `json:"friend"`
	Harness        string `json:"harness"`
	Route          string `json:"route"` // push, mailbox, queue or passive
	Last           string `json:"last"`  // RFC3339 or "-"
	LastExit       string `json:"last_exit"`
	FailedOfLast20 int    `json:"failed_of_last20"`
	Deferred       int    `json:"deferred"`
	Delivered      int    `json:"delivered"` // deliveries in the window (JSON only)
	Failed         int    `json:"failed"`    // of those, the ones that failed (JSON only)
	Broken         string `json:"broken"`    // RFC3339 or "-"
	Reason         string `json:"reason"`    // one line or "-"
}

type HarnessSettings struct {
	Harness, Friend, Dir string
	Home                 string // the friend's home: ~ of every default below
	StateDir             string // the daemon's state directory; DefaultStateDir when empty (grok's default wake file)
	Wake                 string // grok: the wake file the session's monitor tails; <state>/<friend>.wake when empty
	ConfigDir            string // claude: CLAUDE_CONFIG_DIR, the friend's own config directory
	Model                string // opencode: the model, provider/model; empty leaves it alone
	CodexHome            string // codex: CODEX_HOME; Home/.codex when empty
	DSHHome              string // dsh: DSH_HOME; Home/.dsh when empty
	FS                   SettingsFS
}

type HeldAnswer struct {
	Friend string     `json:"friend"`
	Cards  []HeldCard `json:"cards"`
}

type HeldCard struct {
	Card    string `json:"card"`
	Job     string `json:"job"`
	Col     string `json:"col"`
	Kind    string `json:"kind,omitempty"`
	Branch  string `json:"branch,omitempty"`
	Tier    string `json:"tier,omitempty"`
	Stream  string `json:"stream,omitempty"`
	Attempt int    `json:"attempt,omitempty"`
	Gen     int    `json:"gen,omitempty"`
	Epoch   uint64 `json:"epoch"`
	Repo    string `json:"repo,omitempty"`
	Base    string `json:"base,omitempty"`
	Brief   string `json:"brief"`
	// Lane is the lane of her row the server says holds the card (take --lane), 0 for none.
	Lane int    `json:"lane,omitempty"`
	Why  string `json:"-"`
}

type HookRecord struct {
	State      string    // none, armed, proven, unhooked, ...; "" when not read
	Since      time.Time // when it was hooked, or unhooked; zero when never
	LastAnswer time.Time // when her model last answered a challenge; zero is never
	Misses     int       // challenges in a row left unanswered
	Down       string    // why it reads down whatever its state (unhooked, no server, no answer), "" when it stands
	ReadError  string    // why the record could not be read; "" when it was
}

type HostRefused struct{ Session string }

type HostResult struct {
	Session, Attach, Line string
}

type HostSpec struct {
	Name, Dir string
	Command   []string
	DryRun    bool
}

type Hosted struct {
	Session string `json:"session"`
	Harness string `json:"harness"`
	Prompt  string `json:"prompt"`
}

type InboxCounts struct {
	Held, Inbox, Missing int
}

type LaneEnd struct {
	Exit     int
	Err      string        // the harness's error, when the run did not end with an exit
	Wall     time.Duration // the run's wall, its start to its end
	Cap      string        // the cap that stopped it, when one did
	Rejected string        // a permission the harness refused
	Turns    int           // the turns the card had in the lane
	Restart  time.Time     // not zero: the run was found gone by a daemon starting up at this time
	Started  time.Time     // when the lane began the card
	NoReport bool          // the run wrote RESULT.md and no REPORT.md
	// Capped is the card's wall cap by its tier when the lane ended the card at it
	// (lane_cap.go), Tier that tier, Overrun the card's wall past the cap at its end, and
	// Tail the last CapTailLines lines of the lane's output.
	Capped  time.Duration
	Tier    string
	Overrun time.Duration
	Tail    string
}

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

type LaneGovernor struct {
	Rand func() float64   // pseudo-random in [0, 1); nil is math/rand/v2.Float64 (docs/SPEC-FRIEND.md #rate-limit-backs-off-not-down.w1)
	Now  func() time.Time // clock; nil is time.Now
	// contains filtered or unexported fields
}

type LaneHarness interface {
	Deliverer
	// OpenSession starts a new session of the friend with seed as its first
	// turn, and answers the new session's id.
	OpenSession(ctx context.Context, seed string) (session string, err error)
	// DeliverTo pushes text into session as one turn and blocks until it
	// ends: its exit, and a permission the harness refused without asking,
	// read from the turn's output (empty when none). A rate limit is
	// RateLimited and out of funds OutOfFunds (ProviderLimit); a provider's
	// refusal is ProviderRefused, as Deliver answers it.
	DeliverTo(ctx context.Context, session, text string) (LaneTurn, error)
}

type LaneHold struct {
	Lane  int
	Epoch uint64
	Card  string
	Gen   int
	Kind  string
	Job   string
}

type LaneJob struct {
	Dir   string // <friend dir>/jobs/<job>: the harness's working directory
	Card  Card   // Brief and Outbox absolute
	Brief string // the brief's text, inline in the prompt; "" when it is not read yet
}

type LaneMark struct {
	Who   string
	At    time.Time
	Ended bool
}

type LaneRules struct {
	Tiers     []string // row_tiers=flash,pro: the tiers she works; a dealt card of another tier is taken back; none: every tier
	Streams   []string // row_streams=security*,fp-sec*: patterns a card's stream or id must match; none: every card
	TokenCap  int64    // row_token_cap=<n>: tokens one card may spend, all kinds; 0 none
	LoadMax   float64  // row_load_max=<load>: above this one-minute load the lanes are held to LoadWidth; 0 none
	LoadWidth int      // row_load_width=<n>: lanes while the load is above LoadMax; DefaultLoadWidth when unset
	PauseOn   string   // row_pause_on=funds|any: funds (the default) holds only for out of funds; any holds for a rate limit too
	RefuseGo  bool     // row_refuse_go=1: the lane's PATH carries go and gofmt that refuse
}

type LaneState struct {
	Sessions map[int]string     `json:"sessions"`
	Epoch    uint64             `json:"epoch,omitempty"`
	GivenUp  []string           `json:"given_up,omitempty"`
	Started  map[string]Started `json:"started,omitempty"`
	// StopReturns is every card the machine's stop took out of a lane and the stop-return
	// owed or taken for it (stop.go): the next loop pass sends what is owed first.
	StopReturns []StopReturn `json:"stop_returns,omitempty"`
}

type LaneTokens struct {
	cardcost.Tokens
	USD      string // opencode's own reported cost, a decimal; "" unknown
	Sessions int
}

type LaneTurn struct {
	Exit     int
	Rejected string // the line of the output where the harness refused a permission, if any
	// Windows is the subscription windows' use the harness reported in the turn
	// (a Claude Code run's rate_limit_event lines, ReadRateLimitEvents); nil when
	// it reported none. The lanes are paced by it (pacing.go).
	Windows []WindowUse
	// FirstError is the first line of the turn's output that says an error
	// (HarnessFirstError), "" when none does: a run that exits 0 with no report
	// is a harness fault said with it (lanes.go, faultTurn).
	FirstError string
}

type LaneVerdict int

type Launchctl func(ctx context.Context, args ...string) (output string, err error)

type Limit struct {
	Limited bool
	Until   time.Time
	Reason  string
	Usage   Usage
	Overage bool
}

type LimitHit struct {
	Kind   string
	Until  time.Time
	Named  bool
	Reason string
}

type Limits struct {
	Now  func() time.Time
	Down func(until time.Time, reason string)
	Up   func()
	// Notice is the single coordinator message for a detected limit episode.
	// unread asks it to include the unread-reset judgment in that message.
	// A funds refusal delegates its notification to Funds when configured.
	Notice func(until time.Time, reason string, unread bool)
	// Unread is the judgment when a limit's text names no reset this reads: the
	// friend is held for Rest and the text goes to the coordinator, once until
	// a turn runs clean, so the reset is set by a person (friend down --until)
	// and not guessed again each Rest (usage-limit-reset-read-from-the-message-b.w1).
	Unread func(text string)
	// Funds, when set, is handed a failed turn's own wording of a provider
	// refusal for funds with no reset to wake at (an insufficient balance, a
	// 402): the reason (ratelimit.ProviderLimit's rule, one layer up). The
	// daemon wires it to the spend cap, so the refusal stops the turns at once
	// with the spend-cap judgment instead of the limit's own Rest retry
	// (docs/SPEC-FRIEND.md, spend caps).
	Funds func(reason string)
	// Harness is the harness whose own wording a failed turn is read in
	// (ParseLimit), and Rest how long it is down when the text names no
	// reset (DefaultLimitWait when zero): --limit-rest.
	Harness string
	Rest    time.Duration
	// AllowOverage is the owner's word that this friend may spend paid
	// overage; without it a harness on overage reads down.
	AllowOverage bool
	// Pacing is the row's pacing (the fraction of each subscription window the
	// sprint may spend), read at each batch turn; nil, or out of (0, 1], is
	// DefaultPacing. Every output's rate_limit_event feeds the pacer, and a batch
	// turn while a window is at the pacing is Deferred until it resets
	// (pacing.go).
	Pacing func() float64
	// contains filtered or unexported fields
}

type LogFacts struct {
	Last           string // RFC3339 of the newest delivery in the window, or "-"
	LastExit       string // its exit, or "-"
	FailedOfLast20 int    // failures among the newest 20 deliveries in the window
	Deferred       int    // deferrals in the window
	Delivered      int    // deliveries in the window
	Failed         int    // of those, the ones that exited non-zero
}

type NoReport struct {
	Run    string // the harness as the run names it, "claude -p"
	Exit   int
	Outbox string
	Lacks  []string // the files the outbox lacks
}

type NotServed struct{ Why string }

type NotStageable struct {
	Repo, Card, Why, Remedy string
	Job                     string // the job it was staging, when there was one
}

type Notices struct {
	Bus    *bus.Bus
	To     func(context.Context) (string, error)
	Record func(string)
	Now    func() time.Time           // nil uses the monotonic process clock
	Wait   func(context.Context) bool // nil waits one second; false means cancelled
	// contains filtered or unexported fields
}

type OSFS struct{}

type OpenCode struct {
	Dir, Session string
	Run          Exec
	Program      string    // "opencode" when empty
	Out          io.Writer // where the turn's output goes, when set: the daemon's record
	// Allow is every other path the friend's directory is reached by (a
	// symlink in the home directory): with Dir and its real path, allowed in
	// the project config before a turn (AllowDirs), so a headless run never
	// auto-rejects a tool call there. Nil: the config is left alone.
	Allow []string
	// Standalone passes --standalone to every run: opencode 2.0.25 (the
	// background service, 2026-10-09) makes `opencode run` attach to a shared
	// background service (`opencode serve --service`, started once, detached)
	// instead of a private server, so a sealed provider key (nova-secrets exec)
	// reaches no provider ("Incorrect API key provided"); --standalone keeps the
	// run in this process, with this environment. CheckRun sets it when the
	// installed run lists the flag, so an older opencode is never handed it.
	Standalone bool
}

type OpenCodePriced struct {
	*OpenCode

	// Friend is the friend's name, as a capped card's report says it.
	Friend string
	// TokenCap is the friend row's per-card token cap as the daemon last read
	// it (TokenCapOf; 0 none); nil is DefaultTokenCap.
	TokenCap func() int64
	// Tick is the clock a running turn's usage is polled on (every TokenPoll);
	// a real ticker when nil.
	Tick func(time.Duration) (<-chan time.Time, func())
	// contains filtered or unexported fields
}