Skip to content
Chapter 4 · How it works 4-3

Harness implementation

Current reference. System ownership · Domain glossary · Tool policy.

Subagent apply and inspection share a lock keyed by root run. Operations on the same root remain ordered; independent roots can proceed concurrently. Canceled waiters release their lock references, and idle keys leave the lock table.

Cancel validates the transition before stopping live tools, then rereads the durable run because shutdown may let the worker commit progress. It preserves already terminal results and retries version conflicts up to eight times without repeating tool shutdown; exhausted contention still reports commit_conflict.

A root run's selection is pinned when its base context is captured, to size the handoff and choose native continuation (waiting at most five seconds; a selection that cannot be resolved then is pinned at the first model step instead). The Host validates model/reasoning against that catalog at the first model step. Settings changes after the selection is pinned affect the next run. That new root run also captures a bounded Session Run Handoff from up to four earlier terminal roots in the same session/workspace, so a different model can see work performed before Stop even without a final assistant reply. The loaded conversation snapshot supplies the eligible user-message source run IDs; rewound/pruned runs and legacy unattributed messages cannot introduce a handoff. A SQLite read snapshot binds the source runs, model-visible payloads and receipts; the rendered handoff is encrypted with the new run's once-only base context. It is a separate, charged history turn and cannot silently fall out of native history fitting. At most 48 recent entries per source plus its original request and bounded applicable summaries are read, with a 128 KiB per-payload and 2 MiB aggregate read cap; the final portable text takes a tenth of the pinned model's published window (three characters per token, between 16,000 and 400,000 characters; 16,000 when the window is assumed), and the entry count (up to 384) and excerpt clips scale with it. Base capture resolves the run's pin to learn the window. Excerpts and omissions are explicit. Up to four recent compaction records per source supply applicable summaries, prioritizing newer summaries and reporting omitted older coverage. Separate Host-authored directory hints preserve instruction discovery; quoted text cannot supply them. Only root run-local evidence is eligible: completed conversation turns remain in the existing 32-turn base, and old base snapshots are never copied recursively. Assistant statements/proposals remain untrusted quoted text. Receipt outcomes retain provenance; missing receipts or interrupted effects must be checked before repeating a mutation. Native provider continuation, audit-only bytes, child-private history, credentials and approval state are excluded. See ADR 0023. A run under the same model as the newest source continues it natively instead; see Native Continuation. The typed step service rejects missing/invalid snapshots and strips untrusted reasoning fields. The Host reads credentials directly from its own store, so no per-step handoff file exists. New runs receive an unselected pin row atomically; any retained run without a selection fails closed as provider_selection_missing, rather than adopting current settings. There is no retry with another provider, model, key or protocol. Ordinary requests use the pinned reasoning options, with the truncation-recovery exception described in provider execution: the declared lowest effort is used only for a pending truncation repair, then ordinary requests restore the selected effort.

The schema retains a bounded session-workspace lookup index and typed run-model metadata; unknown historical context windows remain unknown. Migration executes and drains every SQL result before advancing user_version, inside the same transaction; any late statement failure rolls back the entire upgrade. This explicit drain is needed because the pinned Microsoft.Data.Sqlite 10.0.11 implementation disposes the reader in ExecuteNonQuery, which can suppress errors from later batch statements. Release migration tests build the original released v18 DDL and frozen development DDL independently of current schema creation. The selected upgrade suffix commits atomically at v38. Version 29 consolidated earlier development changes; v30 normalizes retained conversation history and source receipts. Version 31 adds context mutation fences and indexed compaction/intent lookup; v32 indexes exact execution-request provenance. The schema keeps this index, but verification no longer reads the workspace journal. Version 33 adds agent_run_provider_intents: an optional provider/model choice inserted in the same transaction as its root run, without credentials or permission grants. Explicit intent participates in request idempotency identity and constrains the initial provider pin; existing pins and legacy runs retain their prior behavior. Version 34 records delivery provenance on source receipts and keeps image attachment counts with retained messages. Rewind acknowledges late replies to removed prompts without appending them. Forks copy the attachment counts so context survives deletion of the source run. Version 35 raises the subagent family budget bounds; version 36 makes those counters unbounded for the root's current window; version 37 removes the default ceiling on concurrent runs in one workspace while keeping a user-chosen cap (0 means no cap). Version 38 adds agent_session_advisors, the advisor each session's new root runs pin (ADR 0047; no row means none, and the row is deleted with the session). Versions below v18 fail with harness_schema_incompatible before any owned data is changed. Development v19-v36 databases remain eligible sources; adding a migration extends one ordered catalog instead of every historical branch. Fresh installs use the same released baseline and upgrade batch. Tests cover every retained source, identical schema, rollback/retry, restored FKs and two simultaneous initializer processes. A partial run/kind/sequence index supports bounded provider continuation rehydration. A partial session-receipt index supports a freshness query that compares canonical receipt event order with the encrypted state source. A newer receipt that could not be represented because of a bounded reducer/write failure is projected as partial, without replaying the tool.

Encrypted SessionWorkState rows are keyed by session and workspace. AES-GCM associated data binds the source run/event and version to the current workspace display-identity hash; a changed workspace identity fails closed. Run creation writes the bounded user-goal snapshot in the same transaction as its source prompt event. A narrow English/Vietnamese imperative/correction screen retains bounded constraints with provenance; this is not general semantic extraction. Model-facing user intent follows visible message sources after rewind. Receipt-observed effects remain evidence because chat rewind does not undo files. A successful durable todo_write receipt updates only untrusted model task candidates in the same receipt transaction. Every fact retains its own source run/event provenance, and session deletion removes the state in the artifact deletion transaction. The state is projected as untrusted workflow guidance on model context loads; it carries no permissions or opaque provider continuation data.

Agent prompt contract

The shared core contract requests light Markdown in user-facing prose: bold for key decisions and important warnings, inline code for commands, paths and identifiers, and short phrases rather than whole-paragraph emphasis. Greetings and simple replies stay plain. Explicit user formatting and strict output schemas take precedence; raw JSON/tool arguments receive no Markdown wrappers. This guidance is receipt-bound in the existing persona block for both native and text tool modes and all presets. It adds no model round trip and is guidance, not a guarantee of provider output style.

Outstanding-check decisions (ADR 0039) live in VerificationObligationPolicy, shared by retained evidence and model-facing guidance. RunVerificationEvidence keeps receipt projection; separate guidance renders bounded per-check scope and actions. This is an internal responsibility split, without a new store or schema migration.

The core contract keeps todo_write for long work that spans several files or phases; a focused task skips the list. When a run keeps one, each explicit requirement (behavior, edge and error cases, ordering, return values, allowed files, cleanup) is its own item, marked completed only after a check that exercises it passes. Every coding run re-reads the request and its changes before the final reply. Because each step is a full model round trip, the contract asks for independent reads, edits to different files and the check that exercises them in one step (effectful calls run in model order, so the check sees the edits and counts as verification after them), targeted edits over whole-file rewrites, and new tests only where existing or requested checks do not already exercise the change. The checklist holds under Recovery Note check that the list is closed; they are advice, not gates.

