orizu 0.5.26 → 0.5.28

package/dist/hosted-loop.js

@@ -16,7 +16,8 @@
  *      driver; 'claude-agent-sdk': construct the in-process Claude-Agent-SDK
  *      driver — no server to install or spawn), then drive the SINGLE task prompt
  *      (v0: no queue) through `drainHarnessToSink`;
- *   5. the terminal event decides the run's final status via the sink's PATCH.
+ *   5. checkpoint dirty or local-only Git work without replacing the agent's
+ *      terminal result, then deliver that original result through the sink.
  *
  * SWAPPABILITY (ALI-929 / P3.6): harness SELECTION is the ONLY thing that differs
  * between the two drivers — `start()` → `runPrompt()` → `drainHarnessToSink()` →
@@ -29,19 +30,22 @@
  * per-exec fallback — with firewall brokering the real key never reaches here).
  *
  * TESTABILITY: `runHostedLoop` takes injected `fetchImpl`, `spawnOpenCode`,
- * `installOpenCode`, and `createHarness`, so the whole loop runs in-process
- * against a fake broker + fake OpenCode server with no real binary.
+ * `installOpenCode`, `createHarness`, and Git execution, so the whole loop can
+ * run in-process against fake boundaries; separate tests exercise the real
+ * packaged CLI, HTTPS smart-Git transport, and OpenCode process boundary.
  */
 import { spawnSync, spawn as nodeSpawn } from 'child_process';
 import { closeSync, existsSync, openSync, readFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
-import { HOSTED_TASK_PREAMBLE, PREBAKED_MARKER_PATH, SETUP_HOOK_RELATIVE_PATH, composeHostedTaskPrompt, parsePrebakedMarker, } from './hosted-runtime-assets.js';
+import { isHarnessTerminalKind } from './hosted-harness.js';
+import { SETUP_HOOK_RELATIVE_PATH, composeHostedTaskPrompt, parsePrebakedMarker, resolveHostedTaskPreamble, resolvePrebakedMarkerPath, } from './hosted-runtime-assets.js';
 import { harvestWorkspace } from './hosted-harvest.js';
 import { annotateHeadlessQuestions, withIdleWatchdog } from './hosted-headless.js';
-import { DEFAULT_PROMPT_MAX_DURATION_MS, OPENCODE_PINNED_VERSION, awaitOpenCodeModelResolvable, createOpenCodeHarness, spawnOpenCode, } from './hosted-harness-opencode.js';
+import { DEFAULT_PROMPT_MAX_DURATION_MS, OPENCODE_PINNED_VERSION, awaitOpenCodeModelResolvable, createOpenCodeHarness, permissionForOrigin, spawnOpenCode, } from './hosted-harness-opencode.js';
 import { createClaudeAgentHarness } from './hosted-harness-claude.js';
 import { INJECTED_ENV_VARS_ENV } from './hosted-environment.js';
+import { interceptHostedQuestions } from './hosted-question.js';
 import { drainHarnessToSink, resumeRunEventSink, RunTerminalError, TerminalDeliveryError, } from './hosted-run-event-sink.js';
 import { buildOpenCodeSpawnEnv, defaultProbeEgress, egressCanaryAllowedHost, runEgressCanary, } from './hosted-loop-lifecycle.js';
 // The lifecycle/orchestration seam moved to `hosted-loop-lifecycle.ts`
@@ -136,16 +140,17 @@ function redactionListFromEnv() {
  * falls back to a belt read of the `/opt/orizu/prebaked.json` marker (validated
  * via `parsePrebakedMarker`, so a stray file cannot trigger a skip). Either → true.
  */
-function detectLoopPrebaked(flag) {
-    if (flag)
-        return true;
+function hasValidPrebakedMarker(markerPath) {
     try {
-        return parsePrebakedMarker(readFileSync(PREBAKED_MARKER_PATH, 'utf8')) !== null;
+        return parsePrebakedMarker(readFileSync(markerPath, 'utf8')) !== null;
     }
     catch {
         return false;
     }
 }
+function detectLoopPrebaked(flag, markerPath) {
+    return flag === true || hasValidPrebakedMarker(markerPath);
+}
 /** Best-effort global install of the pinned opencode. Non-fatal: a failure is
  *  recorded and the run finishes cleanly when the subsequent connect fails. */
 function installOpenCodePinned(version) {
@@ -193,6 +198,12 @@ export async function runHostedLoop(opts) {
     const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
     const signal = opts.signal ?? new AbortController().signal;
     const pinnedVersion = context.opencodePinnedVersion ?? OPENCODE_PINNED_VERSION;
+    const diagnose = (message) => {
+        try {
+            opts.onDiagnostic?.(message);
+        }
+        catch { /* diagnostics are best-effort */ }
+    };
     // Resolve the bearer per request. Precedence: an explicit provider, then a
     // fixed string, else read the rotated 0600 bearer file every time (production
     // + rotation path — a host-side rotation overwrites this file and the sink's
@@ -211,6 +222,7 @@ export async function runHostedLoop(opts) {
         fetchImpl,
         now: opts.now,
         redactSecretsList: [...(opts.redactSecretsList ?? []), ...redactionListFromEnv()],
+        onDiagnostic: diagnose,
     });
     // G5 startup canary (fail-closed, POSITIVE CONTROL): when the host applied an
     // enforced egress policy it sets `egressCanaryHost`; probe BOTH the denied host
@@ -220,7 +232,7 @@ export async function runHostedLoop(opts) {
     // unreachable → network broken / indistinguishable from a block) emits
     // `egress_allowed` and finishes the run FAILED rather than touch real customer
     // data. A canary whose own event append fails is likewise fail-closed.
-    if (context.egressCanaryHost) {
+    if (context.egressCanaryHost && !opts.sharedRuntime?.startupComplete) {
         const probe = opts.probeEgress ?? defaultProbeEgress;
         const targets = {
             allowedHost: egressCanaryAllowedHost(context.apiBaseUrl),
@@ -273,7 +285,7 @@ export async function runHostedLoop(opts) {
     // firewall is live, BEFORE any harness/network work. bootstrap deferred it (for
     // enforced-egress providers) precisely so its network access could not precede
     // the canary. Non-fatal, single-writer (this loop sink owns the run now).
-    if (context.runSetupHook) {
+    if (context.runSetupHook && !opts.sharedRuntime?.startupComplete) {
         try {
             const runHook = opts.runSetupHook ?? defaultRunSetupHook;
             const outcome = await runHook({ workspaceDir: context.workspaceDir });
@@ -303,27 +315,38 @@ export async function runHostedLoop(opts) {
             }
         }
     }
+    if (opts.sharedRuntime)
+        opts.sharedRuntime.startupComplete = true;
     // End-of-run auto-harvest (ALI-1036): commit + push anything the agent left
     // uncommitted/unpushed so a run NEVER loses work — on BOTH the success and
-    // failure paths. Runs at most once (guarded), records exactly one of
-    // work_persisted / work_none / work_persist_failed, and NEVER throws or changes
-    // the run's terminal status: a harvest failure is recorded and the run proceeds.
+    // failure paths. Runs at most once (guarded), records exactly one outcome with
+    // critical-intent delivery, and NEVER throws or changes the run's terminal
+    // status. If the event cannot land, safe outcome metadata rides the already-
+    // critical terminal PATCH instead.
+    const prebakedMarkerPath = resolvePrebakedMarkerPath();
     let harvested = false;
+    let checkpointFinishPatch;
     const runAutoHarvest = async () => {
         if (harvested)
-            return;
+            return checkpointFinishPatch;
         harvested = true;
         let outcome;
         try {
-            outcome = harvestWorkspace({
-                workspaceDir: context.workspaceDir,
-                runId: context.runId,
-                author: context.author,
-                exec: opts.harvestExec,
-                // Real harvest only inside a genuine hosted sandbox (prebaked marker
-                // present) — never on a host/test working tree (review finding #1).
-                enabled: existsSync(PREBAKED_MARKER_PATH),
-            });
+            const markerValid = hasValidPrebakedMarker(prebakedMarkerPath);
+            outcome = !opts.harvestExec && !markerValid
+                ? { kind: 'work_persist_failed', error: 'prebaked_marker_invalid' }
+                : harvestWorkspace({
+                    workspaceDir: context.workspaceDir,
+                    runId: context.runId,
+                    sessionBranch: context.sessionBranch,
+                    repositoryRemote: context.repositoryRemote,
+                    credentialHelper: context.repositoryCredentialHelper,
+                    author: context.author,
+                    exec: opts.harvestExec,
+                    // Real harvest requires a parsed marker from the hosted image;
+                    // mere path existence must never authorize default Git mutations.
+                    enabled: markerValid,
+                });
         }
         catch (error) {
             outcome = { kind: 'work_persist_failed', error: error instanceof Error ? error.message : String(error) };
@@ -332,29 +355,54 @@ export async function runHostedLoop(opts) {
             return;
         try {
             if (outcome.kind === 'work_persisted') {
-                await sink.append({ kind: 'work_persisted', payload: { sha: outcome.sha, files: outcome.files } });
+                await sink.append({
+                    kind: 'work_persisted',
+                    payload: { sha: outcome.sha, ...(outcome.files ? { files: outcome.files } : {}) },
+                    critical: true,
+                });
             }
             else if (outcome.kind === 'work_none') {
-                await sink.append({ kind: 'work_none', payload: {} });
+                await sink.append({ kind: 'work_none', payload: {}, critical: true });
+            }
+            else if (outcome.kind === 'work_not_inspected') {
+                await sink.append({ kind: 'work_not_inspected', payload: {}, critical: true });
             }
             else {
-                await sink.append({ kind: 'work_persist_failed', payload: { error: outcome.error } });
+                await sink.append({ kind: 'work_persist_failed', payload: { error: outcome.error }, critical: true });
             }
         }
         catch {
-            // Recording harvest is best-effort — never fail the run because the harvest
-            // event append failed.
+            // Value-free by construction: raw Git/provider errors and credentials must
+            // not enter process diagnostics or the terminal summary.
+            diagnose('hosted checkpoint event delivery failed');
+            const checkpointDelivery = outcome.kind === 'work_persisted'
+                ? {
+                    outcome: 'saved', sha: outcome.sha,
+                    ...(outcome.files ? { fileCount: outcome.files.length } : {}),
+                }
+                : outcome.kind === 'work_none'
+                    ? { outcome: 'no_changes' }
+                    : outcome.kind === 'work_not_inspected'
+                        ? { outcome: 'not_inspected' }
+                        : { outcome: 'unsaved' };
+            checkpointFinishPatch = {
+                summary: { checkpoint_delivery_failed: checkpointDelivery },
+            };
         }
+        return checkpointFinishPatch;
     };
-    let spawned = null;
-    let agentSessionId = null;
-    let installOk = false;
+    let spawned = opts.sharedRuntime?.spawned ?? null;
+    let agentSessionId = opts.sharedRuntime?.agentSessionId ?? null;
+    let installOk = opts.sharedRuntime?.installOk ?? false;
     const harnessKind = context.harness ?? 'opencode';
     try {
-        // --- Harness PROVISIONING: the ONLY thing that differs between the two
-        // drivers (ALI-929). Everything after `harness` is constructed is identical.
+        // A session runtime provisions and starts its harness exactly once. Later
+        // turns reuse this object and therefore the same native conversation.
         let harness;
-        if (harnessKind === 'claude-agent-sdk') {
+        if (opts.sharedRuntime?.harness) {
+            harness = opts.sharedRuntime.harness;
+        }
+        else if (harnessKind === 'claude-agent-sdk') {
             // In-process agent loop: no server to install or spawn. Record an
             // analogous setup artifact so the event stream shape is unchanged.
             installOk = true;
@@ -371,7 +419,7 @@ export async function runHostedLoop(opts) {
             // PRE-BAKED (ALI-1017): the pinned `opencode` is already on PATH, so SKIP the
             // install (npm is blocked under G5 default-deny egress) and record
             // `opencode_prebaked`. FROM-SCRATCH (local-sim / fallback): install as before.
-            const prebaked = detectLoopPrebaked(context.prebaked);
+            const prebaked = detectLoopPrebaked(context.prebaked, prebakedMarkerPath);
             if (prebaked) {
                 installOk = true;
                 await sink.append({
@@ -396,11 +444,12 @@ export async function runHostedLoop(opts) {
             // connection-refused "fetch failed" (ALI-1034).
             spawned = await spawnImpl({
                 model: context.model,
+                permission: permissionForOrigin(context.sessionOrigin),
                 cwd: context.workspaceDir,
                 port: context.opencodePort,
                 env: buildOpenCodeSpawnEnv(context),
                 spawn: nodeChildSpawner,
-                logPath: join(tmpdir(), `opencode-serve-${context.runId}.log`),
+                logPath: opts.sharedRuntime?.spawnLogPath ?? join(tmpdir(), `opencode-serve-${context.runId}.log`),
                 signal,
             });
             if (typeof spawned.readyAfterMs === 'number') {
@@ -451,23 +500,32 @@ export async function runHostedLoop(opts) {
             harness = (opts.createHarness ??
                 ((baseUrl, options) => createOpenCodeHarness({ baseUrl, promptMaxDurationMs: options?.promptMaxDurationMs })))(spawned.baseUrl, { promptMaxDurationMs });
         }
-        const started = await harness.start({
-            workspaceDir: context.workspaceDir,
-            model: context.model,
-            reasoningEffort: context.reasoningEffort,
-            resumeAgentSessionId: context.resumeAgentSessionId,
-        });
-        agentSessionId = started.agentSessionId;
+        if (!opts.sharedRuntime?.harness) {
+            const started = await harness.start({
+                workspaceDir: context.workspaceDir,
+                model: context.model,
+                reasoningEffort: context.reasoningEffort,
+                resumeAgentSessionId: context.resumeAgentSessionId,
+            });
+            agentSessionId = started.agentSessionId;
+            if (opts.sharedRuntime) {
+                opts.sharedRuntime.harness = harness;
+                opts.sharedRuntime.spawned = spawned;
+                opts.sharedRuntime.agentSessionId = agentSessionId;
+                opts.sharedRuntime.installOk = installOk;
+            }
+        }
         // Prompt scaffolding (ALI-1036): wrap the user task with the standing
         // headless preamble, keeping the task verbatim beneath a delimiter.
         const prompt = {
             runId: context.runId,
             messageId: context.messageId,
-            content: composeHostedTaskPrompt(taskPrompt, opts.taskPreamble ?? HOSTED_TASK_PREAMBLE),
+            content: composeHostedTaskPrompt(taskPrompt, opts.taskPreamble ?? resolveHostedTaskPreamble(context.sessionOrigin)),
             author: context.author,
         };
-        // Drive the prompt through (a) question auto-handling annotation and (b) the
-        // idle watchdog (ALI-1037): no harness event for `idleTimeoutMs` aborts the
+        // Drive the prompt through question-deny annotation unless hosted-web
+        // OpenCode interception owns the outcome, then through the idle watchdog
+        // (ALI-1037): no harness event for `idleTimeoutMs` aborts the
         // prompt and throws `AgentStalledError` → the catch below harvests, then
         // finishes the run `failed`. The prompt runs under a CHILD AbortController
         // linked to the loop signal so the watchdog can abort the in-flight prompt
@@ -479,7 +537,95 @@ export async function runHostedLoop(opts) {
             promptController.abort();
         else
             signal.addEventListener('abort', () => promptController.abort(), { once: true });
-        const annotated = annotateHeadlessQuestions(harness.runPrompt(prompt, promptController.signal));
+        // A human interrupt is prompt-scoped: signal the production driver (whose
+        // abort path sends OpenCode POST /session/:id/abort) and invoke stop() as a
+        // best-effort belt. This callback is deliberately total. All callers share
+        // one promise so the question path can await confirmed quiescence. Once this
+        // prompt yields its terminal event, a late marker belongs to the terminal/
+        // harvest window and must not abort the next queued prompt.
+        let hasPromptTerminal = false;
+        let quiescencePromise = null;
+        const beginQuiescence = () => {
+            promptController.abort();
+            if (quiescencePromise)
+                return quiescencePromise;
+            try {
+                quiescencePromise = Promise.resolve(harness.stop()).catch(() => {
+                    diagnose('hosted interrupt stop failed; prompt signal remains authoritative');
+                });
+            }
+            catch {
+                diagnose('hosted interrupt stop failed; prompt signal remains authoritative');
+                quiescencePromise = Promise.resolve();
+            }
+            return quiescencePromise;
+        };
+        const handleInterrupt = () => {
+            if (hasPromptTerminal)
+                return;
+            void beginQuiescence();
+        };
+        const interruptSignal = opts.interruptSignal;
+        if (interruptSignal?.aborted)
+            handleInterrupt();
+        else
+            interruptSignal?.addEventListener('abort', handleInterrupt, { once: true });
+        const terminalSummary = { agentSessionId };
+        let hasQuestionOutcome = false;
+        const promptEvents = harness.runPrompt(prompt, promptController.signal);
+        const hasHostedQuestionInterception = harnessKind === 'opencode' && context.sessionOrigin === 'hosted-web';
+        const intercepted = hasHostedQuestionInterception
+            ? interceptHostedQuestions(promptEvents, {
+                onDetected: question => {
+                    hasQuestionOutcome = true;
+                    terminalSummary.outcome = 'question_pending';
+                    terminalSummary.questionId = question.questionId;
+                },
+                onInvalid: reason => {
+                    hasQuestionOutcome = true;
+                    terminalSummary.outcome = 'question_invalid';
+                    terminalSummary.reason = reason;
+                },
+                // Async-generator resumption occurs only after drain appended the
+                // yielded critical event. Reuse ALI-1760's single abort owner.
+                onPersisted: beginQuiescence,
+                onInvalidPersisted: beginQuiescence,
+            })
+            : promptEvents;
+        const questionAware = hasHostedQuestionInterception
+            ? intercepted
+            : annotateHeadlessQuestions(intercepted);
+        const interruptAware = (async function* () {
+            for await (const event of questionAware) {
+                if (isHarnessTerminalKind(event.kind)) {
+                    hasPromptTerminal = true;
+                    if (hasQuestionOutcome || (interruptSignal?.aborted && event.kind !== 'error')) {
+                        yield {
+                            kind: 'execution_complete',
+                            messageId: prompt.messageId,
+                            critical: true,
+                            payload: { success: false, aborted: true },
+                        };
+                    }
+                    else {
+                        yield event;
+                    }
+                    return;
+                }
+                yield event;
+            }
+            // A signal already durable before prompt startup can make a driver end
+            // without yielding. It is still an intentional cancellation, not a run
+            // failure or a missing-terminal fault.
+            if (interruptSignal?.aborted || hasQuestionOutcome) {
+                yield {
+                    kind: 'execution_complete',
+                    messageId: prompt.messageId,
+                    critical: true,
+                    payload: { success: false, aborted: true },
+                };
+            }
+        })();
         if (idleTimeoutMs <= 0) {
             // <= 0 explicitly DISABLES the watchdog (e.g. ORIZU_AGENT_IDLE_TIMEOUT_MS=0):
             // a stalled prompt will hang until the sandbox/prompt hard cap. Record it so
@@ -493,32 +639,42 @@ export async function runHostedLoop(opts) {
             });
         }
         const drivenStream = idleTimeoutMs > 0
-            ? withIdleWatchdog(annotated, {
+            ? withIdleWatchdog(interruptAware, {
                 timeoutMs: idleTimeoutMs,
                 onTimeout: async () => {
                     promptController.abort();
                     await harness.stop();
                 },
-                // The `question` tool is DENIED headless, so a model stuck retrying it
-                // emits a stream of synthetic `question_auto_answered` events. Those are
+                // Without hosted-web OpenCode interception, a model stuck retrying a
+                // denied question emits synthetic `question_auto_answered` events. Those are
                 // NOT progress — excluding them lets a deny/retry loop trip agent_stalled
                 // instead of resetting the idle timer forever (ALI-1069).
                 isProgress: event => event.kind !== 'question_auto_answered',
             })
-            : annotated;
-        const status = await drainHarnessToSink(drivenStream, sink, {
-            summary: { agentSessionId },
-            // Auto-harvest runs on EVERY terminal path, before the sink seals.
-            beforeFinish: runAutoHarvest,
-        });
-        await harness.shutdown();
+            : interruptAware;
+        let status;
+        try {
+            status = await drainHarnessToSink(drivenStream, sink, {
+                summary: terminalSummary,
+                // Auto-harvest runs on EVERY terminal path, before the sink seals.
+                beforeFinish: runAutoHarvest,
+            });
+        }
+        finally {
+            interruptSignal?.removeEventListener('abort', handleInterrupt);
+        }
+        if (!opts.sharedRuntime)
+            await harness.shutdown();
+        if (opts.sharedRuntime)
+            opts.sharedRuntime.agentSessionId = agentSessionId;
         return { status, agentSessionId, installOk, error: null };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         // Harvest FIRST on every abnormal path (partial work is valuable, incl. an
         // idle-watchdog abort) — before any terminal write seals the sink.
-        await runAutoHarvest();
+        const checkpointPatch = await runAutoHarvest();
+        const checkpointSummary = checkpointPatch?.summary ?? {};
         // 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
@@ -569,7 +725,7 @@ export async function runHostedLoop(opts) {
         // no-ops when the drain already sealed the sink.
         if (!sink.sealed) {
             try {
-                await sink.finish('failed', { summary: { error: message } });
+                await sink.finish('failed', { summary: { error: message, ...checkpointSummary } });
             }
             catch {
                 // best-effort — the terminal write itself may be impossible (bearer gone)
@@ -578,7 +734,7 @@ export async function runHostedLoop(opts) {
         return { status: 'failed', agentSessionId, installOk, error: message };
     }
     finally {
-        if (spawned) {
+        if (spawned && (!opts.sharedRuntime || opts.sharedRuntime.spawned !== spawned)) {
             try {
                 spawned.stop();
             }
@@ -588,6 +744,90 @@ export async function runHostedLoop(opts) {
         }
     }
 }
+export async function startHostedLoopSession(context) {
+    return {
+        context,
+        runtime: {
+            harness: null,
+            spawned: null,
+            agentSessionId: null,
+            installOk: false,
+            startupComplete: false,
+            spawnLogPath: join(context.sessionDir, `opencode-serve-${context.sessionId}.log`),
+            closed: false,
+        },
+    };
+}
+export async function runHostedLoopTurn(session, turn, options) {
+    if (session.runtime.closed)
+        throw new Error('hosted loop session is closed');
+    return runHostedLoop({
+        ...options,
+        context: {
+            ...session.context,
+            runId: turn.runId,
+            taskFile: turn.taskFile,
+            messageId: turn.messageId,
+            bearerFile: turn.bearerFile,
+            resumeAgentSessionId: session.runtime.agentSessionId ?? session.context.resumeAgentSessionId,
+        },
+        taskPrompt: options.taskPrompt,
+        sharedRuntime: session.runtime,
+    });
+}
+export async function closeHostedLoopSession(session) {
+    if (session.runtime.closed)
+        return;
+    session.runtime.closed = true;
+    try {
+        await session.runtime.harness?.shutdown();
+    }
+    finally {
+        session.runtime.spawned?.stop();
+        session.runtime.harness = null;
+        session.runtime.spawned = null;
+    }
+}
+const REQUIRED_CONTEXT_STRINGS = [
+    'apiBaseUrl', 'runId', 'bearerFile', 'taskFile', 'workspaceDir',
+    'sessionBranch', 'repositoryRemote', 'model', 'messageId',
+];
+const OPTIONAL_CONTEXT_STRINGS = [
+    'reasoningEffort', 'opencodePinnedVersion', 'anthropicDummyKey',
+    'resumeAgentSessionId', 'egressCanaryHost', 'repositoryCredentialHelper',
+];
+function isNonemptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function validateHostedLoopContext(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { context: null, fields: ['root'] };
+    const record = value;
+    const fields = REQUIRED_CONTEXT_STRINGS.filter(name => !isNonemptyString(record[name]));
+    const branch = record.sessionBranch;
+    if (typeof branch === 'string' && (branch.length > 255 || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/u.test(branch) ||
+        branch.includes('..') || branch.includes('//') || branch.endsWith('/') || branch.includes('@{')))
+        fields.push('sessionBranch');
+    const author = record.author;
+    if (!author || typeof author !== 'object' || Array.isArray(author) ||
+        !isNonemptyString(author.name) || !isNonemptyString(author.email))
+        fields.push('author');
+    if (record.harness !== undefined && record.harness !== 'opencode' && record.harness !== 'claude-agent-sdk')
+        fields.push('harness');
+    if (record.sessionOrigin !== undefined && record.sessionOrigin !== 'hosted-web' && record.sessionOrigin !== 'cli')
+        fields.push('sessionOrigin');
+    if (record.sandboxBudgetMs !== undefined && (typeof record.sandboxBudgetMs !== 'number' || !Number.isFinite(record.sandboxBudgetMs) || record.sandboxBudgetMs <= 0))
+        fields.push('sandboxBudgetMs');
+    if (record.opencodePort !== undefined && (typeof record.opencodePort !== 'number' || !Number.isInteger(record.opencodePort) || record.opencodePort <= 0 || record.opencodePort > 65_535))
+        fields.push('opencodePort');
+    for (const name of OPTIONAL_CONTEXT_STRINGS)
+        if (record[name] !== undefined && typeof record[name] !== 'string')
+            fields.push(name);
+    for (const name of ['prebaked', 'runSetupHook'])
+        if (record[name] !== undefined && typeof record[name] !== 'boolean')
+            fields.push(name);
+    return { context: fields.length === 0 ? value : null, fields: [...new Set(fields)] };
+}
 function argValue(args, flag) {
     const index = args.indexOf(flag);
     if (index === -1 || index + 1 >= args.length)
@@ -606,19 +846,25 @@ export async function hostedLoopCommand(args, io) {
         io.printErr?.('Usage: orizu internal hosted-loop --context <path>');
         return 1;
     }
-    let context;
+    let rawContext;
     try {
-        context = JSON.parse(readFileSync(contextPath, 'utf8'));
+        rawContext = JSON.parse(readFileSync(contextPath, 'utf8'));
     }
     catch (error) {
         io.printErr?.(`unreadable loop context: ${error instanceof Error ? error.message : String(error)}`);
         return 1;
     }
+    const parsedContext = validateHostedLoopContext(rawContext);
+    if (!parsedContext.context) {
+        io.printErr?.(`invalid loop context: ${parsedContext.fields.join(', ')}`);
+        return 1;
+    }
+    const context = parsedContext.context;
     // Read the bearer per request (via the provider) so a host-side rotation that
     // overwrites the 0600 file is picked up without restarting the loop.
     const bearerProvider = () => readFileSync(context.bearerFile, 'utf8').trim();
     const taskPrompt = readFileSync(context.taskFile, 'utf8');
-    const result = await runHostedLoop({ context, bearerProvider, taskPrompt });
+    const result = await runHostedLoop({ context, bearerProvider, taskPrompt, onDiagnostic: io.printErr });
     io.print(io.json
         ? JSON.stringify({ status: result.status, agentSessionId: result.agentSessionId, error: result.error })
         : `hosted-loop finished: ${result.status}${result.error ? ` (${result.error})` : ''}`);

package/dist/hosted-question-limits.d.ts

@@ -0,0 +1,7 @@
+export declare const HOSTED_QUESTION_LIMITS: Readonly<{
+    readonly questionMax: 2000;
+    readonly optionLabelMax: 200;
+    readonly optionDescriptionMax: 500;
+    readonly optionCountMax: 8;
+}>;
+//# sourceMappingURL=hosted-question-limits.d.ts.map

package/dist/hosted-question-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-question-limits.d.ts","sourceRoot":"","sources":["../src/hosted-question-limits.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB;;;;;EAKxB,CAAA"}

package/dist/hosted-question-limits.js

@@ -0,0 +1,6 @@
+export const HOSTED_QUESTION_LIMITS = Object.freeze({
+    questionMax: 2_000,
+    optionLabelMax: 200,
+    optionDescriptionMax: 500,
+    optionCountMax: 8,
+});

package/dist/hosted-question.d.ts

@@ -0,0 +1,27 @@
+import type { HarnessEvent } from './hosted-harness.js';
+export { HOSTED_QUESTION_LIMITS } from './hosted-question-limits.js';
+export interface HostedPendingQuestionOption {
+    label: string;
+    description: string | null;
+}
+export interface HostedPendingQuestion {
+    questionId: string;
+    question: string;
+    options: HostedPendingQuestionOption[];
+}
+export declare const INVALID_HOSTED_QUESTION_REASON = "expected_exactly_one_bounded_question";
+export declare class InvalidHostedQuestionError extends Error {
+    readonly reason = "expected_exactly_one_bounded_question";
+    constructor();
+}
+export declare function parseHostedQuestion(args: unknown, createQuestionId?: () => string): HostedPendingQuestion;
+export interface InterceptHostedQuestionOptions {
+    createQuestionId?: () => string;
+    onDetected(question: HostedPendingQuestion): void;
+    onPersisted(question: HostedPendingQuestion): Promise<void>;
+    onInvalid?(reason: string): void;
+    onInvalidPersisted?(reason: string): Promise<void>;
+}
+export declare function interceptHostedQuestions(source: AsyncIterable<HarnessEvent>, options: InterceptHostedQuestionOptions): AsyncGenerator<HarnessEvent>;
+export declare function composeHostedAnswerPrompt(question: Pick<HostedPendingQuestion, 'questionId' | 'question'>, answerText: string): string;
+//# sourceMappingURL=hosted-question.d.ts.map

package/dist/hosted-question.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-question.d.ts","sourceRoot":"","sources":["../src/hosted-question.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAIvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAQpE,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,2BAA2B,EAAE,CAAA;CACvC;AAED,eAAO,MAAM,8BAA8B,0CAA0C,CAAA;AAErF,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,MAAM,2CAAiC;;CAMjD;AAsBD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,gBAAgB,GAAE,MAAM,MAAmB,GAC1C,qBAAqB,CAgBvB;AAED,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAA;IAC/B,UAAU,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACjD,WAAW,CAAC,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3D,SAAS,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,kBAAkB,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD;AAED,wBAAuB,wBAAwB,CAC7C,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,EACnC,OAAO,EAAE,8BAA8B,GACtC,cAAc,CAAC,YAAY,CAAC,CAwC9B;AAED,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,IAAI,CAAC,qBAAqB,EAAE,YAAY,GAAG,UAAU,CAAC,EAChE,UAAU,EAAE,MAAM,GACjB,MAAM,CAWR"}