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: aLengthfinish is held while truncation notes remain, then fails asmodel_output_truncated.ContentFilterandErrorfinishes 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 asmodel_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, ormodel_reported_blocker. - R4c
unverified_advice: a failed receipt or an outstanding declared check is held with a code-aware note whileunverified_after_tool_failurenotes 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 stateunverified. 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 asempty_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 advertisedadvisorand the latest tool step was not anadvisorcall. 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
powershellandrun_process,purpose=verificationdeclares a required check that must exit zero.purpose=expected_failurewith an exact nonzero signed 32-bitexpected_exit_codedeclares a negative test that must exit with that code. Only that observed exit satisfies it, and its original receipt stays failed. Unannotated andpurpose=inspectionprocess 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_patchoragent_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 isverifiedwhen no check is outstanding and a declared check launched after the last structured source edit. It isnot_applicablewhen the run made no structured source edit and declared no check. Otherwise it isunverified. 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 asunverifiedonce 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 recordterminal_effectmetadata, but the projection does not read it. - Blocked reports and persistence. A
[BLOCKED]report, itsblocked_reportassistant 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.