Reference

Results and refusals

What each field of a bay result means, and what to do after each refusal.

bay is in development. These pages describe bay as it will ship.

The result document

Every command prints one bay.result/1 document on stdout. A consumer refuses a major schema version that it does not know.

json

{
  "schema": "bay.result/1",
  "op_id": "c7k2m4.1",
  "decision": "blocked",
  "reason": "INPUT_CHANGED",
  "change": "c7k2m4",
  "detail": {
    "input": "contract:api.orders.schema",
    "observed": "v17",
    "required": "v18"
  },
  "allowed": ["read", "refresh", "repair"],
  "retry_when": "candidate_validated_against_required_versions",
  "receipt": "ci-linux/ev901",
  "freshness": {"trunk": "a1b2c3d", "fetched_at": "2026-10-17T19:30:02Z"}
}

Field	Meaning
`schema`	Always `bay.result/1`.
`op_id`	The operation id.
`decision`	`landed`, `queued`, `blocked`, `failed` or `ok`.
`reason`	A fixed reason code when the decision is not `ok` or `landed`.
`change`	The change id.
`detail`	Facts for this reason, such as the input and its observed and required versions.
`allowed`	What you can still do.
`retry_when`	The condition under which a retry can succeed.
`receipt`	The id of one evidence record.
`freshness`	The trunk commit that bay read and when it last fetched.

Ids

A change id is lower-case base32, for example c7k2m4.
An operation id is the change id and a number, for example c7k2m4.1.
A candidate id adds the attempt, for example c7k2m4.1.2.
An evidence id is the producer and an id, for example ci-linux/ev901.

bay land exits 0 when bay accepts the operation. "published": false then says that the landing has not happened yet. waiting_for and next say what the operation waits for and what comes next.

json

{"schema": "bay.result/1", "op_id": "c7k2m4.1", "candidate": "c7k2m4.1.2", "decision": "queued",
 "state": "admitted", "published": false, "waiting_for": "executor_capacity",
 "elapsed_s": 41, "receipts": ["ci-linux/ev901"], "next": "running"}

Reason codes

Each refusal carries one code from a fixed table. A retry with no change in the cause gets the same code and does no work. Three codes are transient: TRUNK_MOVED, CHECK_UNAVAILABLE and HOOK_TIMEOUT. bay retries those within a bound.

Code	Meaning	What to do next
`INPUT_CHANGED`	A declared input has a newer required version.	Read the new version, refresh, and repair. Land a candidate checked against the required versions.
`INPUT_UNOBSERVED`	You have not read the new version of an input yet.	Read the required version, then refresh.
`MERGE_CONFLICT`	The draft does not merge onto trunk. `detail` lists the conflicting paths.	Resolve the listed paths. With Git 2.56 or newer, stage them with `git add --resolved`. Otherwise check them for conflict markers and stage only those paths.
`TRUNK_MOVED`	Trunk moved during the landing.	Nothing. bay retries once more, then joins the queue (`PUBLICATION_QUEUED`).
`PUBLISH_RETRY_EXHAUSTED`	Five uncounted retries ran out (`HOOK_TIMEOUT`, or a deadline release during the push).	Fix the cause, such as a slow hook or a check that runs too long.
`REGISTRY_CHANGED`	The key of the landing executor was revoked after it signed the candidate.	Nothing. An executor with a valid key signs the same tree on the same parent, with no recheck.
`CHECK_FLAKY`	One tree has both a signed `pass` and a `product_failure` for one check.	Fix the check, or quarantine it in the policy.
`CHANGE_NOT_LANDED`	`bay undo` names a change that is not on trunk.	Read the change. Undo it after it lands.
`HOOK_TIMEOUT`	The trunk hook on the host ran past its time bound and refused the push.	Nothing. bay retries the same candidate after a short wait.
`QUEUE_HELD`	Another operation holds the head of the queue. This one has joined the queue.	Keep editing locally. It reaches the head with no action.
`QUEUE_DEADLINE_EXCEEDED`	The progress deadline of the head released this operation three times.	Shorten the check before landing, or raise the budget in the policy.
`PUBLICATION_QUEUED`	The operation holds a place in the queue. `detail` gives its position and the deadline of the head.	Keep editing locally. A newer revision replaces the queued entry at the same position.
`CHECK_FAILED`	A required check failed on the candidate.	Repair the change, then land again.
`CHECK_UNAVAILABLE`	No worker with the required capabilities answered.	Wait. The operation waits outside the queue until a capable worker answers.
`CHECK_UNKNOWN`	A check crashed, timed out, or collected nothing.	Wait for a result, or repair the check.
`POLICY_CHANGED`	The acceptance policy changed after bay checked the candidate.	Refresh. bay checks the candidate again under the current policy.
`WORKSPACE_INCOMPLETE`	The view is not `ready`.	Resume it with `bay start --resume <change>`.
`PUBLISH_OUTCOME_UNKNOWN`	The reply to the push was lost.	Nothing. bay reads trunk again and reconciles.
`CHANGE_ALREADY_LANDED`	This change already landed with a different revision.	Start a new change with `bay start <intent> --new`.
`CHANGE_SUPERSEDED`	Another change holds or delivered this intent.	Read that change. Adopt it when it is abandoned or past its takeover window.
`ABANDON_REFUSED`	An actor that does not hold the change sent an abandon request.	Let the current actor abandon it, or wait until the adopt rules apply.
`COVERAGE_UNKNOWN`	Coordination data is out of reach. Only isolated work can go on.	Keep editing locally. Land when coordination data is reachable.
`REMOTE_NOT_FETCHED`	`bay status --fleet` has no fetch of the configured remote.	Fetch the remote, then run the command again.

