orizu 0.5.7 → 0.5.8

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',
+      },
+    }
+  }
+}

package/src/hosted-loop.ts

@@ -40,10 +40,14 @@ import { join } from 'path'
 
 import type { AgentHarness, HarnessEvent, HarnessPrompt } from './hosted-harness.js'
 import {
+  HOSTED_TASK_PREAMBLE,
   PREBAKED_MARKER_PATH,
   SETUP_HOOK_RELATIVE_PATH,
+  composeHostedTaskPrompt,
   parsePrebakedMarker,
 } from './hosted-runtime-assets.js'
+import { harvestWorkspace, type HarvestExec, type HarvestOutcome } from './hosted-harvest.js'
+import { annotateHeadlessQuestions, withIdleWatchdog } from './hosted-headless.js'
 import {
   OPENCODE_PINNED_VERSION,
   createOpenCodeHarness,
@@ -132,6 +136,28 @@ export interface HostedLoopContext {
   runSetupHook?: boolean
 }
 
+/**
+ * Environment injected into the spawned OpenCode server so the AGENT's bash sees a
+ * PRE-AUTHENTICATED `orizu` CLI (ALI-1044). ORIZU_TOKEN_FILE points at the 0600
+ * rotated bearer file and ORIZU_BASE_URL at the Orizu API — the exact vars the
+ * CLI's auth resolution reads (resolveEnvBearerToken + resolveBaseUrl). The dummy
+ * ANTHROPIC key (model-key brokering, G3) is preserved. No real secret is carried
+ * here: the bearer stays on disk and is read fresh per request from the file.
+ */
+export function buildOpenCodeSpawnEnv(context: HostedLoopContext): Record<string, string> | undefined {
+  const env: Record<string, string> = {}
+  if (context.anthropicDummyKey) {
+    env.ANTHROPIC_API_KEY = context.anthropicDummyKey
+  }
+  if (context.bearerFile) {
+    env.ORIZU_TOKEN_FILE = context.bearerFile
+  }
+  if (context.apiBaseUrl) {
+    env.ORIZU_BASE_URL = context.apiBaseUrl
+  }
+  return Object.keys(env).length > 0 ? env : undefined
+}
+
 export interface InstallResult {
   ok: boolean
   detail: string
@@ -171,6 +197,24 @@ export interface RunHostedLoopOptions {
    *  workspace, non-fatal). Injectable so tests exercise the deferred-hook path
    *  with no real filesystem or child process. */
   runSetupHook?: (input: { workspaceDir: string }) => Promise<SetupHookOutcome> | SetupHookOutcome
+  /**
+   * Standing preamble wrapped around the user task (ALI-1036). Defaults to
+   * `HOSTED_TASK_PREAMBLE`; pass an override to customize it, or an empty string
+   * to send the task verbatim (tests). The user task is always kept verbatim
+   * beneath a delimiter (see `composeHostedTaskPrompt`).
+   */
+  taskPreamble?: string
+  /**
+   * Injectable git runner for the end-of-run auto-harvest (ALI-1036). Default:
+   * real `git` via child_process in `context.workspaceDir`.
+   */
+  harvestExec?: HarvestExec
+  /**
+   * Idle watchdog window (ALI-1037): abort the prompt + fail the run
+   * `agent_stalled` if NO harness event arrives for this many ms. Default: env
+   * `ORIZU_AGENT_IDLE_TIMEOUT_MS` or 10 minutes. <= 0 disables the watchdog.
+   */
+  idleTimeoutMs?: number
 }
 
 export interface HostedLoopResult {
@@ -363,6 +407,25 @@ function defaultRunSetupHook({ workspaceDir }: { workspaceDir: string }): SetupH
   return { ran: true, ok, detail: ok ? 'setup.sh ok' : `setup.sh exit ${res.status ?? 'unknown'}` }
 }
 
+/** Default idle-watchdog window (ALI-1037): abort a prompt that makes no progress
+ *  for this long. The timer resets on every harness EVENT, and a legitimate long
+ *  single tool call (a big `npm install`, a build, an optimization step) emits no
+ *  intermediate events — so this must comfortably exceed the longest expected
+ *  quiet tool call (review finding #2). Overridable per-run via `idleTimeoutMs` or
+ *  the `ORIZU_AGENT_IDLE_TIMEOUT_MS` env var. */
+export const DEFAULT_AGENT_IDLE_TIMEOUT_MS = 25 * 60 * 1000
+
+/** Resolve the idle window: explicit option wins, then env, then the default. */
+function resolveIdleTimeoutMs(override: number | undefined): number {
+  if (typeof override === 'number' && Number.isFinite(override)) return override
+  const raw = process.env.ORIZU_AGENT_IDLE_TIMEOUT_MS
+  if (raw) {
+    const parsed = Number.parseInt(raw, 10)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return DEFAULT_AGENT_IDLE_TIMEOUT_MS
+}
+
 /** Model-key env vars whose value must be scrubbed from every run event. */
 const MODEL_KEY_ENV_VARS = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY']
 
@@ -552,6 +615,44 @@ export async function runHostedLoop(opts: RunHostedLoopOptions): Promise<HostedL
     }
   }
 
