API: expose a server-authorized assignment handoff for an existing OMP session

[castrojo]

Part of #2534.

Downstream observation

projectbluefin/review has removed its separate maintainer dashboard and now runs review batches inside one OMP workbench. We have not merged the Hive contributor path into that workbench because the current public contributor contract does not expose a safe handoff for an already-running OMP session.

Verified on 2026-09-14 against Hive v4 commit 8cf12bac205912dc615731bd2dccb6dabd89a791:

• The WebSocket ready handler clears any prior task, calls selectTask, and sends one server-selected task_assign:

  hive/src/pkg/dashboard/contribute_ws.go

  Lines 3860 to 3984 in 8cf12ba

  	contributor.mu.Unlock()
  	return nil
  	})
  	go h.heartbeatLoop(contributor)
  	case "ready":
  	if contributor == nil {
  	continue
  	}
  	contributor.mu.Lock()
  	abandoned := contributor.currentTask
  	contributor.currentTask = nil
  	// #2568: bump the generation on release so a re-`ready` abandon fences any
  	// later message echoing the old generation for the just-abandoned task.
  	contributor.currentTaskGen = h.nextTaskGen()
  	contributor.lastLeaseRenew = time.Time{}
  	contributor.tokenMintedAt = time.Time{}
  	// #2537: clear any pending/delivered credential state with the task.
  	contributor.pendingToken = ""
  	contributor.credentialDelivered = false
  	contributor.mu.Unlock()
  	if abandoned != nil {
  	// C4: the relay explicitly gave up this task, so revoke its
  	// server-issued lease — a later task_progress for it must not resurrect
  	// ownership.
  	h.revokeLease(identityOf(contributor), abandoned.TaskID)
  	// #5097: same visibility gap as the disconnect path above — the
  	// relay giving a task back by asking for new work left no trace in
  	// the activity feed either.
  	h.addActivity(contributor.profile.GitHubUsername, "released: gave the task back",
  	contributor.role, contributor.cliBackend, contributor.model,
  	contributor.reasoningEffort, taskDescOf(abandoned))
  	h.logger.Warn("[contribute-ws] task abandoned without completion",
  	"username", contributor.profile.GitHubUsername,
  	"abandoned_task", abandoned.TaskID,
  	)
  	// kubestellar/hive#2545: a contributor that sends "ready" while
  	// still holding a task (e.g. the relay's own MAX_TASK_DURATION_MS
  	// watchdog gives up and requeues, or an agent that never actually
  	// started work asks for something new) used to leave currentTask
  	// set and booked no cooldown at all — worse than the disconnect
  	// path immediately above (#2356/#2435), which does both. That left
  	// the abandoned issue permanently out of activeIssues circulation
  	// for the life of the connection: no PR, no failure record, no
  	// re-offer, just a silently held slot. Clear currentTask (above)
  	// so selectTask's activeIssues scan releases the issue, and mirror
  	// the disconnect/task_failed paths by booking the SAME short
  	// non-permanent failure cooldown, so the just-abandoned issue is
  	// not instantly handed straight back to the same contributor in
  	// the very selectTask call below. Synthetic pr-review tasks carry
  	// Number == 0 and must not poison an issue key.
  	if abandoned.Number > 0 {
  	h.recordTaskFailureForTask(abandoned, false)
  	}
  	}
  	h.logger.Info("[contribute-ws] ready for work",
  	"username", contributor.profile.GitHubUsername,
  	"role", contributor.role,
  	)
  	task := h.selectTask(contributor)
  	switch {
  	case task == nil:
  	// Defensive backstop only: after #2436 and #2546 every selectTask
  	// path returns an explicit message, so this should not be reached.
  	// Kept so an unforeseen nil still fails safe (no send) rather than
  	// panicking.
  	h.logger.Info("[contribute-ws] no tasks available",
  	"username", contributor.profile.GitHubUsername,
  	)
  	case task.Type == "task_unavailable":
  	// An explicit negative-ack rather than silence. #2436 finding 1/2/3
  	// covers the enforced refusals (mint failure, disabled tier,
  	// concurrency limit); #2546 adds the three formerly-silent
  	// no-work-right-now reasons (contribution_suspended, hub_not_ready,
  	// no_matching_work). Record the reason on the connection so the ops
  	// tab can show WHY this clanker is idle, then send it.
  	contributor.mu.Lock()
  	contributor.lastIdleReason = task.Reason
  	contributor.mu.Unlock()
  	if err := contributor.send(*task); err != nil {
  	h.logger.Warn("[contribute-ws] failed to send task_unavailable", "error", err)
  	return
  	}
  	h.logger.Info("[contribute-ws] task unavailable",
  	"username", contributor.profile.GitHubUsername,
  	"reason", task.Reason,
  	)
  	default:
  	if err := contributor.send(*task); err != nil {
  	h.logger.Warn("[contribute-ws] failed to send task_assign", "error", err)
  	return
  	}
  	pickupKey := task.TaskKey
  	if pickupKey == "" {
  	pickupKey = worksource.Ref{Repo: task.Repo, Number: task.Number}.Key()
  	}
  	taskDesc := assignDesc(task.Kind, pickupKey, task.Title, task.TaskID)
  	if task.Role != "" {
  	taskDesc = fmt.Sprintf("contributor ran %s task: %s", task.Role, taskDesc)
  	}
  	h.addActivity(contributor.profile.GitHubUsername, "picked up", contributor.role, contributor.cliBackend, contributor.model, contributor.reasoningEffort, taskDesc)
  	h.logger.Info("[contribute-ws] task assigned",
  	"username", contributor.profile.GitHubUsername,
  	"task", task.TaskID,
  	"repo", task.Repo,
  	"number", task.Number,
  	)
  	// #2537: the credential was withheld from the task_assign above and is
  	// delivered only AFTER acceptance. In the DEFAULT trusted-source
  	// auto-accept mode, the task already cleared admission and the per-tier
  	// trust gate in selectTask, so acceptance is automatic HERE — after the
  	// assignment is committed and sent — and the scoped credential is
  	// delivered immediately. This preserves an unattended fleet's timing
  	// (credential arrives right after task_assign) while making the ordering
  	// provable: the credential leaves the hub only once acceptance is
  	// recorded, never bundled with the metadata. In EXPLICIT-accept mode the
  	// hub withholds here and waits for a task_accepted (handled below).
  	if !h.requireExplicitAccept() {
  	h.deliverTaskCredential(contributor, "auto_accept")
  	} else {
  	h.logger.Info("[contribute-ws] credential withheld pending explicit acceptance",
  	"username", contributor.profile.GitHubUsername, "task", task.TaskID)
  	}
  	}