Refusals after the agent left

Some refusals arrive after the agent has left. The executor writes each one as a refused event for the actor of the change. The agent hook delivers it to a live session, an idle session, or the next session of that actor.

Doctor codes

bay doctor uses its own codes. reason names the first red row.

Code	Meaning	What to do next
`GIT_BELOW_FLOOR`	Git is below the floor for the role of this machine.	Upgrade Git to that floor.
`CLAUDE_BELOW_FLOOR`	The Claude adapter is on, and Claude Code is older than 2.1.302.	Upgrade Claude Code, or run without the Claude adapter.
`CLAUDE_ABSENT`	The Claude adapter is on, and `claude` is absent.	Install Claude Code 2.1.302 or newer, or run without the Claude adapter.
`REMOTE_UNREACHABLE`	The remote did not answer with the key of this machine, or no remote is set.	Make the remote answer with the key of this machine.
`HOOKS_MISSING`	A hook entry that bay needs is absent from the project agent settings.	Run `bay install` again.
`SKILL_MISMATCH`	`~/.claude/skills/bay/` is missing or does not match this bay version.	Run `bay install` again.

Reference

Results and refusals

What each field of a bay result means, and what to do after each refusal.

bay is in development. These pages describe bay as it will ship.

The result document

Every command prints one bay.result/1 document on stdout. A consumer refuses a major schema version that it does not know.

json

{
  "schema": "bay.result/1",
  "op_id": "c7k2m4.1",
  "decision": "blocked",
  "reason": "INPUT_CHANGED",
  "change": "c7k2m4",
  "detail": {
    "input": "contract:api.orders.schema",
    "observed": "v17",
    "required": "v18"
  },
  "allowed": ["read", "refresh", "repair"],
  "retry_when": "candidate_validated_against_required_versions",
  "receipt": "ci-linux/ev901",
  "freshness": {"trunk": "a1b2c3d", "fetched_at": "2026-10-17T19:30:02Z"}
}

Field	Meaning
`schema`	Always `bay.result/1`.
`op_id`	The operation id.
`decision`	`landed`, `queued`, `blocked`, `failed` or `ok`.
`reason`	A fixed reason code when the decision is not `ok` or `landed`.
`change`	The change id.
`detail`	Facts for this reason, such as the input and its observed and required versions.
`allowed`	What you can still do.
`retry_when`	The condition under which a retry can succeed.
`receipt`	The id of one evidence record.
`freshness`	The trunk commit that bay read and when it last fetched.

Ids

A change id is lower-case base32, for example c7k2m4.
An operation id is the change id and a number, for example c7k2m4.1.
A candidate id adds the attempt, for example c7k2m4.1.2.
An evidence id is the producer and an id, for example ci-linux/ev901.

A queued landing

json

{"schema": "bay.result/1", "op_id": "c7k2m4.1", "candidate": "c7k2m4.1.2", "decision": "queued",
 "state": "admitted", "published": false, "waiting_for": "executor_capacity",
 "elapsed_s": 41, "receipts": ["ci-linux/ev901"], "next": "running"}

