Unified autonomous steering — Reference

See Bounded autonomy, same-author context fallback and human escalation for the shared visual model.

See Persisted feedback, explicit decision and confirmed effect for the shared visual model.

Reference for the coordinator-owned steering path. Every correction signal is persisted, surfaced, decided by the coordinator, and then executed according to that decision.

For the implementation flow, see the deep dive. For operator behavior, see the experience guide.

Routes

Method & path	Body	Returns	Notes
POST /api/runs/{coordinatorRunId}/steer	kind, optional target_child_run_id, instruction	Steering directive view	Human steering entry point. pause is not supported.
POST /api/runs/{coordinatorRunId}/assembly/review	approved, request_changes, declined, feedback, optional target files	Assembly review decision	Human review still posts to the review gate, but correction feedback is routed through unified steering.

The separate Assembly Gate route was removed; correction feedback uses unified steering through the coordinator.

Steering signal fields

SteeringSignal is the internal normalized contract (apps/Agentweaver.Api/Coordinator/SteeringSignal.cs:29).

Field	Values / type	Meaning
CoordinatorRunId	string	Coordinator run that owns the decision.
Source	human-review, rai, rubberduck, build-test, agent, coordinator, step	Where the feedback came from.
TargetScope	{ kind, subtaskIds?, childRunId? }	Run, work-plan, or subtask target.
Feedback	string	Reasoning context for the coordinator; not parsed for hidden routing.
Severity	advisory, request-changes, blocking	How strong the signal is.
Verb	stop, send, redirect, amend, dispatch-fresh	Delivery verb.
TreeHash	string or null	Aggregate tree hash the feedback was produced against.
TargetFiles	string array or null	Explicit hints only; never inferred from prose.
CreatedBy	string	User, agent, or gate id.

Decision directions

Decision	Meaning	Effect
in_place_steer	A: context-preserving correction	Resume the same child run/session/worktree with revision feedback.
dispatch_fresh	B: conscious fresh dispatch	Reset selected subtasks and launch fresh child runs. Always preceded by coordinator.steering_decision.
proceed	C: proceed or terminal	Continue to review or record a terminal/blocked result.
advisory	D: no-op	Surface the signal and take no corrective action.

A released pod can make a child non-resumable, choosing fresh dispatch over in-place steering. Lack of another author does not itself force escalation: with accumulated feedback/context, a fresh same-author run can preserve prior work without changing lockout. Without context, escalate to human review. Autonomous budgets still bound retries.

Events

Event	When it fires	Payload
coordinator.steering_received	A signal from any source is persisted and queued.	directiveId, source, severity, verb, targetScope, feedback, treeHash
coordinator.steering_decision	The coordinator records its A/B/C/D decision before executing the effect.	directiveId, decision, rationale, subtaskIds, attempt
coordinator.steering	Legacy directive lifecycle event for human steering.	directiveId, kind, targetChildRunId, status, instruction

The decision values distinguish a fresh dispatch, an in-place steer, normal progress, and advice that takes no action. Clients can use the rationale and target subtask ids to explain the result.

Failure and recovery semantics

Case	Observable result	Recovery behavior
Transient in-place revision commit failure	The child stays on the same run/worktree while commit is retried.	AgentTurnExecutor retries CommitChanges up to 3 attempts before surfacing failure.
Persistent child executor failure during in-place revision	Child run terminalizes with run.failed reason the bounded { message, errorCode, retryable } public failure contract and the corresponding workflow.step is failed.	The coordinator preserves the steering instruction and emits a visible dispatch_fresh steering decision for failed targets.
Crash before revision launch or before first confirmed effect	The steering directive remains outstanding; it is not marked applied.	Recovery re-drives unconfirmed targets. Confirmed child effects are skipped so successful children are not re-injected.
Successful in-place revision	Same child run/worktree re-enters assembly after reaching assemble_ready or completed.	The directive is marked applied only when every target is assembly-eligible and every target child has a confirmed SteeringRevisionExecution marker.

the bounded { message, errorCode, retryable } public failure contract is terminal for coordinator child runs. It replaces the previous uninformative watch_stream_completed_without_terminal_event path for child executor throws, so operators see the executor that failed and the timeline gets a failed workflow.step.

Budgets

Bound	Default	Source
Per-subtask recovery attempts	3	CoordinatorSteeringService.MaxRecoveryAttempts
Per-plan steering iterations	6	CoordinatorSteeringDecider.DefaultMaxPlanSteeringIterations

