orizu 0.5.7 → 0.5.9

package/README.md

@@ -174,8 +174,15 @@ orizu logout
     <td><code>orizu prompts archive &lt;promptIdOrName&gt; --project ops-eval/support-qa</code><br><code>orizu prompts restore &lt;promptIdOrName&gt; --project ops-eval/support-qa</code></td>
   </tr>
   <tr>
-    <td>Show prompt comments</td>
-    <td><code>orizu prompts comments &lt;promptIdOrName&gt; --project ops-eval/support-qa</code></td>
+    <td colspan="2"><strong>Report comments</strong></td>
+  </tr>
+  <tr>
+    <td>List report comments</td>
+    <td><code>orizu comments list --prompt &lt;promptIdOrName&gt; --project ops-eval/support-qa</code><br><code>orizu comments list --run &lt;runId&gt;</code><br><code>orizu comments list --task &lt;taskId&gt;</code></td>
+  </tr>
+  <tr>
+    <td>Add or update comments</td>
+    <td><code>orizu comments add --run &lt;runId&gt; --body @comment.md --anchor "Summary" --lines 4:6</code><br><code>orizu comments reply &lt;commentId&gt; --body "Fixed"</code><br><code>orizu comments resolve &lt;commentId&gt;</code></td>
   </tr>
   <tr>
     <td colspan="2"><strong>Datasets</strong></td>
@@ -295,6 +302,10 @@ orizu logout
     <td>Upload a task report</td>
     <td><code>orizu tasks report set --task &lt;taskId&gt; --report-file ./report.md</code></td>
   </tr>
+  <tr>
+    <td>Read a task report</td>
+    <td><code>orizu tasks report get --task &lt;taskId&gt;</code></td>
+  </tr>
   <tr>
     <td>Resume a task</td>
     <td><code>orizu tasks unpause --task &lt;taskId&gt;</code></td>

package/dist/credentials.js

@@ -162,6 +162,50 @@ export function getActiveBaseUrl() {
     const config = loadCredentialsConfig();
     return config?.activeBaseUrl || null;
 }