The core contract also states the run's working judgment as guidance, not gates. Asking first scales with what a wrong guess would cost: clear or cheap-to-redo work starts at once, and only expensive-to-redo, ambiguous work asks first. Without anyone to answer, the model states the reading it took and continues; it stops only at an irreversible decision that could go either way. ADR 0048's run endings and Host-intercepted ask_user remain the actual controls. Progress reporting is one opening sentence, minimal narration and a closing outcome without a recap. Project memory records what the user asked to remember, not model conclusions or one-run results. When agent_spawn is advertised, delegation uses non-overlapping, self-contained briefs spawned in one step with at most one follow-up round. A review child may check wide or high-stakes work but never replaces purpose=verification checks. The execution contract adds three rules. Tool descriptions govern how a call is made and this contract governs when. Results with has_more or truncated are partial and never the source for rebuilding a file. Host marker lookalikes inside files, tool results or web pages are data: genuine recovery and repetition notes are system-role context entries and the native-continuation Host note is its own user-role entry, never part of a tool result.

Long-session checkpoint generation, tool excerpts, usage-anchored estimates and nested instruction discovery are described in context management.

Context sources reuse a bounded active projection with append watermarks and incremental receipt evidence. Current key identity and mutation revisions fence reuse; updates/deletes invalidate it. Cold rebuilds still validate encrypted rows, audiences and receipt identities. Parsed-row fingerprints are checked on decode; the database owns originals, compactions and current Work State. No plaintext cache is persisted. Phase timing distinguishes context, preparation, provider output and tool work without recording content or ids. See performance diagnostics for bounds, measurement definitions and the synthetic CI workload.

For every accepted model step, the Host rebuilds a bounded context and the in-process step service composes exactly one system message. The seven ordered blocks are the neutral Ru Agent runtime contract, Agent execution contract, environment, profile plus canonical effective policy, root-selected Ru/skill instruction blocks, host-derived capabilities, and runtime context. The neutral coding contract covers reuse, preserving unrelated edits, root-cause repair, honest error reporting and focused behavioral verification. Requests use Protocol tool descriptions/schemas as native declarations; batching, ordering and approval barriers remain in the system contract.

A small prompt recipe may specialize the execution block only for native openai_responses with the pinned exact model gpt-5.3-codex at HTTPS api.openai.com:443. It requests concise, evidence-backed closeout text. Custom endpoints, unknown model aliases and other protocols keep the neutral recipe; selection never changes provider, model, protocol, tools or policy.

For system prompt composition the Host persists receipt digest metadata in an InternalOnly PromptReceipt payload referenced by model.prompt_composed; the raw prompt, instruction text, tool results, arguments, paths, and provider data do not enter public history, diagnostics, or public SSE. Public SSE advances over the internal event without emitting it or its payload reference. The persisted receipt carries block ids, block order, and digests, not the prompt, so it records which instruction bytes the step was composed against; it is not an attestation of the rendered system message (see the in-process model runner note above).

The bounded instruction loader first reads the optional user-wide ~/.ru/AGENTS.md (origin User, followed by the workspace guidance), then the fixed AGENTS.md, CONTEXT.md, .ru/AGENTS.md, and .ru/CONTEXT.md candidates below the selected run root, with AGENTS.md content inlined as workflow guidance. The two CONTEXT.md files become short workspace-relative documentation references containing the normalized source SHA-256; their bodies are read through advertised file tools when relevant. The receipt binds the normalized reference text, including that source hash. Source-file containment, decoding and size checks still apply. The loader then discovers direct-child skill directories from RuAgent.Protocol.SkillRoots in precedence order: <workspace-root>/skills, <workspace-root>/.ru/skills, <workspace-root>/.agents/skills, RU_SKILLS_ROOT when set, ~/.ru/skills, ~/.agents/skills, and %LOCALAPPDATA%\Ru\skills, followed by roots registered for this workspace. The prompt listing, the skill tool and /skills share that catalog. A package is recognized only when it contains a case-insensitive SKILL.md; for example:

---
name: pdf-analyzer
description: Analyze and summarize PDF files
allowed-tools: read, bash
---

# PDF Analyzer

Describe the review workflow here.

The loader applies final-path containment, strict UTF-8 decoding, NFC and newline normalization, a 64 KiB per-file cap, and a 256 KiB combined instruction cap. The shared metadata catalog caches validated discovery and checks for changes; Refresh forces a rescan. On-demand loads read and validate a bounded body snapshot. Only SKILL.md is loaded; nearby references/, assets/, and scripts/ files are ignored by discovery and are never automatically read or executed. The typed context has bounded references (128 KiB each), and an 8 MiB serialized-context cap. The Host budgets the encoded JSON aggregate, including mandatory policy, instructions and capability schemas; older references are omitted with a notice instead of failing before automatic compaction. Native history retains up to 4,096 messages and 32 MiB, with 128 Ki-character tool pages and a 64 MiB total request memory ceiling. Exact provider-request token preflight and automatic compaction still enforce the pinned model context window. Existing instruction files skipped for invalid encoding, size or containment are reported by safe source ID and reason, without raw content or absolute paths. The runtime context keeps at most thirty-two references total, counting any omission notice and available workspace-activity reference. Structured tool output projections preserve durable receipts and attach tool-specific paging cursors: read advances UTF-8 bytes, grep advances match results from the original query offset, and terminal read_output advances UTF-16 characters within the same spool; output past the spool's in-memory window lives in a session-scoped file. Spool claims and retained entries bind one session generation; closing it invalidates its writers before accounting is removed. An old writer cannot reserve or refund bytes against a reopened session, or publish removed output. Generation-specific directories isolate cleanup from new writers; a still-open old spill is cleaned after its writer closes, or at the next Broker start. A live background task can defer that cleanup until its bounded lifetime ends (at most 24 hours). Physical writes serialize within their own generation, while the global gate protects only accounting and retained metadata. Projection clipping never rewrites the receipt; bounded history may still omit older exchanges.

AGENTS.md remains the sole persona/style source. Successful structured file operations can also discover nested directory guidance, delivered through a bounded runtime baseline as described in context management. The user-wide file, nested instructions, the four fixed workspace instruction files and discovered skills are untrusted guidance; none can grant tools, capabilities, paths, network access, or approvals. Skills are rendered as ExternalSkill, and their allowed-tools metadata is descriptive only. Workspace SKILL.md bodies never execute tools. The in-process execution authority remains authoritative for path canonicalization, tool policy, approval, and execution; runtime references and tool results stay untrusted. Invalid context or receipt metadata fails closed with the bounded prompt_contract_invalid path; there is no static-prompt fallback or reduced- context retry. Managed runtime wiring enables the standalone web_search/web_fetch tools by default with their network.search/network.fetch scope labels; no settings field controls their exposure. Returned web text is bounded, sanitized, and wrapped with the [untrusted_web_reference] marker. Search uses engine-specific DOM result selectors; known-engine challenge/navigation links are rejected and Bing redirect links are decoded. Fetch uses an in-process AngleSharp parser with no resource loader or JavaScript execution, reads PDF text through PdfPig (parse only, at most 500 pages), preserves code and plain text, and pages extracted text through optional offset/limit. Requests name Ru in the User-Agent rather than posing as a browser. The default download bound is 4 MiB; output defaults to 32000 UTF-16 characters with next_offset/truncated metadata. Pages refetch the source rather than retaining a snapshot. Structured Host projection retains the untrusted web wrapper and advances a clipped page by extracted text characters, excluding the wrapper/marker; its cursor takes precedence over the original page cursor. Free upstream search relevance remains unguaranteed.