+  // 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.
+  let harvested = false
+  const runAutoHarvest = async (): Promise<void> => {
+    if (harvested) return
+    harvested = true
+    let outcome: HarvestOutcome
+    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),
+      })
+    } catch (error) {
+      outcome = { kind: 'work_persist_failed', error: error instanceof Error ? error.message : String(error) }
+    }
+    if (sink.sealed) return
+    try {
+      if (outcome.kind === 'work_persisted') {
+        await sink.append({ kind: 'work_persisted', payload: { sha: outcome.sha, files: outcome.files } })
+      } else if (outcome.kind === 'work_none') {
+        await sink.append({ kind: 'work_none', payload: {} })
+      } else {
+        await sink.append({ kind: 'work_persist_failed', payload: { error: outcome.error } })
+      }
+    } catch {
+      // Recording harvest is best-effort — never fail the run because the harvest
+      // event append failed.
+    }
+  }
+
   let spawned: SpawnedOpenCode | null = null
   let agentSessionId: string | null = null
   let installOk = false
@@ -604,7 +705,7 @@ export async function runHostedLoop(opts: RunHostedLoopOptions): Promise<HostedL
         model: context.model,
         cwd: context.workspaceDir,
         port: context.opencodePort,
-        env: context.anthropicDummyKey ? { ANTHROPIC_API_KEY: context.anthropicDummyKey } : undefined,
+        env: buildOpenCodeSpawnEnv(context),
         spawn: nodeChildSpawner,
         logPath: join(tmpdir(), `opencode-serve-${context.runId}.log`),
         signal,
@@ -629,21 +730,49 @@ export async function runHostedLoop(opts: RunHostedLoopOptions): Promise<HostedL
     })
     agentSessionId = started.agentSessionId
 
+    // Prompt scaffolding (ALI-1036): wrap the user task with the standing
+    // headless preamble, keeping the task verbatim beneath a delimiter.
     const prompt: HarnessPrompt = {
       runId: context.runId,
       messageId: context.messageId,
-      content: taskPrompt,
+      content: composeHostedTaskPrompt(taskPrompt, opts.taskPreamble ?? HOSTED_TASK_PREAMBLE),
       author: context.author,
     }
