Decision supervision

This reference explains how the browser use supervisor handles decisions, pauses, and recovery. For the available supervision paths and their data access, read How Halfspan works and Data access and privacy.

An executor decision is a proposal, clarification, authorization request, or refusal. Only a proposal can carry executable fields, and it must select an action from the current action catalog. Direct HTTP and MCP integrations submit proposals through the restricted service APIs.

Provider responses normalize to output or refusal with response ID, settings, usage, and latency. Completed explicit refusal fields take precedence over accompanying text. An incomplete response or interrupted stream remains a provider failure. There is no keyword-based refusal detection. Explicit refusals bypass the single JSON-repair attempt. A guardian refusal pauses without inventing an ALLOW or TERMINATE judgment.

A managed attempt gets an ID and observation binding before model inference. A proposal enters the existing hard-policy/guardian/permit path. Other outcomes stop before permit creation. Stale results cannot reactivate a changed, revoked, or completed run. Refusal provenance distinguishes structured output from native provider signals.

StopContext version 1 records category, source, reason code, message, recovery action, attempt ID, observation ID, and dispatch certainty. Categories are refusal, clarification, authorization, policy, capability, provider, invalid output, execution, limit, and unknown. Classification uses explicit codes; model-authored prose does not establish permission.

The owner run response includes a nullable stopContext. Stopping a run records its context, invalidates unused permits, and saves signed stop evidence together. Terminal states are preserved. Historical signed records are never rewritten.

Send POST /api/v1/owner/runs/:id/retry with an empty object to resume an eligible paused run without executing a step. The /clarify and /approve routes enforce their own recovery eligibility. All routes require owner authentication and origin checks. A disallowed recovery returns RECOVERY_NOT_ALLOWED; unresolved effects return UNRESOLVED_DISPATCH. Unknown context versions fail closed.

A retryable provider or invalid-output stop permits explicit retry. Configuration stops permit retry after the operator fixes configuration; provider availability is checked again on the next attempt. Refusal and clarification stops permit owner clarification only. Exact approval is offered only for an actual unapproved transaction. Approval does not clear unrelated stops. Exhausted budgets and incompatible capabilities require a new task. Unknown legacy pauses remain inspectable without being relabeled as refusals.

Clarification preserves the original task and grants and creates a fresh observation. Recovery drops private model continuation, rotates restricted credentials, and retains usage counts. Exact mode still requires separate approval after clarification.

Recovery checks unresolved claimed permits against receipts even if the permit has subsequently been revoked. Operations delegated to a hosted service also require a matching service receipt. These checks block redispatch when the external outcome is ambiguous. Recovery cannot override permission checks or resolve an uncertain external transaction on its own.

Signed events include attempt.started, executor.outcome, provider.refusal, run.stopped, run.recovered, and stale-attempt discards. Model evidence records prompt/schema digests and versions, workflow version, effective settings, usage, latency, and observation/action binding. Opaque provider continuation is excluded.

The inspector groups attempts and distinguishes reported rationale, guardian judgment, runtime classification, and receipts. It shows recovery guidance for the specific stop reason. “No action dispatched” applies only to a proven pre-dispatch attempt. Unconfirmed execution is explicitly labeled. Provider text is rendered as text, never executable HTML.

Evaluation reports distinguish live model decisions, fixed-proposal guardian comparisons, and scripted recovery scenarios. Scripted scenarios test how the supervisor handles responses and recovery; they do not measure a model's independent judgment. Read Evaluation for the available comparison modes.

Frozen guardian comparisons keep proposals fixed. Where no authored evidence fixture exists, live evaluation captures provider evidence once per provider/case and attaches it only if the action digest matches. Capture failures, mismatch, and missing readable evidence remain explicit. Every repetition gets a fresh model context. Reports retain case, prompt, and schema digests, model settings, repetition, status, latency, tokens, and provenance. Readable evidence remains opt-in for operational runs.

Rates carry numerator, denominator, and nullable value. Outcome accuracy uses completed eligible decisions. Unnecessary refusals use permissible/proposal-expected cases; missed refusals use refusal-required cases. False approvals count proposals or ALLOW judgments where they were not expected. Paraphrase agreement compares paired cases for the same provider/repetition. Task success is measured only on completed deterministic workflows; recovery success only on recovery scenarios. Unauthorized executions count unexpected persisted domain executions in local enforcement scenarios. Frozen/live-classification suites do not claim task or execution measurements. Errors and unavailable arms are excluded from quality denominators and counted separately.

Cost estimates require explicit per-model pricing and reported token usage. Missing prices remain unpriced; reports do not fabricate invoices or costs.