orizu 0.5.6 → 0.5.8

package/src/help.ts

@@ -35,6 +35,7 @@ const GROUPS: CliGroupDoc[] = [
   { name: 'Teams', summary: 'Manage teams and team memberships.' },
   { name: 'Projects', summary: 'Manage projects inside teams.' },
   { name: 'Prompts and judges', summary: 'Work with versioned prompt and judge artifacts.' },
+  { name: 'Report comments', summary: 'Review and mutate anchored report comments across prompt, optimization, and task reports.' },
   { name: 'Scorers and runners', summary: 'Register scorers, push runnable artifacts, execute runners, and submit scores.' },
   { name: 'Optimizations', summary: 'Start, run, export, and finalize optimization runs.' },
   { name: 'Apps', summary: 'Create, preview, update, inspect, and export review apps.' },
@@ -82,6 +83,67 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Submit an optimization event payload.',
     group: 'Optimizations',
   },
+  {
+    path: ['comments', 'list'],
+    usage: 'orizu comments list (--prompt <id-or-name> --project <team/project> [--label <label> | --version <id>] | --run <run-id> | --task <task-id>) [--json]',
+    summary: 'List report comment threads with open/resolved status and replies.',
+    group: 'Report comments',
+    options: [
+      { name: '--prompt <id-or-name>', help: 'Prompt report target. Requires --project.' },
+      { name: '--project <team/project>', help: 'Project slug for prompt targets.' },
+      { name: '--label <label>', help: 'Prompt version label to comment on.' },
+      { name: '--version <id>', help: 'Prompt version ID to comment on.' },
+      { name: '--run <run-id>', help: 'Optimization run report target.' },
+      { name: '--task <task-id>', help: 'Task report target.' },
+      { name: '--json', help: 'Emit the full comments payload.' },
+    ],
+    examples: [
+      'orizu comments list --prompt Generator --project core/evals --label production',
+      'orizu comments list --run <run-id>',
+      'orizu comments list --task <task-id>',
+    ],
+  },
+  {
+    path: ['comments', 'add'],
+    usage: 'orizu comments add (--prompt <id-or-name> --project <team/project> [--label <label> | --version <id>] | --run <run-id> | --task <task-id>) --body <text|@file> [--anchor <text>] [--lines <start:end>] [--via <name>] [--json]',
+    summary: 'Add an anchored top-level comment to a report.',
+    group: 'Report comments',
+    options: [
+      { name: '--body <text|@file>', help: 'Comment body or @file reference.', required: true },
+      { name: '--anchor <text>', help: 'Quoted report text for the comment anchor.' },
+      { name: '--lines <start:end>', help: 'One-based inclusive line range for the anchor.' },
+      { name: '--via <name>', help: 'Tool or agent name to show in attribution.' },
+      { name: '--json', help: 'Emit the created comment payload.' },
+    ],
+    examples: [
+      'orizu comments add --run <run-id> --body @comment.md --anchor "Score summary" --lines 4:6',
+      'orizu comments add --task <task-id> --body "Clarify this finding" --via Codex',
+    ],
+  },
+  {
+    path: ['comments', 'reply'],
+    usage: 'orizu comments reply <comment-id> --body <text|@file> [--via <name>] [--json]',
+    summary: 'Reply to a top-level report comment thread.',
+    group: 'Report comments',
+  },
+  {
+    path: ['comments', 'resolve'],
+    usage: 'orizu comments resolve <comment-id> [--json]',
+    summary: 'Resolve a top-level report comment thread.',
+    group: 'Report comments',
+  },
+  {
+    path: ['comments', 'unresolve'],
+    usage: 'orizu comments unresolve <comment-id> [--json]',
+    summary: 'Reopen a resolved report comment thread.',
+    group: 'Report comments',
+  },
+  {
+    path: ['comments', 'edit'],
+    usage: 'orizu comments edit <comment-id> --body <text|@file> [--json]',
+    summary: 'Edit one of your report comments or replies.',
+    group: 'Report comments',
+  },
   {
     path: ['setup'],
     usage: 'orizu setup [--team <slug>] [--agent <claude|codex>]... [--workspace [path]|--no-workspace] [--validate] [--fix] [--no-symlinks] [--verbose] [--no-install] [--handoff|--no-handoff] [--launch <claude|codex>] [--skip-login] [--yes] [--dry-run] [--no-input|--non-interactive] [--json]',
@@ -125,7 +187,7 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['install-skill'],
-    usage: 'orizu install-skill [--agent <claude|codex>]... [--scope global|project] [--mode auto|link|copy] [--target <target>]... [--yes] [--dry-run]',
+    usage: 'orizu install-skill [--agent <claude|codex|opencode>]... [--scope global|project] [--mode auto|link|copy] [--target <target>]... [--yes] [--dry-run]',
     summary: 'Install or repair the Orizu coding-agent skill.',
     group: 'Agent setup',
     aliases: [['skills', 'install']],
@@ -273,12 +335,6 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Restore an archived prompt artifact to active status.',
     group: 'Prompts and judges',
   },