Prompt composition is not an authority boundary. Execution-authority policy, approvals, workspace trust, protected paths, external-directory grants, and cancellation remain authoritative. Workspace SKILL.md bodies are untrusted prompt guidance only and never execute tools or grant anything; subagent orchestration uses the existing Harness coordinator and Broker gateway, as recorded in docs/operations/subagents.md. The root catalog includes five subagent tools; child role projections omit delegation. Root-owned read-only list/detail HTTP routes back Client, RPC/SDK, CLI and the WinUI task tree. Schema v29 consolidates the former development migrations for internal ownership, attempts, encrypted scope/message/result references, admission deadlines, family budgets, waits and integration journals. A separate root-bound internal-run marker survives loss of child relation metadata: restart fails that child by name, budget admission denies it, and Stop/session deletion still reach its run. Internal attempt cleanup closes the authority session and drains its background terminal processes before releasing registration; the stable internal session ID, encrypted history and worktree remain available for continuation, while transient authority resources are recreated. Generic run routes cannot reset a child attempt's budget. On explicit session deletion, Host cancels the family and waits for runtime cleanup before asking Broker to reclaim prepared coding artifacts. Broker checks captured physical identities, removes only the owned snapshot/worktree and its per-worktree Git metadata, and never follows junctions or runs global Git pruning. Cleanup also waits while any session has an open run rooted in either owned tree; it does not cancel that session. Unrelated and similarly prefixed sibling roots do not block deletion. Partial filesystem failures retain encrypted evidence and harness rows for retry and return the existing artifacts-pending outcome. A successful retry reports deletion when it reclaims retained runs even if the conversation record is already gone; another cleanup failure stays pending. No automatic expiry retry is implemented. The primary conversation store reports deletion, confirmed absence and failure separately. Only confirmed absence can complete a retained-artifact retry; a storage failure stays an error even if harness rows were successfully removed. Legacy stores returning an ambiguous false are treated as failures. Scratch cleanup follows the same primary-store result: failure preserves its files and approval ledger; successful deletion or confirmed absence permits cleanup. The schema retains scope evidence with the owned run after relation loss, without restoring execution authority. A root-bound preparation journal records reservation before filesystem creation, physical snapshot evidence precedes bulk copying, and Git registration is bracketed by durable checkpoints. Reservations and completed child identities are listed together; a family has no identity limit (ADR 0022 amendment). Minimal encrypted evidence is bounded to 64 KiB per allocation and excludes file contents. Session deletion discovers allocations even without a child run or scope and reclaims only proved physical identities. Unproven or replaced identities fail closed; cleanup does not scan for orphans or reconstruct execution authority. For a live preparation refusal, Broker can explicitly attest that snapshot capture failed before starting any filesystem allocation. Only that attestation lets Host remove the exact still-reserved journal row and return a known tool failure without write reconciliation. A stage value alone, or any failure after allocation starts, cannot establish this condition. Research/review tasks skip Git preparation entirely. In-process snapshot failures reclaim the captured owned directory; provisioning failures after the worktree and Git identities are captured reclaim both trees. Cleanup has a separate ten-second deadline, preserves the original failure and reports a named cleanup error if removal fails. After restart, an existing directory without a captured physical identity returns subagent_cleanup_allocation_unproven; interrupted Git registration before identity capture returns subagent_cleanup_registration_unknown. Both retain evidence for an explicit recovery decision rather than inferring ownership from paths or Git backlinks. Windows directory leases request list access and omit delete sharing for every held ancestor so their names stay stable during guarded operations. Failure to obtain that handle denies the operation; metadata-only handles are not a fallback. Delegated scopes capture the parent and child lease generations. Revocation is monotonic within a generation and survives duplicate opens and policy rebinds. Session close revokes its runs before removing leases and releases only its own child bindings; surviving children stay classified and revoked. Reopening a closed parent with identical IDs and policy cannot revive them. Retained bindings are bounded to 1,024; capacity returns subagent_delegation_capacity without evicting existing proof. Cancellation of unknown runs retains no history. Control and apply intent hashes include a lease generation identifier. A closed root denies apply; an old token presented after a fresh trusted lease open returns decision_stale and requires a new authorization before any journal or file mutation. Children inherit the parent's entire pinned model/provider/protocol selection. There is no subagent setting; legacy role preferences are retired. An explicit model request in the authenticated root prompt may select another signed-in provider's current catalog model. Workspace/tool output cannot opt in. Model absence, catalog failure and unresolved ambiguity are named refusals before workspace preparation; no provider/model/protocol substitution occurs. Existing attempts and continuations keep their pins. See operations for errors and matching. Public root creation rejects an internal session even if a matching conversation document exists; ordinary session-run history also excludes that session before pagination. Durable internal markers preserve the boundary after relation loss. The parent waiting state is waiting_subagents in run/SSE projections and remains active in session activity; clients accept it as an automatically resumed wait. An internal family usage reader uses one SQLite read snapshot to stream usage receipts for the root and all owned attempts, including marker-only children. Absent or invalid reports and partial fields yield an incomplete known subtotal; missing values stay null and numeric zero stays zero. No price estimate is derived. Internal apply inspection also passes through IToolGatewayFactory to the Broker: the Host loads the exact frozen result and encrypted journal, and the Broker checks their fingerprint and each recorded intent before reading bounded current hashes. Read ask/deny rules remain in force. Unopened ancestor directories are unavailable, not proof of absence. The observation hash binds current root identity, binding version, policy and journal outcome; it is neither an approval token nor a write receipt. Matching proposed bytes never change the journal or resolve uncertainty. The schema projects the existing explicit user reconciliation decision into a bounded per-root/agent/result acknowledgment. The latest required native model/tool/execution and encrypted original agent_apply arguments must match. Acknowledgment and the resolution event commit atomically; missing proof or storage failure leaves the run parked. User assertions never rewrite apply status or create file receipts. After acknowledgment, later result collection uses only durable per-file receipts as integration bases; unreceipted writes keep the old base and may conflict with current parent files. Duplicates apply still returns the saved uncertain outcome without replaying writes. Startup fails any run left in ReconciliationRequired with legacy_reconciliation_removed; no new run can enter that state. Startup rehydrates children from their immutable delegation and model pin after parents; ambiguous mutations stay running and return the ordinary failed receipt. Internal children cannot use the Host's ask_user interception. The model-facing tool projection uses their durable role, removes questions/delegation controls, and removes filesystem mutations/terminal execution for review. Role eligibility is shared with the Broker; it does not replace execution policy. Single-child Stop atomically marks only the owning identity cancelled before runtime cleanup, so late messages/admission/continuations cannot revive it and siblings remain usable. Cleanup failures retain the tombstone for explicit retry. The schema includes an encrypted immutable coding change-set store: manifests and ordered 1 MiB content chunks commit together, with a 32 MiB per-file integration limit and the 256 MiB snapshot size limit. Completed coding result publication requires this stored change set; result versions follow attempt numbers. The internal publication tick now collects through the Broker from encrypted scope and configured owned storage after the child session drains. It freezes bytes once and reuses them on restart, with one coding collection per tick and cursor progress across deferred children. Collection rechecks Git directory/common-directory/root identity and every observed file hash, including files initially unchanged, before sealing the result. Durable result outcomes are separate from execution state: permanent collection errors publish durable failed results without rewriting completed model history; a parent wait receives that outcome. Coding continuations wait for sealed bytes or a recorded failure before reusing the worktree. Pending or unknown prior apply operations still require reconciliation before collection. Internal guarded apply loads successful frozen coding results from SQLite and uses the existing gateway approval mapping to reach the Broker. Broker checks every target before issuing a batch decision; authorization binds the result fingerprint, resolved targets, physical root and current lease/policy generation. A batch ask accepts Allow Once or Deny, never directory or remembered grants. Each held-file mutation rechecks the lease under the lifecycle gate, and cancellation is observed between writes. File conflicts preserve parent edits. Intent/receipt persistence failure produces an unknown outcome; loss of final durable reporting raises an explicit reconciliation exception. Duplicate commands return the saved outcome without writing again. The internal prepared-execution receipt bridge preserves native call IDs and maps partial/unknown or lost final reporting to the existing Core reconciliation state; no client action can replay it. Internal native spawn/send/wait/cancel dispatch now runs inside a live Broker authorization callback, bound to the committed native tool-call ID and arguments. It expires on return and rechecks parent cancellation/policy after the callback. Host validates durable ownership; it cannot manufacture that permission. Spawn/send/cancel are scheduled as orchestration mutations, wait is read-only and must be alone, and apply keeps its separate frozen-file authority. Explicit test advertisements exercise both roles, deferred parent wait and coding file integration through the real gateway; the production inventory exposes all five controls to the parent. Public/client/UI workflows expose read-only snapshots and results. Unproven artifact recovery retains evidence and fails by name. LSP, project-level plugin discovery, workspace-declared MCP servers, arbitrary system overrides, Chat compatibility, UI redesign, and OS filesystem/network confinement are outside this implementation. Terminal children run as the current Windows user; structured file tools stay in-process under canonical path containment, with the protected-path denial in plan and standard (ADR-0015).