• selectTask chooses one admitted candidate, records the lease/generation, and returns one assignment envelope:

  hive/src/pkg/dashboard/contribute_ws.go

  Lines 6380 to 6584 in 8cf12ba

  	// #2435: carry any lingering failure history so the ordering below
  	// can deprioritise a recently-failed issue within its bucket.
  	recentFailures: h.recentFailureCountKey(itemKey),
  	})
  	}
  	}
  	if len(candidates) == 0 {
  	// #2546: the hub is running and unsuspended but nothing is admissible right
  	// now (everything is in cooldown, filtered out, disabled, or already held).
  	// Previously a bare nil — indistinguishable on the wire from "suspended" or
  	// "hub not ready". Send an explicit no_matching_work negative-ack.
  	return h.taskUnavailable(taskUnavailableNoMatchingWork)
  	}
  	// Operator priority override (#queue-reorder): the ordered list of issue keys
  	// the operator dragged to the front of the ready-work queue on the Operations
  	// tab. It takes precedence over the default ordering below so a prioritised
  	// issue is OFFERED FIRST. It never bypasses admission: every entry in
  	// `candidates` already passed the SAME cooldown / failure / disabled-repo /
  	// filter / in-flight exclusions above, so a pinned-but-no-longer-actionable key
  	// simply never became a candidate (stale keys are skipped). Rank sentinel: a
  	// candidate NOT in the override ranks at len(override), so all pinned candidates
  	// sort ahead of all unpinned ones while their own relative order is the operator's.
  	var queueOrderIdx map[string]int
  	if h.server.deps != nil && h.server.deps.Config != nil {
  	queueOrderIdx = queueOrderIndex(h.server.deps.Config.Hub.ContributeQueueOrder)
  	}
  	orderRank := func(c candidate) int {
  	if len(queueOrderIdx) == 0 {
  	return 0 // no override → every candidate ties, key is a no-op
  	}
  	if r, ok := queueOrderIdx[fmt.Sprintf("%s#%d", c.repoFull, c.number)]; ok {
  	return r
  	}
  	return len(queueOrderIdx)
  	}
  	// Order the admissible set with a STABLE sort so the pick is deterministic
  	// (easy to reason about and to test — no randomness):
  	// 0. operator priority override first (#queue-reorder) — pinned issues in the
  	// operator's dragged order; a no-op when no override is set;
  	// 1. own-work first (#2390 — preserved unchanged);
  	// 2. then fewer recent failures first (#2435 remedy 3 backstop) — an issue
  	// whose short failure cooldown has just elapsed but which still carries
  	// failure history is deprioritised behind never-failed peers, so a
  	// flaky issue can no longer monopolise the head of the queue even if the
  	// ledger is imperfect;
  	// 3. otherwise the established per-repo / creation scan order is kept.
  	// When the contributor has no own work AND nothing has failed AND no override is
  	// set, this is a no-op and behaviour is identical to the previous first-eligible pick.
  	ownFirst := make([]candidate, len(candidates))
  	copy(ownFirst, candidates)
  	sort.SliceStable(ownFirst, func(i, j int) bool {
  	if ri, rj := orderRank(ownFirst[i]), orderRank(ownFirst[j]); ri != rj {
  	return ri < rj // operator-pinned (lower rank) sorts ahead
  	}
  	if ownFirst[i].isOwn != ownFirst[j].isOwn {
  	return ownFirst[i].isOwn // own work sorts ahead of non-own
  	}
  	if ownFirst[i].interestMatch != ownFirst[j].interestMatch {
  	return ownFirst[i].interestMatch // label-affinity matches ahead of non-matches (#2637)
  	}
  	if ownFirst[i].recentFailures != ownFirst[j].recentFailures {
  	return ownFirst[i].recentFailures < ownFirst[j].recentFailures // fewer failures first
  	}
  	return false // equal keys → SliceStable preserves original scan order
  	})
  	chosen := ownFirst[0]
  	if chosen.isOwn {
  	h.logger.Info("[contribute-ws] prioritizing contributor's own work (#2390)",
  	"username", ownUsername, "repo", chosen.repoFull, "number", chosen.number)
  	}
  	// Mint through the shared path so task_assign and the heartbeat token-refresh
  	// advertise tokens minted the same way (#2393 item 2). tokenMintedAt below
  	// arms the refresh ticker for the token we hand out here. C4: the token is
  	// scoped to the chosen issue's REPOSITORY, not the whole installation.
  	ghToken, err := h.mintScopedToken(c.profile.TrustTier, chosen.repoFull)
  	if err != nil {
  	// #2436 finding 1: a mint failure previously returned nil, stranding the
  	// contributor with no message (the log even said "skipping task" while
  	// abandoning the whole selection). Send an explicit token_mint_failed
  	// negative-ack so the failure is diagnosable instead of an indefinite
  	// hang. We do not fall through to another candidate: the mint is keyed on
  	// the contributor's tier, not the candidate, so every candidate in this
  	// pass would fail identically. Preserve the existing Warn log.
  	h.logger.Warn("[contribute-ws] failed to mint scoped token — task unavailable",
  	"tier", c.profile.TrustTier, "error", err)
  	return h.taskUnavailable(taskUnavailableTokenMintFailed)
  	}
  	// The task id carries the item's own identity segment so two zero-numbered
  	// external items cannot mint the same id within one second
  	// (kubestellar/hive#4245). GitHub-backed work keeps its historical
  	// "ct-<repo>-<number>-<unix>" shape byte for byte.
  	taskID := fmt.Sprintf("ct-%s-%s-%d", chosen.repoFull, taskIDSegment(chosen.ref), time.Now().Unix())
  	// #2539: build the prompt through the shared, credential-free buildTaskPrompt
  	// so the exact text shipped in task_assign below can also be PREVIEWED
  	// read-only in the ops tab. The prompt is a pure function of task metadata —
  	// the minted github_token is attached to the WSMessage separately (never inside
  	// the prompt), so previewing the prompt can never leak the token. buildTaskPrompt
  	// itself carries the #2545 workspace-clone instruction (real checkout into
  	// $HIVE_WORKSPACE_DIR rather than a fork-only --clone=false).
  	canPush := h.contributorCanPush(chosen.repoFull, ownUsername)
  	prompt := buildTaskPromptForContributor(chosen.ref, chosen.title, canPush)
  	if requestedRole != "" {
  	prompt = buildRoleTaskPromptForContributor(chosen.ref, chosen.title, requestedRole, h.roleKickPrompt(requestedRole), canPush)
  	}
  	// #4105: tell the agent up front — from the hub's own handshake-recorded
  	// invocation values — the exact attribution trailer its PR body must end
  	// with, so the footer is intentionally produced rather than appended only
  	// by the post-merge reconciliation safety net (#4088, unchanged).
  	prompt += attributionPromptInstruction(promptInvocationMeta(c))
  	// #2568: mint a fresh assignment generation for this task. It is stamped on the
  	// connection, shipped in task_assign below, and echoed back by the relay so a
  	// later stale-worker completion carrying an older generation is fenced out.
  	gen := h.nextTaskGen()
  	c.mu.Lock()
  	c.currentTask = &WSTaskAssign{
  	TaskID: taskID,
  	Kind: "issue",
  	Role: requestedRole,
  	Repo: chosen.repoFull,
  	Number: chosen.number,
  	Title: chosen.title,
  	Key: chosen.ref.Key(),
  	SourceType: chosen.ref.SourceType,
  	ExternalID: chosen.ref.ExternalID,
  	URL: chosen.url,
  	}
  	c.currentTaskGen = gen
  	// #2568: start the hub-owned lease clock. task_progress renews it; cleanupLoop
  	// auto-releases the task if it is not renewed within wsTaskTimeout.
  	c.lastLeaseRenew = time.Now()
  	// Duration anchor for the run log — lastLeaseRenew moves on every
  	// progress report, so it cannot serve as the start time.
  	c.taskAssignedAt = time.Now()
  	// Store the prompt (never the token) so FleetSnapshot can preview it (#2539),
  	// and clear any stale idle reason now that this connection has real work.
  	c.currentPrompt = prompt
  	c.currentLabels = chosen.labels
  	c.lastIdleReason = ""
  	// #2537: hold the minted scoped token as PENDING rather than shipping it in the
  	// task_assign below. It is delivered only AFTER the acceptance decision — see
  	// the ready-handler (auto-accept default) and the task_accepted handler
  	// (explicit-accept mode) — via deliverTaskCredential. A fresh assignment resets
  	// the delivered flag so the new task's credential is (re)delivered post-accept.
  	// tokenMintedAt is set here so the #2393 refresh cycle is armed for the token we
  	// hand out; deliverTaskCredential re-stamps it on actual delivery to anchor the
  	// 50-minute refresh on when the relay truly received the credential.
  	c.pendingToken = ghToken
  	c.credentialDelivered = false
  	c.tokenMintedAt = time.Now()
  	c.mu.Unlock()
  	// C4: record the SERVER-AUTHORITATIVE lease for this assignment so a later
  	// reconnect can be validated against what the hub actually issued — the exact
  	// {task, repo, generation, tier} bound here — instead of reconstructing ownership
  	// from client-supplied task_progress fields. Revoked on every release path.
  	// #5681: record the item's canonical key too, so the double-assignment guard can
  	// recognise the lease after a restart — including for external work, whose
  	// identity is Key rather than repo#number (#4245).
  	h.recordLeaseForKey(identityOf(c), taskID, chosen.repoFull, chosen.number,
  	chosen.ref.Key(), c.profile.TrustTier, gen, time.Now())
  	// #2566: record this assignment against the identity's rolling hourly/daily
  	// windows so the next selectTask enforces tier_limits.max_per_hour /
  	// max_per_day. Recorded here — after the task is committed to the connection
  	// and we are certain a task_assign will ship — so a refused pass (which returns
  	// early above) never consumes a slot. Uses the same identity key as the
  	// concurrency gate.
  	h.recordAssignment(identityOf(c), time.Now())
  	return &WSMessage{
  	Type: "task_assign",
  	Seq: h.nextSeq(),
  	TaskID: taskID,
  	TaskGen: gen,
  	Kind: "issue",
  	Role: requestedRole,
  	Repo: chosen.repoFull,
  	Number: chosen.number,
  	Title: chosen.title,
  	URL: chosen.url,
  	// Source-aware identity (kubestellar/hive#4245). Additive: a GitHub
  	// assignment carries exactly the fields it always did, and these tell a
  	// relay working a Linear or Jira item what the item actually IS instead
  	// of leaving it to infer one from `number: 0`.
  	TaskKey: chosen.ref.Key(),
  	SourceType: chosen.ref.SourceType,
  	ExternalID: chosen.ref.ExternalID,
  	// #2537: NO github_token / token_expires_at here. The scoped credential is
  	// split out of task_assign and delivered only after acceptance (see
  	// pendingToken / deliverTaskCredential). task_assign now carries exactly the
  	// metadata needed to DECIDE — repo/number/title/url/labels/prompt — plus the
  	// #2568 TaskGen lease token, and no credential, so nothing an agent could act
  	// on is authenticated until the task's source has been accepted under the
  	// operator/contributor policy.
  	Prompt: prompt,
  	// The chosen issue's own labels — the Labels envelope field was declared

• The shipped relay owns either an interactive tmux launch or a headless child CLI rather than handing an assignment to an existing OMP session:

  hive/bin/contributor-relay.js

  Lines 140 to 172 in 8cf12ba

  	// interactive (default) — the legacy path: type the prompt into a live
  	// tmux pane with `tmux send-keys` and scrape the pane for readiness,
  	// progress and completion. Requires an attached-or-attachable TTY and is
  	// unchanged by this feature.
  	//
  	// headless — the non-interactive path added for #2538: drive the backend
  	// CLI in a one-shot / print invocation (`claude -p`, `copilot -p`,
  	// `codex exec`, …), capture its stdout/stderr, and report completion or a
  	// REAL error back over the same WebSocket channel. No tmux, no pane
  	// scraping, no waiting on an invisible prompt — so a K8s Job/Deployment
  	// running this mode either runs to completion or fails loudly (the exact
  	// "healthy-looking but stalled pod" failure #2538 warns about), and it
  	// never needs a human to attach and type `/login`.
  	//
  	// This is opt-in and additive: absent/any-other value keeps the interactive
  	// path exactly as before. K8s manifests (#2549) and the credential boundary
  	// (#2537) are the explicit follow-ons and are NOT built here.
  	const MODE_INTERACTIVE = 'interactive';
  	const MODE_HEADLESS = 'headless';
  	const CONTRIBUTOR_MODE = process.env.CONTRIBUTOR_MODE === MODE_HEADLESS
  	? MODE_HEADLESS
  	: MODE_INTERACTIVE;
  	// contributor-agent.sh creates and exports this before starting the relay. Pin
  	// it at process startup just like CONTRIBUTOR_MODE so a later environment
  	// mutation cannot make the one-shot CLI run outside the workspace that was
  	// granted to Codex with --add-dir.
  	const TASK_WORKSPACE_DIR = process.env.HIVE_WORKSPACE_DIR || process.cwd();
  	// Where the headless runner records its current lifecycle state as JSON, so a
  	// supervising process (or a future K8s liveness/readiness probe reading the
  	// file) can distinguish waiting / working / done / failed — instead of a pod
  	// that merely looks alive. Best-effort: a write failure never aborts a task.
  	const HEADLESS_STATUS_FILE = process.env.HIVE_HEADLESS_STATUS_FILE || '/tmp/contributor-headless-status.json';

  and

  hive/bin/contributor-relay.js

  Lines 1108 to 1253 in 8cf12ba

  	function buildLaunchCommand() {
  	if (cachedLaunchCommand) return cachedLaunchCommand;
  	if (ENTRYPOINT_LAUNCH_CMD) {
  	cachedLaunchCommand = ENTRYPOINT_LAUNCH_CMD;
  	return cachedLaunchCommand;
  	}
  	const { cmd, perm } = resolveBackendShell();
  	const modelFlag = modelFlagFor();
  	const reasoningFlag = BACKEND === 'codex' && REASONING_EFFORT
  	? `-c 'model_reasoning_effort="${REASONING_EFFORT}"'`
  	: '';
  	// Paired with modelFlag, never on its own: agy without --model needs no
  	// --effort, and passing one alone would be a flag agy has no model to apply.
  	const agyEffortFlag = BACKEND === 'agy' && modelFlag ? `--effort ${effectiveReasoningEffort()}` : '';
  	// muse takes effort on its own, independent of --model (unlike agy), and
  	// validates the value itself. Only values muse actually accepts are passed,
  	// so effectiveReasoningEffort() never advertises an effort muse rejected.
  	const museEffortFlag = BACKEND === 'muse' && effectiveReasoningEffort()
  	? `--reasoning-effort ${effectiveReasoningEffort()}`
  	: '';
  	cachedLaunchCommand = [cmd, perm, modelFlag, reasoningFlag, agyEffortFlag, museEffortFlag].filter(Boolean).join(' ');
  	return cachedLaunchCommand;
  	}
  	// --- Headless (non-interactive) one-shot dispatch (kubestellar/hive#2538) ---
  	//
  	// Backends whose CLI supports a one-shot / print invocation that takes the
  	// prompt on the command line, runs to completion, and EXITS with a meaningful
  	// status — the property the headless mode needs. Each entry says how to turn
  	// (binary, perm-flags, prompt) into an argv:
  	//
  	// flag — the sub-command/flag(s) that select one-shot mode. Either a single
  	// token, where the prompt follows as a bare positional
  	// (`claude -p "<prompt>"`, `codex exec "<prompt>"`), or an array of
  	// leading tokens when a sub-command AND a flag both precede the
  	// prompt (`goose run --no-session -t "<prompt>"`). Either way the
  	// prompt is appended as the final, distinct argv element.
  	//
  	// Backends NOT listed here have no known non-interactive entry point (bob /
  	// aider drive an interactive TUI), so headless mode refuses them LOUDLY at
  	// task time rather than silently stalling. Extending this table is how a
  	// future PR adds a backend once its headless invocation is verified.
  	const HEADLESS_BACKENDS = {
  	// claude -p "<prompt>" — print mode: runs the prompt non-interactively and
  	// exits. Same perm flags as the interactive launch (bypass permissions).
  	claude: { flag: '-p' },
  	// litellm is the claude binary pointed at a LiteLLM proxy, so the same
  	// print-mode invocation applies.
  	litellm: { flag: '-p' },
  	// copilot -p "<prompt>" — non-interactive programmatic mode.
  	copilot: { flag: '-p' },
  	// codex exec "<prompt>" — Codex's non-interactive execution sub-command.
  	// --skip-git-repo-check: exec refuses to run at all in a cwd that is not a
  	// git repository ("Not inside a trusted directory..."), and the task
  	// workspace root is exactly that — the agent clones INTO it as its first
  	// act. Verified live against codex 0.146.0 via bin/test_backend_smoke.sh.
  	codex: { flag: ['exec', '--skip-git-repo-check'] },
  	// goose run --no-session -t "<prompt>" — goose's one-shot sub-command. The
  	// bare `goose` binary drives the interactive TUI, but `goose run` is a
  	// documented non-interactive entry point (#2828): `-t` takes the prompt as
  	// its VALUE (not a trailing positional), and --no-session skips creating or
  	// resuming a session file, which one-shot dispatch never needs. Verified
  	// against goose 1.37.0 — the version src/Dockerfile pins via GOOSE_VERSION —
  	// that `run`, `-t` and `--no-session` all exist and that a failed run exits
  	// non-zero, which is the exit-code contract runHeadlessTask() relies on.
  	goose: { flag: ['run', '--no-session', '-t'] },
  	// pi --print --mode json <prompt> — Pi's bounded non-interactive entry point.
  	// AGENT_MODEL is already the canonical provider/model token, so no separate
  	// --provider input is needed (or allowed) and restart/headless stay identical.
  	pi: { flag: ['--print', '--mode', 'json'] },
  	// agy -p "<prompt>" — Antigravity's print mode ("Run a single prompt
  	// non-interactively and print the response", `agy --help`). Verified against
  	// agy 1.1.13: a print-mode run answers on stdout and exits 0, which is the
  	// exit-code contract runHeadlessTask() relies on. NOTE this makes agy
  	// headless-capable on a HOST only — agy's sign-in is an interactive Google
  	// OAuth flow (browser URL + pasted code) with no API-key mode, and a fresh
  	// container has nothing to inherit it from, which is why agy stays OUT of
  	// K8S_HEADLESS_BACKENDS on the /contribute page and out of the contributor
  	// image. The capability and the credential are separate questions.
  	agy: { flag: '-p' },
  	// opencode run "<prompt>" — opencode's one-shot headless invocation
  	// (kubestellar/hive#4970). Unlike agy, opencode is the ONLY launch mode
  	// this backend gets: there is no interactive-tmux wiring for it (see the
  	// getCLIState()/classifyTmuxPane() backend lists below, which opencode
  	// deliberately does not join), so it is only ever reached through
  	// CONTRIBUTOR_MODE=headless. `opencode run` exits with a real status code
  	// on completion, the exit-code contract runHeadlessTask() relies on.
  	opencode: { flag: 'run' },
  	// Kilo is OpenCode-derived but uses distinct credentials and config.
  	kilo: { flag: 'run' },
  	// muse exec "<prompt>" — Muse Code's documented non-interactive
  	// sub-command ("Run one prompt non-interactively (headless)"). Verified
  	// against Muse Code 1.0.3 (1.0.3-R2198.1): a completed run exits 0, a run
  	// with no usable credential exits 1 ("missing meta credentials: run `muse
  	// login` or set META_API_KEY..."), and a bad flag/value exits 2 — the
  	// exit-code contract runHeadlessTask() relies on. muse DOES have an
  	// interactive TUI, but hive has no interactive-tmux wiring for it (it
  	// deliberately does not join the getCLIState()/classifyTmuxPane() backend
  	// lists below), so headless is the only launch mode hive gives it.
  	//
  	// flagsAfterCommand: muse is a SUB-COMMAND-FIRST CLI. Its options are parsed
  	// by `muse exec` itself, not by the `muse` root, so the usual
  	// "<perm flags> <one-shot token> <prompt>" order silently breaks: `muse
  	// --approval-mode never exec "<prompt>"` prints the root help, exits 0, and
  	// never runs the task — a no-op that would look like a passing run. Verified
  	// against 1.0.3: flags must follow `exec`.
  	muse: { flag: 'exec', flagsAfterCommand: true },
  	};
  	// headlessSupportsBackend reports whether the configured backend has a known
  	// one-shot invocation. Used to fail fast at startup and per task.
  	function headlessSupportsBackend() {
  	return Object.prototype.hasOwnProperty.call(HEADLESS_BACKENDS, BACKEND);
  	}
  	// buildHeadlessArgv turns a task prompt into the argv for a one-shot,
  	// non-interactive backend invocation: [binary, ...permFlags, ...modelFlag,
  	// ...oneShotFlags, prompt]. Returns null for an unsupported backend. Never
  	// shell-interpolates the prompt — it is passed as a distinct argv element to
  	// execFile, so apostrophes/quotes in the prompt (the exact #2203 wedge on the
  	// interactive path) cannot break anything here.
  	function buildHeadlessArgv(prompt) {
  	const spec = HEADLESS_BACKENDS[BACKEND];
  	if (!spec) return null;
  	if (BACKEND === 'pi' && !PI_SELECTION.valid) throw new Error(PI_SELECTION.error);
  	const { cmd, perm } = resolveBackend();
  	const permArgs = perm ? perm.split(/\s+/).filter(Boolean) : [];
  	const modelArgs = MODEL && !NO_MODEL_FLAG_BACKENDS.includes(BACKEND) ? ['--model', MODEL] : [];
  	const reasoningArgs = BACKEND === 'codex' && REASONING_EFFORT ? ['-c', `model_reasoning_effort="${REASONING_EFFORT}"`] : [];
  	// Same --model/--effort pairing the interactive launch enforces, so headless
  	// agy honors the configured model instead of silently falling back.
  	const agyEffortArgs = BACKEND === 'agy' && modelArgs.length ? ['--effort', agyEffort] : [];
  	// spec.flag is a single token for most backends, or an array of leading
  	// tokens for backends needing a sub-command plus a flag (goose). Normalize
  	// to an array so both shapes spread the same way ahead of the prompt.
  	const oneShotArgs = Array.isArray(spec.flag) ? spec.flag : [spec.flag];
  	const museEffortArgs = BACKEND === 'muse' && effectiveReasoningEffort()
  	? ['--reasoning-effort', effectiveReasoningEffort()]
  	: [];
  	const flagArgs = [...permArgs, ...modelArgs, ...reasoningArgs, ...agyEffortArgs, ...museEffortArgs];
  	// Sub-command-first CLIs parse their options on the sub-command, not the
  	// root binary, so the one-shot token has to lead (see flagsAfterCommand).
  	const args = spec.flagsAfterCommand
  	? [...oneShotArgs, ...flagArgs, prompt]
  	: [...flagArgs, ...oneShotArgs, prompt];

The downstream consequence is ours: without another upstream seam, one visual OMP workbench cannot consume contributor assignments without either embedding/reimplementing Hive's relay lifecycle or locally selecting work. We are doing neither. review-queue now uses OMP exclusively, while the Hive worker remains a separate foreground path.

Question

Does Hive want to support embedding its contributor lifecycle into an already-running agent host such as OMP?

Possible seams, without prescribing one:

1. An embeddable relay transport that emits the existing server-selected assignment and accepts progress/completion events while the host owns presentation and agent execution.
2. A versioned lease API exposing the same server-owned selection, assignment generation, explicit acceptance, post-acceptance credential delivery, heartbeat, release, and completion semantics as the WebSocket protocol.
3. No new API; downstreams should keep the contributor worker separate from maintainer workbenches.

Any supported seam needs to preserve Hive's ordering and admission decisions, task generation fencing, credential-after-acceptance rule, lease renewal/release behavior, and output capture. It must not let a client request arbitrary issues or synthesize its own batch.

No downstream protocol shim or client-side assignment logic is being added. Please choose the boundary you want; a DESIGN-RESPONSE is sufficient.

[clubanderson]

PROPOSED DESIGN-RESPONSE for maintainer ratification by @clubanderson — recommendation only, not a ratified project decision.

I checked the issue against the requested baseline, 8cf12bac205912dc615731bd2dccb6dabd89a791. Current origin/v4 is 74447948f45a0b56e83558d9726d75706d4a4973, so it has drifted; for the files discussed here the only observed drift is src/pkg/dashboard/contribute_ws.go gaining 37 lines of cooldown-explanation helpers before the contributor WebSocket code. bin/contributor-relay.js did not differ in the checked range. The line citations below are against 8cf12bac205912dc615731bd2dccb6dabd89a791, per the issue.

Recommendation

Choose option 2: a versioned, server-selected lease API, implemented by factoring and reusing the existing WebSocket state machine rather than by creating a second scheduler. The API should expose only “ready / assigned / accept / credential / heartbeat-progress / release / complete-fail” semantics; it must not expose “assign me repo X issue Y”, “give me N tasks”, or client-built batches.

This is stricter than an embeddable relay library because the public boundary is the lease protocol itself, not a JavaScript implementation detail. It is also compatible with existing contributors: the WebSocket protocol should remain the default transport, and the new API should share the same server-side selection, lease, credential, PR-verification, cooldown, and run-log functions so protocol divergence is tested as a bug.

Invariants a seam must preserve

Invariant	How the current code enforces it	What a hostile or buggy embedding could break	Design requirement
Server-owned ordering and admission	ready has no repo/issue selector; it clears any held task, records an abandon/release if necessary, then calls selectTask once and sends that one result (src/pkg/dashboard/contribute_ws.go:3866-3984). selectTask serializes selection with selectMu, checks hub readiness, role permission, suspension, disabled tiers, per-identity concurrency/rate limits, and fast-failure pause before scanning (src/pkg/dashboard/contribute_ws.go:5927-6076). It then builds candidates only from server status, excluding held/cooldown/suppressed/failure/active items, open-PR claims, blocked workflow/dependencies, trackers, role mismatches, and config filters (src/pkg/dashboard/contribute_ws.go:6078-6384). Finally it stable-sorts admitted candidates by operator queue override, own work, label affinity, fewer failures, then scan order, and chooses ownFirst[0] (src/pkg/dashboard/contribute_ws.go:6386-6443).	If a seam lets the host name repo/number, submit an externally selected list, or ask for a batch, it bypasses exactly the server decisions above. That is not equivalent to today’s contract; it turns ordering/admission into client good behavior. Multiple local workbench panes could also overrun per-identity limits unless the server remains the allocator.	The only acquisition operation should be “I am ready”; the response is zero or one server-selected assignment. No arbitrary issue request, no client batch synthesis, no client-side queue ordering.
Task generation fencing	On abandonment, ready bumps currentTaskGen before releasing the prior task (src/pkg/dashboard/contribute_ws.go:3870-3881). On assignment, selectTask mints a fresh generation with nextTaskGen, stores it on the connection, includes it in task_assign, and records it in the authoritative lease (src/pkg/dashboard/contribute_ws.go:6507-6552). Resume requires an exact server lease match on identity/task/repo/number/generation (src/pkg/dashboard/contribute_ws.go:4011-4044). Routine progress and terminal complete/fail reject stale generations before mutation (src/pkg/dashboard/contribute_ws.go:4138-4162, src/pkg/dashboard/contribute_ws.go:4170-4190, src/pkg/dashboard/contribute_ws.go:4407-4415). The relay preserves the generation by storing the assignment and echoing task_gen on progress/complete (bin/contributor-relay.js:4107-4193, bin/contributor-relay.js:1309-1381, bin/contributor-relay.js:3591-3615, bin/contributor-relay.js:3821).	A client that can invent assignments or omit/misuse generations can let late output from an old worker renew or complete the wrong task. The current WebSocket path still has a legacy compatibility escape hatch for unversioned relays (task_gen == 0 is accepted in some paths), so a new public API should not copy that weakness.	Make assignment generation required in the new API. Treat it as an opaque lease token tied to server identity and task id; reject missing, stale, or mismatched generations structurally.
Credential after acceptance	selectTask mints a repo-scoped token for the chosen repo, but stores it as pendingToken; the task_assign explicitly omits github_token and token_expires_at (src/pkg/dashboard/contribute_ws.go:6445-6453, src/pkg/dashboard/contribute_ws.go:6527-6536, src/pkg/dashboard/contribute_ws.go:6560-6584). After task_assign is sent, the default path auto-accepts and calls deliverTaskCredential; explicit mode waits for task_accepted (src/pkg/dashboard/contribute_ws.go:3961-3983, src/pkg/dashboard/contribute_ws.go:3989-3999). acceptTaskCredential only delivers when the accepted task id matches the connection’s current task, and deliverTaskCredential is idempotent and sends the credential via token_refresh (src/pkg/dashboard/contribute_ws.go:4910-4984). The relay accepts the assigned task before execution and handles token delivery/refresh separately (bin/contributor-relay.js:4107-4193, bin/contributor-relay.js:4204-4205).	If an embeddable client receives credentials bundled with candidate metadata, it can decline or ignore the task while retaining write authority. If it can request credentials for an arbitrary repo/issue, it defeats repo scoping. Even with explicit accept, the host may “accept” before it has really scheduled OMP; the server can enforce message ordering, not local honesty.	Keep credentials out of the assignment envelope. Require server-recorded accept before credential delivery. Scope credentials to the server-selected repo and never allow a credential endpoint that takes an arbitrary repo chosen by the client.
Lease renewal and release	Task ownership has a 30-minute hub-owned lease; progress renews it and cleanup auto-releases non-renewed work (src/pkg/dashboard/contribute_ws.go:36-47). The lease record binds identity, task id, repo, number/key, tier, generation, and expiry, and is recorded at assignment (src/pkg/dashboard/contribute_ws.go:632-694, src/pkg/dashboard/contribute_ws.go:6538-6552). renewLease only extends an existing same-identity/same-task lease; revokeLease clears it on release paths (src/pkg/dashboard/contribute_ws.go:736-773). Reconnect resume is allowed only by lookupLease; bad claims receive task_revoke (src/pkg/dashboard/contribute_ws.go:4011-4047). Routine progress updates lastLeaseRenew and renews the held server task, not a client-named task (src/pkg/dashboard/contribute_ws.go:4144-4161). Completion revokes the lease after verifying the held task match (src/pkg/dashboard/contribute_ws.go:4191-4238). Cleanup reclaims expired leases through the same release/cooldown/generation-bump path and sends task_revoke (src/pkg/dashboard/contribute_ws.go:5007-5166). The relay resumes only hub-owned tasks and reasserts task_accepted/task_progress on reconnect (bin/contributor-relay.js:3140-3178, bin/contributor-relay.js:4068-4082).	If a host can renew by task id alone, renew another identity’s lease, or keep heartbeating without proving task progress, it can hold work indefinitely or resurrect released work. If release is client-local only, the server’s active/cooldown state drifts and duplicates become likely.	Renewal, release, completion, and resume must all be server lease operations on the exact assignment id/generation. Heartbeat should not be a generic “socket alive” substitute for task progress.
Output capture as evidence, not authority	Interactive mode types the prompt into tmux and scrapes bounded tmux output for progress/completion; headless mode runs a one-shot CLI and captures bounded, token-redacted stdout/stderr (bin/contributor-relay.js:140-152, bin/contributor-relay.js:1278-1381, bin/contributor-relay.js:3788-3821). The server stores tmuxOutput from progress/completion for diagnostics (src/pkg/dashboard/contribute_ws.go:4064-4065, src/pkg/dashboard/contribute_ws.go:4129-4136, src/pkg/dashboard/contribute_ws.go:4213-4217). Completion authority is not just the client’s PR URL: the server verifies the PR against the assigned repo and contributor before long cooldown/trust credit, then writes a normalized run record (src/pkg/dashboard/contribute_ws.go:4235-4319).	An embedding host can omit, truncate, or fabricate logs. No protocol can fully prove an external OMP session executed the prompt. Treating client output or PR URLs as authoritative would let a buggy/hostile host claim success, earn trust, or suppress work incorrectly.	Require bounded output/progress fields for observability, but keep all consequential decisions server-verified where possible. PR URL verification and normalized completion outcomes must remain server-side.

Option evaluation

1. Embeddable relay transport

This can be acceptable only if it is a transport wrapper around the existing server-selected protocol: the embedded component connects to Hive, sends ready, emits exactly the server’s task_assign to the host, accepts host progress/completion events, and owns accept/credential/lease message ordering. In that shape, server ordering/admission, credential-after-acceptance, and lease generation can remain structural because the host never asks for arbitrary work.

The weak point is that the boundary is partly conventional. Once the assignment crosses into an already-running OMP host, Hive cannot structurally prove that the host actually ran the prompt, captured complete output, stopped a revoked worker, or refrained from local batching. The shipped relay currently owns exactly those lifecycle details: it chooses interactive tmux versus headless mode (bin/contributor-relay.js:140-172), builds backend launch commands and headless argv (bin/contributor-relay.js:1108-1253), dispatches headless one-shot execution and reports exit-derived completion/failure (bin/contributor-relay.js:1278-1381), injects the prompt or starts headless execution on task_assign (bin/contributor-relay.js:4107-4193), and scrapes/stops the interactive CLI before reporting completion (bin/contributor-relay.js:3788-3821). If OMP owns those pieces instead, Hive’s only safe stance is “host output is diagnostic; server leases and PR verification remain authoritative.”

This option has the lowest server API surface but makes a JavaScript relay package or subprocess shim part of the public contract. That may be pragmatic, but it is less clean than a protocol-level lease API for non-JS consumers and already-running hosts.

2. Versioned lease API

This best preserves the invariants structurally if the API is deliberately narrow:

1. POST /contributor/v1/ready — no repo/issue/batch parameters; returns task_unavailable or one server-selected assignment generated by the same code path as selectTask.
2. POST /contributor/v1/assignments/{task_id}/accept with required generation — records acceptance and returns/sends the scoped credential only after the server confirms the held assignment.
3. POST /contributor/v1/assignments/{task_id}/progress with required generation and bounded output tail — renews only the matching server lease.
4. POST /contributor/v1/assignments/{task_id}/release — explicit decline/give-back path that revokes the lease and books the same cooldown/fencing as WebSocket ready abandon or task failure.
5. POST /contributor/v1/assignments/{task_id}/complete / fail with required generation — terminal paths that verify the held assignment, revoke the lease, verify PR claims, and append the same run record.

The API must reuse the same server internals as the WebSocket path. Duplicating the scheduler would be the main failure mode: today the correctness is in the dense interaction among ready, selectTask, lease records, credential delivery, cleanup, and completion verification. A second implementation will drift.

This option explicitly meets the hard constraint: no endpoint may accept an arbitrary issue request or batch definition. The only client-chosen values should be operational evidence about the already-issued assignment: accept/decline, progress text, output tail, completion result, and PR URL to be verified by the server.

3. No new API

This preserves all current invariants because it changes nothing. The existing WebSocket + relay remains the one supported public contract, with the server owning selection and the relay owning agent execution. It is the safest maintenance choice.

It does not solve the downstream problem described in this issue. It forces projectbluefin/review and similar consumers to keep a separate contributor worker or reimplement unsupported local shims. That is a valid product decision, but it means Hive is explicitly not supporting an already-running OMP workbench as a contributor host.

Scope for a first version

Keep out of scope:

• Client-requested repo/issue assignment.
• Multi-assignment batches.
• Client-side queue ordering or admission plugins.
• A general maintainer-workbench API.
• Trust promotion changes.
• New credential scopes or long-lived credentials.
• A guarantee that Hive can prove the host actually executed the prompt; output remains evidence, not authority.
• Copying the WebSocket legacy task_gen == 0 compatibility behavior into the new API.

Include only a single-assignment lease lifecycle and strict generation requirements.

Migration and compatibility

Leave the WebSocket protocol and shipped relay working unchanged. The new API should either wrap the existing WebSocket state machine internally or, preferably, factor the shared state transitions into a common contributor lease service used by both transports. Reusing the same WSMessage-equivalent schema fields is fine, but the public API should be explicitly versioned so strict generation and accept semantics can be required for new clients without breaking old relays.

The cost of divergence is high: selection bugs here are security/correctness bugs, not UI bugs. If WebSocket and REST lease paths have separate admission filters, lease expiry, credential timing, or completion verification, one will eventually allow arbitrary work selection, duplicate assignment, stale completion, or premature credential release. Shared tests should assert identical behavior for server-selected assignment, generation rejection, post-accept credential delivery, renew/release, and verified completion.

Risks of the recommendation

• A new public contract is a maintenance burden: docs, versioning, auth, compatibility tests, and support for non-relay clients.
• A poorly designed API could be worse than no API if it exposes repo/issue selection or batch creation.
• Even a correct API cannot fully trust host-supplied execution logs; OMP bugs could still report misleading progress or omit useful output.
• Strict generation requirements may reveal assumptions hidden by legacy WebSocket compatibility, so rollout needs conformance tests and clear error messages.
• Factoring the current WebSocket code may be invasive; duplicating it is tempting but dangerous because divergence would erode the exact invariants this issue is about.

My bottom line: support embedding, but only at the server-selected lease boundary. Do not export scheduler knobs to the client, and do not make “no arbitrary issues or synthesized batches” a matter of client politeness.

[github-actions]

Hi @clubanderson! To assign yourself, use the slash command: /assign (and /unassign to remove).

Resources: Contributors Guide

[clubanderson]

Unresolved before any seam is ratified: the confinement bypass

The DESIGN-RESPONSE covers ordering, fencing, credential-after-acceptance and lease semantics. There is one more invariant that none of the three options preserves as written, and it is the one that decides whether option 1 or 2 is safe at all.

Hive currently refuses to launch the very host that is asking.

omp is tier T3 — experimental (unconfined):

"No confinement hive can wire; local mode refuses to launch without a per-backend opt-in, container mode is the default"
_{src/docs/backend-support-tiers.md:25}

"omp is interactive-only ... It has no verified local confinement mechanism, so local mode refuses it without HIVE_OMP_DANGEROUSLY_RUN_UNCONFINED=1; container mode is the supported boundary."
_{src/docs/contributor-relay.md:89}

"OMP exposes --auto-approve, but that controls confirmation prompts rather than filesystem or host-state confinement; Hive does not pass it on the interactive contributor path."
_{src/docs/sandbox-isolation.md:48}

That refusal is deliberate and explicitly not blanket-overridable — sandbox-isolation.md:65 notes a single shared flag was rejected because "opting into one unconfined backend would silently opt into all seven."

The problem: an assignment carries a live credential. It is minted server-side for the lease's tier and scoped to the lease's repo (the C4 rule, contribute_ws.go resumeTaskToken), and delivered only after acceptance. Today the only consumer of that credential is a relay Hive itself launched, under whichever confinement the backend tier mandates.

A lease API (option 2) or an embeddable transport (option 1) delivers that same credential to a process Hive did not start, cannot inspect, and — for the motivating caller specifically — has already judged it cannot confine. The API would therefore grant, over HTTP, exactly what just contribute-hive omp local refuses to do at the CLI without a dangerous per-backend opt-in.

This is not an argument against the seam. It is an argument that "who is allowed to hold a lease credential" has to become an explicit, server-side decision rather than an emergent property of "Hive owns the process." Options worth weighing in the response:

• Tier-gate leases. A host declares its execution environment; T3/unconfined hosts get no lease, or only leases on repos/tiers where that is acceptable. Mirrors the existing per-backend opt-in rather than inventing a second policy.
• Narrow the credential. If the host is untrusted, the token it receives should be weaker than the one Hive hands its own confined relay — shorter TTL, tighter scope, or no direct push at all.
• Require an explicit operator opt-in per embedding host, in the spirit of HIVE_<BACKEND>_DANGEROUSLY_RUN_UNCONFINED, so enabling one workbench does not enable all of them.

Why this should be settled now rather than after: #6909 is the first example of the same class. generationAccepted() returned true whenever the client generation was 0, making the #2568 Gate opt-in — an assumption that was harmless only because the sole speaker of the protocol was Hive's own relay. Widening the contract to third-party hosts converts every such latent "our own client would never do that" assumption into a live exposure. The confinement rule is the largest remaining one.

[clubanderson]

Counter-recommendation: prefer option 1, defer option 2

The DESIGN-RESPONSE recommends option 2 (a versioned lease API). Recording a dissent for the maintainer to weigh before ratifying, because the evidence that landed today points the other way.

Why not option 2 first

Option 2 turns each invariant this issue lists — ordering, admission, generation fencing, credential-after-acceptance, lease renewal/release, output capture — into a documented obligation that every third-party client must implement correctly. Hive's guarantee then becomes only as strong as the weakest embedder, and Hive cannot audit them.

The reason to doubt that arrangement is #6909, filed today:

generationAccepted() returned true whenever clientGen == 0, and an omitted task_gen decodes to exactly 0 — so the #2568 Gate was bypassable at all three call sites by leaving a field out.

That bypass survived because the only speaker of the protocol was Hive's own relay, which happens to always stamp the field. The invariant was upheld by accident, not by construction. If the single in-house implementation carried a latent bypass, a published contract implemented by N external workbenches will carry worse ones — and per the confinement analysis above, the motivating embedder is a tier-T3 unconfined host holding a live repo-scoped credential.

Why option 1 fits better

An embeddable transport keeps selection, fencing, heartbeat and release inside code Hive ships and versions. The host owns presentation and agent execution — which is all projectbluefin/review actually asked for. A fencing bug is then fixed once, upstream, instead of in every workbench that reimplemented it.

It also matches the caller: the shipped relay is already JavaScript (bin/contributor-relay.js), so an OMP workbench can consume an embeddable transport directly rather than re-deriving the protocol.

Suggested sequencing

1. Settle the confinement question first. It gates options 1 and 2 equally — either way Hive hands a live credential to a host it did not launch and (for omp) has judged it cannot confine. Tier-gated leases, a narrowed credential, or a per-embedding-host opt-in.
2. Ship option 1 to unblock the downstream.
3. Promote to option 2 only when a second, non-JS embedder appears. By then the invariants will have been exercised through a real seam instead of specified speculatively, and the API can be written from demonstrated requirements.

Option 3 (no seam) should be rejected. The demand is concrete and already costing a downstream; refusing pushes embedders toward local selection logic, which is precisely what these invariants exist to prevent.

Deferring to @clubanderson for the actual ratification — this is a boundary decision, not an implementation detail.

[clubanderson]

Decision: option 1, delivered as the contributor-protocol binding from the runs work

The seam this issue asks for was chosen on 2026-09-22 under #8201 and recorded in #8302: an external host takes a lease over the existing contributor relay, advertising a capability, receives a bounded context bundle, and returns a stage receipt. Hive keeps selection, admission ordering, generation fencing, lease renewal and release, and output capture on the server. No new versioned lease API is added, which is the dissent's option 1 in substance.

What already exists on v5 to support it:

• contribute: lease persistence failures are logged, not returned, so a grant can vanish on restart #8287 lease persistence failures refuse the grant instead of leaking a lease.
• [runs] Lease stage field, stage-advance op, per-stage generations #8297 lease stage field, per-stage generations, and the run-stage capability: a peer that opts in without the capability is refused, never downgraded.
• [runs] Stage handoff receipt schema in outputschema #8295 the stage receipt schema (stage-receipt/v1) a host returns when its work ends.
• [runs] GET /api/runs projection over leases #8299 read-only GET /api/runs for the workbench to show.

On the confinement bypass (OMP is tier T3, unconfined): the answer is the credential rule, not confinement. A host bound this way in report-only mode receives no repository credentials and no dashboard token (#8348 is proving the token never reaches the task MCP URL). Publication is Hive-side only, through #8353. An unconfined host is admissible in report-only and advisory modes because there is nothing for it to misuse; anything that writes stays behind Hive's own publisher and the hive's ACMM level.

#8361 implements the binding. It was written for Flue as the first engine; OMP becomes the second host behind the same adapter interface (start, observe, cancel, receipt fetch). Two gaps an interactive host needs that a batch engine does not, added to #8361's scope:

1. Explicit accept or decline of an offered assignment before any credential or context beyond the summary is delivered, matching the WebSocket protocol's acceptance step.
2. A mid-stage progress event (accepted, running, waiting, terminal, unknown) so the workbench can render state without polling the receipt.

Nothing here asks the downstream for a shim or client-side selection. The seam is Hive's to build; projectbluefin/review can wire the workbench once #8361 lands. Tracked on the #8290 board.

[clubanderson]

Workbench side of the binding, per the 2026-09-23 decision above. To take Hive work, an OMP workbench connects as an ordinary contributor peer and declares ext-exec/omp in capabilities.relay_capabilities together with its workbench_version (must equal the hub's runs.external.omp.workflow_version) and a per-session incarnation; a peer without the token is refused, never downgraded. It then handles a small set of frames on that same channel. On ext_offer (execution_key, work_key, task_id, task_gen, stage, summary: the summary only) it must reply ext_accept or ext_decline with a reason; nothing else arrives until it accepts, and an unanswered offer is treated as declined. On ext_start (the bounded bundle, sent only for an accepted key) it replies ext_started with a remote_run_id, answering deduplicated: true if it already runs that key with the same payload and ext_start_refused with reason conflict for the same key with a different payload. While working it sends ext_progress with state accepted, running, waiting, terminal, or unknown plus the current stage; on ext_cancel it replies ext_cancel_ack reporting acknowledged and stopped as separate facts, never claiming stopped unless it is. It finishes with ext_receipt carrying a stage-receipt/v1 document (path, sha256 digest, size, body) that echoes the admission identities from the bundle. It receives no repository credential and no dashboard token, the receipt is evidence Hive verifies rather than authority, publication stays on the Hive side, and because OMP is unconfined only report-only stages are ever offered to it. The full frame table, the conformance rows, and a runnable second-process fixture are in PR #8433 (src/pkg/extwork/omp, design record src/docs/design/external-workflow-admission.md, section "OMP as second host").

[github-actions]

PR #8520 has merged (#8520) and referenced this issue with a non-closing Refs #6899 rather than a closing keyword.

Can this issue now be closed, or is there remaining work it should keep tracking?

[clubanderson]

Closing as done. The seam this issue asked for shipped as option 1 (decision recorded above, 2026-09-22/23):

• 📝 design: capability-aware contributor assignment hub/relay boundary (RFC #6825) #6975 — design: capability-aware contributor assignment hub/relay boundary
• ✨ extwork: add the OMP workbench as the second external host #8433 — OMP workbench as an external host (ext-exec/omp capability, workbench_version + per-session incarnation)
• ✨ external workflows: dispatch engine-bound tasks and attach OMP peers on auth_ok (gap 5 of #8460) #8494 — dispatch engine-bound tasks and attach OMP peers on auth_ok
• 🌱 runs: add Flue and OMP smoke canaries #8520 — Flue and OMP smoke canaries

Hive keeps server-side selection, admission ordering, generation fencing, lease renewal/release, and the credential-after-acceptance rule; the workbench owns presentation and execution only. Thanks @castrojo for the precise analysis. Follow-ups should go in new issues.

[github-actions]

@castrojo this issue was closed by @clubanderson as completed.

If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.

If you are still seeing the problem, comment /reopen and it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.