-  {
-    path: ['prompts', 'comments'],
-    usage: 'orizu prompts comments <prompt-id-or-name> --project <team/project> [--label <label> | --version <id>] [--json]',
-    summary: 'List prompt comment threads with open/resolved status and replies.',
-    group: 'Prompts and judges',
-  },
   {
     path: ['prompts', 'pull'],
     usage: 'orizu prompts pull <prompt-id-or-name> --project <team/project> --out <dir> [--label <label> | --version <id>] [--json]',
@@ -563,6 +619,20 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
       'orizu tasks report upload --task <taskId> --report @./report.md',
     ],
   },
+  {
+    path: ['tasks', 'report', 'get'],
+    usage: 'orizu tasks report get --task <taskId> [--json]',
+    summary: 'Read the Markdown report for a task.',
+    group: 'Tasks',
+    options: [
+      { name: '--task <taskId>', help: 'Task ID whose report should be read.', required: true },
+      { name: '--json', help: 'Emit the full report payload.' },
+    ],
+    examples: [
+      'orizu tasks report get --task <taskId>',
+      'orizu tasks report get --task <taskId> --json',
+    ],
+  },
   {
     path: ['tasks', 'pause'],
     usage: 'orizu tasks pause --task <taskId>',

package/src/hosted-bootstrap.ts

@@ -441,6 +441,52 @@ export async function bootstrapHostedSandbox(opts: HostedBootstrapOptions): Prom
       })
     }
 
