dispatcher

type CommandBroker interface {
	RegisterCommands(commands map[string]orchestrator.CommandDef, builtinPolicies map[string]sandbox.BuiltinPolicy, ctx sandbox.TokenContext, resolve SecretResolver) string
	UnregisterCommandToken(token string)
	SocketPath() string
}

type CreateOpts struct {
	// CheckoutBranch, when non-empty, causes Create to check out an existing
	// branch directly (git worktree add <path> <branch>) rather than creating
	// a new boid/<id8> branch. Used for root tasks (ParentID == "") so the
	// worktree HEAD matches task.BaseBranch directly (P2).
	CheckoutBranch string

	// ForkPoint overrides the start-point used when creating a new boid/<id8>
	// branch (CheckoutBranch == ""). Defaults to baseBranch when empty.
	// Reserved for P3 (child fork from parent HEAD branch); unused in P2.
	ForkPoint string

	// BaseBranchForkPoint is the start point used when the requested
	// baseBranch does not exist yet (ClassifyBaseBranch case 3) and must
	// be created locally. Sourced from ProjectMeta.ForkPoint via
	// Visibility.ForkPoint. Empty falls back to refs/remotes/origin/HEAD;
	// if that is also unset, Create returns an error.
	BaseBranchForkPoint string
}

type EnvironmentInput struct {
	Visibility      orchestrator.Visibility
	WorkspacePeers  map[string]string
	BuiltinPolicies map[string]orchestrator.BuiltinPolicy
	HostCommands    map[string]orchestrator.CommandDef

	// Network plumbing. ProxyPort=0 means no proxy (and therefore no egress
	// restriction wired by dispatcher). HostGatewayIP is the address agents
	// see for the host; combined with ProxyPort it becomes proxy_url.
	ProxyPort      int
	HostGatewayIP  string
	AllowedDomains []string

	// Job category — Kind=Session gates the `session:` block; everything
	// else inherits the same layout but without per-session metadata.
	Kind        orchestrator.JobKind
	HarnessType string
	DisplayName string
}