When autonomous budgets exhaust, the decider chooses proceed and assembly escalates durably to in_review, stage review, with the run awaiting review. It does not latch terminal assembly-blocked. Human request-changes resets the autonomous budgets as a new supervised mandate; HumanReviewRoundTrips is telemetry, not a cap.

Status and persistence

State / record	Purpose
SteeringDirective	Stores the signal, status, chosen action, attempt, source/severity/scope, and tree hash.
assembly_steering work-plan status	Decision-in-progress lease for assembly-originated feedback.
SteeringRevisionExecution	Attempt-specific marker proving an in-place revision effect ran.
RecoveryAttempts on subtask	Per-subtask loop bound.
SteeringIterations on work plan	Per-plan loop bound.

A human redirect/amend/send sent to POST /api/runs/{id}/steer while the coordinator is parked at the assembly human-review gate (awaiting_review) is delivered straight into the review gate rather than the child-turn queue (#226): redirect/amend become a request-changes decision on the same path as POST /assembly/review (settling relayed), and send becomes an advisory note (settling applied). When the gate is armed on a different API replica the directive is durably persisted with the terminal status deferred for the owning pod's poller to drain, and the endpoint answers 202 Accepted. See resilient assembly review.

See also

• Events reference
• Coordinator reference
• Unified autonomous steering — Deep Dive

Diagram details and constraints

Element	Contract
title	Rejected work keeps useful context
takeaway	A steering decision chooses the effect; rejection does not always rotate the author.
group-title-0	FEEDBACK AND SCOPE
group-title-1	BOUNDED DIRECTION
group-title-2	AUTHOR CONTINUITY AND HUMAN ESCALATION
Gate request-changes	Gate request-changes
Gate request-changes	Structured target-file hints
Gate request-changes	not prose-inferred blame
Implicated + dependent	Implicated + dependent
Implicated + dependent	Rebuild closure without blame
Implicated + dependent	structured TARGET_FILES
Signal + decision	Signal + decision
Signal + decision	Persist explicit direction
Signal + decision	accumulated context
In-place revision	In-place revision
In-place revision	Same author and session
In-place revision	no reset-to-pending
Fresh dispatch	Fresh dispatch
Fresh dispatch	Scoped author selection
Fresh dispatch	handoff with context
No alternate author	No alternate author
No alternate author	Context permits same author
No alternate author	bounded conscious fallback
Human escalation	Human escalation
Human escalation	No context or budget left
Human escalation	durable review request
Human decision	Human decision
Human decision	Approve, change or decline
Human decision	no wall-clock timeout
Fresh autonomous budget	Fresh autonomous budget
Fresh autonomous budget	Only human changes reset it
Fresh autonomous budget	no human-round-trip cap
e0	scope
e1	signal
e2	resume
e3	fresh
e4	no alt
e5	context
e6	no context
e7	Proceed
e8	await
e9	changes
e10	retry
groups	FEEDBACK AND SCOPE; BOUNDED DIRECTION; AUTHOR CONTINUITY AND HUMAN ESCALATION

Diagram details and constraints

Element	Contract
title	One signal, four explicit effects
takeaway	Durable decisions choose resume, fresh dispatch, human escalation or advisory continuation.
group-title-0	NORMALIZED FEEDBACK AND DURABLE DIRECTIVE
group-title-1	DECISION AND RESUMABILITY
group-title-2	ALTERNATIVE EFFECTS
Gate feedback	Gate feedback
Gate feedback	Implemented assembly sources
Gate feedback	structured scope
SteeringSignal	SteeringSignal
SteeringSignal	Normalize reason and targets
SteeringSignal	one decision contract
Persist directive	Persist directive
Persist directive	Received event is visible
Persist directive	queued / durable
Bounded decider	Bounded decider
Bounded decider	Budget + attempt resumability
Bounded decider	human-only budget reset
Persist decision	Persist decision
Persist decision	Decision event follows commit
Persist decision	explicit direction
In-place steer	In-place steer
In-place steer	Keep author and session
In-place steer	attempt-specific proof
Fresh dispatch	Fresh dispatch
Fresh dispatch	Conscious fresh execution
Fresh dispatch	bounded same-author fallback
Durable human park	Durable human park
Durable human park	Proceed / exhausted budget
Durable human park	not a failure terminal
Advisory continuation	Advisory continuation
Advisory continuation	No child-state reset
Advisory continuation	separate from in-place
e0	normalize
e1	submit
e2	decide
e3	commit
e4	resume
e5	fresh
e6	Proceed
e7	advisory
groups	NORMALIZED FEEDBACK AND DURABLE DIRECTIVE; DECISION AND RESUMABILITY; ALTERNATIVE EFFECTS