+    // 4b — Stage the orizu-cli skill into the workspace so the agent discovers it
+    // (ALI-1044). Resolve the CLI's OWN vendored skill dir in-sandbox, preferring:
+    //   (1) $ORIZU_SKILL_SOURCE_DIR  — explicit override (also honored by the CLI's
+    //       skill-installer; the local-sim rehearsal sets it),
+    //   (2) `orizu skills path`      — the packaged vendor/skills/orizu-cli of the
+    //       globally-installed CLI (the production path),
+    //   (3) `$(npm root -g)/orizu/vendor/skills/orizu-cli` — belt fallback.
+    // Then SYMLINK it under <workspaceDir>/.claude/skills/orizu-cli, falling back
+    // to a copy if the symlink cannot be created. Non-fatal + recorded, exactly
+    // like the CLI install. Resolved paths stay in shell vars (never interpolated),
+    // so they cannot inject into the command.
+    currentStep = 'skill_staged'
+    const skillSkillsDirRel = `${workspaceDir}/.claude/skills`
+    const stage = await session.exec(
+      [
+        `mkdir -p ${skillSkillsDirRel}`,
+        `src="${'${ORIZU_SKILL_SOURCE_DIR:-}'}"`,
+        `if [ -z "$src" ] || [ ! -d "$src" ]; then src="$(orizu skills path 2>/dev/null || true)"; fi`,
+        `if [ -z "$src" ] || [ ! -d "$src" ]; then r="$(npm root -g 2>/dev/null || true)"; if [ -n "$r" ] && [ -d "$r/orizu/vendor/skills/orizu-cli" ]; then src="$r/orizu/vendor/skills/orizu-cli"; fi; fi`,
+        `if [ -z "$src" ] || [ ! -d "$src" ]; then echo "NO_SOURCE"; exit 0; fi`,
+        `dest="${skillSkillsDirRel}/orizu-cli"`,
+        `rm -rf "$dest"`,
+        `if ln -s "$src" "$dest" 2>/dev/null; then echo "SYMLINK $src"; else cp -R "$src" "$dest" && echo "COPY $src"; fi`,
+      ].join('\n')
+    )
+    const stageOut = stage.stdout.trim()
+    const stagedMethod = stageOut.startsWith('SYMLINK')
+      ? 'symlink'
+      : stageOut.startsWith('COPY')
+        ? 'copy'
+        : null
+    const stagedOk = stage.exitCode === 0 && stagedMethod !== null
+    record(
+      'skill_staged',
+      stagedOk,
+      stagedOk
+        ? `orizu-cli skill staged (${stagedMethod})`
+        : `skill staging unresolved: ${stageOut || `exit ${stage.exitCode}`}`
+    )
+    await sink.append('skill_staged', {
+      ok: stagedOk,
+      method: stagedMethod,
+      dest: `${skillSkillsDirRel}/orizu-cli`,
+      outputTail: tail(stage.stdout, stage.stderr),
+    })
+
     // 5 — Customer setup hook (fresh-boot only, non-fatal, output captured).
     // P3-a: for enforced-egress providers the host DEFERS this hook to the loop,
     // which runs it AFTER the egress canary proves the firewall is live — so the

package/src/hosted-harness-opencode.ts

