Skip to content

120. Record absorbed steers as agent-run receipts ​

Date: 2026-11-02

Status ​

Accepted

Companion decisions:

  • ADR 0119 (proposed): what a steer is. Steering is correct without this ADR.
  • ADR 0121 (proposed): the default and the opt-outs.

Context ​

ADR 0119 (proposed) lets a running cycle absorb entity updates, but the notification that prompted a steer still schedules a follow-up cycle. Unless something tells that cycle what was absorbed, it redoes the work.

ADR 0144 adds no Fullsend handled-state gate: handled state belongs in the harness's CEL or pre-script. ADR 0098 allows "an explicit per-harness receipt" for that purpose. A receipt that the agent or anyone else can forge would make a harness skip work it still owes, so where the receipt lives is the core of the decision.

ADR 0144 already defines host-written final metadata for a bound fullsend run: the run-level result that names the canonical entity key, the platform-verified result revision, and the selected cycle. The host writes it outside the sandbox.

This ADR aims to let the next cycle's harness recognize absorbed updates without adding a runner skip and without trusting content the sandbox can write.

Options ​

OptionWhy not chosen
Runner-level skip of absorbed recordsADR 0144 rules out a second handled-state gate
A forge comment carrying a receipt marker, admitted by authorAgent-authored output is posted under the same identities, and a bot_role "does not make the bot's content trustworthy" (ADR 0107)
A field of the host-written ADR 0144 final run metadata (chosen)—

Decision ​

We adopt an absorbed-steer receipt, written as a field of the host-written ADR 0144 final run metadata, to let the next cycle's harness CEL or pre-script recognize the updates a steered run absorbed.

Fullsend adds no runner skip.

What is written ​

When a run with at least one acknowledged steer publishes its final metadata, the host adds a receipt field that holds:

  • the issuing run's identity, harness, repository, and canonical entity key;
  • for each steered cycle, the cycle, the steer count, and the heads the steers offered (for audit only, see below);
  • for each absorbed record, its record key and the SHA-256 of the filtered record file as delivered (steer envelope v1 records[].sha256).

The receipt sits in the metadata file the host writes, never in the agent's output tree.

Why the sandbox cannot forge it ​

  • The host writes the metadata outside the sandbox. On GitHub Actions the actions/upload-artifact step publishes it after fullsend run exits, with the Actions runtime credential that the runner gives that step. Fullsend never passes that credential into the sandbox.
  • A reader accepts a receipt only from the prior run of the same harness's own workflow, and only when the receipt's harness, repository, and canonical entity match the cycle being checked. A receipt from any other run or workflow is ignored.
  • Trust comes from this host-only write path, not from who authored a forge comment.

Reading and admitting it ​

  • Before CEL or the pre-script runs, the host reads the receipt from the platform's record of the prior run of the same harness and entity. On GitHub Actions that record is the prior workflow run's fullsend-<agent> artifact.
  • The host compares each absorbed record with current state: it re-derives the current filtered record file and checks its SHA-256. A record that changed, is missing, or cannot be verified is not listed as absorbed, so the cycle runs for it.
  • The host then stages the verified receipt in the snapshot's agent-runs history, where CEL and the pre-script read it as ADR 0098 allows. The closed entity-context-snapshot v1agent-runs schema has no field for it, so receipts need entity-context-snapshot v2 with these fields: absorbed record key and digest, steer count, offered heads, and issuing run identity.
  • Every doubt fails open. Metadata that is missing, unreadable, or mismatched is ignored, and the cycle does the work.

What a receipt does not prove ​

A steer never changes the cycle's platform-verified result revision (ADR 0119). An acknowledgement proves the message arrived, not that the agent acted on it. Consumers must not treat an acknowledged steer, or a head named in a receipt, as proof the agent worked on that newer head.

Forge scope ​

  • GitHub: GitHub Actions, from the workflow run's fullsend-<agent> artifact.
  • Other platforms: supported where the platform keeps equivalent host-written run metadata for a prior run; otherwise not supported, and every steered cycle is followed by a full cycle.
  • Jira: not applicable. Entity-context-snapshot v1 does not stage Jira entities, so they do not steer (ADR 0119).

Consequences ​

  • A harness that reads receipts skips redundant follow-up cycles; one that does not still runs them, which stays correct.
  • Receipt trust rests on the host-only write path of the run metadata and a per-record digest check, not on forge identity or content filtering.
  • Receipts wait on the ADR 0144 final metadata and entity-context-snapshot v2; until both exist, every steered cycle is followed by a full cycle.
  • Auto-merge and approval gates keep comparing the verified result revision with live state; a receipt gives them no newer revision.

Open questions ​

  • Which shipped harnesses should read receipts first, and does a shared helper belong in fullsend-ai/agents?