orizu 0.5.13 → 0.5.15

package/src/hosted-run-event-sink.ts

@@ -161,6 +161,27 @@ export class CriticalDeliveryError extends Error {
   }
 }
 
+/**
+ * Raised when `finish()` itself is undeliverable (ALI-1065 finding 2): a
+ * CriticalDeliveryError thrown WHILE DELIVERING A TERMINAL TRANSITION, carrying
+ * the intended status + finish options so the caller can retry the delivery
+ * with the ORIGINAL outcome. Before this, the error surfaced as a bare
+ * CriticalDeliveryError and the loop's generic catch re-finished the run
+ * 'failed' — a ~1s transport blip on the SUCCESS terminal recorded a succeeded
+ * run as failed. Subclasses CriticalDeliveryError so existing classification
+ * (drop-vs-surface) is unchanged.
+ */
+export class TerminalDeliveryError extends CriticalDeliveryError {
+  readonly intendedStatus: TerminalStatus
+  readonly finishOptions: FinishOptions | undefined
+  constructor(message: string, intendedStatus: TerminalStatus, finishOptions?: FinishOptions) {
+    super(message)
+    this.name = 'TerminalDeliveryError'
+    this.intendedStatus = intendedStatus
+    this.finishOptions = finishOptions
+  }
+}
+
 /**
  * Raised on a 403 from the RunAPI. Named for what a 403 actually is — NOT "the
  * run is terminal" (that is 404/410). A 403 means the caller may no longer write
@@ -534,17 +555,31 @@ export function createRunEventSink(options: CreateRunEventSinkOptions): RunEvent
       diag(`finish(${status}) called on an already-sealed sink — ignored (idempotent)`)
       return
     }
-    // Pre-terminal appends (still writable): flush coalesced tokens, then the
-    // bounded transcript tail (the seal below refuses any later append).
-    await flushTokens()
-    if (opts?.transcript) {
-      await postEvent(
-        AGENT_TRANSCRIPT_EVENT_TYPE,
-        { text: tail(opts.transcript, TRANSCRIPT_TAIL_MAX_CHARS), truncated: opts.transcript.length > TRANSCRIPT_TAIL_MAX_CHARS },
-        true
-      )
+    // ALI-1065 finding 2: a delivery failure ANYWHERE inside finish (the
+    // transcript tail is a critical append; the terminal PATCH is the
+    // transition itself) must carry the INTENDED status out to the caller.
+    // Without this, the loop's generic catch converted an undeliverable
+    // SUCCESS terminal into a recorded 'failed'. RunTerminalError/RunAuthError
+    // pass through unchanged — they are classifications, not delivery
+    // failures.
+    try {
+      // Pre-terminal appends (still writable): flush coalesced tokens, then the
+      // bounded transcript tail (the seal below refuses any later append).
+      await flushTokens()
+      if (opts?.transcript) {
+        await postEvent(
+          AGENT_TRANSCRIPT_EVENT_TYPE,
+          { text: tail(opts.transcript, TRANSCRIPT_TAIL_MAX_CHARS), truncated: opts.transcript.length > TRANSCRIPT_TAIL_MAX_CHARS },
+          true
+        )
+      }
+      await patchTerminal(status, opts)
+    } catch (error) {
+      if (error instanceof CriticalDeliveryError && !(error instanceof TerminalDeliveryError)) {
+        throw new TerminalDeliveryError(error.message, status, opts)
+      }
+      throw error
     }
-    await patchTerminal(status, opts)
   }
 
   return {
@@ -661,6 +696,39 @@ export async function drainHarnessToSink(
     beforeFinishRan = true
     if (opts.beforeFinish) await opts.beforeFinish()
   }
+  // ALI-1065 finding 3: the server now rejects appends to a terminal run with
+  // 410 (the run was cancelled/finished out from under this writer). The sink
+  // seals itself and raises RunTerminalError; the drain must treat that as a
+  // clean server-side termination — stop consuming and report 'cancelled' —
+  // not crash the loop into a spurious re-finish (Orizu records win; the
+  // stored status is whatever the server committed). The hook still runs so
+  // partial work is harvested, but with a sealed sink its own appends no-op.
+  const handleServerTerminal = async (): Promise<TerminalStatus> => {
+    await runBeforeFinish()
+    return 'cancelled'
+  }
+  // finish() can ALSO surface RunTerminalError (its pre-terminal token flush /
+  // transcript append hits the 410 before the PATCH ever runs) — accept the
+  // server's termination the same way instead of crashing the drain. A finish
+  // whose PATCH meets an already-terminal run does NOT throw (patchTerminal
+  // seals on a terminal 409), so this wrapper changes nothing on that path.
+  //
+  // SEALED-BEFORE-FINISH: the beforeFinish hook's own best-effort appends
+  // (auto-harvest events) swallow errors — including the RunTerminalError of a
+  // 410 that SEALED the sink. finish() on a sealed sink is an idempotent no-op,
+  // so without this check the drain would report the intended status as
+  // delivered when in fact the server terminated the run out from under us.
+  const finishAccepting = async (status: TerminalStatus, finishOpts: FinishOptions): Promise<TerminalStatus> => {
+    await runBeforeFinish()
+    if (sink.sealed) return 'cancelled'
+    try {
+      await sink.finish(status, finishOpts)
+      return status
+    } catch (error) {
+      if (error instanceof RunTerminalError) return 'cancelled'
+      throw error
+    }
+  }
   for await (const event of events) {
     if (event.kind === 'execution_complete') {
       // A prompt the caller/agent stopped is a cancellation, not a failure: the
@@ -668,40 +736,39 @@ export async function drainHarnessToSink(
       // and stop()-initiated paths. A genuine failure (success:false, no abort
       // flag) still lands 'failed'.
       if (event.payload.aborted === true) {
-        await runBeforeFinish()
-        await sink.finish('cancelled', {
+        return finishAccepting('cancelled', {
           summary: opts.summary,
           evidence: opts.evidence,
           transcript: opts.transcript,
         })
-        return 'cancelled'
       }
       const success = event.payload.success !== false
       const status: TerminalStatus = success ? 'succeeded' : 'failed'
       const summary = success
         ? opts.summary
         : { ...(opts.summary ?? {}), error: event.payload.error ?? 'execution failed' }
-      await runBeforeFinish()
-      await sink.finish(status, { summary, evidence: opts.evidence, transcript: opts.transcript })
-      return status
+      return finishAccepting(status, { summary, evidence: opts.evidence, transcript: opts.transcript })
     }
     if (event.kind === 'error') {
-      await runBeforeFinish()
-      await sink.finish('failed', {
+      return finishAccepting('failed', {
         summary: { ...(opts.summary ?? {}), error: event.payload.error ?? 'agent error' },
         evidence: opts.evidence,
         transcript: opts.transcript,
       })
-      return 'failed'
     }
-    await sink.append(event)
+    try {
+      await sink.append(event)
+    } catch (error) {
+      if (error instanceof RunTerminalError) return handleServerTerminal()
+      throw error
+    }
   }
   // The harness contract guarantees a terminal event; reaching here means the
   // stream ended abnormally. Fail closed so the run never dangles non-terminal.
   await runBeforeFinish()
-  await sink.finish('failed', {
+  if (sink.sealed) return 'cancelled'
+  return finishAccepting('failed', {
     summary: { ...(opts.summary ?? {}), error: 'harness stream ended without a terminal event' },
     transcript: opts.transcript,
   })
-  return 'failed'
 }

package/src/hosted-session-cli.ts

@@ -35,6 +35,8 @@
  * local-sim end-to-end test.
  */
 
