orizu 0.5.13 → 0.5.15

package/src/github-setup.ts

@@ -19,7 +19,7 @@ import { existsSync, mkdirSync } from 'fs'
 import { join } from 'path'
 
 import { authedFetch } from './http.js'
-import { assertWorkspaceDirUsable } from './workspace.js'
+import { assertWorkspaceDirUsable, workspaceExists } from './workspace.js'
 
 export type SetupFetcher = (path: string, init?: RequestInit) => Promise<Response>
 
@@ -56,7 +56,37 @@ export interface GithubLinkResult {
 }
 
 const DEFAULT_POLL_INTERVAL_MS = 2000
-const DEFAULT_POLL_TIMEOUT_MS = 180000
+// ALI-1141: long enough for a slow org-picker + repo-selection walk, but the
+// wait MUST be finite — when the App is already installed in the target org,
+// GitHub only offers "Configure" and never redirects to our setup callback, so
+// an unbounded poll would spin forever. (Still under the server's 15-minute
+// nonce TTL, so the poll times out before the server would report `expired`.)
+const DEFAULT_POLL_TIMEOUT_MS = 600000
+// ALI-1141: after this long with no callback, the likeliest cause is the
+// already-installed org above — surface it instead of heartbeating silently.
+const ALREADY_INSTALLED_HINT_MS = 90000
+
+/**
+ * Why the poll can never succeed when the App is already installed in the org
+ * (ALI-1141): GitHub's `installations/new?state=` page then only offers
+ * "Configure", and completing configuration does NOT redirect to the App's
+ * Setup URL with our state nonce — the callback that flips the row out of
+ * `pending` never fires. Printed as a mid-poll hint and folded into the
+ * timeout error so the user is never left with an unexplained hang.
+ */
+function alreadyInstalledHintLines(teamSlug: string): string[] {
+  return [
+    '   ⚠ GitHub has not called back yet. The most likely cause: the Orizu GitHub',
+    '     App is ALREADY INSTALLED in that org — GitHub then only offers',
+    '     "Configure", and finishing configuration never notifies Orizu, so this',
+    '     wait cannot succeed. Remedies:',
+    '     • Install the App into a DIFFERENT GitHub org for this team (each org',
+    '       installation can be linked to exactly one Orizu team).',
+    '     • If the org is not linked to any Orizu team, uninstall the Orizu App',
+    '       from the org (GitHub → org Settings → GitHub Apps) and re-run',
+    `       \`orizu github link --team ${teamSlug}\` to do a fresh install.`,
+  ]
+}
 
 function defaultSleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
@@ -118,10 +148,12 @@ export async function runGithubLink(teamSlug: string, io: GithubLinkIo): Promise
   const sleep = io.sleep ?? defaultSleep
   const interval = io.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS
   const timeout = io.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS
-  const deadline = now() + timeout
+  const started = now()
+  const deadline = started + timeout
   // Periodic heartbeat so a long install does not look hung; never echoes state.
   const HEARTBEAT_MS = 15000
-  let lastHeartbeat = now()
+  let lastHeartbeat = started
+  let printedAlreadyInstalledHint = false
 
   for (;;) {
     const poll = await fetcher(`/api/cli/github/link?state=${encodeURIComponent(state)}`)
@@ -149,11 +181,23 @@ export async function runGithubLink(teamSlug: string, io: GithubLinkIo): Promise
       // status 'pending' → keep waiting.
     }
     if (now() >= deadline) {
+      // Same actionable message as the mid-poll hint: an already-installed org
+      // is the one known way to reach this timeout with nothing else wrong.
       throw new Error(
-        'Timed out waiting for the GitHub App install to complete. ' +
+        `Timed out waiting for the GitHub App install to complete after ${Math.round(timeout / 60000)} minutes. ` +
+          'If the Orizu GitHub App is already installed in that org, GitHub never notifies Orizu when you finish the "Configure" flow — ' +
+          'install the App into a DIFFERENT GitHub org for this team (or uninstall it from the org first if no other Orizu team uses it). ' +
           `Resume with \`orizu github link --team ${teamSlug}\` after finishing the install.`
       )
     }
