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 EnvironmentInput struct {
	Visibility     orchestrator.Visibility
	WorkspacePeers map[string]string
	// WorkspacePeerAdvertise, when non-nil, drives the workspace_projects
	// listing (docs/plans/git-gateway-cutover.md PR6 cutover). See
	// SandboxRuntimeInfo.WorkspacePeerAdvertise's doc comment.
	WorkspacePeerAdvertise map[string]PeerAdvertise
	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

	// CloneDir is this job's own project's absolute sandbox-internal clone
	// directory, e.g. "/workspace/bm-next" (workspace 親化リファクタリング,
	// nose 2026-07-13 decision). Empty unless Visibility.Clone is set — the
	// `filesystem.project_dir` field already carries the *host* path for
	// descriptive purposes, but under clone-mode dispatch the host path is
	// not actually visible inside the sandbox at all, so agents need this
	// separate field to know where their own project's working tree
	// actually lives.
	CloneDir 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 PeerAdvertise struct {
	// Name is the peer's repo name (the last segment of its upstream_url's
	// host/owner/repo form), used purely for display/discoverability.
	Name string
	// CloneURL is the full gateway clone URL for this peer, scoped fetch-only
	// to this job's gateway token (docs/plans/container-based-boid.md
	// 「workspace peer プロジェクト」: peers are fetch-only; writing to a peer
	// means a cross-project child task instead).
	CloneURL string
	// ReferencePath is the sandbox-internal RO bind-mount path of the peer's
	// `.git` (sandboxClonePeerReferenceDirFmt), usable as `git clone
	// --reference` when an agent does clone the peer.
	ReferencePath string
	// CloneDir is the suggested absolute sandbox-internal directory for this
	// peer, e.g. "/workspace/bm-next-lp" (workspace 親化リファクタリング,
	// nose 2026-07-13 decision). It is only a suggestion — nothing enforces
	// an agent actually clones the peer here — but using the same leaf name
	// projectDirName would resolve for the peer's own project (were it
	// dispatching as self) keeps the directory name stable regardless of
	// which project happens to be the one dispatching, and keeps it off
	// $HOME/tmp (both tmpfs, RAM-backed).
	CloneDir string
}

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
	Projects    ProjectLookup
	// Hydrator optionally resolves a project's workspace-hydrated
	// ProjectMeta (project.yaml `meta.name` plus workspace merge) by project
	// ID. It is used only for workspace-peer name resolution in
	// buildPeerAdvertise — the self project's name is already resolved at
	// JobSpec-build time via Visibility.ProjectName and does not need this.
	// nil (test wiring, or a daemon build that doesn't wire it) makes
	// buildPeerAdvertise degrade to the pre-existing basename fallback, same
	// as orchestrator.DispatchPlanner.Hydrator's nil behavior.
	Hydrator orchestrator.MetaHydrator
	// 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

	// GitGateway is the git gateway's job-token registry
	// (docs/plans/git-gateway-cutover.md PR4: gateway lifecycle + dispatch
	// wiring). nil disables gateway token registration entirely — Dispatch
	// and UnregisterJob treat that as a no-op rather than panicking (test
	// wiring, or a daemon build without the gateway constructed). PR4 is
	// inert: registration happens, but nothing inside the sandbox talks to
	// the gateway yet (that's PR5/PR6).
	GitGateway *gitgateway.Registry
	// GatewayURL points at the daemon's own gateway listener address string,
	// filled in by Server.Start once the gateway's TCP listener is bound —
	// the same late-binding-via-pointer pattern as ProxyPort, since the
	// gateway (like the default proxy listener) is only known once Start
	// has run. nil disables gateway URL propagation into SandboxRuntimeInfo.
	GatewayURL *string
	// 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
	// StdinForward requests a dedicated stdin pipe for a non-interactive
	// (Interactive=false) session, so a later Attach's RuntimeAttachRequest.Input
	// can feed real bytes to the child process — `boid exec` piped from a
	// non-TTY stdin (e.g. `echo hi | boid exec cat`) needs this; a hook job
	// never does. False (the default, every hook job) keeps stdin on the null
	// device exactly as before: a hook script that probes stdin must keep
	// seeing an immediate EOF, not block forever waiting for a forwarder that
	// will never attach. Ignored when Interactive is true — PTY sessions
	// always support input via the PTY master, forwarding or not.
	StdinForward 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

	// 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

	// 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

	// 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 capabilities.docker is
	// declared in project.yaml.
	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

	// GatewayURL is the git gateway's sandbox-facing base URL
	// (http://10.0.2.2:<port>), set by Runner from the daemon's own
	// gateway listener (docs/plans/git-gateway-cutover.md PR4: gateway
	// lifecycle + dispatch wiring). Empty when the gateway isn't wired.
	//
	// PR4 is inert: BuildSandboxSpec does not thread this into env or mounts
	// yet — nothing inside the sandbox reads it. The env var advertise
	// (e.g. GIT_HTTP_GATEWAY_URL) is explicitly deferred to the cutover PR
	// (PR6); the runner clone sequence that would consume it is PR5.
	GatewayURL string

	// GatewayJobToken is this job's git gateway token, registered against
	// the gateway's Registry at dispatch time (self project fetch/fetch+push,
	// workspace peers and workspace extra_repos fetch-only) and unregistered
	// when the job completes (see Runner.registerGatewayToken /
	// Runner.UnregisterJob). Empty when the gateway isn't wired.
	//
	// Same PR4-is-inert caveat as GatewayURL: carried here for PR5/PR6 to
	// consume, not yet used by BuildSandboxSpec.
	GatewayJobToken string

	// GatewayCloneURL is the full gateway clone URL for spec's own project
	// (GatewayURL + "/j/" + GatewayJobToken + "/<host>/<owner>/<repo>.git"),
	// built by Runner.buildGatewayCloneURL (docs/plans/git-gateway-cutover.md
	// PR5). Empty unless spec.Visibility.Clone is non-nil (the opt-in
	// sandbox-clone path) — computing it is otherwise wasted work, since
	// nothing would consume it. BuildSandboxSpec only reads this when
	// spec.Visibility.Clone != nil.
	GatewayCloneURL string

	// WorkspacePeerAdvertise is the {name, clone URL, reference path} view of
	// WorkspacePeers exposed to the agent via environment.yaml's
	// `workspace_projects` (docs/plans/git-gateway-cutover.md PR6 cutover
	// 「5. peer advertise の変更」 — replaces the pre-cutover host path
	// enumeration). Built by Runner.buildPeerAdvertise, keyed by peer project
	// ID; nil when the gateway isn't wired or no peer has a resolvable
	// upstream_url. Distribution stays file-based (environment.yaml) for now
	// — RPC-based advertise is a later container-migration step (「タスクコン
	// テキストの伝搬」), out of scope here.
	WorkspacePeerAdvertise map[string]PeerAdvertise

	// CloneWorkspaceDir is the host-side runtime dir path
	// (`<RuntimesDir>/<runtime_id>/workspace`) that BuildSandboxSpec bind-
	// mounts at the sandbox-internal clone target (/workspace/<name>) when
	// spec.Visibility.Clone is set (docs/plans/git-gateway-cutover.md PR6
	// cutover — 「一時領域の実体はホスト側 runtime dir の bind mount を既定と
	// する」, 2026-07-08 decision in container-based-boid.md). Allocated and
	// mkdir'd by Runner.Dispatch before BuildSandboxSpec runs, the same way
	// startDockerProxy pre-creates its runtime dir. Empty when RuntimesDir is
	// unset (e.g. minimal test wiring) — cloneMounts then skips the bind and
	// the clone lands on the sandbox's own tmpfs root instead, a safe but
	// non-default degrade (working tree + build artifacts in RAM).
	CloneWorkspaceDir 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

	// ProjectName is project.yaml's `meta.name` (see
	// orchestrator.Visibility.ProjectName's doc comment). The caller fills
	// this from the same workspace-hydrated ProjectMeta it already reads
	// Env/HostCommands/AdditionalBindings/KitRoots from.
	ProjectName 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 TerminalSize struct {
	Rows int
	Cols int
}

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

	Projects ProjectLookup
	// Hydrator is optional workspace-hydrated ProjectMeta lookup, threaded
	// straight to Runner.Hydrator (see its doc comment). nil disables
	// workspace-peer meta.name resolution; buildPeerAdvertise falls back to
	// filepath.Base(WorkDir).
	Hydrator orchestrator.MetaHydrator

	// 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
	// GitGateway is the git gateway's job-token registry
	// (docs/plans/git-gateway-cutover.md PR4). nil disables gateway token
	// registration entirely.
	GitGateway *gitgateway.Registry
	// GatewayURL points at the daemon's own gateway listener address string,
	// filled in by Server.Start once the gateway's TCP listener is bound
	// (same late-binding pattern as ProxyPort). nil disables gateway URL
	// propagation into SandboxRuntimeInfo.
	GatewayURL *string
}

type WorkspaceLookup interface {
	Load(slug string) (*orchestrator.WorkspaceMeta, error)
}