+import { readFileSync } from 'fs'
+
 import {
   createLocalSimProvider,
   type SandboxEgressPolicy,
@@ -52,16 +54,19 @@ import { resumeRunEventSink } from './hosted-run-event-sink.js'
 import { AGENT_GIT_IDENTITY, BEARER_BASENAME } from './hosted-runtime-assets.js'
 import { createVercelProvider } from './vercel-sandbox-provider.js'
 import { buildEgressPolicy, DEFAULT_EGRESS_CANARY_HOST } from './egress-policy.js'
-import { hostedLoopCommand, type HostedLoopContext } from './hosted-loop.js'
+import { DEFAULT_HOSTED_MODEL, hostedLoopCommand, type HostedLoopContext } from './hosted-loop.js'
 import { hostedBootCommand } from './hosted-boot.js'
 import { mergeJobCommand } from './merge-job.js'
 import { authedFetch } from './http.js'
 import { resolveBaseUrl } from './http.js'
+import { findUnknownOption } from './option-validation.js'
 import { getWorkspaceRoot } from './workspace.js'
 import { attachedWorkspaceId } from './workspace-sync.js'
 import { tailWorkbenchRun } from './workbench-cli.js'
 
-export const DEFAULT_HOSTED_MODEL = 'anthropic/claude-opus-4-8'
+// Default hosted model — SINGLE source of truth in hosted-loop-lifecycle.ts
+// (ALI-1086); re-exported here so existing importers keep working.
+export { DEFAULT_HOSTED_MODEL }
 export const DEFAULT_DURATION_MINUTES = 60
 export const MAX_DURATION_MINUTES = 24 * 60
 export const DEFAULT_ROTATION_INTERVAL_MS = 55 * 60 * 1000
@@ -73,6 +78,13 @@ export const DEFAULT_AGENT_TOKEN_TTL_MINUTES = 60
  *  before declaring the detached launch a failure. */
 export const DEFAULT_READINESS_TIMEOUT_MS = 30 * 1000
 export const DEFAULT_READINESS_POLL_MS = 500
+/** Must match the coordinator Worker's session-start request ceiling. */
+export const MAX_HOSTED_START_BODY_BYTES = 128 * 1024
+/** `workspace_sessions.id` and `workbench_runs.id` are PostgreSQL UUIDs. The
+ *  server creates both before its coordinator poke, and the Worker injects the
+ *  session id into the final DO body. A representative UUID makes the local
+ *  projection byte-exact without creating either server-side row. */
+const GENERATED_HOSTED_UUID_PLACEHOLDER = '00000000-0000-4000-8000-000000000000'
 /** Non-secret placeholder OpenCode uses to form requests; the firewall proxy
  *  overrides the real Anthropic header (model-key brokering). NEVER a real key. */
 export const ANTHROPIC_DUMMY_KEY = 'sk-ant-orizu-proxy-broker-placeholder'
@@ -785,6 +797,10 @@ export interface HostedCommandIo {
 }
 
 function argVal(args: readonly string[], flag: string): string | null {
+  const inlinePrefix = `${flag}=`
+  const inlineArg = args.find(arg => arg.startsWith(inlinePrefix))
+  if (inlineArg) return inlineArg.slice(inlinePrefix.length)
+
   const index = args.indexOf(flag)
   if (index === -1 || index + 1 >= args.length) return null
   const value = args[index + 1]
@@ -792,7 +808,7 @@ function argVal(args: readonly string[], flag: string): string | null {
 }
 
 function hasFlag(args: readonly string[], flag: string): boolean {
-  return args.includes(flag)
+  return args.some(arg => arg === flag || arg.startsWith(`${flag}=`))
 }
 
 function numFlag(args: readonly string[], flag: string): number | undefined {
@@ -803,7 +819,7 @@ function numFlag(args: readonly string[], flag: string): number | undefined {
 }
 
 const HOSTED_USAGE =
-  'Usage: orizu session start --hosted --task "<prompt>" [--duration <min> (default 60, max 1440)] ' +
+  'Usage: orizu session start --hosted (--task "<prompt>" | --task-file <path>) [--duration <min> (default 60, max 1440)] ' +
   '[--model <provider/model>] [--reasoning-effort <level>] [--project <team/project>] ' +
   '[--title <title>] [--tail]\n' +
   'Default: the Orizu server provisions the sandbox (no VERCEL_* or model key needed on your machine); ' +
@@ -814,6 +830,42 @@ const HOSTED_USAGE =
   'Note (v0, --operator only): if you disconnect, the agent token expires within its TTL (<=60m) and the run ' +
   'finishes cleanly; reconnect with `orizu run tail --run <id>`. The sandbox timeout is independent (up to 24h).'
 
+const HOSTED_START_OPTIONS = new Set([
+  '--hosted',
+  '--task',
+  '--task-file',
+  '--workspace',
+  '--duration',
+  '--model',
+  '--reasoning-effort',
+  '--project',
+  '--title',
+  '--tail',
+  '--operator',
+  '--provider',
+  '--runtime',
+  '--image',
+  '--snapshot',
+  '--model-key',
+  '--json',
+])
+
+const HOSTED_START_VALUE_OPTIONS = new Set([
+  '--task',
+  '--task-file',
+  '--workspace',
+  '--duration',
+  '--model',
+  '--reasoning-effort',
+  '--project',
+  '--title',
+  '--provider',
+  '--runtime',
+  '--image',
+  '--snapshot',
+  '--model-key',
+])
+
 /** Printed on EVERY `--operator` use (founder-locked: deprecate NOW, remove
  *  after Phase 6 validation). Loud on purpose. */
 export const OPERATOR_DEPRECATION_WARNING =
@@ -834,21 +886,65 @@ export async function startHostedViaServer(
   io: HostedCommandIo,
   fetcher: HostFetcher = (path, init) => authedFetch(path, init)
 ): Promise<number> {
+  const durationMinutes = numFlag(args, '--duration')
+  const model = argVal(args, '--model') ?? undefined
+  const reasoningEffort = argVal(args, '--reasoning-effort') ?? undefined
+  const projectSlug = argVal(args, '--project') ?? undefined
+  const title = argVal(args, '--title') ?? undefined
   const payload: Record<string, unknown> = {
     workspaceId,
     task,
-    durationMinutes: numFlag(args, '--duration'),
-    model: argVal(args, '--model') ?? undefined,
-    reasoningEffort: argVal(args, '--reasoning-effort') ?? undefined,
-    projectSlug: argVal(args, '--project') ?? undefined,
-    title: argVal(args, '--title') ?? undefined,
+    durationMinutes,
+    model,
+    reasoningEffort,
+    projectSlug,
+    title,
+  }
+  const serializedPayload = JSON.stringify(payload)
+  const payloadBytes = new TextEncoder().encode(serializedPayload).byteLength
+  if (payloadBytes > MAX_HOSTED_START_BODY_BYTES) {
+    const message =
+      `Hosted task prompt is too large: request body is ${payloadBytes} bytes; ` +
+      `maximum is ${MAX_HOSTED_START_BODY_BYTES} bytes (128 KiB).`
+    if (io.json) io.print(JSON.stringify({ ok: false, error: message }))
+    else io.printErr?.(message)
+    return 1
+  }
+
+  // Mirror the exact JSON shape that reaches the session Durable Object after
+  // the API creates its UUID run/session rows, normalizes optional strings, and
+  // the Worker injects sessionId. This second guard keeps near-boundary prompts
+  // from triggering server-side state that would only be compensated after a
+  // coordinator 413. Keep this field list in sync with pokeCoordinatorStart in
+  // app/api/cli/hosted-sessions/route.ts.
+  const normalizedModel = model?.trim() || undefined
+  const normalizedReasoningEffort = reasoningEffort?.trim() || undefined
+  const coordinatorPayload = JSON.stringify({
+    runId: GENERATED_HOSTED_UUID_PLACEHOLDER,
+    task,
+    durationMinutes:
+      durationMinutes !== undefined && durationMinutes > 0
+        ? durationMinutes
+        : undefined,
+    model: normalizedModel,
+    reasoningEffort: normalizedReasoningEffort,
+    sessionId: GENERATED_HOSTED_UUID_PLACEHOLDER,
+  })
+  const coordinatorPayloadBytes = new TextEncoder().encode(coordinatorPayload).byteLength
+  if (coordinatorPayloadBytes > MAX_HOSTED_START_BODY_BYTES) {
+    const message =
+      `Hosted task prompt is too large: coordinator request body would be ${coordinatorPayloadBytes} bytes ` +
+      `after generated run/session IDs; maximum is ${MAX_HOSTED_START_BODY_BYTES} bytes (128 KiB).`
+    if (io.json) io.print(JSON.stringify({ ok: false, error: message }))
+    else io.printErr?.(message)
+    return 1
   }
   let response: Response
   try {
     response = await fetcher('/api/cli/hosted-sessions', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(payload),
+      body: serializedPayload,
     })
   } catch (error) {
     io.printErr?.(`hosted session request failed: ${error instanceof Error ? error.message : String(error)}`)
@@ -935,7 +1031,44 @@ export async function hostedCommand(
     return 1
   }
 
-  const task = argVal(args, '--task')
+  const unknownOption = findUnknownOption(args, HOSTED_START_OPTIONS, HOSTED_START_VALUE_OPTIONS)
+  if (unknownOption) {
+    const followsTaskFlag = args.some(
+      (arg, index) =>
+        arg === '--task' &&
+        (args[index + 1] === unknownOption || args[index + 1]?.startsWith(`${unknownOption}=`))
+    )
+    const taskValueHint = followsTaskFlag
+      ? '\nTask text beginning with a dash must use --task=<prompt> or --task-file <path>.'
+      : ''
+    io.printErr?.(`unknown option ${unknownOption}${taskValueHint}\n${HOSTED_USAGE}`)
+    return 1
+  }
+
+  const inlineTask = argVal(args, '--task')
+  const taskFile = argVal(args, '--task-file')
+  if (hasFlag(args, '--task') && hasFlag(args, '--task-file')) {
+    io.printErr?.(`Use either --task or --task-file, not both.\n${HOSTED_USAGE}`)
+    return 1
+  }
+
+  let task = inlineTask
+  if (taskFile) {
+    try {
+      task = readFileSync(taskFile, 'utf8')
+    } catch (error) {
+      io.printErr?.(
+        `Could not read task file '${taskFile}': ${error instanceof Error ? error.message : String(error)}`
+      )
+      return 1
+    }
+    if (task.trim().length === 0) {
+      io.printErr?.(
+        `Task file '${taskFile}' is empty or contains only whitespace. Add a task prompt and try again.`
+      )
+      return 1
+    }
+  }
   if (!task) {
     io.printErr?.(HOSTED_USAGE)
     return 1

package/src/index.ts

@@ -3607,14 +3607,30 @@ async function resolveSetupTeam(teamSlugArg: string | null, noInput: boolean, dr
   return createTeamOnServer(name)
 }
 
-async function resolveSetupProjects(team: Team): Promise<Project[]> {
+async function resolveSetupProjects(team: Team, noInput: boolean, dryRun: boolean): Promise<Project[]> {
   const projects = await fetchProjects(team.slug)
 
-  if (projects.length === 0) {
-    throw new Error(`Team '${team.slug}' has no projects. Create a project before running setup.`)
+  if (projects.length > 0) {
+    return projects
+  }
+
+  // ALI-1140: a just-created team (or a pre-existing empty one) has no projects
+  // by definition — continue the wizard into creating the first project instead
+  // of dead-ending on the path setup itself offered.
+  if (noInput || dryRun) {
+    throw new Error(
+      `Team '${team.slug}' has no projects. Create one with \`orizu projects create --name <name> --team ${team.slug}\`, then re-run setup.`
+    )
   }
 
-  return projects
+  printLine(`   Team '${sanitizeTerminalText(team.slug)}' has no projects yet. Let's create the first one.`)
+  const name = await askText('   Project name?', '')
+  if (!name) {
+    throw new Error('Project name is required to create a project.')
+  }
+  const project = await createProjectOnServer(team.slug, name)
+  printLine(`   Created project ${sanitizeTerminalText(`${project.teamSlug}/${project.slug}`)}`)
+  return [project]
 }
 
 function projectSeedsFromProjects(projects: Project[]): WorkspaceProjectSeed[] {
@@ -3757,13 +3773,13 @@ async function setupCommand() {
 
       if (auth.state === 'signed-in' && !validateOnly) {
         const team = await resolveSetupTeam(teamSlug, noInput, dryRun)
-        const serverProjects = await resolveSetupProjects(team)
+        const serverProjects = await resolveSetupProjects(team, noInput, dryRun)
         teamSlug = team.slug
         teamId = team.id
         projects = projectSeedsFromProjects(serverProjects)
         printLine(`   ${formatProjectSetupProgress(projects.length)}`)
         if (!hasArg('--local') && !noInput && !dryRun) { let link: GithubLinkResult | null = null; try { link = await runGithubLink(team.slug, { print: printLine, fetcher: authedFetch, openUrl: openInBrowser, confirm: (org) => askYesNo(`   Connect this team to GitHub org '${org}'?`, true) }) } catch (error) { printLine(`   GitHub link skipped: ${getErrorMessage(error)} Run \`orizu github link --team ${team.slug}\` to finish.`) }
-        if (link) { try { hostedAttached = (await runInteractiveHostedSetup({ teamSlug: team.slug, targetDir: workspaceRoot, local: hasArg('--local'), activeInstallation: link.status === 'active' }, { print: printLine, fetcher: authedFetch })).attached } catch (error) { throw new Error(`Hosted setup failed: ${getErrorMessage(error)} Remove any partial clone in ${workspaceRoot} if one exists, then re-run \`orizu setup\` (or pass --local to scaffold a local-only workspace).`) } } }
+        if (link) { try { hostedAttached = (await runInteractiveHostedSetup({ teamSlug: team.slug, targetDir: workspaceRoot, local: hasArg('--local'), activeInstallation: link.status === 'active' }, { print: printLine, fetcher: authedFetch })).attached } catch (error) { throw new Error(`Hosted setup failed: ${getErrorMessage(error)} Re-running \`orizu setup\` is safe — provisioning adopts the existing workbench repo and resumes where it left off (or pass --local to scaffold a local-only workspace).`) } } } // hint must not blame local state (ALI-1143): provisioning failures are server-side, and both provisioning (adopt) and the clone step (skip-if-cloned, ALI-1069) are idempotent on re-run
       } else if (!teamSlug && !noInput && !validateOnly) {
         teamSlug = await askText('   Team slug?', 'local-team')
       }

package/src/merge-job.ts

@@ -44,6 +44,7 @@ import {
   type DeployKeyMergeResult,
   type GitCommandRunner,
 } from './deploy-key-merge-core.js'
+import { assertSecureTokenTransport } from './http.js'
 import { redactSecrets } from './secret-redaction.js'
 
 export type MergeJobFetch = (url: string, init?: RequestInit) => Promise<Response>
@@ -67,7 +68,7 @@ export interface MergeJobEnv {
 
 export function resolveMergeJobEnv(
   env: Record<string, string | undefined>
-): { ok: true; value: MergeJobEnv } | { ok: false; missing: string[] } {
+): { ok: true; value: MergeJobEnv } | { ok: false; missing: string[]; invalid: string[] } {
   const missing: string[] = []
   const req = (name: string): string => {
     const value = env[name]?.trim()
@@ -78,7 +79,25 @@ export function resolveMergeJobEnv(
   const jobKey = req('ORIZU_MERGE_JOB_ID')
   const coordinatorUrl = req('ORIZU_COORDINATOR_URL')
   const baseUrl = req('ORIZU_BASE_URL')
-  if (missing.length > 0) return { ok: false, missing }
+  if (missing.length > 0) return { ok: false, missing, invalid: [] }
+
+  const origins = [
+    ['ORIZU_COORDINATOR_URL', coordinatorUrl],
+    ['ORIZU_BASE_URL', baseUrl],
+  ] as const
+  const invalid = origins.flatMap(([name, value]) => {
+    try {
+      const parsed = new URL(value)
+      // Userinfo is never accepted, including on loopback: rejecting it at the
+      // env boundary keeps configured credentials out of every retry/error path.
+      if (parsed.username || parsed.password) return [name]
+      assertSecureTokenTransport(value)
+      return []
+    } catch {
+      return [name]
+    }
+  })
+  if (invalid.length > 0) return { ok: false, missing: [], invalid }
   return {
     ok: true,
     value: {
@@ -445,10 +464,10 @@ export interface MergeJobCommandIo {
 export async function mergeJobCommand(io: MergeJobCommandIo): Promise<number> {
   const resolved = resolveMergeJobEnv(process.env)
   if (!resolved.ok) {
-    io.printErr?.(
-      `merge-job: missing required env: ${resolved.missing.join(', ')} ` +
-        '(the MergeJobCoordinator sandbox env contract)'
-    )
+    const detail = resolved.missing.length > 0
+      ? `missing required env: ${resolved.missing.join(', ')}`
+      : `invalid or insecure origin env: ${resolved.invalid.join(', ')}`
+    io.printErr?.(`merge-job: ${detail} (the MergeJobCoordinator sandbox env contract)`)
     return 1
   }
   const log = (line: string): void => io.printErr?.(`[merge-job] ${line}`)

package/src/option-validation.ts

@@ -0,0 +1,63 @@
+function optionName(arg: string): string {
+  const equalsIndex = arg.indexOf('=')
+  return equalsIndex === -1 ? arg : arg.slice(0, equalsIndex)
+}
+
+function isNegativeNumericValue(arg: string): boolean {
+  return arg.length > 1 && !arg.startsWith('--') && Number.isFinite(Number(arg))
+}
+
+function isUnambiguouslySingleDashValue(arg: string): boolean {
+  // A short option cannot contain whitespace immediately after its dash. This
+  // keeps Markdown-list prompts such as `--task "- fix the test"` available
+  // without letting a misspelled option such as `--task -taks` get swallowed.
+  return /^-\s/.test(arg) || isNegativeNumericValue(arg)
+}
+
+function followsValueOption(
+  args: readonly string[],
+  index: number,
+  valueOptions: ReadonlySet<string>
+): boolean {
+  if (index === 0) return false
+  const previous = args[index - 1]
+  return previous.startsWith('--') && !previous.includes('=') && valueOptions.has(previous)
+}
+
+/**
+ * Return the first dash-prefixed option that is not in a command's explicit
+ * allowlist. An unambiguously value-like single-dash token immediately
+ * following a value-taking option is data: this keeps inputs such as
+ * `--duration -5` and `--task "- fix the test"` available without allowing a
+ * stray token or mistyped short option.
+ *
+ * `valueOptions` permits the unambiguous `--option=value` form. A separate
+ * token beginning with `--`, or an option-like single-dash word, is parsed as
+ * an option so a missing value cannot swallow a typo. Callers whose value is
+ * itself option-like can use the inline form; Markdown list markers and finite
+ * negative numbers remain safe as separate values.
+ */
+export function findUnknownOption(
+  args: readonly string[],
+  allowedOptions: ReadonlySet<string>,
+  valueOptions: ReadonlySet<string> = new Set()
+): string | null {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (!arg.startsWith('-') || arg === '-') continue
+    if (!arg.startsWith('--')) {
+      if (isUnambiguouslySingleDashValue(arg) && followsValueOption(args, index, valueOptions)) continue
+      return arg
+    }
+
+    const name = optionName(arg)
+    if (!allowedOptions.has(name)) return name
+
+    const hasInlineValue = arg.length > name.length
+    if (hasInlineValue) {
+      if (!valueOptions.has(name)) return arg
+      continue
+    }
+  }
+  return null
+}

package/src/workbench-cli.ts

@@ -9,6 +9,7 @@
 import { spawnSync } from 'child_process'
 
 import { authedFetch } from './http.js'
+import { findUnknownOption } from './option-validation.js'
 import { getWorkspaceRoot, workspaceExists } from './workspace.js'
 import { attachedWorkspaceId, stringOrNull } from './workspace-sync.js'
 
@@ -269,6 +270,19 @@ const DEFAULT_TAIL_INTERVAL_SECONDS = 2
 // hot-spin against the API while a non-terminal run is quiet. Draining full
 // pages intentionally skips the sleep — that is catch-up, not polling.
 const MIN_TAIL_INTERVAL_MS = 500
+const SESSION_START_OPTIONS = new Set(['--project', '--workspace', '--json'])
+const WORKBENCH_VALUE_OPTIONS = new Set([
+  '--after',
+  '--interval',
+  '--message',
+  '--project',
+  '--run',
+  '--session',
+  '--status',
+  '--summary',
+  '--title',
+  '--workspace',
+])
 
 function defaultSleep(ms: number): Promise<void> {
   return new Promise(resolve => setTimeout(resolve, ms))
@@ -774,11 +788,19 @@ function hasFlag(args: string[], flag: string): boolean {
 }
 
 function argValue(args: string[], flag: string): string | null {
-  const index = args.indexOf(flag)
-  if (index === -1 || index + 1 >= args.length || args[index + 1].startsWith('--')) {
-    return null
+  const inlinePrefix = `${flag}=`
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]
+    if (arg.startsWith(inlinePrefix)) {
+      return arg.slice(inlinePrefix.length)
+    }
+    if (arg === flag) {
+      return index + 1 < args.length && !args[index + 1].startsWith('--')
+        ? args[index + 1]
+        : null
+    }
   }
-  return args[index + 1]
+  return null
 }
 
 function numberArg(args: string[], flag: string): number | undefined {
@@ -795,7 +817,7 @@ function positionalArgs(args: string[]): string[] {
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i]
     if (arg.startsWith('--')) {
-      if (argValue(args, arg) !== null) {
+      if (!arg.includes('=') && WORKBENCH_VALUE_OPTIONS.has(arg) && argValue(args.slice(i), arg) !== null) {
         i += 1
       }
       continue
@@ -1017,6 +1039,13 @@ async function dispatchWorkbenchCommand(args: string[], io: WorkbenchCommandIo):
     // not run from inside it (defaults to cwd).
     const workspaceDir = argValue(args, '--workspace') ?? undefined
     if (subcommand === 'start') {
+      const unknownOption = findUnknownOption(args, SESSION_START_OPTIONS, WORKBENCH_VALUE_OPTIONS)
+      if (unknownOption) {
+        return emitJsonError(
+          io,
+          `unknown option ${unknownOption}\nUsage: orizu session start [--project <team/project>] [--workspace <dir>] [--json]`
+        )
+      }
       const result = await runSessionStart({
         fetcher,
         cwd: workspaceDir,

package/vendor/skills/orizu-cli/SKILL.md

@@ -199,5 +199,5 @@ Detailed walkthrough — GEPA mechanics, Orizu-tracked optimization, optional DS
 
 - **Orizu is the source of truth for run metadata and pointers**: production/default prompt/scorer/runner pointers, version lineage, score runs, optimization runs, and report history all live in Orizu — query them with `orizu ...` commands (e.g. `orizu prompts list`, `orizu prompts versions`, `orizu runs ...`), never by reading repo files.
 - **The repo is the working set (files only)**: source, configs, `App.tsx`, schemas, and local traces under `logs/<run-id>`. It is the scratch space you edit and commit; it does NOT hold the canonical pointer/run state — that is in Orizu.
-- **Hosted sessions ship a pre-authenticated CLI**: inside a hosted agent sandbox the `orizu` CLI is already authenticated via `ORIZU_TOKEN_FILE` (with `ORIZU_BASE_URL` pointing at the API). You do NOT run `orizu login` — just call `orizu ...`. The bearer carries a **team-curator READ scope**: you can read projects, datasets (+ content/artifact bytes), prompts, scorers, runners/optimizers, runs, and reports across your own team, and execute runs / submit scores / create artifacts / create promotion manifests as the agent actor.
-- **Human-only actions will 403**: manifest approve / reject / apply, production and default pointer flips, and team/member/billing/integration admin are deliberately outside the agent envelope. Do not attempt them from a hosted session — they return 403 by design. Prepare a promotion manifest and hand it to a human curator to approve and apply.
+- **Hosted sessions ship a pre-authenticated CLI**: inside a hosted agent sandbox the `orizu` CLI is already authenticated via `ORIZU_TOKEN_FILE` (with `ORIZU_BASE_URL` pointing at the API). You do NOT run `orizu login` — just call `orizu ...`. The bearer carries **full team-curator authority while your session is active** (ADR-008): anything a curator-role human can read or write in your team — create/read/update projects, datasets (+ rows/artifact bytes), prompts, scorers, runners/optimizers, apps, tasks, runs, score runs, reports, and promotion-manifest proposals — you can too, across the whole team. (The full per-role access matrix lives in the Orizu repo at `docs/authorization-matrix.md`.)
+- **Human-only actions will 403**: promotion-manifest **approval / apply / reject**, production and default pointer flips, session/credential lifecycle (starting or ending hosted sessions, minting tokens, deploy keys), integration/connector credential reads (secrets reach your sandbox only as environment variables resolved at boot — never via API/DB), and team/member/installation/billing management. Do not attempt them from a hosted session — they return 403 by design. Prepare a promotion manifest and hand it to a human curator to approve and apply.