Harness ownership

The scripts/harness Python package is test-only tooling, exercised by the tests/test_harness_* suite: bounded helpers for temporary data/log roots, leased loopback ports, child-process lifecycle classification, public-route classification with safe fixture request descriptions, and artifact assembly. It is not a production contract gate — the managed .NET suites, the route checker and build.bat are — and it owns no production process: the Public Host is a single process (ADR-0014), so no Broker or worker child exists. An early child exit is recorded only as its role, exit code, and lifecycle classification; raw child output is not copied into the public artifact. The Harness does not change the start-or-attach RuAgent.Client contract for RuApp/CLI; credentials and fixed runtime defaults remain Public Host-owned.

The GUI Harness extends that ownership boundary through an explicit RuAppComposition: production uses the managed backend provider, while a short-lived loopback descriptor selects an external Harness edge and a bounded JSONL event sink. The WinUI shell, API clients, Agent SSE client, session history path, and reply lifecycle remain the same. Harness mode never takes over an existing RuApp instance and drives only the agent-* scenarios.

Only the parent model's Broker-authorized tools interact with children. Public HTTP exposes two GET snapshots/result-page endpoints; RPC/SDK and CLI/WinUI expose observation/export only. Generic run mutation endpoints also reject internal children (including marker-only ownership). A child tool requiring approval is denied with subagent_parent_action_required so the parent can handle the blocker under its own normal policy; no child approval is auto-granted.

Historical user-action rows, retained in v29, keep immutable root/agent/result bindings and uncertain-write proof. Unexecuted queued/approval-waiting actions are cancelled; already executing rows are reconciled through the existing parent gate without replay. No new public action can enqueue integration. Journal receipts and model-only context notes remain valid for historical reconciliation.

A single SQLite read snapshot binds child identities, attempts, exact pinned model, original spawn task, publication outcome and journal acknowledgments. Internal session IDs, provider credentials/options and selected context are omitted from public transport. Result pages are root/agent/version-bound byte cursors that preserve UTF-8 boundaries. Historical approval details in read snapshots remain bounded to 8 KiB; larger proposals retain identity and a named details-too-large state. Child output remains readable; child approval writes are refused. Per-attempt and family usage sum only actual durable reports, with nullable totals and explicit incompleteness. subagent.changed SSE frames are transient hints, carry attempt/result identities, and never commit a parent run version. List/detail reads resync reconnecting clients; WinUI also polls while its view is loaded. Detach/unload never cancels server work. The SubagentTreeView observer owns its read lifetime and stale-response gate separately from ChatView. AgentSidePanelControl bridges its snapshots into the session summary card and hosts a closable Subagents tab. SubagentPresentation supplies grouped task labels; SubagentTreeModel binds root/selection/version read tickets. Detail and export have separate partials, and the existing MarkdownBlock renders a bounded 256 KiB preview. A compact ChatView entry opens the same reader as an overlay at narrow widths. Users can inspect and export only; no child mutation controls or additional public endpoints are introduced.

Data ownership

ASP.NET Core owns business persistence in the existing %LOCALAPPDATA%\Ru\agent_harness.db SQLite WAL database; RU_DATA_ROOT selects an isolated root. Schema v18 adds settings, conversation sessions and Activity Timeline records alongside runs, events, workspaces and work state. The v18-to-v29 upgrade converts exclusive/single-slot workspace coordinators to shared coordination without changing runs, trust or permission snapshots. Runtime membership has no cap by default (schema v37); the existing concurrency API accepts shared mode with no cap (0) or a cap of two or more, and cannot disable parallel sessions. Runnable work beyond a cap waits for a lease. The runtime loop drives every registered run at once, and provider steps are unbounded unless RU_MAX_CONCURRENT_MODEL_STEPS sets a cap. One session still owns at most one active run. GUI and CLI use the same admission policy. Since schema v30, messages live in business_session_messages with absolute per-session indices, source fingerprints in business_session_source_receipts, and small metadata/summary rows in business_sessions. FTS5 is a transactional message-search projection. Settings and activity keep bounded JSON payloads inside SQLite rows. No new ORM or second database is introduced. Windows Credential Manager remains the API-key store.

