# agrun.js — Distribution Docs

_This file is auto-generated by `npm run build`._

- Build ID: `ee53fdabf-dirty`
- Detailed docs are emitted under `agrun_docs/` next to this file.

## Bundled Sources

- `README.md`
- `agrun_docs/usage-quickstart.md`
- `agrun_docs/feature-toggles.md`
- `agrun_docs/host-deployment-profiles.md`
- `agrun_docs/public-runtime-api.md`
- `agrun_docs/result-schema.md`
- `agrun_docs/trace-json-contract.md`
- `agrun_docs/candidate-quality-signal.md`
- `agrun_docs/todo-state-integration.md`

## Start Here

**New to agrun.js?** Read [Usage Quickstart](agrun_docs/usage-quickstart.md) first — it covers what agrun.js is, core concepts, install, a real OpenAI-backed chatbot in ~25 lines, and common errors.

**Need to enable / disable a capability?** Read [Feature Toggles](agrun_docs/feature-toggles.md) — every supported on/off knob in one page.

**Looking up an option or callback?** Read [Public Runtime API](agrun_docs/public-runtime-api.md).

**Need the visual runtime flow?** Read [Flowchart](FLOWCHART.md).

**Parsing `result` in your UI?** Read [Result Schema](agrun_docs/result-schema.md).

## 10-Minute Path

1. Load `dist/agrun.js` in the browser.
2. Create a runtime with at least one skill.
3. Run one turn with `runtime.run()` or create a session first.
4. Add `createIndexedDBSessionStore()` when you need persistence.
5. Observe progress through `onStep`.
6. Handle `approval_required`, `result.error`, and `result.output`.

## Engineer Task Index