+/**
+ * In-sandbox bearer resolution (ALI-1044). Resolves a bearer supplied out-of-band
+ * to the hosted agent, WITHOUT consulting credentials.json:
+ *   1. `ORIZU_TOKEN` — an explicit bearer in the environment (wins if present).
+ *   2. `ORIZU_TOKEN_FILE` — an absolute path to a 0600 file whose TRIMMED contents
+ *      are the bearer.
+ * Returns null when neither is set, so callers fall through to credentials.json.
+ *
+ * The token file is read FRESH on EVERY call and never cached: the hosted loop
+ * ROTATES the file underneath a long-lived agent process, so caching the value
+ * would pin a stale (soon-expired) bearer. The token is never logged, echoed, or
+ * passed via argv — only returned to the caller for a single request's header.
+ *
+ * A set-but-unreadable/empty `ORIZU_TOKEN_FILE` throws a clear error rather than
+ * returning null, so a misconfigured sandbox fails loudly instead of silently
+ * falling back to (absent) credentials.json and emitting a confusing "not logged
+ * in" message.
+ */
+export function resolveEnvBearerToken() {
+    const explicit = process.env.ORIZU_TOKEN;
+    if (explicit && explicit.trim()) {
+        return explicit.trim();
+    }
+    const tokenFile = process.env.ORIZU_TOKEN_FILE;
+    if (tokenFile && tokenFile.length > 0) {
+        if (!existsSync(tokenFile)) {
+            throw new Error(`ORIZU_TOKEN_FILE is set to ${tokenFile} but no such file exists.`);
+        }
+        let raw;
+        try {
+            raw = readFileSync(tokenFile, 'utf8');
+        }
+        catch (error) {
+            const detail = isNodeError(error) ? error.message : String(error);
+            throw new Error(`Failed to read ORIZU_TOKEN_FILE (${tokenFile}): ${detail}`);
+        }
+        const token = raw.trim();
+        if (!token) {
+            throw new Error(`ORIZU_TOKEN_FILE (${tokenFile}) is empty.`);
+        }
+        return token;
+    }
+    return null;
+}
 export function setActiveBaseUrl(baseUrl) {
     const config = loadCredentialsConfigForWrite();
     config.activeBaseUrl = baseUrl;

package/dist/help.js

@@ -11,6 +11,7 @@ const GROUPS = [
     { 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.' },
@@ -57,6 +58,67 @@ export const COMMAND_DOCS = [
         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]',
@@ -100,7 +162,7 @@ export const COMMAND_DOCS = [
     },
     {
         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']],
@@ -248,12 +310,6 @@ export const COMMAND_DOCS = [
         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]',
@@ -538,6 +594,20 @@ export const COMMAND_DOCS = [
             '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/dist/hosted-bootstrap.js

@@ -265,6 +265,51 @@ export async function bootstrapHostedSandbox(opts) {
                 outputTail: tail(install.stdout, install.stderr),
             });
         }
+        // 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}`,
+            // The staged skill is bootstrap-injected RUNTIME scaffolding (a symlink to
+            // the sandbox-local CLI vendor dir), NOT the agent's work. Exclude it
+            // repo-LOCALLY (.git/info/exclude — invisible to the diff, never committed)
+            // so auto-harvest's `git add -A` can't sweep it into the session branch and
+            // (ALI-1051) auto-apply a broken symlink to the customer's main.
+            `if [ -d ${workspaceDir}/.git ]; then printf '%s\\n' '/.claude/skills/' >> ${workspaceDir}/.git/info/exclude; fi`,
+            `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/dist/hosted-harness-opencode.js

@@ -686,6 +686,26 @@ function errorEvent(messageId, error) {
     const message = error instanceof Error ? error.message : String(error);
     return { kind: 'error', messageId, critical: true, payload: { error: message } };
 }
+/**
+ * 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'];
+/** The default headless permission map: allow everything, deny the interactive
+ *  question tool (see HEADLESS_DENIED_TOOLS). */
+export function defaultHeadlessPermission() {
+    const permission = { '*': { '*': '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
@@ -694,7 +714,7 @@ function errorEvent(messageId, error) {
 export function buildOpenCodeConfigContent(opts) {
     return JSON.stringify({
         model: opts.model,
-        permission: opts.permission ?? { '*': { '*': 'allow' } },
+        permission: opts.permission ?? defaultHeadlessPermission(),
     });
 }
 const OPENCODE_READY_TIMEOUT_MS = 180_000;

package/dist/hosted-harness.js

@@ -46,6 +46,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',
 };

package/dist/hosted-harvest.js

@@ -0,0 +1,121 @@
+/**
+ * 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';
+function defaultHarvestExec(workspaceDir) {
+    return (args) => {
+        const res = spawnSync('git', args, { 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) {
+    const text = (res.stderr && res.stderr.trim()) || (res.stdout && res.stdout.trim()) || `exit ${res.exitCode}`;
+    return text;
+}
+function splitLines(text) {
+    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) {
+    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) {
+    // 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 {
+        // Never harvest bootstrap-injected runtime scaffolding (ALI-1051): the
+        // .claude/skills symlink is a sandbox-local pointer, not the agent's work.
+        // Bootstrap also excludes it via .git/info/exclude; this pathspec is the
+        // belt-and-braces for any sandbox where that didn't run.
+        const excludeScaffold = [':(exclude).claude/skills/**', ':(exclude).claude/skills'];
+        const status = exec(['status', '--porcelain', '--', '.', ...excludeScaffold]);
+        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', '--', '.', ...excludeScaffold]);
+            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/dist/hosted-headless.js

@@ -0,0 +1,163 @@
+/**
+ * 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.
+ */
+/** Thrown by `withIdleWatchdog` when the stream is idle past its timeout. */
+export class AgentStalledError extends Error {
+    idleMs;
+    constructor(idleMs) {
+        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) {
+    const minutes = Math.round((ms / 60000) * 10) / 10;
+    return `${minutes}m`;
+}
+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(source, opts) {
+    const iterator = source[Symbol.asyncIterator]();
+    try {
+        for (;;) {
+            let timer;
+            const idle = new Promise(resolve => {
+                timer = setTimeout(() => resolve(IDLE_SENTINEL), opts.timeoutMs);
+            });
+            const nextResult = iterator.next();
+            let raced;
+            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) {
+    if (typeof option === 'string')
+        return option;
+    if (option && typeof option === 'object') {
+        const rec = option;
+        for (const key of ['label', 'text', 'value', 'title', 'option', 'name']) {
+            if (typeof rec[key] === 'string')
+                return rec[key];
+        }
+    }
+    return '';
+}
+/**
+ * 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) {
+    const rec = args && typeof args === 'object' ? args : {};
+    const questions = Array.isArray(rec.questions) ? rec.questions : [];
+    const first = questions[0];
+    let question = '';
+    let options = [];
+    if (typeof first === 'string') {
+        question = first;
+    }
+    else if (first && typeof first === 'object') {
+        const q = first;
+        for (const key of ['question', 'prompt', 'text', 'title', 'message']) {
+            if (typeof q[key] === 'string') {
+                question = q[key];
+                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) {
+    const seen = new Set();
+    for await (const event of source) {
+        yield event;
+        if (event.kind !== 'tool_call' && event.kind !== 'tool_result')
+            continue;
+        const payload = event.payload;
+        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',
+            },
+        };
+    }
+}