-    const status = await drainHarnessToSink(harness.runPrompt(prompt, signal), sink, {
+    // Drive the prompt through (a) question auto-handling annotation and (b) 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
+    // (unblocking a signal-respecting harness the same way a cancel would), then
+    // best-effort `harness.stop()` the driver.
+    const idleTimeoutMs = resolveIdleTimeoutMs(opts.idleTimeoutMs)
+    const promptController = new AbortController()
+    if (signal.aborted) promptController.abort()
+    else signal.addEventListener('abort', () => promptController.abort(), { once: true })
+    const annotated = annotateHeadlessQuestions(harness.runPrompt(prompt, promptController.signal))
+    const drivenStream =
+      idleTimeoutMs > 0
+        ? withIdleWatchdog(annotated, {
+            timeoutMs: idleTimeoutMs,
+            onTimeout: async () => {
+              promptController.abort()
+              await harness.stop()
+            },
+          })
+        : 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()
     return { status, agentSessionId, installOk, error: null }
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     // Fail closed: never leave the run non-terminal. finish() is idempotent and
-    // no-ops when the drain already sealed the sink.
+    // no-ops when the drain already sealed the sink. Harvest FIRST (partial work
+    // is valuable, incl. an idle-watchdog abort) — before the terminal seals.
+    await runAutoHarvest()
     if (!sink.sealed) {
       try {
         await sink.finish('failed', { summary: { error: message } })

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

@@ -77,6 +77,13 @@ const EVENT_TYPE_BY_KIND: Partial<Record<HarnessEventKind, string>> = {
   // through this SAME sink (single writer). See EGRESS_*_EVENT_TYPE below.
   egress_blocked: EGRESS_BLOCKED_EVENT_TYPE,
   egress_allowed: EGRESS_ALLOWED_EVENT_TYPE,
+  // Durability + headless (ALI-1036 / ALI-1037), emitted by the in-sandbox loop
+  // through this SAME sink (single writer): auto-harvest results + headless
+  // question auto-handling record.
+  work_persisted: 'work_persisted',
+  work_none: 'work_none',
+  work_persist_failed: 'work_persist_failed',
+  question_auto_answered: 'agent_question_auto_answered',
 }
 
 /** The RunAPI event type a harness kind maps to, or null if it is not appendable
@@ -576,6 +583,15 @@ export interface DrainOptions {
   transcript?: string
   summary?: Record<string, unknown>
   evidence?: Record<string, unknown>
+  /**
+   * Hook invoked AFTER the stream yields its terminal event but BEFORE `finish()`
+   * seals the sink, on EVERY terminal path (success, failure, abnormal end). Used
+   * by the loop's end-of-run auto-harvest (ALI-1036) so `work_persisted` /
+   * `work_none` / `work_persist_failed` can still be appended while the sink is
+   * writable. Its own failure must never change the run's terminal status — the
+   * hook itself is responsible for swallowing errors.
+   */
+  beforeFinish?: () => Promise<void>
 }
 
 /**
@@ -590,6 +606,14 @@ export async function drainHarnessToSink(
   sink: RunEventSink,
   opts: DrainOptions = {}
 ): Promise<TerminalStatus> {
+  // Run the pre-terminal hook (auto-harvest) at most once, right before the first
+  // finish() on any terminal path — while the sink is still writable.
+  let beforeFinishRan = false
+  const runBeforeFinish = async (): Promise<void> => {
+    if (beforeFinishRan) return
+    beforeFinishRan = true
+    if (opts.beforeFinish) await opts.beforeFinish()
+  }
   for await (const event of events) {
     if (event.kind === 'execution_complete') {
       // A prompt the caller/agent stopped is a cancellation, not a failure: the
@@ -597,6 +621,7 @@ 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', {
           summary: opts.summary,
           evidence: opts.evidence,
@@ -609,10 +634,12 @@ export async function drainHarnessToSink(
       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
     }
     if (event.kind === 'error') {
+      await runBeforeFinish()
       await sink.finish('failed', {
         summary: { ...(opts.summary ?? {}), error: event.payload.error ?? 'agent error' },
         evidence: opts.evidence,
@@ -624,6 +651,7 @@ export async function drainHarnessToSink(
   }
   // 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', {
     summary: { ...(opts.summary ?? {}), error: 'harness stream ended without a terminal event' },
     transcript: opts.transcript,

package/src/hosted-runtime-assets.ts

@@ -44,6 +44,37 @@ export const SETUP_HOOK_RELATIVE_PATH = '.orizu/setup.sh'
  */
 export const AGENT_GIT_IDENTITY = { name: 'Orizu Agent', email: 'agent@orizu.ai' } as const
 
+// -- Hosted task prompt scaffolding (ALI-1036) -------------------------------
+
+/**
+ * Standing preamble wrapped around every hosted task prompt so a NATURAL task
+ * ("review X and update the readme") runs unattended with zero magic words. The
+ * agent is told to work autonomously (never block on the human), commit as it
+ * goes, and treat Orizu — not the repo — as the home for production pointers and
+ * run metadata. An end-of-run auto-harvest (ALI-1036, `harvestWorkspace`) is the
+ * safety net for anything left uncommitted; the preamble names it so the agent
+ * knows partial work is preserved.
+ */
+export const HOSTED_TASK_PREAMBLE =
+  'You are running unattended in a hosted sandbox. Work autonomously: never ask the user ' +
+  'questions — when uncertain, choose the most reasonable/reversible option and note the ' +
+  'decision. Commit your work to the current branch in logical units as you go (an automatic ' +
+  'checkpoint will also save anything uncommitted at the end). Never switch branches. ' +
+  'Production/default pointers and run metadata live in Orizu, not this repo.'
+
+/** Delimiter separating the standing preamble from the verbatim user task. */
+export const HOSTED_TASK_DELIMITER = '--- YOUR TASK ---'
+
+/**
+ * Compose the full hosted prompt: the standing preamble, a clear delimiter, then
+ * the user's task VERBATIM beneath it. Passing an empty preamble yields the task
+ * unchanged (an explicit opt-out for tests / callers that scaffold elsewhere).
+ */
+export function composeHostedTaskPrompt(task: string, preamble: string = HOSTED_TASK_PREAMBLE): string {
+  if (!preamble) return task
+  return `${preamble}\n\n${HOSTED_TASK_DELIMITER}\n${task}`
+}
+
 // -- Pre-baked runtime marker (ALI-1017) -------------------------------------
 
 /**