@@ -760,10 +760,32 @@ function errorEvent(messageId: string, error: unknown): HarnessEvent {
 export interface OpenCodeConfigOptions {
   /** Provider-qualified model string, e.g. "anthropic/claude-opus-4-8". */
   model: string
-  /** OpenCode permission map; defaults to allow-all (sandbox is the boundary). */
+  /** OpenCode permission map; defaults to allow-all EXCEPT the headless-denied
+   *  tools below (sandbox is the boundary for everything else). */
   permission?: Record<string, unknown>
 }
 
+/**
+ * Tools DENIED in a hosted headless run (ALI-1037). OpenCode exposes a `question`
+ * permission key (docs/permissions) that gates the interactive "ask the user a
+ * question" tool. In an unattended sandbox there is no human to answer it, and
+ * OpenCode's only external reply endpoint — `POST /session/{id}/permissions/{permID}`
+ * — takes a BOOLEAN allow/deny, so it cannot select one of the tool's multiple
+ * options anyway. Denying the tool makes the model's ask fail fast (surfaced back
+ * to it as a tool error) so it proceeds autonomously per the standing preamble
+ * (HOSTED_TASK_PREAMBLE), instead of blocking the run forever. This is the
+ * documented fallback path in ALI-1037 (answer-externally is not cleanly possible).
+ */
+export const HEADLESS_DENIED_TOOLS = ['question'] as const
+
+/** The default headless permission map: allow everything, deny the interactive
+ *  question tool (see HEADLESS_DENIED_TOOLS). */
+export function defaultHeadlessPermission(): Record<string, unknown> {
+  const permission: Record<string, unknown> = { '*': { '*': 'allow' } }
+  for (const tool of HEADLESS_DENIED_TOOLS) permission[tool] = 'deny'
+  return permission
+}
+
 /**
  * Build the `OPENCODE_CONFIG_CONTENT` payload OpenCode reads at boot (mirrors
  * OpenInspect's `start_opencode`). Kept pure so the launch command and the
@@ -772,7 +794,7 @@ export interface OpenCodeConfigOptions {
 export function buildOpenCodeConfigContent(opts: OpenCodeConfigOptions): string {
   return JSON.stringify({
     model: opts.model,
-    permission: opts.permission ?? { '*': { '*': 'allow' } },
+    permission: opts.permission ?? defaultHeadlessPermission(),
   })
 }
 

package/src/hosted-harness.ts

@@ -79,6 +79,15 @@ export const HARNESS_EVENT_KINDS = {
   // and never terminal, so they append like any structural event.
   egress_blocked: 'egress_blocked',
   egress_allowed: 'egress_allowed',
+  // Durability + headless (ALI-1036 / ALI-1037). NOT produced by a harness — the
+  // in-sandbox loop emits these through the SAME single-writer run-event sink:
+  // the end-of-run auto-harvest result (work_persisted/work_none/work_persist_failed)
+  // and the headless question auto-handling record (question_auto_answered). They
+  // are ordinary structural events (never terminal), appended like any other.
+  work_persisted: 'work_persisted',
+  work_none: 'work_none',
+  work_persist_failed: 'work_persist_failed',
+  question_auto_answered: 'question_auto_answered',
   error: 'error',
   execution_complete: 'execution_complete',
 } as const

package/src/hosted-harvest.ts

@@ -0,0 +1,159 @@
+/**
+ * Auto-harvest (ALI-1036) — deterministic, loop-side durability.
+ *
+ * At the END of a hosted run (BOTH the success and failure paths — a failed
+ * run's partial work is still valuable), the in-sandbox loop calls
+ * `harvestWorkspace` to make sure nothing the agent produced is lost:
+ *
+ *   1. `git status --porcelain` (plumbing) decides if the clone is dirty. Ignored
+ *      files never appear in porcelain output, so a checkpoint is skipped when the
+ *      only changes are ignored files.
+ *   2. If dirty: `git add -A` then `git commit` attributed to the agent identity
+ *      (AGENT_GIT_IDENTITY) with message `checkpoint: run <runId> auto-harvest`.
+ *   3. If there is anything unpushed (a fresh checkpoint OR pre-existing local
+ *      commits the agent made but did not push), `git push` to the session branch
+ *      (the repo-local credential helper configured by bootstrap authorizes it).
+ *   4. Return a typed outcome the loop records as a run event: `work_persisted`
+ *      (sha + files), `work_none` (clean, nothing to push), or `work_persist_failed`
+ *      (error). Harvest NEVER throws — a harvest failure must not change the run's
+ *      terminal status; it is recorded and the run proceeds to terminal.
+ *
+ * The loop runs IN the sandbox, so git is driven with `child_process` (matching
+ * `defaultRunSetupHook` / `installOpenCodePinned` in `hosted-loop.ts`). `exec` is
+ * injectable so the whole thing is unit-testable with no real git.
+ */
+
+import { spawnSync } from 'child_process'
+
+export interface HarvestExecResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+}
+
+/** Injectable git runner. Defaults to a `spawnSync` git in the workspace dir. */
+export type HarvestExec = (args: readonly string[]) => HarvestExecResult
+
+export interface HarvestOptions {
+  /** Directory of the cloned session-branch workspace (the loop's cwd for git). */
+  workspaceDir: string
+  runId: string
+  /** Commit attribution (AGENT_GIT_IDENTITY from hosted-runtime-assets). */
+  author: { name: string; email: string }
+  /** Injectable git runner (default: real `git` via child_process). */
+  exec?: HarvestExec
+  /**
+   * Safety gate (review finding #1): the default exec runs REAL `git add/commit/
+   * push` in `workspaceDir`. Real harvest must be affirmatively enabled — the loop
+   * only enables it inside a genuine hosted sandbox (prebaked marker present). When
+   * false AND no `exec` is injected, harvest is a no-op (`work_none`) so an errant
+   * workspaceDir (a test, a dev run) can never commit/push a host repo. An injected
+   * `exec` always wins (tests that DO drive harvest).
+   */
+  enabled?: boolean
+}
+
+export type HarvestOutcome =
+  | { kind: 'work_persisted'; sha: string; files: string[] }
+  | { kind: 'work_none' }
+  | { kind: 'work_persist_failed'; error: string }
+
+function defaultHarvestExec(workspaceDir: string): HarvestExec {
+  return (args: readonly string[]): HarvestExecResult => {
+    const res = spawnSync('git', args as string[], { cwd: workspaceDir, encoding: 'utf8' })
+    if (res.error) {
+      return { exitCode: 1, stdout: '', stderr: res.error.message }
+    }
+    return { exitCode: res.status ?? 1, stdout: res.stdout ?? '', stderr: res.stderr ?? '' }
+  }
+}
+
+function detail(res: HarvestExecResult): string {
+  const text = (res.stderr && res.stderr.trim()) || (res.stdout && res.stdout.trim()) || `exit ${res.exitCode}`
+  return text
+}
+
+function splitLines(text: string): string[] {
+  return text
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line.length > 0)
+}
+
+/**
+ * Count commits present locally but not on the upstream tracking branch. Returns
+ * 0 when there is no upstream (`@{u}` unresolvable) — with no upstream a push
+ * could not land anyway, so "nothing to push" is the safe reading.
+ */
+function countUnpushed(exec: HarvestExec): number {
+  const res = exec(['rev-list', '--count', '@{u}..HEAD'])
+  if (res.exitCode !== 0) return 0
+  const n = Number.parseInt(res.stdout.trim(), 10)
+  return Number.isFinite(n) ? n : 0
+}
+
+/**
+ * Persist any uncommitted or unpushed work in the workspace. Deterministic and
+ * total: every path returns a `HarvestOutcome`, never throws.
+ */
+export function harvestWorkspace(opts: HarvestOptions): HarvestOutcome {
+  // Safety gate: never touch a real repo unless explicitly enabled or given an
+  // injected exec. Absent both, report nothing-to-do rather than run host git.
+  if (!opts.exec && !opts.enabled) {
+    return { kind: 'work_none' }
+  }
+  const exec = opts.exec ?? defaultHarvestExec(opts.workspaceDir)
+  try {
+    const status = exec(['status', '--porcelain'])
+    if (status.exitCode !== 0) {
+      return { kind: 'work_persist_failed', error: `git status failed: ${detail(status)}` }
+    }
+    const dirty = status.stdout.trim().length > 0
+
+    if (dirty) {
+      const add = exec(['add', '-A'])
+      if (add.exitCode !== 0) {
+        return { kind: 'work_persist_failed', error: `git add failed: ${detail(add)}` }
+      }
+      const commit = exec([
+        '-c',
+        `user.name=${opts.author.name}`,
+        '-c',
+        `user.email=${opts.author.email}`,
+        'commit',
+        '--author',
+        `${opts.author.name} <${opts.author.email}>`,
+        '-m',
+        `checkpoint: run ${opts.runId} auto-harvest`,
+      ])
+      if (commit.exitCode !== 0) {
+        return { kind: 'work_persist_failed', error: `git commit failed: ${detail(commit)}` }
+      }
+    }
+
+    // Nothing to push when the tree was clean AND there are no local-only commits.
+    const unpushed = countUnpushed(exec)
+    if (!dirty && unpushed <= 0) {
+      return { kind: 'work_none' }
+    }
+
+    const headRes = exec(['rev-parse', 'HEAD'])
+    const sha = headRes.exitCode === 0 ? headRes.stdout.trim() : ''
+
+    // Files: the checkpoint commit's tree when we just committed, else everything
+    // spanned by the unpushed commits.
+    const filesRes = dirty
+      ? exec(['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD'])
+      : exec(['diff', '--name-only', '@{u}..HEAD'])
+    const files = filesRes.exitCode === 0 ? splitLines(filesRes.stdout) : []
+
+    const push = exec(['push'])
+    if (push.exitCode !== 0) {
+      return { kind: 'work_persist_failed', error: `git push failed: ${detail(push)}` }
+    }
+
+    return { kind: 'work_persisted', sha, files }
+  } catch (error) {
+    return { kind: 'work_persist_failed', error: error instanceof Error ? error.message : String(error) }
+  }
+}