+    if (!printedAlreadyInstalledHint && now() - started >= ALREADY_INSTALLED_HINT_MS) {
+      for (const line of alreadyInstalledHintLines(teamSlug)) io.print(line)
+      io.print(
+        `   Still waiting (Ctrl+C to abort; resume later with \`orizu github link --team ${teamSlug}\`)…`
+      )
+      printedAlreadyInstalledHint = true
+      lastHeartbeat = now()
+    }
     if (now() - lastHeartbeat >= HEARTBEAT_MS) {
       io.print('   …still waiting for the GitHub install to complete.')
       lastHeartbeat = now()
@@ -338,8 +382,7 @@ export async function runHostedAttach(
   io.print(`   Cloning ${repoFullName}...`)
   // Clone with the helper inline + the workspace id in the env so the token is
   // brokered on demand and never materializes in the URL or on disk.
-  gitOrThrow(
-    io.git,
+  const clone = io.git(
     [
       '-c',
       `credential.helper=${CREDENTIAL_HELPER}`,
@@ -351,6 +394,22 @@ export async function runHostedAttach(
     ],
     { env: { ORIZU_WORKSPACE_ID: options.workspaceId } }
   )
+  if (clone.status !== 0) {
+    const detail = clone.stderr || `exit ${clone.status}`
+    // A local-only workspace (`orizu setup --local`) has orizu.team.json but no
+    // `.git`, so it passes `assertWorkspaceDirUsable` yet fails the clone —
+    // `git clone` refuses the non-empty dir up front and writes nothing, so
+    // every byte in there is the user's workspace, not an incomplete clone.
+    // Never advise deleting it.
+    if (workspaceExists(options.targetDir)) {
+      throw new Error(
+        `git clone failed: ${detail} ${options.targetDir} already holds a local Orizu workspace (orizu.team.json) without a hosted clone, so the workbench repo can't be cloned into it. Don't delete it — move it aside or re-run \`orizu setup\` with \`--workspace <empty-path>\` (or keep it local with \`--local\`).`
+      )
+    }
+    throw new Error(
+      `git clone failed: ${detail} Remove or empty the incomplete clone directory ${options.targetDir}, then re-run \`orizu setup\`.`
+    )
+  }
   // Persist the helper repo-locally for future pull/push (cwd-resolved).
   gitOrThrow(io.git, ['config', 'credential.helper', CREDENTIAL_HELPER], { cwd: options.targetDir })
   gitOrThrow(io.git, ['config', 'credential.useHttpPath', 'true'], { cwd: options.targetDir })

package/src/help.ts

@@ -772,16 +772,28 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['session', 'start'],
-    usage: 'orizu session start [--project <team/project>] [--workspace <dir>] [--json]',
+    usage: 'orizu session start [--project <team/project>] [--workspace <dir>] [--json] | orizu session start --hosted (--task <prompt> | --task-file <path>) [--duration <min>] [--project <team/project>] [--tail]',
     summary:
-      'Start a durable workspace session and print the session id. When run inside the workbench clone (or with --workspace), the remote session branch is fetched and checked out locally, and the exact next git commands are printed.',
+      'Start a durable workspace session, or add --hosted with a task prompt to start a coordinator-managed hosted agent. Plain sessions check out their remote session branch locally when run inside the workbench clone (or with --workspace).',
     group: 'Sessions',
     options: [
       { name: '--project <team/project>', help: 'Optionally scope the session to a project in the attached workspace.' },
       { name: '--workspace <dir>', help: 'Workbench clone directory when not running from inside it.' },
+      { name: '--hosted', help: 'Start a coordinator-managed hosted agent session instead of a plain durable session.' },
+      { name: '--task <prompt>', help: 'Hosted agent task prompt. Mutually exclusive with --task-file.' },
+      { name: '--task-file <path>', help: 'Read the hosted agent task prompt from a UTF-8 file. Mutually exclusive with --task.' },
+      { name: '--duration <min>', help: 'Hosted sandbox duration in minutes (default 60, maximum 1440).' },
+      { name: '--model <provider/model>', help: 'Optional hosted model override.' },
+      { name: '--reasoning-effort <level>', help: 'Optional hosted model reasoning-effort override.' },
+      { name: '--title <title>', help: 'Optional hosted run title.' },
+      { name: '--tail', help: 'Follow the hosted run until it reaches a terminal state.' },
       { name: '--json', help: 'Emit the machine-readable session payload.' },
     ],
-    examples: ['orizu session start', 'orizu session start --project highlight/hip --json'],
+    examples: [
+      'orizu session start',
+      'orizu session start --project highlight/hip --json',
+      'orizu session start --hosted --task-file ./task.md --project highlight/hip --duration 90',
+    ],
   },
   {
     path: ['session', 'status'],

package/src/hosted-boot.ts

@@ -50,7 +50,7 @@ import {
   type HostedLoopContext,
   type HostedLoopResult,
 } from './hosted-loop.js'
-import { DEFAULT_EGRESS_CANARY_HOST } from './hosted-loop-lifecycle.js'
+import { DEFAULT_EGRESS_CANARY_HOST, DEFAULT_HOSTED_MODEL } from './hosted-loop-lifecycle.js'
 import { resumeRunEventSink } from './hosted-run-event-sink.js'
 import { stageOrizuSkill } from './hosted-skill-staging.js'
 
@@ -62,8 +62,6 @@ export type BootFetch = (url: string, init?: RequestInit) => Promise<Response>
  *  DO-path `workers/session-coordinator/src/bootstrap.ts`); kept in sync by
  *  grep. Inlined (not imported) to avoid a hosted-session-cli import cycle. */
 const ANTHROPIC_DUMMY_KEY = 'sk-ant-orizu-proxy-broker-placeholder'
-/** Default hosted model — mirrors hosted-session-cli.ts `DEFAULT_HOSTED_MODEL`. */
-const DEFAULT_HOSTED_MODEL = 'anthropic/claude-opus-4-8'
 
 // -- Frozen env contract ------------------------------------------------------
 
@@ -513,6 +511,9 @@ export interface RunHostedBootOptions {
     context: HostedLoopContext
     taskPrompt: string
     bearerProvider: () => string
+    /** Verbatim secrets the loop's event redaction must scrub (ALI-1062: the
+     *  boot secret — bare hex, so no shape pattern would ever catch it). */
+    redactSecretsList: readonly string[]
   }) => Promise<HostedLoopResult>
   now?: () => number
   log?: (line: string) => void
@@ -565,6 +566,17 @@ export async function runHostedBoot(opts: RunHostedBootOptions): Promise<HostedB
   const log = opts.log ?? ((): void => {})
   const now = opts.now ?? ((): number => Date.now())
 
+  // 0 — ENV HYGIENE (ALI-1062): the boot secret is the DO path's only durable
+  // credential (it mints agent bearers at the internet-reachable agent-token
+  // route for up to 24h), and `env.bootSecret` is already captured — so scrub
+  // the raw value from the process env NOW, before anything downstream can
+  // inherit it: the opencode/agent process is spawned with `{...process.env}`
+  // (nodeChildSpawner) and the customer `.orizu/setup.sh` hook inherits the
+  // env too. Nothing reads it from the env after this point — the rotation /
+  // boot-status closures hold `env.bootSecret`, and the git credential helper
+  // reads the 0600 run-dir boot-secret FILE (written in step 4).
+  delete processEnv.ORIZU_BOOT_SECRET
+
   // 1 — Pull the agent bearer (retry/backoff — the DO may still be arming).
   const bearer = await pullAgentBearer({
     agentTokenUrl: env.agentTokenUrl,
@@ -738,10 +750,20 @@ export async function runHostedBoot(opts: RunHostedBootOptions): Promise<HostedB
     const runLoop =
       opts.runLoop ??
       ((input): Promise<HostedLoopResult> =>
-        runHostedLoop({ context: input.context, taskPrompt: input.taskPrompt, bearerProvider: input.bearerProvider }))
+        runHostedLoop({
+          context: input.context,
+          taskPrompt: input.taskPrompt,
+          bearerProvider: input.bearerProvider,
+          redactSecretsList: input.redactSecretsList,
+        }))
     const result = await runLoop({
       context: loopContext,
       taskPrompt: session.task,
+      // ALI-1062 exact-value redaction: the boot secret is 64 bare hex chars —
+      // no TOKEN_SHAPE_PATTERNS rule can catch it, so it MUST ride the loop's
+      // verbatim redaction list or an echoed env dump would land it in
+      // workbench_run_events.
+      redactSecretsList: [env.bootSecret],
       // Read the bearer FILE fresh per request (review F1): `startBearerRotation`
       // rewrites `bearerFileAbs` before the current bearer expires, so a run
       // exceeding the ~60-min TTL (DO cap is 24h) keeps a valid bearer. A frozen

package/src/hosted-harness-opencode.ts

@@ -155,6 +155,23 @@ const ANTHROPIC_ADAPTIVE_THINKING_MODELS = new Set([
 ])
 const ANTHROPIC_ADAPTIVE_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max'])
 
+/**
+ * Split a possibly provider-qualified model string into provider + model id.
+ * SINGLE-SLASH ids ("anthropic/claude-opus-4-8") are the assumed form; a bare
+ * id defaults to provider "anthropic". This is THE shared parse — consumed by
+ * BOTH the prompt path (`buildPromptRequestBody`) and the pre-prompt
+ * validation (`awaitOpenCodeModelResolvable`), so the two can never drift:
+ * parity is exactly what makes the validation meaningful (ALI-1086).
+ * KNOWN LIMIT: `split('/', 2)` drops everything after the second slash, so a
+ * 3-part id ("openrouter/anthropic/claude-x") misparses to provider
+ * "openrouter" + model "anthropic" — identically in both places (today's
+ * pre-existing prompt-path behavior, now shared rather than duplicated).
+ */
+export function qualifyHostedModel(model: string): { providerId: string; modelId: string } {
+  const [providerId, modelId] = model.includes('/') ? model.split('/', 2) : ['anthropic', model]
+  return { providerId, modelId }
+}
+
 export function buildPromptRequestBody(
   content: string,
   model: string | undefined,
@@ -167,7 +184,9 @@ export function buildPromptRequestBody(
   }
   if (!model) return body
 
-  const [providerId, modelId] = model.includes('/') ? model.split('/', 2) : ['anthropic', model]
+  // Shared parse (see qualifyHostedModel): keeps the prompt path and the
+  // ALI-1086 pre-prompt validation in lockstep by construction.
+  const { providerId, modelId } = qualifyHostedModel(model)
   const modelSpec: Record<string, unknown> = { providerID: providerId, modelID: modelId }
 
   if (reasoningEffort) {
@@ -757,6 +776,190 @@ function errorEvent(messageId: string, error: unknown): HarnessEvent {
   return { kind: 'error', messageId, critical: true, payload: { error: message } }
 }
 
+// -- Pre-prompt model validation (ALI-1086) -----------------------------------
+//
+// The pinned OpenCode (see OPENCODE_PINNED_VERSION) resolves model ids against
+// a catalog that is its BUNDLED snapshot merged with a runtime fetch of
+// https://models.dev/api.json (verified empirically on ALI-1086: fetched at
+// boot when reachable, cached to <cache>/opencode/models.json, refreshed when
+// stale). When models.dev is unreachable the bundled snapshot is stale
+// (predates claude-opus-4-8) and the FIRST prompt dies inside the SSE stream
+// with an opaque `run_failed: Model not found`. These helpers let the hosted
+// loop ask the RUNNING `opencode serve` — `GET /config/providers` is the
+// runtime's actual resolvable catalog — whether the requested model resolves,
+// BEFORE the prompt is posted, and fail fast naming the alternatives.
+
+/** provider id → model ids the RUNNING opencode instance can resolve. */
+export type OpenCodeModelCatalog = ReadonlyMap<string, readonly string[]>
+
+const MODEL_CATALOG_REQUEST_TIMEOUT_MS = 10_000
+
+/**
+ * Read the resolvable catalog from a running `opencode serve` via
+ * `GET /config/providers` (shape: `{ providers: [{ id, models: { <id>: … } }] }`,
+ * verified against opencode-ai@1.14.41). Returns null on ANY transport/shape
+ * failure — the caller treats that as "cannot validate", never as "invalid".
+ */
+export async function fetchOpenCodeModelCatalog(
+  baseUrl: string,
+  fetchImpl: HarnessFetch = globalThis.fetch as HarnessFetch,
+  timeoutMs: number = MODEL_CATALOG_REQUEST_TIMEOUT_MS
+): Promise<OpenCodeModelCatalog | null> {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(`${baseUrl.replace(/\/$/, '')}/config/providers`, {
+      signal: controller.signal,
+    })
+    if (!res.ok) return null
+    const data = asRecord(await res.json())
+    if (!Array.isArray(data.providers)) return null
+    const catalog = new Map<string, string[]>()
+    for (const entry of data.providers) {
+      const provider = asRecord(entry)
+      const id = typeof provider.id === 'string' ? provider.id : null
+      if (!id) continue
+      catalog.set(id, Object.keys(asRecord(provider.models)))
+    }
+    return catalog
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+function sharedPrefixLength(a: string, b: string): number {
+  const max = Math.min(a.length, b.length)
+  let i = 0
+  while (i < max && a[i] === b[i]) i += 1
+  return i
+}
+
+/** Rank candidate model ids by similarity to the requested id (longest shared
+ *  prefix first, ties broken lexicographically DESCENDING so the newest of a
+ *  versioned family leads) and cap the list — the fail-fast error should lead
+ *  with the closest/newest substitutes, not a full catalog dump. */
+export function rankModelAlternatives(
+  requested: string,
+  candidates: readonly string[],
+  limit = 8
+): string[] {
+  return [...new Set(candidates)]
+    .sort((a, b) => {
+      const byPrefix = sharedPrefixLength(requested, b) - sharedPrefixLength(requested, a)
+      return byPrefix !== 0 ? byPrefix : b.localeCompare(a)
+    })
+    .slice(0, limit)
+}
+
+export type ModelValidationOutcome =
+  | { kind: 'resolvable'; waitedMs: number }
+  | {
+      kind: 'unresolvable'
+      /** Provider-qualified requested model, e.g. "anthropic/claude-opus-4-8". */
+      requested: string
+      /** Provider-qualified resolvable substitutes, closest first. */
+      alternatives: string[]
+      /** False when the PROVIDER itself is unknown to the runtime. */
+      providerKnown: boolean
+      waitedMs: number
+    }
+  | { kind: 'skipped'; reason: string }
+
+export interface AwaitModelResolvableOptions {
+  /** Base URL of the running `opencode serve`. */
+  baseUrl: string
+  /** Requested model, provider-qualified or bare (bare → "anthropic"). */
+  model: string
+  fetchImpl?: HarnessFetch
+  /**
+   * Total budget to wait for the model to become resolvable. OpenCode's
+   * models.dev refresh runs in the BACKGROUND at boot, so the catalog can be
+   * bundled-only for the first seconds after the server answers HTTP; polling
+   * bridges that window instead of failing a run the refresh would have fixed.
+   */
+  timeoutMs?: number
+  pollMs?: number
+  sleep?: (ms: number) => Promise<void>
+  now?: () => number
+}
+
+const MODEL_RESOLVE_TIMEOUT_MS = 30_000
+const MODEL_RESOLVE_POLL_MS = 2_000
+
+/**
+ * Decide whether the requested model is resolvable by the RUNNING opencode,
+ * polling briefly so the boot-time models.dev refresh has time to land.
+ * Fail-open on validator infrastructure, with a DELIBERATE asymmetry on null
+ * catalog reads:
+ *   - null BEFORE any successful read → `skipped` immediately (dead/absent
+ *     endpoint; opencode's own `session.error` remains the backstop, and the
+ *     early exit keeps absent-endpoint runs — and tests — cheap);
+ *   - null AFTER at least one successful read → a transient boot-window blip
+ *     (5xx/drop): sleep and keep polling within the budget; a budget that
+ *     ends in that state returns `skipped`, NEVER a false `unresolvable` off
+ *     a flaky read.
+ * Only a HEALTHY catalog that never lists the model within the budget yields
+ * `unresolvable`, with ranked, provider-qualified alternatives.
+ */
+export async function awaitOpenCodeModelResolvable(
+  opts: AwaitModelResolvableOptions
+): Promise<ModelValidationOutcome> {
+  const timeoutMs = opts.timeoutMs ?? MODEL_RESOLVE_TIMEOUT_MS
+  const pollMs = opts.pollMs ?? MODEL_RESOLVE_POLL_MS
+  const sleep = opts.sleep ?? ((ms: number): Promise<void> => new Promise(r => setTimeout(r, ms)))
+  const now = opts.now ?? ((): number => Date.now())
+  const { providerId, modelId } = qualifyHostedModel(opts.model)
+  const requested = `${providerId}/${modelId}`
+
+  const startedAt = now()
+  let lastGoodCatalog: OpenCodeModelCatalog | null = null
+  let sawTransientFailure = false
+  for (;;) {
+    const catalog = await fetchOpenCodeModelCatalog(opts.baseUrl, opts.fetchImpl)
+    if (catalog === null) {
+      if (lastGoodCatalog === null) {
+        // Never answered — the endpoint is dead/absent, not blipping. Skip
+        // immediately rather than invent a failure mode (or a slow wait) the
+        // run would not otherwise have.
+        return { kind: 'skipped', reason: 'opencode /config/providers unavailable' }
+      }
+      // Transient failure after a successful read (boot-window 5xx/drop) —
+      // keep polling within the budget.
+      sawTransientFailure = true
+    } else {
+      lastGoodCatalog = catalog
+      sawTransientFailure = false
+      if ((catalog.get(providerId) ?? []).includes(modelId)) {
+        return { kind: 'resolvable', waitedMs: now() - startedAt }
+      }
+      // Deliberately NOT failing fast when the provider itself is unknown:
+      // the models.dev refresh can add whole providers too, so the poll runs
+      // the full budget either way.
+    }
+    if (now() - startedAt >= timeoutMs) break
+    await sleep(pollMs)
+  }
+
+  if (sawTransientFailure || lastGoodCatalog === null) {
+    // The budget ended on a flaky read — never declare `unresolvable` off it.
+    return { kind: 'skipped', reason: 'opencode /config/providers became unavailable mid-poll' }
+  }
+
+  const providerKnown = lastGoodCatalog.has(providerId)
+  const candidates = providerKnown
+    ? (lastGoodCatalog.get(providerId) ?? []).map(id => `${providerId}/${id}`)
+    : [...lastGoodCatalog.entries()].flatMap(([pid, ids]) => ids.map(id => `${pid}/${id}`))
+  return {
+    kind: 'unresolvable',
+    requested,
+    alternatives: rankModelAlternatives(requested, candidates),
+    providerKnown,
+    waitedMs: now() - startedAt,
+  }
+}
+
 // -- spawnOpenCode: the P3.5 in-sandbox launch helper ------------------------
 
 export interface OpenCodeConfigOptions {

package/src/hosted-loop-lifecycle.ts

@@ -24,6 +24,27 @@
 
 import type { HarnessEvent } from './hosted-harness.js'
 
+/**
+ * Default provider-qualified hosted model — the SINGLE source of truth
+ * (ALI-1086). Imported by both the operator-path session CLI
+ * (`hosted-session-cli.ts`) and the DO-path boot (`hosted-boot.ts`); never
+ * re-inline it.
+ *
+ * PIN CONSTRAINT: the hosted OpenCode runtime is HARD-PINNED to
+ * `opencode-ai@1.14.41` (`OPENCODE_PINNED_VERSION`, SSE-fragile — do not bump)
+ * whose BUNDLED model catalog predates this model (newest bundled anthropic
+ * opus: claude-opus-4-7). Verified empirically on ALI-1086: 1.14.41 DOES fetch
+ * `https://models.dev/api.json` at boot when reachable (cached to
+ * `~/.cache/opencode/models.json`, refreshed when stale, disabled only by
+ * `OPENCODE_DISABLE_MODELS_FETCH`), so with models.dev on the sandbox egress
+ * allowlist (#1392, `ORIZU_HOSTED_EGRESS_ALLOWLIST`) this id resolves in new
+ * sandboxes. If the catalog fetch is blocked/stale anyway, the loop's
+ * pre-prompt validation (`awaitOpenCodeModelResolvable`) fails the run fast,
+ * naming the resolvable alternatives. The durable fix for the stale bundled
+ * catalog is the ALI-929 harness swap.
+ */
+export const DEFAULT_HOSTED_MODEL = 'anthropic/claude-opus-4-8'
+
 /**
  * The run-scoped context the host orchestrator writes for the loop. Paths are
  * ABSOLUTE (or sandbox-root-relative) so the loop resolves them regardless of

package/src/hosted-loop.ts

@@ -51,8 +51,10 @@ import { annotateHeadlessQuestions, withIdleWatchdog } from './hosted-headless.j
 import {
   DEFAULT_PROMPT_MAX_DURATION_MS,
   OPENCODE_PINNED_VERSION,
+  awaitOpenCodeModelResolvable,
   createOpenCodeHarness,
   spawnOpenCode,
+  type ModelValidationOutcome,
   type SpawnOpenCodeOptions,
   type SpawnedOpenCode,
 } from './hosted-harness-opencode.js'
@@ -60,6 +62,8 @@ import { createClaudeAgentHarness } from './hosted-harness-claude.js'
 import {
   drainHarnessToSink,
   resumeRunEventSink,
+  RunTerminalError,
+  TerminalDeliveryError,
   type HostedFetch,
   type TerminalStatus,
 } from './hosted-run-event-sink.js'
@@ -80,6 +84,7 @@ import {
 // coordinator. Re-exported here so this module's public surface is unchanged.
 export {
   DEFAULT_EGRESS_CANARY_HOST,
+  DEFAULT_HOSTED_MODEL,
   buildOpenCodeSpawnEnv,
   egressCanaryAllowedHost,
   runEgressCanary,
@@ -140,6 +145,16 @@ export interface RunHostedLoopOptions {
   createClaudeHarness?: () => AgentHarness
   spawnOpenCode?: (opts: SpawnOpenCodeOptions) => SpawnedOpenCode | Promise<SpawnedOpenCode>
   installOpenCode?: () => Promise<InstallResult>
+  /**
+   * Pre-prompt model validation against the RUNNING opencode's resolvable
+   * catalog (ALI-1086). Default: `awaitOpenCodeModelResolvable`, which polls
+   * `GET /config/providers` briefly so the boot-time models.dev refresh can
+   * land. An `unresolvable` outcome fails the run BEFORE the first prompt with
+   * an error naming the requested id and the resolvable alternatives; a
+   * `skipped` outcome (catalog endpoint unreachable) proceeds — opencode's own
+   * `session.error` remains the backstop. Injectable for tests.
+   */
+  validateModel?: (input: { baseUrl: string; model: string }) => Promise<ModelValidationOutcome>
   now?: () => number
   signal?: AbortSignal
   /** Extra verbatim secrets to redact (the bearer is added by the sink itself). */
@@ -170,6 +185,9 @@ export interface RunHostedLoopOptions {
    * `ORIZU_AGENT_IDLE_TIMEOUT_MS` or 25 minutes. <= 0 disables the watchdog.
    */
   idleTimeoutMs?: number
+  /** Injectable sleep for the terminal-delivery retry backoff (ALI-1065
+   *  finding 2). Tests pass a no-op to avoid real delays. */
+  sleepImpl?: (ms: number) => Promise<void>
 }
 
 export interface HostedLoopResult {
@@ -211,6 +229,16 @@ function resolveIdleTimeoutMs(override: number | undefined): number {
   return DEFAULT_AGENT_IDLE_TIMEOUT_MS
 }
 
+/**
+ * Loop-level retry schedule for an undeliverable TERMINAL transition (ALI-1065
+ * finding 2). Each entry is a pause before one more full sink delivery cycle
+ * (which itself retries ~4 times over ~350ms), so a transport blip of a few
+ * seconds recovers with the ORIGINAL status instead of being re-recorded as
+ * 'failed'. Bounded: a persistently unreachable control plane fails the
+ * DELIVERY visibly (result.error) without recording a wrong outcome.
+ */
+export const TERMINAL_DELIVERY_RETRY_DELAYS_MS: readonly number[] = [2_000, 8_000]
+
 /** Model-key env vars whose value must be scrubbed from every run event. */
 const MODEL_KEY_ENV_VARS = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY']
 
@@ -515,6 +543,43 @@ export async function runHostedLoop(opts: RunHostedLoopOptions): Promise<HostedL
         })
       }
 
+      // Fail-fast model validation (ALI-1086): ask the RUNNING opencode whether
+      // the requested model is resolvable BEFORE the first prompt. The pinned
+      // opencode's bundled catalog is stale (predates claude-opus-4-8) and only
+      // a boot-time models.dev fetch (#1392 allowlists it) refreshes it — when
+      // that fetch is blocked, the first prompt used to die inside the SSE
+      // stream with an opaque `run_failed: Model not found`. Now the run fails
+      // immediately with a structured artifact + an error naming the requested
+      // id AND the resolvable alternatives. Fail-open on validator
+      // infrastructure: an unreachable catalog endpoint (`skipped`) proceeds
+      // silently — opencode's own session.error remains the backstop. Healthy
+      // and skipped runs append NO event, so the ALI-929 cross-harness
+      // stream-identity invariant is untouched (validation exists only on the
+      // opencode path; the Claude-SDK driver resolves models itself).
+      const validateModel = opts.validateModel ?? awaitOpenCodeModelResolvable
+      const validation = await validateModel({ baseUrl: spawned.baseUrl, model: context.model })
+      if (validation.kind === 'unresolvable') {
+        await sink.append({
+          kind: 'artifact',
+          payload: {
+            step: 'model_validation',
+            ok: false,
+            requestedModel: validation.requested,
+            resolvableAlternatives: validation.alternatives,
+            providerKnown: validation.providerKnown,
+            opencodeVersion: pinnedVersion,
+            waitedMs: validation.waitedMs,
+          },
+        })
+        throw new Error(
+          `requested model ${validation.requested} is not resolvable by the pinned ` +
+            `opencode runtime (opencode-ai@${pinnedVersion}); resolvable alternatives: ` +
+            `${validation.alternatives.join(', ') || '(none)'} — retry with --model ` +
+            `set to one of these (stale bundled catalog + blocked models.dev refresh; ` +
+            `see ALI-1086, durable fix ALI-929)`
+        )
+      }
+
       // Derive the per-prompt max-duration cap from the sandbox budget so a long
       // `--duration` run is not killed at the hard-coded 90-min cap while its
       // sandbox is still alive; floored at the harness default for short/undated
@@ -591,10 +656,58 @@ export async function runHostedLoop(opts: RunHostedLoopOptions): Promise<HostedL
     return { status, agentSessionId, installOk, error: null }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
-    // Fail closed: never leave the run non-terminal. finish() is idempotent and
-    // no-ops when the drain already sealed the sink. Harvest FIRST (partial work
-    // is valuable, incl. an idle-watchdog abort) — before the terminal seals.
+    // Harvest FIRST on every abnormal path (partial work is valuable, incl. an
+    // idle-watchdog abort) — before any terminal write seals the sink.
     await runAutoHarvest()
+
+    // ALI-1065 finding 2: an undeliverable TERMINAL transition must NEVER be
+    // re-recorded as 'failed' — the run's outcome was already decided; only its
+    // DELIVERY failed. Retry the delivery with the ORIGINAL status (spaced past
+    // the sink's own ~350ms retry window, so a ~1s transport blip recovers),
+    // and if it still cannot land, fail the DELIVERY visibly: return the
+    // intended status with a non-null error, which the boot reports via its
+    // boot-status callback, and the coordinator's session-end finalizer sweeps
+    // the still-'running' row server-side with an explicit marker.
+    if (error instanceof TerminalDeliveryError) {
+      const sleep = opts.sleepImpl ?? ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)))
+      for (const delayMs of TERMINAL_DELIVERY_RETRY_DELAYS_MS) {
+        if (sink.sealed) break
+        await sleep(delayMs)
+        try {
+          await sink.finish(error.intendedStatus, error.finishOptions)
+          return { status: error.intendedStatus, agentSessionId, installOk, error: null }
+        } catch (retryError) {
+          // The run went terminal server-side while we were retrying: accept
+          // the server record (Orizu records win) instead of retrying further.
+          if (retryError instanceof RunTerminalError) {
+            return { status: 'cancelled', agentSessionId, installOk, error: null }
+          }
+          // Otherwise keep retrying within the bounded schedule; never change
+          // the status.
+        }
+      }
+      if (sink.sealed) {
+        // A concurrent/preceding delivery landed after all — the record is
+        // terminal server-side with our intended status semantics preserved.
+        return { status: error.intendedStatus, agentSessionId, installOk, error: null }
+      }
+      return {
+        status: error.intendedStatus,
+        agentSessionId,
+        installOk,
+        error: `terminal delivery failed (intended status preserved): ${message}`,
+      }
+    }
+
+    // The run went terminal SERVER-side (cancel/finish out from under this
+    // writer): the sink sealed itself; accept the server record (Orizu records
+    // win) instead of fabricating a local failure.
+    if (error instanceof RunTerminalError) {
+      return { status: 'cancelled', agentSessionId, installOk, error: null }
+    }
+
+    // Fail closed: never leave the run non-terminal. finish() is idempotent and
+    // no-ops when the drain already sealed the sink.
     if (!sink.sealed) {
       try {
         await sink.finish('failed', { summary: { error: message } })