Reason codes

Code	Meaning	What to do next
`INPUT_CHANGED`	A declared input has a newer required version.	Read the new version, refresh, and repair. Land a candidate checked against the required versions.
`INPUT_UNOBSERVED`	You have not read the new version of an input yet.	Read the required version, then refresh.
`MERGE_CONFLICT`	The draft does not merge onto trunk. `detail` lists the conflicting paths.	Resolve the listed paths. With Git 2.56 or newer, stage them with `git add --resolved`. Otherwise check them for conflict markers and stage only those paths.
`TRUNK_MOVED`	Trunk moved during the landing.	Nothing. bay retries once more, then joins the queue (`PUBLICATION_QUEUED`).
`PUBLISH_RETRY_EXHAUSTED`	Five uncounted retries ran out (`HOOK_TIMEOUT`, or a deadline release during the push).	Fix the cause, such as a slow hook or a check that runs too long.
`REGISTRY_CHANGED`	The key of the landing executor was revoked after it signed the candidate.	Nothing. An executor with a valid key signs the same tree on the same parent, with no recheck.
`CHECK_FLAKY`	One tree has both a signed `pass` and a `product_failure` for one check.	Fix the check, or quarantine it in the policy.
`CHANGE_NOT_LANDED`	`bay undo` names a change that is not on trunk.	Read the change. Undo it after it lands.
`HOOK_TIMEOUT`	The trunk hook on the host ran past its time bound and refused the push.	Nothing. bay retries the same candidate after a short wait.
`QUEUE_HELD`	Another operation holds the head of the queue. This one has joined the queue.	Keep editing locally. It reaches the head with no action.
`QUEUE_DEADLINE_EXCEEDED`	The progress deadline of the head released this operation three times.	Shorten the check before landing, or raise the budget in the policy.
`PUBLICATION_QUEUED`	The operation holds a place in the queue. `detail` gives its position and the deadline of the head.	Keep editing locally. A newer revision replaces the queued entry at the same position.
`CHECK_FAILED`	A required check failed on the candidate.	Repair the change, then land again.
`CHECK_UNAVAILABLE`	No worker with the required capabilities answered.	Wait. The operation waits outside the queue until a capable worker answers.
`CHECK_UNKNOWN`	A check crashed, timed out, or collected nothing.	Wait for a result, or repair the check.
`POLICY_CHANGED`	The acceptance policy changed after bay checked the candidate.	Refresh. bay checks the candidate again under the current policy.
`WORKSPACE_INCOMPLETE`	The view is not `ready`.	Resume it with `bay start --resume <change>`.
`PUBLISH_OUTCOME_UNKNOWN`	The reply to the push was lost.	Nothing. bay reads trunk again and reconciles.
`CHANGE_ALREADY_LANDED`	This change already landed with a different revision.	Start a new change with `bay start <intent> --new`.
`CHANGE_SUPERSEDED`	Another change holds or delivered this intent.	Read that change. Adopt it when it is abandoned or past its takeover window.
`ABANDON_REFUSED`	An actor that does not hold the change sent an abandon request.	Let the current actor abandon it, or wait until the adopt rules apply.
`COVERAGE_UNKNOWN`	Coordination data is out of reach. Only isolated work can go on.	Keep editing locally. Land when coordination data is reachable.
`REMOTE_NOT_FETCHED`	`bay status --fleet` has no fetch of the configured remote.	Fetch the remote, then run the command again.

Refusals after the agent left

Doctor codes

bay doctor uses its own codes. reason names the first red row.

Code	Meaning	What to do next
`GIT_BELOW_FLOOR`	Git is below the floor for the role of this machine.	Upgrade Git to that floor.
`CLAUDE_BELOW_FLOOR`	The Claude adapter is on, and Claude Code is older than 2.1.302.	Upgrade Claude Code, or run without the Claude adapter.
`CLAUDE_ABSENT`	The Claude adapter is on, and `claude` is absent.	Install Claude Code 2.1.302 or newer, or run without the Claude adapter.
`REMOTE_UNREACHABLE`	The remote did not answer with the key of this machine, or no remote is set.	Make the remote answer with the key of this machine.
`HOOKS_MISSING`	A hook entry that bay needs is absent from the project agent settings.	Run `bay install` again.
`SKILL_MISMATCH`	`~/.claude/skills/bay/` is missing or does not match this bay version.	Run `bay install` again.