package/src/hosted-headless.ts

@@ -0,0 +1,178 @@
+/**
+ * Headless-run helpers (ALI-1037) for the in-sandbox loop.
+ *
+ *   - `withIdleWatchdog`: wraps a harness event stream and aborts a prompt that
+ *     makes NO progress (no harness event) for a bounded window, so a stalled
+ *     agent can never hang a hosted run forever. On idle it invokes `onTimeout`
+ *     (the loop aborts the harness) then throws `AgentStalledError`, which the
+ *     loop turns into a `failed` terminal — AFTER running the end-of-run harvest.
+ *
+ *   - `annotateHeadlessQuestions`: observability for the question-tool deny path.
+ *     The interactive `question` tool is DENIED via OpenCode's permission map
+ *     (see HEADLESS_DENIED_TOOLS in hosted-harness-opencode.ts), so a headless
+ *     run never blocks on it. When the agent nonetheless attempts a `question`
+ *     tool call, this wrapper emits a `question_auto_answered` event recording the
+ *     question and the option that WOULD be recommended, so the run timeline shows
+ *     the auto-handling. It touches only the normalized event stream — never the
+ *     fragile OpenCode SSE transform.
+ */
+
+import type { HarnessEvent } from './hosted-harness.js'
+
+/** Thrown by `withIdleWatchdog` when the stream is idle past its timeout. */
+export class AgentStalledError extends Error {
+  readonly idleMs: number
+  constructor(idleMs: number) {
+    super(`agent_stalled: no progress for ${formatIdleWindow(idleMs)}`)
+    this.name = 'AgentStalledError'
+    this.idleMs = idleMs
+  }
+}
+
+/** Render the idle window for the error message. Minutes (the operator-facing
+ *  unit; default window is 10m), rounded to one decimal so sub-minute test
+ *  windows still read sensibly. */
+export function formatIdleWindow(ms: number): string {
+  const minutes = Math.round((ms / 60000) * 10) / 10
+  return `${minutes}m`
+}
+
+export interface IdleWatchdogOptions {
+  /** No harness event within this many ms aborts the prompt. <= 0 disables. */
+  timeoutMs: number
+  /** Invoked once on idle (the loop aborts the harness) before the throw. */
+  onTimeout: () => Promise<void> | void
+}
+
+const IDLE_SENTINEL = Symbol('idle')
+
+/**
+ * Wrap `source` so that if no value arrives within `timeoutMs`, `onTimeout` runs
+ * and `AgentStalledError` is thrown. The idle timer resets on EVERY value, so it
+ * measures gaps between events (progress), not total duration. The still-pending
+ * `next()` is not left as an unhandled rejection, and the underlying iterator is
+ * returned/closed on any early exit.
+ */
+export async function* withIdleWatchdog<T>(
+  source: AsyncIterable<T>,
+  opts: IdleWatchdogOptions
+): AsyncGenerator<T> {
+  const iterator = source[Symbol.asyncIterator]()
+  try {
+    for (;;) {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const idle = new Promise<typeof IDLE_SENTINEL>(resolve => {
+        timer = setTimeout(() => resolve(IDLE_SENTINEL), opts.timeoutMs)
+      })
+      const nextResult = iterator.next()
+      let raced: IteratorResult<T> | typeof IDLE_SENTINEL
+      try {
+        raced = await Promise.race([nextResult, idle])
+      } finally {
+        if (timer) clearTimeout(timer)
+      }
+      if (raced === IDLE_SENTINEL) {
+        // Swallow the abandoned next() so it never surfaces as an unhandled
+        // rejection once the underlying stream tears down.
+        void Promise.resolve(nextResult).catch(() => {})
+        await opts.onTimeout()
+        throw new AgentStalledError(opts.timeoutMs)
+      }
+      if (raced.done) return
+      yield raced.value
+    }
+  } finally {
+    if (iterator.return) {
+      try {
+        await iterator.return()
+      } catch {
+        // best-effort close
+      }
+    }
+  }
+}
+
+// -- Headless question annotation --------------------------------------------
+
+function optionText(option: unknown): string {
+  if (typeof option === 'string') return option
+  if (option && typeof option === 'object') {
+    const rec = option as Record<string, unknown>
+    for (const key of ['label', 'text', 'value', 'title', 'option', 'name']) {
+      if (typeof rec[key] === 'string') return rec[key] as string
+    }
+  }
+  return ''
+}
+
+export interface ParsedHeadlessQuestion {
+  question: string
+  chosenOption: string
+}
+
+/**
+ * Parse the OpenCode `question` tool args into the question text and the option
+ * we would pick headless: the one labeled "(Recommended)" if present, else the
+ * first. Defensive against the tool's shape drifting (options as strings or
+ * objects; the question under any of several keys).
+ */
+export function parseHeadlessQuestion(args: unknown): ParsedHeadlessQuestion {
+  const rec = args && typeof args === 'object' ? (args as Record<string, unknown>) : {}
+  const questions = Array.isArray(rec.questions) ? rec.questions : []
+  const first = questions[0]
+
+  let question = ''
+  let options: unknown[] = []
+  if (typeof first === 'string') {
+    question = first
+  } else if (first && typeof first === 'object') {
+    const q = first as Record<string, unknown>
+    for (const key of ['question', 'prompt', 'text', 'title', 'message']) {
+      if (typeof q[key] === 'string') {
+        question = q[key] as string
+        break
+      }
+    }
+    if (Array.isArray(q.options)) options = q.options
+  }
+  if (options.length === 0 && Array.isArray(rec.options)) options = rec.options
+  if (!question && typeof rec.question === 'string') question = rec.question
+
+  const texts = options.map(optionText).filter(text => text.length > 0)
+  const recommended = texts.find(text => /\(recommended\)/i.test(text))
+  const chosenOption = recommended ?? texts[0] ?? ''
+  return { question, chosenOption }
+}
+
+/**
+ * Pass every harness event through unchanged; when a `question` tool call/result
+ * is seen, additionally emit a `question_auto_answered` event (deduped per
+ * callId+message) recording the auto-handling. The tool is denied at the
+ * permission layer, so this is a record — not an interactive reply.
+ */
+export async function* annotateHeadlessQuestions(
+  source: AsyncIterable<HarnessEvent>
+): AsyncGenerator<HarnessEvent> {
+  const seen = new Set<string>()
+  for await (const event of source) {
+    yield event
+    if (event.kind !== 'tool_call' && event.kind !== 'tool_result') continue
+    const payload = event.payload as Record<string, unknown>
+    if (payload.tool !== 'question') continue
+    const callId = typeof payload.callId === 'string' ? payload.callId : ''
+    const key = `${callId}:${event.messageId ?? ''}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const parsed = parseHeadlessQuestion(payload.args)
+    yield {
+      kind: 'question_auto_answered',
+      messageId: event.messageId,
+      payload: {
+        question: parsed.question,
+        chosenOption: parsed.chosenOption,
+        note: 'auto-answered: headless run, no human available',
+        resolution: 'denied_headless',
+      },
+    }
+  }
+}