feat(core): give unattended runs an explicit approval policy

[oratis]

Summary

PR 0 of docs/FLOATBOAT_ADOPTION_PLAN.md §4 — the one slice that is an independent security fix and depends on nothing else in that plan.

Scheduled jobs and headless CI runs have no approver, but the loop expressed that only as a missing approval callback. runHeadless already installs approval: async () => false, so "no callback" and "no human" were never the same question — and the resulting refusal read as the generic requires approval, which in an unattended log looks transient when it is in fact terminal.

runAgent now takes two options:

Option	Meaning
unattended	Stated by the host, not inferred from a missing callback
onApprovalRequired	deny (default) refuses the call and continues — exactly what every host did before. abort stops the run with stopReason: 'blocked', exit code 6

abort is the option that didn't exist. A job whose first write is refused otherwise keeps looping against a wall, burns tokens, and reports a confidently wrong result.

Correctly scoped, per the plan

The plan claimed unattended runs might "silently allow". That was wrong and I'm not shipping it as written — the ask path already fails closed. What's actually missing is (a) the ability to stop rather than limp on, and (b) visibility. Both are here.

The real inherited-permission problem is narrower and stated honestly below.

Two things found while wiring it up

1. Unattended runs inherit permissions.defaultMode. A bypassPermissions set for interactive convenience silently becomes the posture of every 3am job. Headless now warns when the mode is inherited from settings rather than passed for this run (--mode is a deliberate per-run choice, so it stays quiet). The clamp itself is not in this PR — it needs TriggerProfile to exist as the opt-in, so it lands with PR 7 and will be marked breaking there.

2. Aborting mid-batch left tool_use blocks unanswered. A provider rejects that message sequence on resume. Tool results now flush through one helper that synthesizes "Tool call not executed: the run stopped before reaching it." for the remainder. This was caught by a test that asserted the transcript explains why the run stopped — it didn't, at first.

Drive-by doc fix

docs/cli-flags.md's exit-code table contradicted the implementation: it listed 3 as "Tool denied by permissions" and 5 as "API key invalid", and called 3–5 "reserved for M3+". The code and docs/quickstart.md have always said 3 api/provider · 4 max-turns · 5 aborted. Corrected to match apps/cli/src/headless.ts, which owns the contract, since I'm adding 6 to that same table.

Test plan

• pnpm test — 1173 passed, 16 skipped (was 1156 + 16; +9 core, +8 cron)
• pnpm typecheck · pnpm lint (--max-warnings=0) · pnpm format:check · pnpm build
• node scripts/check-docs.mjs

New coverage:

Test	Asserts
deny is the default	Call refused, run continues, reason says unattended
abort stops the run	stopReason: 'blocked', and the refusal is still in history
abort is inert when nothing needs approval	No false positives
Attended runs untouched	The approval callback is still consulted
resolveUnattendedApproval defaults	Jobs stored before the field keep deny
Hand-edited typo in cron.json	'ABORT' falls back to deny, never widens
Store round-trip	An explicit abort survives save/load

Documentation

• Updated docs/quickstart.md — new Scheduled jobs section covering the policy table and the inherited-defaultMode caveat
• Updated docs/cli-flags.md — exit-code table corrected + 6 added

Release notes label

• release-notes:feature — new onApprovalRequired option and exit code 6; the default preserves existing behaviour, so nothing breaks

Checklist

• PR 标题是 conventional commits 格式
• 所有 commits 都是 conventional commits 格式
• 添加了对应测试
• CI 全绿（待 CI 运行）

Related

Plan: docs/FLOATBOAT_ADOPTION_PLAN.md §2.E / §4 (PR 0). Research: docs/research/floatboat.md §3.1(a).

🤖 Generated with Claude Code