dispatcher

type CommandBroker interface {
	// RegisterCommands takes the short-name-keyed view of resolved host
	// commands (ResolveHostCommands' byName return value —
	// docs/plans/phase5-shim-and-task-context.md, "5a: shim
	// 固定ディレクトリ化" PR1). As of the 5a-3 cutover (PR3) this is the sole
	// broker key — the shim always sends the declared short name as
	// ExecRequest.Command (sandbox.CommandFromArgv0 — every shim's
	// bind-mount basename equals its declared name by construction under
	// sandboxShimBinDir), and the broker's pre-5a-3 absolute-path Path-scan
	// fallback was dropped in the same change.
	RegisterCommands(commands map[string]orchestrator.CommandDef, builtinPolicies map[string]sandbox.BuiltinPolicy, ctx sandbox.TokenContext, resolve SecretResolver) string
	UnregisterCommandToken(token string)
	SocketPath() 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 JobContextSnapshot struct {
	Instructions              []orchestrator.RoutedInstruction
	Env                       WorkspaceEnvView
	Payload                   json.RawMessage
	PayloadPatchAllowedTraits []orchestrator.TraitType
}

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
	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
	// CloseInput signals that no more input is coming for jobID — the WS
	// attach transport's counterpart to the old raw-hijack transport's
	// implicit half-close (docs/plans/cli-remote-connection.md Phase 3 PR3;
	// see LocalRuntime.CloseInputRuntime's doc comment for the full
	// rationale). A no-op for jobs whose runtime has no notion of "closing"
	// input (interactive PTY sessions, or non-interactive sessions with no
	// StdinForward pipe).
	CloseInput(jobID string) 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

	// ResolvedHostCommandsByName is the short-name-keyed view of the resolved
	// host command defs produced by ResolveHostCommands
	// (docs/plans/phase5-shim-and-task-context.md, "5a: shim 固定ディレクトリ化"
	// PR1). It is the single source of truth for host command wiring:
	//
	//   - the broker's policy table (CommandBroker.RegisterCommands) keys off
	//     it directly;
	//   - buildHostCommandRulesEnv turns the same map into
	//     BOID_HOST_COMMAND_RULES;
	//   - hostCommandSymlinks (5a-3) materializes one
	//     `/run/boid/bin/<name> -> boid` symlink per entry — so every
	//     host_command becomes a shim on PATH under its declared short name,
	//     even when host_commands.<name>.path aliases the source file to a
	//     different basename.
	//
	// The pre-5a-3 absolute-path-keyed sibling (ResolvedHostCommands / byPath)
	// was dropped: it existed only to key the retired hostCommandMounts /
	// buildHostCommandNamesEnv / per-command PATH parent, all replaced by the
	// fixed-directory scheme. Empty when the job declares no host commands.
	ResolvedHostCommandsByName 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 the `boid task env` broker RPC (Phase 5b PR1) so it
	// knows which hosts are reachable without burning a turn on a 403.
	AllowedDomains []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, built by Runner.buildPeerAdvertise and keyed by peer
	// project ID (docs/plans/git-gateway-cutover.md PR6 cutover 「5. peer
	// advertise の変更」 — replaces the pre-cutover host path enumeration);
	// nil when the gateway isn't wired or no peer has a resolvable
	// upstream_url.
	//
	// Currently unused by BuildSandboxSpec: environment.yaml's
	// `workspace_projects` section (its sole consumer) was removed by the
	// environment.yaml 縮退 (docs/plans/phase5-shim-and-task-context.md 決定
	// 事項 4, Phase 5b PR5) — peer advertise has no CLI replacement yet,
	// tracked as a later 5b item / separate phase. Kept here — the same
	// "carried but inert across a PR boundary" pattern as GatewayURL /
	// GatewayJobToken above — as the ready-made input for that future
	// `boid workspace peers`-style RPC.
	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

	// WorkspaceHomeDir is the host-side per-workspace home directory
	// resolved by Runner.resolveWorkspaceHome
	// (docs/plans/home-workspace-volume.md Phase 4 PR1):
	// ~/.local/share/boid/homes/<slug>, guaranteed to exist (and, if the
	// workspace declares an init.sh, already initialized) by the time
	// Dispatch reaches BuildSandboxSpec.
	//
	// PR2 (docs/plans/home-workspace-volume.md) reads this field: the
	// Clone / projectVisible / default HOME branches below (via homeMounts)
	// bind it read-write at HOME's sandbox-internal path instead of a plain
	// tmpfs, with $HOME/.boid layered as a job-scoped tmpfs on top so
	// $HOME/.boid/output/payload_patch.json stays isolated per job even
	// though the rest of HOME now persists across jobs in the same
	// workspace (see homeMounts' doc comment for why that overlay survived
	// the Phase 5b PR6 cutover — codex review found removing it exploitable).
	// env["HOME"] itself is unchanged — it still comes from hostHomeDir(),
	// the *target* path inside the sandbox; only the *contents* now come
	// from the workspace home instead of starting empty every job.
	//
	// When empty (test wiring that never resolved a workspace — most of
	// sandbox_builder_test.go's minimal SandboxRuntimeInfo{} literals —
	// or any other caller that has not threaded a workspace home through
	// yet) the HOME branches gracefully degrade to the pre-PR2 behaviour: a
	// single fresh tmpfs. The ProfileInit branch never reads this field at
	// all — see its own doc comment for why bind-mounting HOME there would
	// defeat its host-tool-discovery purpose.
	WorkspaceHomeDir string

	// WorkspaceSlug is the normalized workspace slug WorkspaceHomeDir was
	// resolved for (docs/plans/home-workspace-volume.md Phase 4 PR3) —
	// filepath.Base(WorkspaceHomeDir), computed once by Runner.Dispatch.
	// BuildSandboxSpec threads it into env["BOID_WORKSPACE_SLUG"] so the
	// claude/codex/opencode adapters' fail-fast "harness CLI not found"
	// error (run.go, triggered when PR3's retired adapter bindings leave no
	// CLI on PATH) can name the exact workspace whose init.sh needs the
	// install step. Empty for test wiring that never resolved a workspace
	// (most of sandbox_builder_test.go's minimal SandboxRuntimeInfo{}
	// literals) — the env var is simply omitted in that case.
	WorkspaceSlug 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 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
	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
	// 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 WorkspaceEnvHostCommand struct {
	Name   string                   `json:"name" yaml:"name"`
	Allow  []string                 `json:"allow,omitempty" yaml:"allow,omitempty"`
	Deny   []string                 `json:"deny,omitempty" yaml:"deny,omitempty"`
	Reject []WorkspaceEnvRejectRule `json:"reject,omitempty" yaml:"reject,omitempty"`
}

type WorkspaceEnvRejectRule struct {
	Match  string `json:"match" yaml:"match"`
	Reason string `json:"reason" yaml:"reason"`
}

type WorkspaceEnvView struct {
	AllowedDomains []string                  `json:"allowed_domains,omitempty" yaml:"allowed_domains,omitempty"`
	HostCommands   []WorkspaceEnvHostCommand `json:"host_commands,omitempty" yaml:"host_commands,omitempty"`
}

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