- Create runtime: [Public Runtime API](agrun_docs/public-runtime-api.md#runtime-creation)
- Run one turn: [Run Entry Contract](agrun_docs/public-runtime-api.md#run-entry-contract)
- Use sessions: [Session APIs](agrun_docs/public-runtime-api.md#session-apis)
- Persist with IndexedDB: [Usage Quickstart](agrun_docs/usage-quickstart.md#real-chatbot-openai-25-lines)
- Use OpenAI Responses API: [Usage Quickstart](agrun_docs/usage-quickstart.md#openai-responses-api)
- Disable memory: [Global Memory Configuration](agrun_docs/public-runtime-api.md#global-memory-configuration)
- Add web search: [Usage Quickstart](agrun_docs/usage-quickstart.md#add-web-search)
- Add approval gates: [Feature Toggles](agrun_docs/feature-toggles.md#action-policy-approval-gates)
- Observe events: [Result Schema](agrun_docs/result-schema.md#step-event-schema)
- Parse errors: [Result Schema](agrun_docs/result-schema.md#error-schema)
- Wire TodoState: [TodoState Integration](agrun_docs/todo-state-integration.md)

## Bundled Usage Docs

- [Usage Quickstart](agrun_docs/usage-quickstart.md) — `agrun_docs/usage-quickstart.md`
- [Feature Toggles](agrun_docs/feature-toggles.md) — `agrun_docs/feature-toggles.md`
- [Host Deployment Profiles](agrun_docs/host-deployment-profiles.md) — `agrun_docs/host-deployment-profiles.md`
- [Public Runtime API](agrun_docs/public-runtime-api.md) — `agrun_docs/public-runtime-api.md`
- [Result Schema](agrun_docs/result-schema.md) — `agrun_docs/result-schema.md`
- [Trace JSON Contract](agrun_docs/trace-json-contract.md) — `agrun_docs/trace-json-contract.md`
- [Candidate Quality Signal](agrun_docs/candidate-quality-signal.md) — `agrun_docs/candidate-quality-signal.md`
- [TodoState Integration](agrun_docs/todo-state-integration.md) — `agrun_docs/todo-state-integration.md`

## Full Docs Index

### Tutorials — learn by doing

Progressive, hand-held walkthroughs. Read these first if you are new.

- [Usage Quickstart](agrun_docs/usage-quickstart.md) — what agrun.js is, core concepts, install, 25-line chatbot, when to use what, common errors.

### How-to — task-oriented recipes

Ask "how do I X?"; scan the list.

- [Approval Flow](agrun_docs/approval-flow.md) — wire human-in-the-loop approval and resumption.
- [Testing Guide](agrun_docs/testing-guide.md) — test layers, running tests, neuter-verification, adding a test.
- [Standard Live E2E](agrun_docs/standard-live-e2e.md) — current executable four-scenario real-provider standard, roster, artifacts, and acceptance caveats.
- [Golden and Spike Testing](agrun_docs/golden-and-spike-testing.md) — deterministic Golden contracts, Spike experiments, paid matrix controls, cassette replay, and quality gates.
- [Web UI Integration Contract](agrun_docs/webui-integration-contract.md) — embed the runtime in a web UI.
- [Admin Workspace Skill Action Contract](agrun_docs/admin-workspace-skill-action-contract.md) — wire workspace runtime actions.
- [Admin Workspace Skill Source](agrun_docs/admin-workspace-skill-source.md) — source format for workspace skills.
- [Gemini Server Auth Proxy](agrun_docs/gemini-server-auth-proxy.md) — serve Gemini keys via proxy.
- [Development Secrets](agrun_docs/development-secrets.md) — local `.env.local` conventions.
- [Release Process](agrun_docs/release-process.md) — cut and publish a release.
- [Repo Hygiene](agrun_docs/repo-hygiene.md) — policy for generated artifacts and reference dirs (study-sources, agrun_debug_runs, output, tmp).
- [Repository Structure Governance Plan](agrun_docs/repository-structure-governance-plan.md) — phased Epic and acceptance contract for tests, runtime facades, study provenance, and artifact cleanup.
- [Distribution Bundle](agrun_docs/distribution-bundle.md) — what npm run build produces and how engineers consume dist/.
- [Long Task Lab Demo Design](agrun_docs/long-task-lab-demo.md) — PRD and implementation plan for a long-running task demo websystem.
- [Long Task Lab Record JSONL Plan](agrun_docs/long-task-lab-record-jsonl-plan.md) — IndexedDB record ledger and JSONL export/import plan for Long Task Lab.
- [Long Task Lab Demo Checklist](agrun_docs/long-task-lab-demo-checklist.md) — one-command Records demo and manual PWA/E2E checklist for Long Task Lab.
- [Host Deployment Profiles](agrun_docs/host-deployment-profiles.md) — host pattern for composing createRuntime options by deployment shape (demo/trusted/readonly) plus per-run disable.

### Reference — exact contracts

Look up an option, flag, schema, or API signature.

- [Feature Toggles](agrun_docs/feature-toggles.md) — every enable/disable flag in one place.
- [Public Runtime API](agrun_docs/public-runtime-api.md) — `createRuntime` / `runtime.run` / options / events.
- [Result Schema](agrun_docs/result-schema.md) — result object shape emitted by `runtime.run`.
- [Trace JSON Contract](agrun_docs/trace-json-contract.md) — live E2E trace contract for CLI and browser Inspector with OpenTelemetry-compatible spans.
- [Candidate Quality Signal](agrun_docs/candidate-quality-signal.md) — AI-first long-form candidate self-review action, objective candidateQualitySignal facts, publish behavior, and live debug checklist.
- [TodoState Integration](agrun_docs/todo-state-integration.md) — enable, configure, observe, and override the TodoState subsystem (5 actions, 7 config knobs, onStep events, debug helper).
- [Action Contract](agrun_docs/action-contract.md) — action schema and execution envelope.
- [AGRUN-274 Release/Export Audit](agrun_docs/audits/agrun-274-release-export-audit-2026-05-27.md) — AGRUN-274 release/export audit proving deleted Set A names are absent from src/dist public exports while provider adapters remain.
- [AGRUN-248-A Workspace Candidate Lifecycle](agrun_docs/audits/agrun-248-a-workspace-candidate-lifecycle.md) — AGRUN-248-A workspace candidate lifecycle state machine and candidate-path mismatch signal evidence.
- [Runtime Config + Permission Lifecycle Audit](agrun_docs/audits/runtime-config-permission-lifecycle-2026-05-24.md) — audit and first implementation slice for runtime config lifecycle and action permission metadata.
- [OpenAI Responses Empty Text Repair](agrun_docs/audits/openai-empty-response-repair-2026-05-25.md) — OpenAI Responses empty output repair lowers reasoning effort on retry without runtime-authored content.
- [AGRUN Test Import Seam](agrun_docs/audits/agrun-test-import-seam-2026-05-25.md) — Node source imports can load createRuntime without virtual module loader while dist/browser builds keep bundled skills and roles.
- [Deferred Architecture Backlog Review 2026-05-25](agrun_docs/audits/deferred-architecture-backlog-review-2026-05-25.md) — Step 6 review keeps deferred architecture backlog items blocked pending positive evidence or explicit product need.
- [AGRUN-246-J Structure Repair Hints](agrun_docs/audits/agrun-246-j-structure-repair-hints-2026-05-25.md) — AGRUN-246-J structure repair diagnostics preserve dotted section numbers and expose better normalize_headings repair hints.
- [AGRUN-246-J Workspace Repair Churn](agrun_docs/audits/agrun-246-j-workspace-repair-churn-2026-05-25.md) — AGRUN-246-J workspace repair churn hardening: heading-only normalize_headings patches can validate and apply in one action with applyIfValid.
- [AGRUN-246-K Source-Relevance Recovery Convergence (REJECTED)](agrun_docs/audits/agrun-246-k-source-relevance-recovery-convergence-2026-05-25.md) — AGRUN-246-K REJECTED 2026-05-25: read-phase consecutive-non-relevant convergence signal was built, unit-tested, and live-verified but the LLM did not pivot; rolled back. Wrong intervention point — the failure commits in the search phase.
- [AGRUN-246-L Search-Phase Query Diversification (REJECTED)](agrun_docs/audits/agrun-246-l-search-phase-query-diversification-2026-05-25.md) — AGRUN-246-L REJECTED 2026-05-25: search-phase queryAngle signal v1 (optional) had AI skipping the field, v2 (required:true) had AI declaring narrow same-cluster angles and worsening to 0/3 strict pass. Rolled back via git reset; both commits unpushed. Wrong-shape — needs orthogonality not diversity-count.
- [AGRUN-246-L Offline Query-Diversification Calibration](agrun_docs/audits/agrun-246-l-offline-calibration-2026-05-25.md) — AGRUN-246-L offline calibration rejects pure token-overlap and topic-anchor hardcoding; recommends AI-declared queryAngle/queryIntent diversity as the next no-runtime-code implementation shape.
- [AGRUN-246-N Orthogonality Lever Research](agrun_docs/audits/agrun-246-n-orthogonality-lever-research-2026-05-25.md) — AGRUN-246-N research opens after AGRUN-246-L rejection. Reviews O-Researcher / GPT Researcher / Anthropic multi-agent / query fan-out prior art and recommends upfront search plan + offline-calibrated orthogonality verifier. Calibration on 16-trace corpus (7 246-K + 6 246-L v1/v2 + 3 extras) gives CONDITIONAL PASS: Latin token Jaccard >= 0.556 on the >=3 query subset cleanly separates source_fail from strict_pass with the 1 ambiguous trace tolerated. Tool-shape change must enforce minCount=3 for verifier to be sufficient. Phase 2 (design + simulator + >=5 trace live verify) gated by this Phase 1 calibration result..
- [AGRUN-246-M Source Relevance Scorer Permissiveness](agrun_docs/audits/agrun-246-m-source-relevance-scorer-permissiveness-2026-05-25.md) — AGRUN-246-M closes the deferred wikipedia-scorer permissiveness flagged by AGRUN-246-K rerun5. Root cause: the fallback overlap >= 2 path in read-source-quality.js used substring .includes() with no length normalization, so a 118 kB Wikipedia general-topic page trivially cleared the bar via 2 common token hits diluted across the body. Fix: distinctive-token density gate in the fallback usable path. Requires at least one distinctive token in body AND density (distinctive hits per kB) >= 0.1, with fallback to the legacy gate when the query has zero distinctive tokens. No domain-specific allowlists, no taxonomy, no LLM call. 8 unit tests pass including 3 new AGRUN-246-M regressions. npm run build + full npm test + dist check pass..
- [Cross-Model Baseline PAUSED 2026-05-25](agrun_docs/audits/agrun-cross-model-baseline-paused-2026-05-25.md) — Cross-model baseline PAUSED checkpoint 2026-05-25. After AGRUN-246-N Phase 2 rejection, next direction was to measure runtime production-readiness across the model x thinking-level matrix (openai gpt-5-mini, gemini-3.1-flash-lite low/high, optional 2.5-flash/2.5-pro) x 3 traces each. Partial data: openai/gpt-5-mini trace 1 STRICT PASS 100 (3021 cjk, 3-relevant sources), trace 2 partial 75 (3158 cjk, source-gate fail with 7 reads), trace 3 interrupted by user laptop battery pause. flash-lite low trace 1 interrupted. Repo state preserved (HEAD 8abb8c19c pushed), background tasks stopped via TaskStop, audit includes exact resume entrypoints. Early signal: capable-model traces look fine, supporting the strategic claim that the AGRUN-246 saga 43% ceiling is a flash-lite limit not a runtime limit..
- [AGRUN-246-N Phase 2 Tool-Shape Design + Simulator Gate](agrun_docs/audits/agrun-246-n-tool-shape-design-2026-05-25.md) — AGRUN-246-N Phase 2 tool-shape design + simulator gate. Specifies web_search extension to accept Mode B searchPlan (array of {query, aspect} entries, minCount=3, maxCount=8) plus an orthogonality verifier preflight (Latin token Jaccard with calibrated threshold 0.556 from Phase 1) and structured planRejected diagnostic envelope with retry budget=2. Simulator (scripts/simulate-agrun-246-n-search-plan.mjs) hits gemini-3.1-flash-lite REST endpoint directly with the proposed Mode B argsExample injected into a cold-start planner prompt. 10/10 trials across two batches PASS: Mode B emission rate 100%, orthogonality rate 100%, overall pass rate 100%. Max pairwise Jaccard ranged 0.154-0.400, well below the 0.556 threshold. Phase 2 implementation authorized; live verify gate (>=5 traces) remains mandatory before commit..
- [AGRUN Codeloom Test/ADR Contract Review](agrun_docs/audits/agrun-codeloom-test-adr-contract-review-2026-05-25.md) — Current review closes stale Codeloom test/ADR contract-file todo with before-finalize helper moved and improvement reflection kept.
- [Repo/File Write Tools Design](agrun_docs/repo-file-write-tools-design.md) — future real file mutation tools boundary: preview, approval, patch digest.
- [Agent Skills](agrun_docs/agent-skills.md) — built-in skills and their contracts.
- [Authoring Host Actions and Skills](agrun_docs/authoring-skills.md) — current custom action authoring contract and the unimplemented defineSkill registration boundary.
- [Provider Registry](agrun_docs/provider-registry-design.md) — implemented custom provider registry contract and compatibility boundary.

### Explanation — why the system is shaped this way

Read these before changing a subsystem.

- [Design Overview](agrun_docs/governance/DESIGN.md) — root governance view of implemented opt-in composition and acceptance-gated default direction.
- [Current Product Specification](agrun_docs/governance/SPEC.md) — root current-product requirements and non-goals, excluding unimplemented proposed APIs.
- [Epic Portfolio](agrun_docs/governance/EPIC.md) — active epic portfolio, dependencies, proposed interfaces, and acceptance gates.
- [Roadmap](agrun_docs/governance/ROADMAP.md) — current Now/Next/Later delivery view and 4.x-to-5.0 compatibility policy.
- [Task Board](agrun_docs/governance/TASK.md) — generated current task projection from task.jsonl.
- [Architecture SSOT](agrun_docs/architecture-ssot.md) — authority order for committed code/tests, task.jsonl, ADRs, contracts, governance views, evidence, and generated artifacts.
- [AI-First Self Check](agrun_docs/ai-first-self-check.md) — the WHO-DECIDES litmus: forbidden push-mode vs allowed harness gates, code anchors, and a pre-merge checklist to run before changing `src/runtime/`.
- [Spec](agrun_docs/spec.md) — top-level architecture and design principles.
- [Workspace Edit Harness Design](agrun_docs/workspace-edit-harness-design.md) — research-backed boundary for workspace propose/apply patch tools and normalize_headings.
- [MVP](agrun_docs/mvp.md) — MVP scope and intentional cuts.
- [Agentic Execution Flow](agrun_docs/agentic-execution-flow.md) — end-to-end OODAE loop walkthrough.
- [Multi-Agent](agrun_docs/multi-agent.md) — multi-agent orchestration: handoff_to_skill vs spawn_subagent vs use_agent_skill, safety boundaries, and SDK comparison.
- [Planner Architecture](agrun_docs/planner-architecture.md) — planner, repair cascade, guardrails.
- [Native Tools Readiness](agrun_docs/native-tools-readiness.md) — native tools default-readiness matrix, blockers, and test evidence.
- [Runtime Internal Architecture](agrun_docs/runtime-internal-architecture.md) — state pipeline internals.
- [Runtime State and Memory Architecture](agrun_docs/runtime-state-and-memory-architecture.md) — persistence, compaction, global memory policy.
- [Evidence Graph Memory Architecture](agrun_docs/evidence-graph-memory-architecture.md) — tier classification and provenance.
- [Context and Continuity Model](agrun_docs/context-and-continuity-model.md) — context snapshots, inquiry context, research continuity.
- [Research and Evidence Model](agrun_docs/research-and-evidence-model.md) — web search, URL reading, evidence tiers.
- [Skill System Architecture](agrun_docs/skill-system-architecture.md) — tool provisioning and scope.
- [Agent Harness Runtime Patterns](agrun_docs/agent-harness-runtime-patterns.md) — runtime harness patterns mapped to AGRUN-213/214 roadmap slices.
- [Error Handling and Recovery](agrun_docs/error-handling-and-recovery.md) — structured errors, failure modes, recovery.
- [Long-Running Multi-Topic Tasks](agrun_docs/long-running-multi-topic-tasks.md) — thread isolation and topic routing design.
- [Anthropic Long-Running Agent Research](agrun_docs/anthropic-long-run-agent-research.md) — Anthropic long-running agent patterns (Initializer/Coding split, Ralph Loop, ACI, multi-agent) and agrun gap analysis.
- [Hermes Long-Running Agent Research](agrun_docs/hermes-long-running-agent-research.md) — Hermes agent long-running mechanisms (SQLite WAL, session lineage, auxiliary LLM compaction, stateful SSE scrubbers, self-registering tools) and agrun gap analysis.
- [Learnings from Sample Projects](agrun_docs/learnings-from-sample-projects.md) — patterns distilled from reference projects.
- [Sample Reference Guide](agrun_docs/sample-reference-guide.md) — index of sample projects under study.
- [OpenClaw agrun Mapping](agrun_docs/openclaw-agrun-mapping.md) — conceptual mapping to OpenClaw.
- [Documentation Classification SSOT](agrun_docs/docs-classification-ssot.md) — active vs learning vs historical documentation boundaries for SSOT cleanup.
- [Docs Bundle Design](agrun_docs/docs-bundle-design.md) — design for making generated dist documentation easier to scan by task and feature.
- [Observability, Node Live Timing, and Gemini Thinking Research](agrun_docs/observability-otel-gemini-thinking-research.md) — OTel adapter direction, Node live timing facts, and Gemini thinking controls for workspace-tool debugging.

### Decisions — architecture decision records

One decision per file. Start with the guide.

- [ADR README](agrun_docs/adr/README.md) — when and how to write an ADR.
- [ADR Template](agrun_docs/adr/_template.md) — ADR skeleton.
- [ADR 0001 Runtime Hardening Batch](agrun_docs/adr/0001-runtime-hardening-batch.md) — JSON parsing, IndexedDB resilience, approval signing, sensitive content filtering.
- [ADR 0002 Long-Running Multi-Topic Architecture](agrun_docs/adr/0002-long-running-multi-topic-architecture.md) — threadId scoping, topic router, evidence filtering.
- [ADR 0003 Native Tools Default Readiness](agrun_docs/adr/0003-native-tools-default-readiness.md) — native_tools default decision, envelope opt-out, and provider caveats. **Superseded by ADR-0031 (2026-05-16)**.
- [ADR 0031 Envelope Is Default Planner Mode](agrun_docs/adr/0031-envelope-is-default-planner-mode.md) — historical envelope-default decision after Gemini-side instability; superseded by ADR-0058.
- [ADR 0057 Deferred Action Loading](agrun_docs/adr/0057-deferred-action-loading.md) — deferred action namespaces as an opt-in prompt-size mechanism.
- [ADR 0058 Native Tools Default Planner Mode](agrun_docs/adr/0058-native-tools-default-planner-mode.md) — native_tools is the measured default with envelope fallback and explicit opt-out.
- [ADR 0059 Dist Is Generated Release Artifact](agrun_docs/adr/0059-dist-is-generated-release-artifact.md) — dist is generated and Git-ignored; package publication rebuilds and enforces a dist-only payload.
- [ADR 0061 Citation Contract Review Budget](agrun_docs/adr/0061-citation-contract-review-budget.md) — host-declared citation minimum stays non-blocking; its terminal review becomes a bounded repeatable budget with once-only depth semantics preserved.
- [ADR 0060 Composable Fast Runtime](agrun_docs/adr/0060-composable-fast-runtime.md) — read-only observability plus opt-in minimal/plugin composition implemented; provider and default-promotion gates remain.

### Release notes

Per-version change summaries. See [CHANGELOG.md](CHANGELOG.md) for the aggregated list.

- [Release Notes v0.2.0](agrun_docs/release-notes-v0.2.0.md) — v0.2.0 release notes.
- [Release Notes v0.2.0 rc.2](agrun_docs/release-notes-v0.2.0-rc.2.md) — v0.2.0 rc.2 release notes.
- [Release Notes v0.2.0 rc.1](agrun_docs/release-notes-v0.2.0-rc.1.md) — v0.2.0 rc.1 release notes.

### Live-test evidence

MCP Chrome / browser-runtime verification runs. Each file is a single-scoped run with scope-statement.

- [AGRUN-656 Short Direct-Terminal Contract Convergence 2026-07-31](agrun_docs/live-tests/agrun-656-short-direct-terminal-contract-convergence-2026-07-31.md) — One host-declared advisory review converges short direct answers and preserves read-backed citation integrity across three providers.
- [AGRUN-655 Standard Live Quality Parity 2026-07-31](agrun_docs/live-tests/agrun-655-standard-live-quality-parity-2026-07-31.md) — Standard Live grades delivered direct answers instead of empty seeded workspace stats while preserving strict real quality failures.
- [AGRUN-654 Bounded Runtime Retention 2026-07-30](agrun_docs/live-tests/agrun-654-bounded-runtime-retention-2026-07-30.md) — Bounded debug/event history prevents the 161-read heap failure without dropping onStep delivery or current semantic state.
- [AGRUN-653 Unique Evidence Convergence 2026-07-30](agrun_docs/live-tests/agrun-653-unique-evidence-convergence-2026-07-30.md) — Normalized URL identities retain strongest read evidence and make repeated reads converge without false progress.
- [AGRUN-652 Canonical Citation Parity 2026-07-30](agrun_docs/live-tests/agrun-652-canonical-citation-parity-2026-07-30.md) — Numeric references now retain canonical read-backed Sources through candidate, terminal, and delivered audits.
- [AGRUN-673/674 Validation Matrix 2026-07-31](agrun_docs/live-tests/agrun-673-674-validation-matrix-2026-07-31.md) — 673 validated live: OpenAI's planner-door delivery ships all 4 citations (was 2/3 with a disclosure); new AGRUN-676 stale candidate flag found and fixed in the same round; only remaining OpenAI miss is word count (n=1, unticketed).
- [AGRUN-669 All-Fixes Matrix 2026-07-31](agrun_docs/live-tests/agrun-669-all-fixes-matrix-2026-07-31.md) — First all-fixes matrix: aggregate flat at 5/9, two new mechanisms found (citation review bypassed by terminal-repair escape; literal backslash-n surviving into delivered text), neither caused by 669/670.
- [AGRUN-668 Clean Measurement Matrix 2026-07-31](agrun_docs/live-tests/agrun-668-clean-measurement-matrix-2026-07-31.md) — Twelve-cell matrix after 667/668: Gemini reaches 3/3 for the first time in the arc; OpenAI's two misses are exactly the AGRUN-669/670 mechanisms implemented right after.
- [AGRUN-662 ADR-0061 Validation Matrix 2026-07-31](agrun_docs/live-tests/agrun-662-adr-0061-validation-matrix-2026-07-31.md) — ADR-0061 validation: OpenAI citation delivery 0->3/3/3 with a first-ever strict pass; every remaining failure individually named.
- [AGRUN-666 Fix Matrix Rerun 2026-07-31](agrun_docs/live-tests/agrun-666-fix-matrix-rerun-2026-07-31.md) — Twelve-cell rerun on the fixed bundle: strict 5/9 (was 4/9), Gemini runaway closed, one failure mode left — OpenAI citation delivery, owned by ADR-0061.
- [AGRUN-657 Long Acceptance Matrix 2026-07-31](agrun_docs/live-tests/agrun-657-long-acceptance-matrix-2026-07-31.md) — Twelve formal long-task cells reject acceptance a second time; five of six failures are citation-delivery, not content.
- [AGRUN-657 Long Acceptance Smoke 2026-07-31](agrun_docs/live-tests/agrun-657-long-acceptance-smoke-2026-07-31.md) — One-trial-per-cell long-task smoke shows movement since the AGRUN-651 rejection and finds a nested-sub-section structure-gate false positive.
- [AGRUN-651 Three-Provider Long Acceptance 2026-07-30](agrun_docs/live-tests/agrun-651-three-provider-long-acceptance-2026-07-30.md) — Repeated three-provider long-task evidence rejects acceptance and scopes source parity, repeat-read, and memory follow-ups.
- [AGRUN-650 Approximate-Length Contract 2026-07-30](agrun_docs/live-tests/agrun-650-approximate-length-contract-2026-07-30.md) — One requested-length SSOT keeps approximate targets AI-owned while preserving exact and minimum hard gates.
- [AGRUN-649 Provider-Adjusted Live SLO 2026-07-30](agrun_docs/live-tests/agrun-649-provider-adjusted-slo-2026-07-30.md) — Provider-adjusted live SLO separates external latency, controllable overhead, and grouped workspace no-progress outcomes.
- [AGRUN-624 Live SLO Reassessment 2026-07-30](agrun_docs/live-tests/agrun-624-live-slo-reassessment-2026-07-30.md) — Trace-backed SLO reassessment separates provider latency, workspace convergence, and long-task source acceptance.
- [AGRUN-648 Composable Runtime Acceptance 2026-07-30](agrun_docs/live-tests/agrun-648-composition-acceptance-2026-07-30.md) — Three-provider repeated cold/warm fail-fast matrix rejects a 5.0 minimal-profile default while retaining opt-in composition.
- [Live Quality Smoke Multi-turn Report 2026-06-14](agrun_docs/live-tests/live-quality-smoke-multiturn-report-2026-06-14.md) — Live quality smoke covering direct single-shot, tool single-shot, multi-turn direct chat, and a Gemini 1500-word Harness Engineering report; found memory extraction overhead, time hallucination without host clock, cited-unread URLs, repeated semantic sections, and long-report tail inefficiency.
- [AGRUN-294D No-web Host Evidence Live 2026-05-28](agrun_docs/live-tests/agrun-294d-no-web-host-evidence-live-2026-05-28.md) — AGRUN-294D no-web host evidence live E2E; OpenAI gpt-5-mini high reasoning and Gemini 3.1 flash-lite high thinking both used host_data_query and workspace publish with successfulEvidenceCount=1, successfulReadUrlCount=0, no web_search/read_url, and monotonic runtime event sequences.
- [AGRUN-246-J Source Structure Closeout 2026-05-25](agrun_docs/live-tests/agrun-246-j-source-structure-closeout-2026-05-25.md) — AGRUN-246-J canonical Mandarin closeout; mixed-script source relevance, exact-phrase search, source minimum, and structure repair now pass with qualityScore 100, with churn HBR.
- [AGRUN-246-L Verify Rejected 2026-05-25](agrun_docs/live-tests/agrun-246-l-verify-rejected-2026-05-25.md) — AGRUN-246-L verify rejected 2026-05-25 across 2 live batches; v1 optional queryAngle 1/3 strict pass with field skipped, v2 required:true 0/3 strict pass with AI declaring narrow same-cluster angles; reset --hard af6f105ba; lesson: required structured fields with no semantic-orthogonality constraint amplify the bias they were meant to catch.
- [AGRUN-246-N Phase 2 Verify Rejected 2026-05-25](agrun_docs/live-tests/agrun-246-n-phase-2-verify-rejected-2026-05-25.md) — AGRUN-246-N Phase 2 implementation rejected 2026-05-25 at live verify gate. Built per design audit and simulator PASS (10/10), 17 unit tests green, but 5-trace canonical Mandarin live verify on gemini-3.1-flash-lite produced 0/5 strict pass (median qualityScore 29) vs pre-change baseline 3/7 = 43%. Verifier mechanism worked correctly (4/5 Mode B emission, 0 rejections - plans already orthogonal with max Jaccard 0.091-0.400). Diagnosis: Mode B atomicity (N queries in 1 action) condensed the AI search phase, reducing total evidence accumulation. Rollback via git reset --hard 689358c50; commit 09f2d62a4 dropped, never pushed. Lesson: simulator PASS measuring first-envelope emission does NOT predict multi-cycle loop dynamics..
- [AGRUN-246-K Verify Rejected 2026-05-25](agrun_docs/live-tests/agrun-246-k-verify-rejected-2026-05-25.md) — AGRUN-246-K verify attempt rejected after 3 live reruns: convergence signal mechanism worked and reached the prompt at elevated state, but the LLM did not pivot; worst trace got worse (26 reads vs 18 baseline). Code rolled back; AGRUN-246-L opened for the right lever.
- [AGRUN-246-K Distribution Sampling 6-trace 2026-05-25](agrun_docs/live-tests/agrun-246-k-distribution-sampling-2026-05-25.md) — AGRUN-246-K 6-trace distribution sampling on canonical Mandarin Gemini flash-lite; source-fail rate 3 of 7, all failing runs read 16-18 URLs with 15-17 consecutive non-relevant streak after one early harness.io hit; data-backed threshold proposal 3.
- [AGRUN-246-J Workspace Repair Churn 3-Trace Live Distribution 2026-05-25](agrun_docs/live-tests/agrun-246-j-workspace-repair-churn-live-rerun-2026-05-25.md) — AGRUN-246-J 3-trace canonical Mandarin live distribution measuring applyIfValid impact; propose+apply pair cycles collapse to 3 when AI uses it, but total planner cycles stay flat on average (37.7 vs 39) and 1 of 3 runs failed source gate.
- [Workspace Multi Edit Cycle Delta 2026-05-25](agrun_docs/live-tests/workspace-multi-edit-cycle-delta-2026-05-25/SUMMARY.md) — Workspace multi_edit cycle-delta live evidence gate; gemini flash-lite used multi_edit in variant but baseline failed to complete, so workspace_diff remains deferred.
- [Report Output Quality Regression Synthesis 2026-05-25](agrun_docs/live-tests/report-output-quality-regression-synthesis-2026-05-25.md) — Report-quality synthesis across AGRUN-246-J and Long Task Lab HBRs; blocked structure patch previews no longer re-open propose loops under hard veto.
- [AGRUN-246-J Current HEAD Mandarin Rerun 2026-05-25](agrun_docs/live-tests/agrun-246-j-current-head-rerun-2026-05-25.md) — AGRUN-246-J current HEAD Mandarin flash-lite rerun; length/source gates passed but structure quality still failed.
- [AGRUN-246-J Post Structure Hints Rerun 2026-05-25](agrun_docs/live-tests/agrun-246-j-post-structure-hints-rerun-2026-05-25.md) — AGRUN-246-J post-structure-hints Mandarin rerun; action-surface fix recovers length but source relevance and structure still fail.
- [AGRUN-246-J Mandarin Post-249 Retest 2026-05-24](agrun_docs/live-tests/agrun-246-j-mandarin-post-249-2026-05-24.md) — AGRUN-246-J canonical Mandarin flash-lite post-249/250/251 close-out retest; path discipline improved but strict user quality gate still failed.
- [AGRUN-252 Todo Publish Readiness Churn 2026-05-24](agrun_docs/live-tests/agrun-252-todo-publish-readiness-churn-2026-05-24.md) — AGRUN-252 Todo publish readiness churn guard; Todo-only repair syncs TodoState before publish while budget remains and OpenAI live rerun reduced publish attempts.
- [AGRUN-251 Late-Budget Protocol Window 2026-05-24](agrun_docs/live-tests/agrun-251-late-budget-protocol-window-2026-05-24.md) — AGRUN-251 late-budget protocol guard for blocking impossible final-cycle workspace mutations while preserving explicit finalize/read/publish.
- [AGRUN-250 Terminal Churn 2026-05-24](agrun_docs/live-tests/agrun-250-terminal-churn-2026-05-24.md) — AGRUN-250 terminal churn follow-up for readiness-only publish retry, structured readiness mismatch issues, and CJK-aware length growth guard.
- [AGRUN-249 After Trace 2026-05-24](agrun_docs/live-tests/agrun-249-after-trace-2026-05-24.md) — AGRUN-249 after-trace evidence for long-form expansion, structure repair, CJK length contract, flash-lite English/Mandarin passes, and OpenAI capable regression.
- [Long Task Lab Debug Diagnosis 2026-05-21](agrun_docs/live-tests/long-task-lab-debug-diagnosis-2026-05-21.md) — Long Task Lab Debug Inspector Agent Limitation Diagnosis for evidence gate failures, source issue counts, repeated query detection, and Chrome DevTools UI proof.
- [Long Task Lab Default TNO Rerun 2026-05-21](agrun_docs/live-tests/long-task-lab-default-tno-rerun-2026-05-21.md) — Full Chrome DevTools MCP rerun of Default-provider TNO 3000-word mission after source-link guard; completion/source links passed but evidence quality kept score at 75/100.
- [Long Task Lab Default TNO Source Links 2026-05-21](agrun_docs/live-tests/long-task-lab-default-tno-source-links-2026-05-21.md) — Long Task Lab Default-provider TNO 3000-word result review, workspace publish source-link guard, citations output, and quality HBR.
- [Long Task Lab Default Provider Gateway 2026-05-21](agrun_docs/live-tests/long-task-lab-default-provider-gateway-2026-05-21.md) — Long Task Lab Default provider uses the owner GPT gateway as hidden local-dev config, hides model/key UI, redacts gw_ keys, and rejects XOR hardcoded frontend secrets.
- [Long Task Lab Read URL Connection Debug 2026-05-21](agrun_docs/live-tests/long-task-lab-readurl-connection-debug-2026-05-21.md) — Long Task Lab Test read_url button, Debug Read URL auth/status metric, and Chrome DevTools live POST /read-url 200 proof.
- [Long Task Lab Read URL API Key Input 2026-05-21](agrun_docs/live-tests/long-task-lab-readurl-api-key-input-2026-05-21.md) — Long Task Lab Read URL API key input, non-blocking authenticated-endpoint warning, secret-safe storage proof, and XOR hardcode rejection.
- [Long Task Lab Quality Score And Read URL Fallback 2026-05-21](agrun_docs/live-tests/long-task-lab-quality-score-readurl-fallback-2026-05-21.md) — Long Task Lab quality scoring panel, Debug quality metric, opt-in alternate read_url fallback, and Chrome DevTools UI proof.
- [Long Task Lab TNO 3000-Word Report 2026-05-21](agrun_docs/live-tests/long-task-lab-tno-3000-report-2026-05-21.md) — Chrome DevTools MCP real OpenAI Long Task Lab run for a 3000-word TNO Systems PTE LTD report; completed through workspace publish with 3149 inspector words and source-quality HBR.
- [Long Task Lab Current Agent Inspector 2026-05-21](agrun_docs/live-tests/long-task-lab-current-agent-inspector-2026-05-21.md) — Long Task Lab Debug tab Current Agent Activity, API exchange records, custom-provider timeout propagation, and Chrome DevTools completion proof.
- [Node 3000 Gemini Flash-Lite Workspace Patch 2026-05-20](agrun_docs/live-tests/node-agrun-3000-gemini-flash-lite-workspace-patch-2026-05-20.md) — Node 3000-word live evidence for workspace patch redirect, normalize_headings, Flash-Lite limited publish, and Gemini 3.5 ready control.
- [Browser Read URL Live Smoke 2026-05-01](agrun_docs/live-tests/browser-read-url-live-smoke-2026-05-01.md) — Browser read_url service live smoke verifies Network POST /read-url 200 and Healthy Run Inspector classification.
- [Native Tools Readiness 2026-04-29](agrun_docs/live-tests/native-tools-readiness-2026-04-29.md) — AGRUN-213e native tools default-readiness live provider checklist.
- [AGRUN-145 Slice D Browser Smoke](agrun_docs/live-tests/agrun-145-slice-d-browser-smoke.md) — AGRUN-145 thread-aware compaction harness executes identically in Chromium via Vite ESM.
- [AGRUN-146 Drift Detector Browser Smoke](agrun_docs/live-tests/agrun-146-drift-detector-browser-smoke.md) — AGRUN-146 goal-drift detector and pluggable `similarityFn` behave identically in Chromium via Vite ESM.
- [AGRUN-142 Goal Anchor Browser Smoke](agrun_docs/live-tests/agrun-142-goal-anchor-browser-smoke.md) — AGRUN-142 three-layer goal-anchor harness behaves identically in Chromium via Vite ESM.

### Archive — historical, superseded

Historical or superseded material kept for context.

- [LLM-first Runtime Refactor Plan](agrun_docs/llm-first-runtime-refactor-plan.md) — superseded plan kept for archive context.
- [Task Board Archive 2026-04-25](agrun_docs/archive/task-board-archive-2026-04-25.md) — task board history before 2026-04-25 cleanup.

## Compatibility Note

`dist/agrun.md` used to concatenate the full guide. It is now a short navigation page; the detailed generated files live in `dist/agrun_docs/`.