Each store imports its legacy settings.json, sessions/*.json or activity_log.jsonl once, atomically with a durable migration marker. Activity also imports leftover file outboxes and .processing files. Original files remain unchanged as backups and are ignored after successful import. Invalid session documents and malformed/oversized activity lines are skipped as before; invalid settings remain unmarked and can be repaired before a settings save. I/O failures or cancellation roll back the import so a later attempt can retry. See ADR 0013 for the migration and backup boundary.

Session deletion is coordinated by the Public Host through DELETE /sessions/{sessionId}. The route keeps its stable HTTP 200 response envelope: only status: "ok" confirms that the session and its owned Harness artifacts were removed; a missing or failed delete returns status: "error" even with HTTP 200. WinUI refreshes the sidebar only after application-level success and creates a replacement session only after successfully deleting the last one.

GET /sessions additionally carries workspace_id, workspace_label, and workspace_path per session, resolved from the session's latest Harness run (null when the session has no runs or the workspace identity changed), so WinUI can group the sidebar by workspace without a second round trip.

Session creation and import accept optional X-Ru-Client-Source: gui|cli; unknown values return HTTP 400. The source is durable session metadata in the existing SQLite metadata/summary rows and is returned as client_source by session listings. It is a presentation label, never execution authority. GUI and CLI creation paths label their own sessions; resuming a session does not change its source. Older sessions and callers omitting the header retain a null source. The GUI renders Workspaces, Recents and CLI Session in that order, with CLI sessions grouped by source independently of their working directory. CLI rows can be reordered within their section; GUI rows keep existing workspace/Recents placement. Sidebar organization never changes execution cwd or session source.

GET /sessions retains its bounded newest-500 summary response. New callers use GET /sessions/page?limit=100&cursor=...&query=... to reach older summaries; message-content filtering uses FTS5 and title filtering uses literal text. Pages carry the same workspace, source and running-state enrichment as the original listing. List cursors are keyset positions, not a frozen database snapshot: sessions updated while paging can move to the refreshed first page.

GET /sessions/{sessionId}/messages returns the newest page in chronological order, with start_index, total_messages, history_epoch and next_cursor. The cursor moves toward older messages and binds the session, captured count and rewind epoch. Appends do not shift previous indices; rewind makes earlier cursors return session_history_cursor_stale (HTTP 409). Malformed cursors return HTTP 400. Limit is 1–200; the normal serialized message budget is 4 MiB. A single valid 1 MiB UTF-8 message may expand under JSON escaping and is returned alone (at most roughly 6 MiB plus metadata), within the 8 MiB Client response cap. Reads and model context remain bounded; retained history is no longer deleted after 200 messages. GetAsync/activate return a bounded tail and explicit offset/count/epoch metadata. GET /sessions/search?query=... returns bounded literal-phrase FTS hits with absolute message indices.

Export walks all retained pages in chronological order and refuses a concurrent rewind or an oversized output instead of silently exporting a tail. Import reports the complete persisted count in session.messages, omitted transcript entries in dropped_entries, and partial_import when any entry was omitted. An import with no persistable message fails without retaining an empty session. Migration cannot recover messages that older builds already pruned. Rewind deletes visible tail rows but retains source receipts, preventing late outbox delivery from re-adding them. No automatic conversation/run retention policy is enabled.

Operational backup, verification, offline restore/compaction and opt-in pruning are documented in database maintenance and ADR 0030.

Interrupted imports attempt bounded compensation with a cleanup token independent of the request. The Session Store checks emptiness and deletes in one immediate transaction, preserving messages already committed by the import or another client. Cleanup failure is logged without replacing the original failure or cancellation; CLI and GUI propagate caller cancellation. Create and append remain separate transactions, so this does not promise rollback of a completed import after its response is lost.

WinUI gives Creating its own cancellation lifetime, including the period before a run ID arrives. A late accepted response is canceled rather than attached to a different session. Composer text and attachments clear only after acceptance for the matching session/draft. Unsent drafts retain at most eight sessions and 32 MiB of estimated serialized content (1 MiB text and 24 MiB attachments per session); exceeding a cap refuses the switch and leaves the active draft intact. Picker and clipboard image intake share validation and normalization before the four-image/4 MiB decoded-per-image request boundary.

The canonical data-location contract is documented in ADR 0004.

Session Work State

The bounded, encrypted workflow record attached to one Conversation Session and canonical workspace identity: user goal and constraints, the latest task list, receipt-backed observations and verification codes, blockers, and next actions with provenance, capped at 16 KiB with at most 16 entries per list. User intent remains linked to its original run and event; model task candidates are untrusted and persisted only from a successful durable todo_write receipt, and file observations and verification records require receipt provenance. It is context guidance only: it carries no approvals, grants, credentials, raw terminal output, or execution authority, and a workspace identity change makes the state unavailable. A new session stays independent.

When the state is rendered into model context, tasks, file observations and verifications whose receipt tool result is still in that context are left out, with one note saying so: the model already sees the todo_write call or tool result itself, and repeating it made every task update resend a list that grows with each tool call. A receipt that compaction folded into a summary, or that came from an earlier run, is not in the context and is still rendered. Avoid: global memory, cross-session authority, model prose as proof, or work state as permission

Session Run Handoff

A bounded, encrypted base-context snapshot of model-visible evidence from up to four earlier terminal root runs in the same Conversation Session and workspace. Only runs whose user messages remain attributed in the loaded conversation snapshot are eligible; rewind/pruning cannot restore removed run details. It carries applicable checkpoint excerpts, recorded requests, assistant statements/ proposals, tool-result excerpts and receipt outcomes with run/event provenance, including work stopped before a final reply. It is captured once for a new root run, alongside the existing 32 completed conversation turns and Session Work State. Historical proposals are quoted context, never executable native calls; missing receipts and omitted details remain explicitly unverified. Internal child runs, audit-only payloads, provider continuation and execution authority are not inherited. Model selection remains pinned separately per run. Avoid: complete memory, cross-session history, inherited approvals, automatic re-execution of unfinished calls

Native Continuation

ADR 0049. At base capture, HarnessModelContextBootstrapper asks ReadNativeContinuationCandidateAsync for the session's newest visible terminal root run with the same preset and permission profile, and an ending other than context_limit_reached, request_too_large, checkpoint_* or context_*. AgentRunHandoffModelFacts.SharesModelAsync then compares both pins: backend, alias, protocol, base URI, model, account, calling mode, tool profile, and computer-use and provider-search pins. Last, ReadNativeContinuationSliceAsync projects the source without following its own continuation. NativeRunContinuation.Close keeps the closed prefix and turns the first unsettled batch, and everything after it, into a Host note listing each call and its receipt or none; the source's recovery and repetition notes are dropped. The slice must hold at most 256 entries, keeping carried base sequences inside the guards' 512-sequence window, and leave half of the window free, assuming 128,000 tokens when no window is published.

A source that passes is recorded as the reserved base entry base:native-continuation. The source's own dialogue turn is dropped from the base, and the text handoff skips rendering it while still reading it for scope hints. On every uncached load, SqliteModelContextSource appends the slice (and base:native-continuation-note) after the captured base, with base sequences, before the run's own compactions apply; the marker itself never reaches the model. SqliteProviderContinuationReader replays recorded provider items for retained steps of the run and of the one source its marker names. Any failed condition, including a source that cannot be projected, falls back to the text handoff.

Tool Output Projection

A bounded, untrusted model-visible view of a durable Broker receipt. Structured read, grep, web_fetch, and terminal read_output projections retain their own cursor units (UTF-8 bytes, match results, extracted UTF-16 characters, and spool UTF-16 characters respectively); a cursor continues the same source or spool and never changes the receipt, tool authority, or approval state. Grep's next_offset means a known next page; a scan_incomplete flag with no cursor describes incomplete coverage, not a pagination promise. Text pages preserve character boundaries: file cursors are UTF-8 byte boundaries, web cursors are UTF-16 boundaries outside surrogate pairs, and a window too small to advance returns a named failure. Missing source identity fails closed when clipping needs a cursor. The bounded prompt may still omit older output exchanges. Native history is limited to 4,096 messages / 32 MiB and tool pages to 128 Ki characters; exact provider-token preflight remains authoritative. Runtime references are at most 128 KiB each and are collectively fitted to the 8 MiB serialized context cap; outputs already present in retained native history are not duplicated in the system prompt. Read windows default to 1 MiB and accept up to 4 MiB, with serialized-output fitting before Broker normalization and byte cursors for continuation. Avoid: treating projected output as a new receipt, complete history, or authority

Subagent

A stable child identity owned by one root run, with an internal session and bounded attempts. Coding children use private worktrees; research/review children read the parent workspace and cannot mutate or launch terminals. Child tool projections follow the stored role and omit user questions and delegation controls. A single child Stop persists its tombstone before runtime cleanup and preserves siblings. Delegation is tied to the exact live lease generation: cancellation survives duplicate opens and policy rebinds, and reopening a closed parent cannot revive its old children. Session close releases that session's bindings; retained bindings are capped at 1,024 without eviction. Control and apply authorizations include the lease generation so tokens from a closed lease cannot authorize a new one. Harness orchestrates them through the existing coordinator; Broker owns delegated authority and integration. Model selection is pinned per attempt and defaults to the parent's exact provider/model/protocol. There is no subagent setting. Only an explicit user request in the owning root's authenticated prompt may opt into another model; workspace/tool/child content cannot opt in. Overrides resolve exact model identities in current catalogs of signed-in providers. Unavailable, ambiguous or unreadable catalogs fail by name, with no substitute. Existing attempts and continuations retain their pins. A durable root-bound internal-run marker preserves classification and cleanup ownership if child relation metadata is lost; it never grants execution authority. Public session deletion reclaims prepared coding artifacts through Broker after cancellation and runtime drain. Captured physical identities constrain snapshot/worktree and Git metadata deletion; failures retain evidence for retry. Encrypted cleanup scope lives with the owned run even after relation loss, and cannot restore execution authority. An encrypted, root-bound allocation journal reserves the identity before filesystem preparation and captures physical cleanup evidence before bulk copying and after Git registration. A live Broker refusal before allocation starts can release only the exact still-reserved identity without requiring write reconciliation; journal stage alone is insufficient proof. Research/review tasks, including web searches, skip Git preparation; coding uses the workspace repository when it is a root with a commit and otherwise a private base repository in the snapshot's owned directory (ADR 0042). Session deletion can reclaim proved allocations after restart even without a child run or execution scope. An unproven directory or interrupted Git registration without captured identity stays pending with a named error; the journal never restores execution authority. Public root creation and ordinary session-run listing reject internal sessions, including marker-only ownership. waiting_subagents remains active in session activity and has an exact public run/SSE status; clients treat it as an ordinary waiting state. The internal family usage reader sums only durable provider usage receipts across the root and owned attempts. Missing/corrupt reports or partial token fields leave the snapshot incomplete; token totals do not imply a monetary cost estimate. Generic run routes cannot reset an internal attempt's budget. Execution completion and result collection have distinct outcomes: a completed child may yield a durable failed result if its artifact cannot be collected. Coding followups wait until the prior result is sealed before reusing the worktree. Internal apply loads an exact frozen coding result and obtains Broker authorization for that file set; a batch approval is single-use and cannot create remembered rules or directory grants. Ambiguous write/journal outcomes require reconciliation and never trigger automatic replay. Internal inspection loads the frozen result and encrypted journal through the same gateway; Broker reads bounded current hashes under read policy and reports existing intents and receipts separately. A hash matching the proposal never creates a receipt or resolves an uncertain apply. The schema projects an explicit user reconciliation decision into the apply journal in the same transaction as the targeted native resolution event. Later coding results use only actual per-file receipts as bases; unknown/pending outcomes and unreceipted writes remain unchanged, and duplicate apply never replays the batch. Internal native control dispatch requires an exact call-bound Broker callback permission that expires when dispatch returns; metadata validation alone grants no authority. The root catalog exposes agent_spawn, agent_send, agent_wait, agent_cancel and agent_apply; child projections exclude them. Two read-only HTTP endpoints provide list/detail and version-bound UTF-8 result paging. CLI /subagents, RPC/SDK and the WinUI panel expose observation/export only. The session card and narrow-window button open a Subagents tab with grouped tasks, stable branch glyphs and a version-bound Markdown reader. Stopped work remains distinct from successful completion. Generic run mutations also reject internal children. Approval-required child tools are denied with subagent_parent_action_required; the parent handles the blocker under its own policy. No child approval is auto-granted or shown as a user action. Root SSE emits transient subagent.changed hints with child attempt/result identities; clients fetch snapshots on attach/reconnect and deduplicate by snapshot/attempt versions. Historical user-apply records remain in v29 for receipt/reconciliation integrity. Unexecuted legacy user actions are cancelled by the root drive; already executing actions are reconciled without replay. New integrations only originate from the parent's agent_apply tool. See ADR 0022 and the implementation evidence. Avoid: a new execution authority, a user conversation, or an OS sandbox

Markdown Skill

Definition: Markdown Skill (glossary).

A shared Broker catalog supplies canonical directory IDs and bounded YAML metadata. The prompt includes one budgeted ExternalSkill catalog block; full bodies are loaded on demand with skill. Metadata revisions describe the discovered file, while body_sha256 identifies the exact loaded body. Expected revision/digest arguments can reject a changed definition. Source path and resource base accompany body loads; references and scripts are never automatically read or executed.

/skill <id> [arguments] is an explicit GUI chat invocation: the Host validates user invocation policy and requirements, then atomically persists a model-only SkillInvocation payload with the visible user prompt. Run command invocation also appends that durable workflow. $ARGUMENTS expansion happens only in the rendered workflow, preserving the original body digest. It does not launch tools. Terminal chat has removed these slash controls and accepts ordinary skill requests through its prompt; model invocation rules remain unchanged.

Active skill projection validates successful native receipts and Host invocation provenance before compaction, retaining at most four complete workflows within 128 KiB of bodies. It deduplicates identity/version, reports omissions and re-attaches missing workflows as untrusted user context after compact/restart. It never rereads changed disk content to restore a run. New runs do not inherit an unbounded collection of previous workflows.

The catalog, user invocation and resource details are documented in skill operations. ADR 0032 records ownership and snapshot lifetime. allowed-tools is descriptive only; no skill content changes Broker policy, approvals or execution authority. Avoid: treating SKILL.md as a permission manifest or executable plugin

Native Tool Batch

One model step may contain optional narration and one or more ordered native tool calls. The Host persists the assistant call batch and every durable result; approval resume rehydrates and re-evaluates the retained proposals without a new model proposal. Initial execution, approval/input resume and approval refresh share proposal-batch classification, pause and abort cleanup in the Harness; initial proposal persistence stays interleaved with evaluation, and refresh cannot execute the batch. Read-only calls may execute concurrently in model order with at most eight active, while mutations and terminal calls retain sequential barriers. A complete call written out as text to an advertised tool is salvaged into the same path. Avoid: one-call-per-step rule, reissuing approved calls

Completion policy

AgentRunCoordinator routes every returned model step through one ordered, pure policy (CompletionPolicy, internal). Each rule returns one decision, and each decision maps to an existing commit handler, so commit shapes, outbox entries and recovery notes are unchanged. Rules R1 to R3 run before the verification refresh, on the pinned step. Rules R4 to R9 run after it, on the refreshed evidence, so they see the latest receipts. The first rule that applies wins.

Before the refresh:

  • R1 unusable_finish: a Length finish is held while truncation notes remain, then fails as model_output_truncated. ContentFilter and Error finishes fail at once. Streamed text is retracted and partial tool calls are never dispatched.
  • R2 tool_calls: the step proceeds to the repetition guard and dispatch.
  • R3 commentary_only: commentary stays in model history and is held with up to three notes, then fails as model_commentary_only.

After the refresh, for a step without tool calls:

  • R4a blocked_reply: a [BLOCKED] reply keeps the model's own report and fails the run. The error code is the failed receipt's or verification's code, or model_reported_blocker.
  • R4c unverified_advice: a failed receipt or an outstanding declared check is held with a code-aware note while unverified_after_tool_failure notes remain. The cap is three per run, shared by tool-failure and verification holds.
  • R4d verification_advisory_complete: once those notes are spent, a verification-bound failure completes the run with state unverified. Blank text is not a completion and falls through to R8.
  • R4e tool_failure_fail: once those notes are spent, a failed tool receipt with no verification evidence fails the run with its code.
  • R5 unverified_source_edit: one hold after source edits with no declared check since them.
  • R6 open_todos: one hold while the latest task list has open rows. It quotes up to eight of them.
  • R7 completion_review: one hold after source edits in a run where a declared check failed at least once, when no declared check is outstanding or awaiting verification, the source-edit hold was not issued and the latest list is not fully completed.
  • R8 empty_reply: a blank final reply gets up to three notes, then fails as empty_model_reply.
  • R9 complete: the reply is accepted, unless R10 holds it first.
  • R10 advisor_recommended (ADR 0047): one hold on a reply R9 would accept, in a root run whose user selected a resolvable advisor, when the step advertised advisor and the latest tool step was not an advisor call. The note recommends a consultation; the model may consult or repeat its reply, which completes the run. The Host never consults on the model's behalf.

R5 to R7 and R10 are one-time advice and never fail a run. The per-kind caps are listed under Recovery Note.

Recovery Note

A durable ModelContextNote beginning with [HARNESS RECOVERY], addressed to the ModelContext audience, that answers a dead-end model step instead of failing the run; the same model takes the next step with that feedback in context. Bounds are per kind — 3 unverified_after_tool_failure notes (shared by tool-failure and verification holds), 4 model_repairable notes, 3 empty_model_reply notes and 3 consecutive model_output_truncated notes, plus 3 model_commentary_only notes, one unverified_source_edit note, one open_todos note, one completion_review note and one advisor_recommended note — under a cap of 24 notes within the recovery window (the last 512 durable events, about fifty steps), measured over the recovery notes visible in the assembled context. The per-case bounds count the same window, except the four one-time nudges, which stay once per run; a long run that meets the same failure far apart gets the same bounded recovery each time. A note is persisted with the system role and is therefore never folded away by compaction, so it keeps its event sequence and leaves the count only when the run has moved past the window. Every note is same-model bounded self-correction, never provider/model/tool substitution. Responses commentary-only text stays in model context with its original phase, without a final conversation outbox entry; the next step receives a recovery note asking it to continue or close out. Other unusable replies remain audit-only; when a bound is spent the run fails closed with the original code. A model may instead emit a final [BLOCKED] report describing the incomplete/partial outcome. The marker is removed from durable visible history, and the run ends as failed with the receipt code (or model_reported_blocker without a failed receipt), never verified success. This report does not spend further recovery notes. Its durable outbox remains deliverable after runtime cleanup. An exhausted provider-transient step is failed with its provider code; it does not park for Continue. A user's deny settles the asked call with an approval_denied receipt and the run resumes (ADR 0048); that receipt never draws unverified-failure notes, and an ambiguous mutation stays running with its ordinary failed result. A repeated policy_denied tool receipt followed by prose is a tool outcome, not an approval decision, so it may still take the bounded unverified_after_tool_failure notes with the denial code as the terminal code. The note states the reason from the failed receipt: an expected-exit mismatch, a required check with no confirmed result, or otherwise a failed tool call. It then asks for a repair tool call or a final [BLOCKED] report. Once its notes are spent, a verification-bound failure (an outstanding declared check or the tracking limit) completes the run with state unverified, and any other failed tool call fails the run (completion policy R4d and R4e). Provider Length finishes suppress the whole incomplete step, including any partial tool calls, before execution; bounded recovery requests smaller output. ContentFilter and Error finishes fail as model_content_filtered and model_reply_error without recovery. Whitespace-only final text counts as empty.

A final text reply after an unverified source edit gets a separate one-time hold, not a failure path. A successful or unknown-effect apply_patch or agent_apply call sets the condition, as does a write, edit, write_file or edit_file call whose path is not .md, .markdown, .txt, .rst or .adoc. File deletion, file restoration and terminal commands never set it. A launched purpose=verification check clears it; a failing one stays on the outstanding-check path. While a declared check is outstanding, that path decides and the hold stays silent. Otherwise the first non-empty final text is held once per run: its streamed text is retracted and a durable unverified_source_edit note asks for a purpose=verification build or test of the request's requirements, fixes for any failure, and a statement of any untested requirement. If nothing applicable can run, the model finishes again and says so. A later final reply is not held again, and a model that ignores the note still completes, with summary verification unverified. The condition is projected from original receipts, so it survives compaction and restart. Model step safe code unverified_source_edit_advised; note safe code unverified_source_edit. Empty final replies keep their existing recovery.

Two more one-time holds follow it, in this order, on a non-empty final text reply that the outstanding-check guard and the source-edit hold did not take. Both are advice, never failure paths, and each is a durable [HARNESS RECOVERY] system note counted in the global cap. open_todos fires when the latest successful todo_write list still has rows that are not completed. Its note quotes up to eight open items, each flattened to one line and cut at 120 characters, and asks the model to finish and check each one, mark it completed, or remove it with a reason. completion_review fires when the run made source edits, a declared check failed at least once in the run (a first-time pass pays no review), no declared check is outstanding or awaiting verification, the source-edit note was never issued, and the latest list is not fully completed. Its note asks the model to re-read the request and the changed code, confirm each explicit requirement is met and exercised by a check, fix any gap and rerun the affected purpose=verification check, then name any requirement left unchecked. A fully completed list skips this review. Model step safe codes are open_todos_advised and completion_review_advised; note safe codes are open_todos and completion_review. Each hold retracts the streamed text, and a later final reply is not held by the same hold again. A coding run with source edits therefore normally takes one extra model step (unverified_source_edit or completion_review, never both), and an open checklist can add one more.

Streamed text remains provisional until the Harness accepts the step. When a step is suppressed (failed-tool recovery, the source-edit hold, the checklist holds, rejected repeated calls, unusable or empty output), the Harness retracts that step's text through the existing assistant.delta reset before publishing recovery feedback or starting another step. Retraction follows redaction completion so buffered tails cannot reappear. The reset retains the rejected model-step identity and advances its sequence; earlier accepted steps and tool receipts remain intact in GUI and TUI.

Avoid: fallback answer, substitute model, retry on another backend

Receipt-backed verification

Verification is advisory (ADR 0039). It records evidence and holds final replies. It never grants or denies execution.

RunVerificationEvidence projects original run-local tool proposals and receipts before compaction. A fresh process rebuilds the same declared checks from encrypted history; summaries, handoffs and model claims cannot create or clear them. The projection travels as private context metadata, outside canonical provider history, and outstanding checks are supplied in bounded runtime context guidance. It keeps three completion facts: whether a declared check launched after the last structured source edit, whether any structured source edit ran (sticky), and the latest successful todo_write list. A failed or unparseable todo_write keeps the previous list.

  • Declared checks. For powershell and run_process, purpose=verification declares a required check that must exit zero. purpose=expected_failure with an exact nonzero signed 32-bit expected_exit_code declares a negative test that must exit with that code. Only that observed exit satisfies it, and its original receipt stays failed. Unannotated and purpose=inspection process failures remain diagnostics that create no obligation.
  • Identity. New authenticated terminal receipts carry an authority-derived verification_identity (resolved executable, exact argv and canonical cwd, and the expected exit for a negative test). It is independent of timeout and workflow intent, so cwd aliases resolve the same check. Legacy receipts without it keep raw-argument identity.
  • Outstanding checks. A declared check whose latest result is failed or pending, including an expected-exit mismatch, is outstanding. Only the same identity passing later retires it. Other checks, reads and summaries do not. A later result for the same identity replaces the earlier latest result; original receipts remain in history. A pending background check is read through its terminal execution until it exits.
  • Source edits. A successful or unknown-effect structured source edit (write, edit, write_file, edit_file, apply_patch or agent_apply, outside documentation paths) marks the run as awaiting verification until a declared check launches. Terminal commands, computer-use input, file deletion and file restoration never mark a source edit. No command or computer input invalidates an earlier check.
  • supersedes. Removed from the launch schemas; a call that still sends it fails schema validation. Verification ignores it in old receipts, so it retires nothing.
  • Rejected before launch. A declared check rejected before any process started (a malformed call, a policy denial or an unresolvable executable) observed nothing and creates no obligation. Its failed receipt still counts as a tool failure for the tool-failure guard.
  • Tracking. Up to 256 required checks are retained separately from 64 recent diagnostics. At the limit a passed check gives up its row to a new one; only a buffer full of checks that still owe an answer reports verification_tracking_limit, which is verification-bound.
  • Holds, completion and labels. Final-reply handling follows the completion policy. An outstanding check or the tracking limit holds a final reply up to three times (R4c). When those notes are spent, the run completes (R4d) with its summary verification state unverified. A [BLOCKED] reply ends the run as failed with the model's own report. Terminal summaries load the same original-receipt evidence before the immutable live and late-subscriber summary is reserved. The summary label is verified when no check is outstanding and a declared check launched after the last structured source edit. It is not_applicable when the run made no structured source edit and declared no check. Otherwise it is unverified. Computer input and other activity never change it.
  • Recovery note text. The note names the reason: a missing or pending result ("a required check has no confirmed result"), an expected-exit mismatch ("a declared negative test returned a different exit code"), or otherwise a failed tool call. It asks for a repair tool call or a final [BLOCKED] report, and it tells the model that a verification-bound failure completes as unverified once the notes are spent.
  • Workspace journal and terminal_effect. The workspace change journal (ADR 0008) is not read for verification. Journal freshness therefore does not affect completion or labels, and an edit by a parallel run after a check is not reflected in this run's label. Broker receipts still record terminal_effect metadata, but the projection does not read it.
  • Blocked reports and persistence. A [BLOCKED] report, its blocked_report assistant payload and the final conversation outbox intent commit atomically with the Running-to-Failed transition and one failure event. Outbox delivery is fenced and idempotent. It does not move the failed run to Completed, including after restart.

Passed checks are evidence for declared checks only. They do not prove that all code is correct or that every possible verification has run. Deterministic tests cover the projection, holds and labels. They do not establish real-provider outcomes.

Repeated Tool Recovery

The same schema-invalid enum/type/required field is counted across changed file names and content: after three rejected calls the repetition guard advises repair, then stops after its existing bounded note budget. A corrected schema is allowed. Field diagnostics come from the Protocol catalog and never rewrite arguments or expand execution authority.

Identical calls and short failed-call cycles are suppressed before duplicate dispatch. Up to two [REPETITION GUARD] notes ask the same model to change its arguments; exhaustion fails the run as repeated_tool_call. Suppressed assistant steps remain audit-only, because they have no tool receipts to pair in native model history. Trailing guard notes preserve the failed receipt for both repetition checks and the final-answer verification guard. A note cannot make a failed verification verified: once its holds are spent, the run completes with its verification state reported as unverified.

Agent Persona Source

The root-selected AGENTS.md instruction is the sole Agent persona/style source; an optional user-wide ~/.ru/AGENTS.md is read before it, so workspace guidance wins where they disagree. The built-in prompt is a neutral execution contract. Root instructions may guide persona and workflow but cannot grant tools, folders, network access, or override Broker policy. Avoid: embedded fallback persona

Runtime driver state ownership

AgentRuntimeLoopService drives runs; AgentRuntimeRootRegistry owns registered roots/coordinators, and AgentRuntimeCoordinatorFactory composes a drive. If composition fails before a coordinator exists, AgentRunFailureTransition commits a named terminal failure directly through the event store before runtime registration is released. It re-reads on version conflicts, preserves concurrent terminal states, and bounds each attempt to eight commits. Store failure retains registration for a later retry. History acknowledgement uses the same persistence path when composition fails; a history-delivery failure also needs no provider or tool gateway to settle the run. AgentRuntimeParkingState owns client-wait and recovered-approval/version fences. AgentRuntimeRunLifecycle releases registration, Broker resources and retained approval state only after pending user-apply and child work is cancelled. The separation preserves the recovered-approval version race and cleanup order.

VerificationEvidenceBuffer retains required checks separately from up to 64 recent diagnostic checks. A check is keyed by its identity, and a later result for that identity replaces the earlier latest result. Overflow applies to required evidence, not to optional lookups or to already-satisfied negative tests. Execution policy is unaffected by any of this.