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 InitJobInput struct {
	// Profile selects the sandbox filesystem layout. Must be sandbox.ProfileInit
	// for kit-init / workspace-configure (host root ro-rbind, broker skipped).
	Profile sandbox.Profile

	// WritableDirs is the list of host directories to bind read-write into the
	// sandbox so the agent can write generated yaml files. Each entry must be an
	// absolute host path; it is bind-mounted at the same path inside the
	// sandbox. The directory must already exist on the host before dispatch
	// (caller is responsible for mkdir). Per-file binds are intentionally not
	// supported: harness-side file editors do atomic writes (write to
	// `<name>.tmp.<pid>.<rand>` in the parent dir, then rename) which would
	// fail with EROFS on a single-file IsFile bind and force the skill into
	// shell-only writes, breaking harness-agnosticism.
	WritableDirs []string

	// ReadOnlyBinds is additional host paths to bind read-only into the
	// sandbox. Used by workspace-configure to give the agent access to linked
	// project directories (package.json / go.mod / hook scripts) without
	// granting write access.
	ReadOnlyBinds []string

	// Argv is the literal program + arguments to exec inside the sandbox.
	// For agent harnesses (claude / codex / opencode) the adapter builds its
	// own argv from its CLI conventions and may ignore this; it is still
	// required so the shell adapter fall-through path works and so the runner
	// can record a meaningful command in diagnostics.
	Argv []string

	// DisplayName is the human-readable label shown in the TUI / Web UI.
	DisplayName string

	// Env carries additional environment variables to inject into the sandbox
	// on top of the standard HOME / PATH / TERM set. Used to pass context like
	// BOID_WORKSPACE_SLUG to the skill.
	Env map[string]string

	// Instruction is the optional bootstrap prompt the agent should pick up
	// on launch. Mirrors SessionJobInput.Instruction: when non-empty it is
	// delivered through Env (BOID_USER_ANSWER) so the harness adapter
	// receives it as the first turn of user input — for ProfileInit jobs
	// this is how `boid kit init` / `boid workspace configure` kicks the
	// embedded skill ("boid kit init を実行して" etc.) without making the
	// user type anything after the harness opens.
	Instruction string

	// HarnessType selects the agent adapter. Must be one of "claude" /
	// "codex" / "opencode" / "shell". Validated by the caller.
	HarnessType 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 ProxyAllocator interface {
	GetOrCreate(workspaceID string, allowed []string) (int, error)
}

type Runner struct {
	DB          *sql.DB
	Runtime     JobRuntime
	Broker      CommandBroker
	Sandbox     SandboxPreparer
	SecretStore *SecretStore
	Worktrees   *WorktreeManager
	TaskLookup  TaskLookup
	Projects    ProjectLookup
	// Workspaces resolves WorkspaceMeta at dispatch time for the workspace
	// the dispatched project is linked to. When nil (test wiring, missing
	// disk) the runner falls back to the global floor for proxy allowlist
	// resolution. Together with ProxyAllocator it implements the
	// workspace-scoped proxy egress allowlist (project-workspace-allowed-domains).
	Workspaces     WorkspaceLookup
	ProxyAllocator ProxyAllocator
	BoidBinary     string
	ServerSocket   string
	// ProxyPort is the default-workspace proxy port (back-compat fallback
	// when the per-workspace allocator path isn't wired or returns an
	// error). Workspaces with no overrides reuse this port via the
	// allocator's GetOrCreate("default", ...) entry.
	ProxyPort *int
	// AllowedDomains is the daemon-wide proxy egress allowlist (the floor
	// from config.yaml sandbox.allowed_domains + boid defaults). Workspace
	// overrides are added on top via orchestrator.ResolveAllowedDomains.
	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 points at the default-workspace proxy port. Used as the
	// fallback when ProxyAllocator is not wired (or fails). Sandboxes
	// linked to a workspace get a per-workspace port via ProxyAllocator.
	ProxyPort *int
	// AllowedDomains is the daemon-wide proxy egress allowlist floor
	// (config.yaml sandbox.allowed_domains + boid built-in defaults).
	// Workspaces add entries on top via workspace.yaml; they cannot remove
	// floor entries (orchestrator.ResolveAllowedDomains enforces this).
	AllowedDomains []string
	// Workspaces is the WorkspaceLookup used at dispatch time to discover
	// each workspace's AllowedDomains overrides. nil disables workspace
	// hydration and the runner stays on the floor only.
	Workspaces WorkspaceLookup
	// ProxyAllocator is the per-workspace proxy listener registry. nil
	// disables workspace-scoped proxy allocation and the runner serves
	// every sandbox via the default-workspace listener.
	ProxyAllocator ProxyAllocator
	// 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 WorkspaceLookup interface {
	Load(slug string) (*orchestrator.WorkspaceMeta, error)
}

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
}