type Job struct {
	ID             string    `json:"id"`
	TaskID         string    `json:"task_id"`
	ProjectID      string    `json:"project_id"`
	HandlerID      string    `json:"handler_id"`
	DisplayName    string    `json:"display_name,omitempty"` // persisted via the jobs.display_name column (migration 0027)
	Role           string    `json:"role"`
	RuntimeID      string    `json:"runtime_id,omitempty"`
	Interactive    bool      `json:"interactive"`
	TTY            bool      `json:"tty"`
	Status         JobStatus `json:"status"`
	ExitCode       int       `json:"exit_code,omitempty"`
	Output         string    `json:"output,omitempty"`
	ExecutionState string    `json:"execution_state,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

type JobCompletionResult struct {
	Output   string
	ExitCode int
}

type JobEventSink interface {
	JobCreated(taskID, jobID string)
}

type JobFilter struct {
	Status       string
	Interactive  *bool // nil = no filter
	TasklessOnly bool  // true = only jobs where task_id IS NULL
}

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

type JobRuntime interface {
	Start(ctx context.Context, spec RuntimeStartSpec) (*RuntimeHandle, error)
	Attach(ctx context.Context, runtimeID string, req RuntimeAttachRequest) error
	Resize(ctx context.Context, runtimeID string, size TerminalSize) error
	Wait(ctx context.Context, runtimeID string) (RuntimeExit, error)
	Stop(ctx context.Context, runtimeID string) error
	// Signal sends a single signal to the runtime's process group without
	// any follow-up SIGKILL. Used by NotifyTask to drive an "agent-stop"
	// SIGUSR1 to run-agent.py while leaving the runner chain intact: the
	// go-native runner subcommands set this signal to SIG_IGN (see
	// runner.ignoreStopSignal), which is inherited across execve so pasta and
	// the child runners survive while run-agent.py re-installs its own handler.
	// Implementations should be no-op when the runtime has already exited.
	Signal(ctx context.Context, runtimeID string, sig syscall.Signal) error
}

type JobStatus string

type LocalRuntime struct {
	RootDir string
	// contains filtered or unexported fields
}

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

type PreparedSandbox struct {
	SpecPath   string
	StatePath  string
	RootDir    string
	StagingDir string
}

type ProjectLookup interface {
	GetProject(id string) (*orchestrator.Project, error)
	ListProjects() ([]*orchestrator.Project, error)
}

type Runner struct {
	DB              *sql.DB
	Runtime         JobRuntime
	Broker          CommandBroker
	Sandbox         SandboxPreparer
	SecretStore     *SecretStore
	Worktrees       *WorktreeManager
	TaskLookup      TaskLookup
	Projects        ProjectLookup
	BoidBinary      string
	ServerSocket    string
	ProxyPort       *int
	AllowedDomains  []string
	RuntimesDir     string
	AttachmentsRoot string
	JobEvents       JobEventSink // optional; nil disables job lifecycle broadcasts
	// contains filtered or unexported fields
}

type RuntimeAttachRequest struct {
	Input  io.Reader
	Output io.Writer
	Error  io.Writer
}

type RuntimeExit struct {
	ExitCode int
	// TranscriptPath は子プロセスの stdout/stderr 全量を保存しているファイルへの
	// パス。 silent な exit_code!=0 (transcript が 0 byte) ケースを diag log で
	// 一発判別できるようにするために提供する。 サポートしない runtime は空文字。
	TranscriptPath string
}

type RuntimeHandle struct {
	ID          string
	Interactive bool
	TTY         bool
}

type RuntimeInputWriter interface {
	WriteInput(jobID string, data []byte) error
	ResizeRuntime(jobID string, size TerminalSize) error
}

type RuntimeStartSpec struct {
	JobID       string
	TaskID      string
	ProjectID   string
	HandlerID   string
	Role        string
	Command     string
	Interactive bool
	TTY         bool
	// DesiredID, when non-empty, asks the runtime to use this UUID as its
	// session identifier instead of generating a fresh one. The caller uses
	// this to pre-allocate a runtime directory (e.g. for a per-sandbox docker
	// proxy socket) before Start is called. The runtime honours the request
	// on a best-effort basis: if the directory already exists or the ID is
	// otherwise unusable, Start returns an error.
	DesiredID string
}

type RuntimeSubscriber interface {
	Subscribe(jobID string) (snapshot []byte, ch <-chan []byte, cancel func(), ok bool)
}

type SandboxPreparer interface {
	PrepareSandbox(spec sandbox.Spec) (*PreparedSandbox, error)
}

type SandboxRuntimeInfo struct {
	JobID        string
	BoidBinary   string
	ServerSocket string
	ProxyPort    int

	BrokerSocket string
	BrokerToken  string

	// WorktreeDir is set by dispatcher when Visibility.UseWorktree is true,
	// having been resolved through its WorktreeManager. Empty otherwise.
	WorktreeDir string

	// WorkspacePeers maps peer project IDs (same workspace, excluding self) to
	// host paths. Dispatcher resolves this from its ProjectLookup so peer
	// visibility/authorization does not leak into orchestrator.JobSpec.
	WorkspacePeers map[string]string

	// StagingDir, when non-empty, is added to CleanupPaths so the sandbox
	// setup script removes it on teardown in addition to the caller-supplied
	// CleanupFunc.
	StagingDir string

	// RootDir, when non-empty, overrides the default per-sandbox ROOT.
	RootDir string

	// Foreground indicates whether the job runs in the foreground (user-facing
	// stdout/stderr, no trap-based completion callback). boid exec sets this
	// to true; hook/gate jobs leave it false so stdout is captured and a
	// `boid job done` trap posts completion back to the daemon.
	Foreground bool

	// ResolvedHostCommands is the absolute-path-keyed view of spec.HostCommands
	// produced by ResolveHostCommands. The same map is registered with the
	// broker so the shim's os.Executable() lookup hits a known key. Empty when
	// the job declares no host commands.
	ResolvedHostCommands map[string]orchestrator.CommandDef

	// DockerEnabled, when true, indicates capabilities.docker is declared in
	// project.yaml.
	DockerEnabled bool

	// ProxySocketPath, when non-empty, is the host-side Unix socket path of the
	// per-sandbox docker proxy. sandbox_builder bind-mounts it into the sandbox
	// at the fixed sandbox path (see dockerProxySandboxSocket) and injects
	// DOCKER_HOST / CONTAINER_HOST / TESTCONTAINERS_* env vars.
	// Set by the runner before BuildSandboxSpec when DockerEnabled is true.
	ProxySocketPath string

	// AllowedDomains is the proxy egress allowlist. It is purely informational
	// inside the sandbox (the proxy itself enforces it on the host), surfaced
	// to the agent via environment.yaml so it knows which hosts are reachable
	// without burning a turn on a 403.
	AllowedDomains []string

	// AttachmentsRoot is the data-home directory under which per-task
	// attachments live (`<AttachmentsRoot>/tasks/<task_id>/attachments`). When
	// non-empty and the JobSpec has a TaskID, BuildSandboxSpec appends a
	// read-only bind to `<homeDir>/.boid/attachments` so the agent can read
	// user-attached files via its standard Read tool. The bind source is
	// allowed to be missing — the sandbox setup script handles that via the
	// Guard expression so attachments are optional per task.
	AttachmentsRoot string
}

type SecretResolver func(key string) (string, error)

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

type SessionJobInput struct {
	// ProjectID and ProjectWorkDir locate the host filesystem the sandbox
	// will expose; ProjectWorkDir is the cwd seen by the agent.
	ProjectID      string
	ProjectWorkDir string

	// HarnessType selects the agent adapter the runner-inner-child will
	// dispatch through. Must be one of "claude" / "codex" / "opencode" /
	// "shell" (validated by the caller; BuildSessionJobSpec does not police it).
	HarnessType string

	// Argv is the literal program + arguments the shell adapter consumes.
	// The claude / codex / opencode adapters ignore it (they build their
	// argv from CLI conventions). Required when HarnessType == "shell";
	// ignored otherwise.
	Argv []string

	// Instruction is the optional bootstrap prompt the agent should pick up
	// on launch (e.g. the `--instruction` flag of `boid agent`, or the
	// WebUI Session dialog's text field). When non-empty it is plumbed
	// through RunContext.UserAnswer so the adapter's existing "user reply"
	// path delivers it as the first turn of input. Empty leaves the adapter
	// to pick its default bootstrap (no positional for session mode on claude,
	// since the /boid-task skill is meaningless without a task.yaml).
	Instruction string

	// Readonly controls Visibility.Writable. Sessions default to writable
	// (interactive use prioritises developer ergonomics over fail-safety)
	// so callers must opt into a read-only session explicitly.
	Readonly bool

	// Model overrides the harness binary's default model selection.
	Model string

	// Project trait overlay (the session has no behavior to resolve from,
	// so the caller fills these directly from ProjectMeta).
	Env                map[string]string
	HostCommands       map[string]orchestrator.HostCommandSpec
	AdditionalBindings []orchestrator.BindMount
	KitRoots           []string
	SecretNamespace    string
	DockerEnabled      bool

	// DisplayName is the human-readable label persisted to jobs.display_name
	// (and shown in the TUI / Web UI). Empty falls back to "<harness>
	// session" downstream.
	DisplayName string
}

type TaskLookup interface {
	GetTask(id string) (*orchestrator.Task, error)
}

type TerminalSize struct {
	Rows int
	Cols int
}

type WireConfig struct {
	DB          *sql.DB
	Runtime     JobRuntime
	Broker      CommandBroker
	Sandbox     SandboxPreparer
	SecretStore *SecretStore

	// Worktrees resolves per-task git worktrees when a JobSpec declares
	// Visibility.UseWorktree. Pass nil to disable worktree-backed jobs.
	Worktrees  *WorktreeManager
	TaskLookup TaskLookup
	Projects   ProjectLookup

	// BoidBinary is the host path to the boid executable that should be
	// bind-mounted into sandboxes.
	BoidBinary string
	// ServerSocket is the host path to the daemon UNIX socket (for boid exec
	// jobs that talk to boid over HTTP from inside the sandbox).
	ServerSocket string
	// ProxyPort, when non-zero, enables HTTP(S) proxy environment variables
	// pointing at host-gateway:<ProxyPort>.
	ProxyPort *int
	// AllowedDomains is the proxy egress allowlist. Plumbed through to
	// environment.yaml so agents can see which hosts the proxy will let
	// through without having to probe with a 403-burning fetch.
	AllowedDomains []string
	// RuntimesDir is the root directory where per-sandbox runtime directories
	// are created. When non-empty and DockerEnabled, the runner pre-allocates a
	// runtime directory here to host the per-sandbox docker proxy socket and
	// resource ledger.
	RuntimesDir string
	// AttachmentsRoot is the data-home directory under which per-task
	// attachments live (`<root>/tasks/<id>/attachments`). When non-empty the
	// runner threads it through SandboxRuntimeInfo so BuildSandboxSpec can
	// add the read-only bind to `~/.boid/attachments` for every harness.
	AttachmentsRoot string
}

type Worktree struct {
	ID         string     `json:"id"`
	TaskID     string     `json:"task_id"`
	ProjectID  string     `json:"project_id"`
	Path       string     `json:"path"`
	Branch     string     `json:"branch"`
	BaseBranch string     `json:"base_branch"`
	CreatedAt  time.Time  `json:"created_at"`
	CleanedAt  *time.Time `json:"cleaned_at,omitempty"`
}

type WorktreeManager struct {
	RootDir string // e.g. ~/.local/share/boid/worktrees
	DB      *sql.DB
	GitBin  string // path to git binary; defaults to "git"
}

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