From c4971b93d32a950bb971fa3c5902e083c8905b2e Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Sat, 25 Jul 2026 14:54:38 -0400
Subject: [PATCH 01/36] fix(timing): accumulate active time for in-flight
 stages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`active_time_ms` was only ever computed from terminal stage events, so a
stage still running contributed zero to the run rollup. A run parked in one
long agent stage reported 2m 8s of active time against 16m 53s of wall
clock — the two finished stages — while the running stage had been doing
continuous inference and tool work for over 14 minutes.

`live_run_timing` summed `filter_map(|stage| stage.timing)`, and
`stage.timing` is only written at finalization. Wall time ticked live off
`start_time`; active time did not tick at all.

Stage projections now accumulate brackets from the event log:

- Closing an inference bracket folds its span into `live_inference_ms`
  instead of discarding it, including across retries, matching the
  in-process stopwatch.
- Tool calls open a batch on the first outstanding call and close it when
  the last one drains, so tools running concurrently within a turn count
  once — the same span `execute_tool_calls` is bracketed by. Summing
  per-call durations would over-count parallel tool use. Subagent tool
  events are excluded; they run inside the root call's span already.
- `StageProjection::live_timing(now)` composes accumulators with any open
  bracket, per handler: agent stages use the brackets, prompt and command
  stages count elapsed time as inference and tool respectively, and
  handlers that wait on a human, timer, condition, or child branches
  report zero.

Active is clamped to wall per stage. A worker killed mid-turn leaves its
bracket open forever, and without the clamp it would tick up unbounded.
The clamp does not need to detect the dead worker: a stage cannot have been
active longer than it has existed. `watchdog.timeout` remains the authority
on whether a run is stuck. The clamp is deliberately not applied at run
level, where concurrent branches can legitimately sum past run wall time.

Timing is derived from events rather than emitted by the worker, so this
needs no event-schema change and applies to runs already stored.
`StageProjection.timing` keeps its terminal-only meaning, and the
authoritative breakdown still replaces the live estimate at terminal
events.

The billing endpoint had the same hole behind its `wall_only` fallback:
running stages reported zero inference/tool/active. Not visible in the
product, which renders only `wall_time_ms`, but wrong for any other
consumer of `GET /runs/{id}/billing`.

Parallel branch stages lose their breakdown permanently, even after
completion, because `parallel.branch.completed` carries only `duration_ms`.
That is a separate data-loss bug, tracked in #644.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../app/routes/run-detail/header.tsx          |   9 +-
 ...05-21-wall-and-active-time-metrics-plan.md |  11 +-
 docs/public/api-reference/fabro-api.yaml      |  66 ++-
 .../src/server/handler/billing.rs             |  16 +-
 lib/components/fabro-store/src/run_state.rs   | 475 +++++++++++++++++-
 .../fabro-types/src/run_projection.rs         | 462 ++++++++++++++++-
 lib/foundation/fabro-types/src/timing.rs      |  26 +
 .../src/.openapi-generator/FILES              |   1 +
 .../fabro-api-client/src/models/index.ts      |   1 +
 .../fabro-api-client/src/models/run-timing.ts |   2 +-
 .../src/models/stage-projection.ts            |  12 +
 .../src/models/stage-timing.ts                |   2 +-
 .../src/models/stage-tool-batch-projection.ts |  29 ++
 13 files changed, 1060 insertions(+), 52 deletions(-)
 create mode 100644 lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts

diff --git a/apps/fabro-web/app/routes/run-detail/header.tsx b/apps/fabro-web/app/routes/run-detail/header.tsx
index efc68f09b..3b7081596 100644
--- a/apps/fabro-web/app/routes/run-detail/header.tsx
+++ b/apps/fabro-web/app/routes/run-detail/header.tsx
@@ -326,6 +326,7 @@ function DurationPopover({
 }) {
   const endMs = completedAt != null ? Date.parse(completedAt) : now;
   const sinceCreatedMs = Math.max(0, endMs - Date.parse(createdAt));
+  const isRunning = completedAt == null;
   return (
     <>
       <PopoverHeader>Duration</PopoverHeader>
@@ -335,8 +336,14 @@ function DurationPopover({
           <dd className="mt-0.5 font-mono text-fg">{formatDurationMs(sinceCreatedMs)}</dd>
         </div>
         <div>
-          <dt className="text-fg-3">Active (inference + tools)</dt>
+          <dt className="text-fg-3">
+            Active (inference + tools){isRunning ? " — estimated" : ""}
+          </dt>
           <dd className="mt-0.5 font-mono text-fg">{formatDurationMs(timing.active_time_ms)}</dd>
+          <dd className="mt-0.5 text-fg-3">
+            {formatDurationMs(timing.inference_time_ms)} inference ·{" "}
+            {formatDurationMs(timing.tool_time_ms)} tools
+          </dd>
         </div>
       </dl>
     </>
diff --git a/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md b/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md
index 90438d3b5..3683e5879 100644
--- a/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md
+++ b/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md
@@ -157,7 +157,14 @@ git diff --check
   provider-reported model-only compute time.
 - LLM retry backoff, queueing outside a request/stream, human waits, steering
   waits, and scheduler gaps are wall time but not active time.
-- Active timing is finalized-event based in v1; live active-time ticking can be
-  added later if it becomes necessary.
+- ~~Active timing is finalized-event based in v1; live active-time ticking can
+  be added later if it becomes necessary.~~ **Superseded 2026-07-25.** It became
+  necessary: a run parked in one long agent stage reported ~12% of its wall time
+  as active, because in-flight stages contributed nothing. Stage projections now
+  accumulate inference and tool brackets from the event log and expose
+  `StageProjection::live_timing(now)`, the active-time twin of
+  `live_wall_time_ms`. Finalized values remain authoritative and still replace
+  the live estimate at terminal events. See
+  `.ai/plans/live-active-time-accumulation.md`.
 - No compatibility layer is required for existing API clients or stored run
   event data.
diff --git a/docs/public/api-reference/fabro-api.yaml b/docs/public/api-reference/fabro-api.yaml
index b028d89c0..568aa30e5 100644
--- a/docs/public/api-reference/fabro-api.yaml
+++ b/docs/public/api-reference/fabro-api.yaml
@@ -10673,7 +10673,38 @@ components:
             - type: "null"
           description: |
             Per-attempt timing breakdown for the latest terminal attempt:
-            wall time plus the active inference/tool breakdown.
+            wall time plus the active inference/tool breakdown. Null while the
+            stage is still in flight; the live estimate is derived from
+            `live_inference_ms`, `live_tool_ms`, and any open bracket.
+        live_inference_ms:
+          type: integer
+          format: uint64
+          minimum: 0
+          default: 0
+          description: |
+            Inference time accumulated from closed brackets during the current
+            attempt. Live estimate only — the authoritative value arrives with
+            the terminal event and lands in `timing`. Excludes the currently
+            open bracket, whose span is measured from `inference.started_at`.
+          example: 78230
+        live_tool_ms:
+          type: integer
+          format: uint64
+          minimum: 0
+          default: 0
+          description: |
+            Tool time accumulated from closed tool batches during the current
+            attempt. A batch spans the first dispatched call through the
+            completion that drains the last outstanding one, so tools running
+            concurrently within a turn are counted once.
+          example: 7588
+        tool_batch:
+          oneOf:
+            - $ref: "#/components/schemas/StageToolBatchProjection"
+            - type: "null"
+          description: |
+            Open tool batch: when the batch started and which calls have not
+            yet reported completion.
         usage:
           $ref: "#/components/schemas/BilledTokenCounts"
         model:
@@ -10734,6 +10765,28 @@ components:
           $ref: "#/components/schemas/StageState"
           description: Lifecycle state of the stage projection.
 
+    StageToolBatchProjection:
+      description: >
+        One open tool batch: tool calls dispatched together that have not all
+        reported completion. `open_call_ids` is a set rather than a count so a
+        duplicated completion in a replayed log cannot drain the batch early.
+      type: object
+      required:
+        - started_at
+        - open_call_ids
+      properties:
+        started_at:
+          type: string
+          format: date-time
+          description: >
+            When the batch opened — the first dispatched call observed while no
+            other calls were outstanding.
+        open_call_ids:
+          type: array
+          items:
+            type: string
+          description: Calls dispatched but not yet completed, by tool call id.
+
     StageInferenceProjection:
       description: >
         One open inference bracket: a dispatched LLM request that has not yet
@@ -12244,6 +12297,12 @@ components:
         observed LLM request/stream elapsed time; `tool_time_ms` is tool or
         command execution elapsed time; `active_time_ms` equals
         `inference_time_ms + tool_time_ms`.
+
+        For a terminal stage these come from the worker's own stopwatch and are
+        authoritative. For a stage still in flight they are a live estimate
+        reconstructed from the event log, and `active_time_ms` is clamped to
+        `wall_time_ms`. The estimate is replaced by the authoritative
+        breakdown when the stage reaches a terminal event.
       type: object
       required:
         - wall_time_ms
@@ -12278,6 +12337,11 @@ components:
         Timing rollup for an entire run. Active fields sum work across stage
         visits, so `active_time_ms` can exceed `wall_time_ms` when parallel
         branches run concurrently.
+
+        For a running run, stages still in flight contribute a live estimate
+        rather than nothing, so wall and active both advance continuously.
+        Unlike `StageTiming`, active is not clamped to wall here — concurrent
+        branches can legitimately sum past run wall time.
       type: object
       required:
         - wall_time_ms
diff --git a/lib/apps/fabro-server/src/server/handler/billing.rs b/lib/apps/fabro-server/src/server/handler/billing.rs
index a1888713c..6cc4cbdde 100644
--- a/lib/apps/fabro-server/src/server/handler/billing.rs
+++ b/lib/apps/fabro-server/src/server/handler/billing.rs
@@ -175,7 +175,7 @@ fn live_billing_rows(projection: &RunProjection, now: DateTime<Utc>) -> Vec<Live
             index
         });
         let row = &mut rows[index];
-        let stage_timing = billing_stage_timing(stage, now);
+        let stage_timing = stage.live_timing(now);
         row.timing = row.timing.saturating_add(&stage_timing);
 
         if stage_id.visit() >= row.latest_visit {
@@ -188,20 +188,6 @@ fn live_billing_rows(projection: &RunProjection, now: DateTime<Utc>) -> Vec<Live
     rows
 }
 
-/// Per-visit timing for a stage. For terminal visits, the stored breakdown is
-/// used directly. For in-flight visits, fall back to the live wall-clock since
-/// `started_at` (no active breakdown yet — that is only finalized at terminal
-/// event time in v1).
-fn billing_stage_timing(stage: &StageProjection, now: DateTime<Utc>) -> StageTiming {
-    if let Some(timing) = stage.timing {
-        return timing;
-    }
-    if let Some(live_wall) = stage.live_wall_time_ms(now) {
-        return StageTiming::wall_only(live_wall);
-    }
-    StageTiming::default()
-}
-
 fn stage_has_billing_row(stage: &StageProjection) -> bool {
     stage.completion.is_some()
         || stage.timing.is_some()
diff --git a/lib/components/fabro-store/src/run_state.rs b/lib/components/fabro-store/src/run_state.rs
index 9ab1e2b2d..df05f84b3 100644
--- a/lib/components/fabro-store/src/run_state.rs
+++ b/lib/components/fabro-store/src/run_state.rs
@@ -449,7 +449,7 @@ impl RunProjectionReducer for RunProjection {
                     context_window.event_seq = Some(event.seq);
                     stage.context_window = Some(context_window);
                 }
-                close_inference_bracket(self, stored, props.visit, event.seq);
+                close_inference_bracket(self, stored, props.visit, event.seq, ts);
             }
             EventBody::AgentLlmStarted(props) => {
                 open_inference_bracket(self, stored, props, event.seq, ts);
@@ -478,10 +478,10 @@ impl RunProjectionReducer for RunProjection {
                 inference.first_output_kind = None;
             }
             EventBody::AgentError(props) => {
-                close_inference_bracket(self, stored, props.visit, event.seq);
+                close_inference_bracket(self, stored, props.visit, event.seq, ts);
             }
             EventBody::AgentSessionEnded(_) => {
-                close_inference_brackets_for_session(self, stored);
+                close_inference_brackets_for_session(self, stored, ts);
             }
             EventBody::AgentSessionActivated(props) => {
                 let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
@@ -497,7 +497,7 @@ impl RunProjectionReducer for RunProjection {
                     return Ok(());
                 };
                 stage.agent_control = AgentControlState::WaitingForSteer;
-                close_inference_bracket(self, stored, props.visit, event.seq);
+                close_inference_bracket(self, stored, props.visit, event.seq, ts);
             }
             EventBody::AgentSteeringInjected(props) => {
                 let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
@@ -746,6 +746,7 @@ impl RunProjectionReducer for RunProjection {
                 });
             }
             EventBody::AgentToolStarted(props) => {
+                let is_root_session = stored.parent_session_id.is_none();
                 let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
                 else {
                     return Ok(());
@@ -766,6 +767,22 @@ impl RunProjectionReducer for RunProjection {
                         projection.invoked = true;
                     }
                 }
+                // A subagent's tools run inside the root session's tool call,
+                // so the root batch already covers them. Timing them again
+                // would double-count that span.
+                if is_root_session {
+                    stage.open_tool_call(props.tool_call_id.clone(), ts);
+                }
+            }
+            EventBody::AgentToolCompleted(props) => {
+                if stored.parent_session_id.is_some() {
+                    return Ok(());
+                }
+                let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
+                else {
+                    return Ok(());
+                };
+                stage.close_tool_call(&props.tool_call_id, ts);
             }
             _ => {}
         }
@@ -1044,6 +1061,22 @@ fn matching_inference_slot<'a>(
     visit: u32,
     seq: u32,
 ) -> Option<&'a mut Option<StageInferenceProjection>> {
+    Some(&mut matching_inference_stage(state, stored, visit, seq)?.inference)
+}
+
+/// Resolve the stage owning a bracket this event is allowed to mutate,
+/// borrowing the whole projection so the caller can also fold elapsed time
+/// into the stage's live accumulators.
+///
+/// Same gating as [`matching_inference_slot`]: `None` for child-session
+/// events, for a stage with no open bracket, and for a bracket belonging to a
+/// different session (which is what post-failover events look like).
+fn matching_inference_stage<'a>(
+    state: &'a mut RunProjection,
+    stored: &RunEvent,
+    visit: u32,
+    seq: u32,
+) -> Option<&'a mut StageProjection> {
     if stored.parent_session_id.is_some() {
         return None;
     }
@@ -1053,7 +1086,7 @@ fn matching_inference_slot<'a>(
         .inference
         .as_ref()
         .is_some_and(|inference| inference.session_id == session_id);
-    opened_here.then_some(&mut stage.inference)
+    opened_here.then_some(stage)
 }
 
 /// Resolve the open inference bracket this event is allowed to mutate.
@@ -1066,11 +1099,37 @@ fn matching_inference_bracket<'a>(
     matching_inference_slot(state, stored, visit, seq)?.as_mut()
 }
 
-/// Close the bracket on a stage-addressed terminal event.
-fn close_inference_bracket(state: &mut RunProjection, stored: &RunEvent, visit: u32, seq: u32) {
-    if let Some(slot) = matching_inference_slot(state, stored, visit, seq) {
-        *slot = None;
-    }
+/// Close the bracket on a stage-addressed terminal event, folding its elapsed
+/// time into the stage's live inference accumulator.
+fn close_inference_bracket(
+    state: &mut RunProjection,
+    stored: &RunEvent,
+    visit: u32,
+    seq: u32,
+    ts: DateTime<Utc>,
+) {
+    let Some(stage) = matching_inference_stage(state, stored, visit, seq) else {
+        return;
+    };
+    close_bracket_on_stage(stage, ts);
+}
+
+/// Take the open bracket and add its span to `live_inference_ms`.
+///
+/// Retries inside the bracket are deliberately included: the in-process
+/// stopwatch counts a retried attempt's elapsed time as inference, and
+/// `agent.llm.retry` keeps the bracket open rather than reopening it.
+fn close_bracket_on_stage(stage: &mut StageProjection, ts: DateTime<Utc>) {
+    let Some(inference) = stage.inference.take() else {
+        return;
+    };
+    stage.accumulate_inference_ms(elapsed_ms(inference.started_at, ts));
+}
+
+/// Non-negative milliseconds between two instants, saturating at zero so a
+/// clock skew or an out-of-order replay cannot produce a negative span.
+fn elapsed_ms(from: DateTime<Utc>, to: DateTime<Utc>) -> u64 {
+    u64::try_from(to.signed_duration_since(from).num_milliseconds().max(0)).unwrap_or(0)
 }
 
 /// Close every bracket opened by the session that just ended.
@@ -1088,7 +1147,11 @@ fn close_inference_bracket(state: &mut RunProjection, stored: &RunEvent, visit:
 /// opened. Implemented as a normal stage lookup it would find no target and
 /// silently no-op, leaving the bracket open forever on exactly the path it
 /// exists to cover.
-fn close_inference_brackets_for_session(state: &mut RunProjection, stored: &RunEvent) {
+fn close_inference_brackets_for_session(
+    state: &mut RunProjection,
+    stored: &RunEvent,
+    ts: DateTime<Utc>,
+) {
     if stored.parent_session_id.is_some() {
         return;
     }
@@ -1101,7 +1164,7 @@ fn close_inference_brackets_for_session(state: &mut RunProjection, stored: &RunE
             .as_ref()
             .is_some_and(|inference| inference.session_id == session_id);
         if opened_here {
-            stage.inference = None;
+            close_bracket_on_stage(stage, ts);
         }
     }
 }
@@ -1417,18 +1480,17 @@ fn finalize_unfinished_stages_after_run_failed(
             continue;
         }
 
+        // Close any bracket still open so its span is not dropped on the
+        // floor when the live estimate is frozen into `timing` below.
+        close_bracket_on_stage(stage, timestamp);
+
+        // Freeze the live estimate before flipping to a terminal state:
+        // `live_timing` reads `effective_state` and would return wall-only
+        // once the stage no longer looks in-flight.
+        let frozen = stage.live_timing(timestamp);
         stage.state = terminal_state;
-        if stage.timing.is_none() {
-            if let Some(started_at) = stage.started_at {
-                let wall_time_ms = u64::try_from(
-                    timestamp
-                        .signed_duration_since(started_at)
-                        .num_milliseconds()
-                        .max(0),
-                )
-                .expect("non-negative milliseconds fit in u64");
-                stage.timing = Some(fabro_types::StageTiming::wall_only(wall_time_ms));
-            }
+        if stage.timing.is_none() && stage.started_at.is_some() {
+            stage.timing = Some(frozen);
         }
     }
 }
@@ -1560,6 +1622,373 @@ mod tests {
     use super::{RunProjection, RunProjectionReducer, build_summary};
     use crate::{Error, EventEnvelope, StageId};
 
+    /// Live accumulation of inference and tool time while a stage is in
+    /// flight. The finalized breakdown still arrives with the terminal event
+    /// and replaces these; these exist so a long-running stage is not reported
+    /// as doing no work.
+    mod live_active_accumulation {
+        use fabro_types::run_event::{
+            AgentLlmFirstOutputProps, AgentLlmRetryProps, AgentLlmStartedProps,
+            AgentToolCompletedProps, AgentToolStartedProps,
+        };
+        use fabro_types::{
+            LlmOutputKind, LlmRetryPhase, ModelRef, Speed, StageOutcome, StageProjection,
+        };
+
+        use super::*;
+
+        fn stage_id() -> StageId {
+            StageId::new("plan", 1)
+        }
+
+        fn agent_event(seq: u32, ts: &str, body: EventBody) -> EventEnvelope {
+            let mut event = test_stage_event_at(seq, ts, body, stage_id());
+            event.event.session_id = Some("session-1".to_string());
+            event
+        }
+
+        /// An event from a sub-agent session nested under the root session.
+        fn child_event(seq: u32, ts: &str, body: EventBody) -> EventEnvelope {
+            let mut event = agent_event(seq, ts, body);
+            event.event.session_id = Some("session-child".to_string());
+            event.event.parent_session_id = Some("session-1".to_string());
+            event
+        }
+
+        fn llm_started() -> EventBody {
+            EventBody::AgentLlmStarted(AgentLlmStartedProps {
+                requested_model: ModelRef {
+                    provider: "anthropic".parse().unwrap(),
+                    model_id: "claude-fable-5".into(),
+                    speed:    Some(Speed::Fast),
+                },
+                visit:           1,
+            })
+        }
+
+        fn tool_started(tool_call_id: &str) -> EventBody {
+            EventBody::AgentToolStarted(AgentToolStartedProps {
+                tool_name:         "Bash".to_string(),
+                tool_call_id:      tool_call_id.to_string(),
+                arguments:         json!({}),
+                visit:             1,
+                tool_call:         None,
+                turn_id:           None,
+                parent_message_id: None,
+            })
+        }
+
+        fn tool_completed(tool_call_id: &str) -> EventBody {
+            EventBody::AgentToolCompleted(AgentToolCompletedProps {
+                tool_name:    "Bash".to_string(),
+                tool_call_id: tool_call_id.to_string(),
+                output:       json!("ok"),
+                is_error:     false,
+                visit:        1,
+                tool_result:  None,
+                turn_id:      None,
+            })
+        }
+
+        fn agent_message() -> EventBody {
+            EventBody::AgentMessage(live_agent_message_props(live_counts(10, 5)))
+        }
+
+        fn started_state() -> RunProjection {
+            let mut state = initialized_projection();
+            state
+                .apply_event(&test_stage_event_at(
+                    1,
+                    "2026-04-07T12:00:00Z",
+                    EventBody::StageStarted(started_props()),
+                    stage_id(),
+                ))
+                .unwrap();
+            state
+        }
+
+        fn stage(state: &RunProjection) -> &StageProjection {
+            state.stage(&stage_id()).unwrap()
+        }
+
+        #[test]
+        fn closing_an_inference_bracket_accumulates_its_span() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(2, "2026-04-07T12:00:05Z", llm_started()))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    3,
+                    "2026-04-07T12:00:06Z",
+                    EventBody::AgentLlmFirstOutput(AgentLlmFirstOutputProps {
+                        kind:  LlmOutputKind::Text,
+                        visit: 1,
+                    }),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(4, "2026-04-07T12:00:12Z", agent_message()))
+                .unwrap();
+
+            // 12:00:05 -> 12:00:12; first_output is a marker, not the close.
+            assert_eq!(stage(&state).live_inference_ms, 7_000);
+            assert!(stage(&state).inference.is_none());
+        }
+
+        #[test]
+        fn concurrent_tool_calls_count_once_not_per_call() {
+            let mut state = started_state();
+            for (seq, id) in [(2, "call-a"), (3, "call-b"), (4, "call-c")] {
+                state
+                    .apply_event(&agent_event(seq, "2026-04-07T12:00:00Z", tool_started(id)))
+                    .unwrap();
+            }
+            // All three finish 10s later. Summing per-call spans would report
+            // 30s; the batch actually occupied 10s of wall time.
+            for (seq, id) in [(5, "call-a"), (6, "call-b"), (7, "call-c")] {
+                state
+                    .apply_event(&agent_event(
+                        seq,
+                        "2026-04-07T12:00:10Z",
+                        tool_completed(id),
+                    ))
+                    .unwrap();
+            }
+
+            assert_eq!(stage(&state).live_tool_ms, 10_000);
+            assert!(stage(&state).tool_batch.is_none());
+        }
+
+        #[test]
+        fn a_batch_stays_open_until_its_last_call_reports() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(
+                    2,
+                    "2026-04-07T12:00:00Z",
+                    tool_started("call-a"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    3,
+                    "2026-04-07T12:00:02Z",
+                    tool_started("call-b"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    4,
+                    "2026-04-07T12:00:05Z",
+                    tool_completed("call-a"),
+                ))
+                .unwrap();
+
+            assert_eq!(
+                stage(&state).live_tool_ms,
+                0,
+                "batch must not close while call-b is outstanding"
+            );
+
+            state
+                .apply_event(&agent_event(
+                    5,
+                    "2026-04-07T12:00:09Z",
+                    tool_completed("call-b"),
+                ))
+                .unwrap();
+
+            // Measured from the batch open, not from the last call's start.
+            assert_eq!(stage(&state).live_tool_ms, 9_000);
+        }
+
+        #[test]
+        fn successive_batches_accumulate() {
+            let mut state = started_state();
+            for (seq, ts, body) in [
+                (2, "2026-04-07T12:00:00Z", tool_started("call-a")),
+                (3, "2026-04-07T12:00:04Z", tool_completed("call-a")),
+                (4, "2026-04-07T12:00:10Z", tool_started("call-b")),
+                (5, "2026-04-07T12:00:16Z", tool_completed("call-b")),
+            ] {
+                state.apply_event(&agent_event(seq, ts, body)).unwrap();
+            }
+
+            assert_eq!(stage(&state).live_tool_ms, 10_000);
+        }
+
+        #[test]
+        fn a_duplicate_completion_does_not_drain_the_batch_early() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(
+                    2,
+                    "2026-04-07T12:00:00Z",
+                    tool_started("call-a"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    3,
+                    "2026-04-07T12:00:00Z",
+                    tool_started("call-b"),
+                ))
+                .unwrap();
+            // call-a reports twice, as a replayed or duplicated log can.
+            state
+                .apply_event(&agent_event(
+                    4,
+                    "2026-04-07T12:00:03Z",
+                    tool_completed("call-a"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    5,
+                    "2026-04-07T12:00:04Z",
+                    tool_completed("call-a"),
+                ))
+                .unwrap();
+
+            assert_eq!(stage(&state).live_tool_ms, 0);
+            assert!(stage(&state).tool_batch.is_some());
+        }
+
+        #[test]
+        fn subagent_tool_calls_do_not_double_count_against_the_root_batch() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(
+                    2,
+                    "2026-04-07T12:00:00Z",
+                    tool_started("root-call"),
+                ))
+                .unwrap();
+            // The sub-agent's own tools run inside the root call's span.
+            state
+                .apply_event(&child_event(
+                    3,
+                    "2026-04-07T12:00:01Z",
+                    tool_started("child-call"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&child_event(
+                    4,
+                    "2026-04-07T12:00:02Z",
+                    tool_completed("child-call"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    5,
+                    "2026-04-07T12:00:08Z",
+                    tool_completed("root-call"),
+                ))
+                .unwrap();
+
+            assert_eq!(stage(&state).live_tool_ms, 8_000);
+        }
+
+        #[test]
+        fn session_end_accumulates_rather_than_discarding_the_bracket() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(2, "2026-04-07T12:00:05Z", llm_started()))
+                .unwrap();
+
+            let mut ended = test_stage_event_at(
+                3,
+                "2026-04-07T12:00:20Z",
+                EventBody::AgentSessionEnded(AgentSessionEndedProps {}),
+                stage_id(),
+            );
+            ended.event.session_id = Some("session-1".to_string());
+            state.apply_event(&ended).unwrap();
+
+            assert_eq!(stage(&state).live_inference_ms, 15_000);
+            assert!(stage(&state).inference.is_none());
+        }
+
+        #[test]
+        fn a_foreign_session_close_leaves_the_bracket_and_accumulator_alone() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(2, "2026-04-07T12:00:05Z", llm_started()))
+                .unwrap();
+
+            // Post-failover: a new session emits the message, so the old
+            // bracket is not this event's to close or bill.
+            let mut foreign =
+                test_stage_event_at(3, "2026-04-07T12:00:20Z", agent_message(), stage_id());
+            foreign.event.session_id = Some("session-2".to_string());
+            state.apply_event(&foreign).unwrap();
+
+            assert_eq!(stage(&state).live_inference_ms, 0);
+            assert!(stage(&state).inference.is_some());
+        }
+
+        #[test]
+        fn a_retry_keeps_accumulating_within_one_bracket() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(2, "2026-04-07T12:00:00Z", llm_started()))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    3,
+                    "2026-04-07T12:00:04Z",
+                    EventBody::AgentLlmRetry(AgentLlmRetryProps {
+                        provider:   "anthropic".to_string(),
+                        model:      "claude-fable-5".to_string(),
+                        attempt:    0,
+                        delay_secs: 0.0,
+                        error:      json!({ "kind": "stream" }),
+                        phase:      Some(LlmRetryPhase::Consume),
+                        visit:      1,
+                    }),
+                ))
+                .unwrap();
+            state
+                .apply_event(&agent_event(4, "2026-04-07T12:00:11Z", agent_message()))
+                .unwrap();
+
+            // The whole bracket counts, retry included, matching the
+            // in-process stopwatch.
+            assert_eq!(stage(&state).live_inference_ms, 11_000);
+            assert_eq!(stage(&state).inference, None);
+        }
+
+        #[test]
+        fn stage_completion_replaces_the_live_estimate_with_finalized_timing() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(2, "2026-04-07T12:00:00Z", llm_started()))
+                .unwrap();
+            state
+                .apply_event(&agent_event(3, "2026-04-07T12:00:09Z", agent_message()))
+                .unwrap();
+            assert_eq!(stage(&state).live_inference_ms, 9_000);
+
+            state
+                .apply_event(&test_stage_event_at(
+                    4,
+                    "2026-04-07T12:00:10Z",
+                    EventBody::StageCompleted(completed_props(10_000, StageOutcome::Succeeded)),
+                    stage_id(),
+                ))
+                .unwrap();
+
+            let stage = stage(&state);
+            assert_eq!(
+                stage.live_timing(test_dt("2026-04-07T12:30:00Z")),
+                stage.timing.unwrap(),
+                "a terminal stage reports its finalized breakdown, not a live estimate"
+            );
+        }
+    }
+
     fn test_event(seq: u32, body: EventBody, node_id: Option<&str>) -> EventEnvelope {
         let event = RunEvent {
             id: format!("evt-{seq}"),
diff --git a/lib/foundation/fabro-types/src/run_projection.rs b/lib/foundation/fabro-types/src/run_projection.rs
index 027cce2fc..0576d32f6 100644
--- a/lib/foundation/fabro-types/src/run_projection.rs
+++ b/lib/foundation/fabro-types/src/run_projection.rs
@@ -1,5 +1,5 @@
 use std::borrow::Cow;
-use std::collections::{BTreeMap, HashMap};
+use std::collections::{BTreeMap, BTreeSet, HashMap};
 use std::num::NonZeroU32;
 
 use chrono::{DateTime, Utc};
@@ -354,10 +354,31 @@ pub struct StageProjection {
     /// immutable projections under their own `StageId`s.
     ///
     /// `None` for stages still in flight (`started_at` is set but no terminal
-    /// event has been observed yet). For live wall-time ticking, the UI uses
-    /// `started_at`; once terminal this carries the finalized breakdown.
+    /// event has been observed yet). For a live breakdown while in flight, use
+    /// [`StageProjection::live_timing`]; once terminal this carries the
+    /// finalized, authoritative breakdown.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub timing:                Option<StageTiming>,
+    /// Inference time accumulated from closed brackets during this attempt.
+    ///
+    /// Live estimate only: the authoritative value arrives with the terminal
+    /// event and lands in `timing`. Excludes the currently-open bracket, which
+    /// [`StageProjection::live_timing`] adds from `inference.started_at`.
+    #[serde(default, skip_serializing_if = "is_zero_ms")]
+    pub live_inference_ms:     u64,
+    /// Tool time accumulated from closed tool batches during this attempt.
+    ///
+    /// A batch spans the first `agent.tool.started` with no outstanding calls
+    /// through the `agent.tool.completed` that drains the last one, so tools
+    /// running concurrently within a turn are counted once. This matches how
+    /// the in-process stopwatch brackets `execute_tool_calls`; summing
+    /// per-call durations would over-count parallel tool use.
+    #[serde(default, skip_serializing_if = "is_zero_ms")]
+    pub live_tool_ms:          u64,
+    /// Open tool batch for this stage: when the current batch started, and the
+    /// `tool_call_id`s that have not yet reported completion.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tool_batch:            Option<StageToolBatchProjection>,
     #[serde(default)]
     pub usage:                 BilledTokenCounts,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -395,6 +416,30 @@ pub struct StageProjection {
     pub state:                 StageState,
 }
 
+/// Serde guard so zero-valued live accumulators stay off the wire.
+#[allow(
+    clippy::trivially_copy_pass_by_ref,
+    reason = "serde skip_serializing_if predicates receive fields by reference"
+)]
+fn is_zero_ms(value: &u64) -> bool {
+    *value == 0
+}
+
+/// One open tool batch: tool calls dispatched together that have not all
+/// reported completion.
+///
+/// `open_call_ids` is a set rather than a count because `agent.tool.completed`
+/// identifies its call by id, and a projection replaying a truncated or
+/// duplicated log must not let a repeated completion drain the batch early.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct StageToolBatchProjection {
+    /// When the batch opened — the first `agent.tool.started` observed while
+    /// no other calls were outstanding.
+    pub started_at:    DateTime<Utc>,
+    /// Calls dispatched but not yet completed, by `tool_call_id`.
+    pub open_call_ids: BTreeSet<String>,
+}
+
 /// One open inference bracket: a dispatched LLM request that has not yet
 /// produced a message, error, or interrupt.
 #[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
@@ -506,6 +551,9 @@ impl StageProjection {
             response: None,
             completion: None,
             timing: None,
+            live_inference_ms: 0,
+            live_tool_ms: 0,
+            tool_batch: None,
             usage: BilledTokenCounts::default(),
             model: None,
             root_agent_todos: None,
@@ -563,6 +611,118 @@ impl StageProjection {
         self.timing.map(|timing| timing.wall_time_ms)
     }
 
+    /// Live timing breakdown in milliseconds — the active-time twin of
+    /// [`Self::live_wall_time_ms`].
+    ///
+    /// Once terminal, returns the stored `timing` unchanged: the finalized
+    /// breakdown comes from the worker's own stopwatch and is authoritative.
+    ///
+    /// While in flight, returns an estimate reconstructed from the event log:
+    /// accumulated closed brackets plus whatever bracket is open right now.
+    /// The estimate is per-handler, because only agent stages emit brackets at
+    /// all:
+    ///
+    /// - `Agent` — accumulated inference and tool brackets, plus the open
+    ///   inference bracket and open tool batch.
+    /// - `Prompt` — one inference call spanning the stage, so elapsed time
+    ///   since `started_at` counts as inference. Matches the finalized
+    ///   `active_only(inference, 0)`.
+    /// - `Command` — the command *is* the work, so elapsed time counts as tool.
+    ///   Matches the finalized `active_only(0, duration_ms)`.
+    /// - Everything else — zero. Waiting on a human, a timer, a condition, or
+    ///   child branches is wall time, not active time.
+    ///
+    /// Active is clamped to wall. A worker killed mid-turn leaves its bracket
+    /// open forever (see [`StageInferenceProjection`]), and without the clamp
+    /// that bracket would tick up without bound. The clamp does not need to
+    /// know the worker died: a stage cannot have been active longer than it
+    /// has existed. `watchdog.timeout` remains the authority on whether a run
+    /// is actually stuck.
+    #[must_use]
+    pub fn live_timing(&self, now: DateTime<Utc>) -> StageTiming {
+        if let Some(timing) = self.timing {
+            return timing;
+        }
+
+        let wall_time_ms = self.live_wall_time_ms(now).unwrap_or(0);
+        let elapsed = |since: DateTime<Utc>| {
+            u64::try_from(now.signed_duration_since(since).num_milliseconds().max(0)).unwrap_or(0)
+        };
+
+        // `handler` is absent on projections built from events written before
+        // stage execution identity. Treat those as agent stages, matching
+        // `StageHandler::from_handler_type`: the accumulators below are only
+        // ever populated by agent events, so a legacy non-agent stage still
+        // reads zero rather than being credited work it never did.
+        let handler = self.handler.unwrap_or(StageHandler::Agent);
+        let (inference_time_ms, tool_time_ms) = match handler {
+            StageHandler::Agent => {
+                let open_inference = self
+                    .inference
+                    .as_ref()
+                    .map_or(0, |inference| elapsed(inference.started_at));
+                let open_tool = self
+                    .tool_batch
+                    .as_ref()
+                    .map_or(0, |batch| elapsed(batch.started_at));
+                (
+                    self.live_inference_ms.saturating_add(open_inference),
+                    self.live_tool_ms.saturating_add(open_tool),
+                )
+            }
+            StageHandler::Prompt => (wall_time_ms, 0),
+            StageHandler::Command => (0, wall_time_ms),
+            // Waiting on a human, a timer, a condition, or child branches is
+            // wall time, not active time.
+            StageHandler::Human
+            | StageHandler::Wait
+            | StageHandler::Conditional
+            | StageHandler::Parallel
+            | StageHandler::ParallelFanIn
+            | StageHandler::StackManagerLoop
+            | StageHandler::Start
+            | StageHandler::Exit => (0, 0),
+        };
+
+        StageTiming::new(wall_time_ms, inference_time_ms, tool_time_ms).clamped_to_wall()
+    }
+
+    /// Fold a closed inference bracket into the live accumulator.
+    pub fn accumulate_inference_ms(&mut self, elapsed_ms: u64) {
+        self.live_inference_ms = self.live_inference_ms.saturating_add(elapsed_ms);
+    }
+
+    /// Record a dispatched tool call, opening a batch if none is outstanding.
+    pub fn open_tool_call(&mut self, tool_call_id: String, started_at: DateTime<Utc>) {
+        self.tool_batch
+            .get_or_insert_with(|| StageToolBatchProjection {
+                started_at,
+                open_call_ids: BTreeSet::new(),
+            })
+            .open_call_ids
+            .insert(tool_call_id);
+    }
+
+    /// Retire a tool call. Folds the batch into the live accumulator once the
+    /// last outstanding call reports, so concurrent calls count once.
+    pub fn close_tool_call(&mut self, tool_call_id: &str, now: DateTime<Utc>) {
+        let Some(batch) = self.tool_batch.as_mut() else {
+            return;
+        };
+        batch.open_call_ids.remove(tool_call_id);
+        if !batch.open_call_ids.is_empty() {
+            return;
+        }
+        let elapsed = u64::try_from(
+            now.signed_duration_since(batch.started_at)
+                .num_milliseconds()
+                .max(0),
+        )
+        .unwrap_or(0);
+        self.live_tool_ms = self.live_tool_ms.saturating_add(elapsed);
+        self.tool_batch = None;
+    }
+
     /// Begin a new automatic attempt within this stage execution: clear every
     /// per-attempt field so prior-attempt data does not leak, then record
     /// `started_at` and `state = Running`. Preserves `first_event_seq`
@@ -709,10 +869,13 @@ impl RunProjection {
     /// terminal conclusion yet.
     ///
     /// Run-level wall time ticks from `run.started` to `now`. Active time sums
-    /// inference and tool timing from stages that have already emitted a
-    /// terminal stage event. Stage projections do not currently track live
-    /// inference/tool time while a stage is still running, so active time steps
-    /// forward when each stage completes while wall time advances continuously.
+    /// [`StageProjection::live_timing`] across every stage, so an in-flight
+    /// stage contributes its live estimate rather than nothing — both halves
+    /// advance continuously. Terminal stages contribute their finalized,
+    /// authoritative breakdown.
+    ///
+    /// Active is not clamped to run wall time here: concurrent branches can
+    /// legitimately sum past it. The clamp applies per stage.
     #[must_use]
     pub fn live_run_timing(&self, now: DateTime<Utc>) -> Option<RunTiming> {
         let start = self.start.as_ref()?;
@@ -720,7 +883,7 @@ impl RunProjection {
         let active = self
             .stages
             .values()
-            .filter_map(|stage| stage.timing)
+            .map(|stage| stage.live_timing(now))
             .fold(RunTiming::default(), |acc, timing| {
                 acc.saturating_add(&RunTiming::from(timing))
             });
@@ -971,3 +1134,286 @@ mod iter_stages_tests {
         }
     }
 }
+
+#[cfg(test)]
+mod live_timing_tests {
+    use std::collections::HashMap;
+    use std::num::NonZeroU32;
+
+    use chrono::{DateTime, TimeZone, Utc};
+
+    use super::{RunProjection, StageToolBatchProjection};
+    use crate::{
+        Graph, ModelRef, RunId, RunSpec, StageHandler, StageInferenceProjection, StageProjection,
+        StageState, StageTiming, StartRecord, WorkflowSettings, test_support,
+    };
+
+    fn seq(n: u32) -> NonZeroU32 {
+        NonZeroU32::new(n).unwrap()
+    }
+
+    fn at(seconds: i64) -> DateTime<Utc> {
+        Utc.timestamp_opt(1_700_000_000 + seconds, 0).unwrap()
+    }
+
+    fn projection() -> RunProjection {
+        RunProjection::new(
+            "Test run".to_string(),
+            RunSpec {
+                run_id:           RunId::new(),
+                settings:         WorkflowSettings::default(),
+                graph:            Graph::new("test"),
+                graph_source:     None,
+                workflow_slug:    None,
+                automation:       None,
+                source_directory: None,
+                labels:           HashMap::default(),
+                provenance:       test_support::test_run_provenance(),
+                manifest_blob:    None,
+                definition_blob:  None,
+                git:              None,
+                fork_source_ref:  None,
+            },
+            at(0),
+        )
+    }
+
+    /// In-flight stage that started at `at(0)`.
+    fn running(handler: StageHandler) -> StageProjection {
+        let mut stage = StageProjection::new(seq(1));
+        stage.handler = Some(handler);
+        stage.started_at = Some(at(0));
+        stage.state = StageState::Running;
+        stage
+    }
+
+    fn open_bracket(started_at: DateTime<Utc>) -> StageInferenceProjection {
+        StageInferenceProjection {
+            session_id: "session-1".to_string(),
+            started_at,
+            requested_model: ModelRef {
+                provider: "anthropic".parse().unwrap(),
+                model_id: "claude-sonnet-5".into(),
+                speed:    None,
+            },
+            first_output_at: None,
+            first_output_kind: None,
+            retries: 0,
+        }
+    }
+
+    #[test]
+    fn terminal_stage_returns_stored_timing_unchanged() {
+        let mut stage = running(StageHandler::Agent);
+        stage.state = StageState::Succeeded;
+        stage.timing = Some(StageTiming::new(90_000, 78_000, 7_000));
+        // Live accumulators are stale leftovers; the finalized value wins.
+        stage.live_inference_ms = 5;
+        stage.live_tool_ms = 5;
+
+        assert_eq!(
+            stage.live_timing(at(600)),
+            StageTiming::new(90_000, 78_000, 7_000)
+        );
+    }
+
+    #[test]
+    fn agent_stage_sums_accumulators_and_open_brackets() {
+        let mut stage = running(StageHandler::Agent);
+        stage.live_inference_ms = 30_000;
+        stage.live_tool_ms = 5_000;
+        // Inference open for 20s, tools open for 10s, at t=120s.
+        stage.inference = Some(open_bracket(at(100)));
+        stage.tool_batch = Some(StageToolBatchProjection {
+            started_at:    at(110),
+            open_call_ids: ["call-1".to_string()].into_iter().collect(),
+        });
+
+        assert_eq!(
+            stage.live_timing(at(120)),
+            StageTiming::new(120_000, 50_000, 15_000)
+        );
+    }
+
+    #[test]
+    fn agent_stage_without_brackets_reports_only_accumulators() {
+        let mut stage = running(StageHandler::Agent);
+        stage.live_inference_ms = 30_000;
+        stage.live_tool_ms = 5_000;
+
+        assert_eq!(
+            stage.live_timing(at(120)),
+            StageTiming::new(120_000, 30_000, 5_000)
+        );
+    }
+
+    #[test]
+    fn prompt_stage_counts_elapsed_as_inference() {
+        let stage = running(StageHandler::Prompt);
+
+        assert_eq!(
+            stage.live_timing(at(45)),
+            StageTiming::new(45_000, 45_000, 0)
+        );
+    }
+
+    #[test]
+    fn command_stage_counts_elapsed_as_tool() {
+        let stage = running(StageHandler::Command);
+
+        assert_eq!(
+            stage.live_timing(at(45)),
+            StageTiming::new(45_000, 0, 45_000)
+        );
+    }
+
+    #[test]
+    fn waiting_handlers_report_wall_time_with_zero_active() {
+        for handler in [
+            StageHandler::Human,
+            StageHandler::Wait,
+            StageHandler::Conditional,
+            StageHandler::Parallel,
+            StageHandler::ParallelFanIn,
+            StageHandler::StackManagerLoop,
+            StageHandler::Start,
+            StageHandler::Exit,
+        ] {
+            let stage = running(handler);
+            let timing = stage.live_timing(at(600));
+
+            assert_eq!(
+                timing,
+                StageTiming::new(600_000, 0, 0),
+                "{handler} should report wall time only"
+            );
+        }
+    }
+
+    #[test]
+    fn open_bracket_from_a_killed_worker_is_clamped_to_wall() {
+        let mut stage = running(StageHandler::Agent);
+        // Bracket opened before the stage even started — the pathological
+        // shape a killed worker leaves behind. Without the clamp this would
+        // report 700s of inference against 600s of wall.
+        stage.inference = Some(open_bracket(at(-100)));
+
+        let timing = stage.live_timing(at(600));
+
+        assert_eq!(timing.wall_time_ms, 600_000);
+        assert_eq!(timing.active_time_ms, 600_000);
+    }
+
+    #[test]
+    fn clamping_preserves_the_inference_tool_split() {
+        let mut stage = running(StageHandler::Agent);
+        // 3:1 inference:tool, totalling 200s of active against 100s of wall.
+        stage.live_inference_ms = 150_000;
+        stage.live_tool_ms = 50_000;
+
+        let timing = stage.live_timing(at(100));
+
+        assert_eq!(timing.wall_time_ms, 100_000);
+        assert_eq!(timing.active_time_ms, 100_000);
+        assert_eq!(timing.inference_time_ms, 75_000);
+        assert_eq!(timing.tool_time_ms, 25_000);
+    }
+
+    #[test]
+    fn live_run_timing_counts_in_flight_stages_not_just_terminal_ones() {
+        // The shape that motivated this change: two finished stages and one
+        // long-running agent stage that had been active nearly the whole run.
+        let mut projection = projection();
+        projection.start = Some(StartRecord {
+            start_time: at(0),
+            run_branch: None,
+            base_sha:   None,
+        });
+
+        let baseline = projection.stage_entry("baseline", 1, seq(1));
+        baseline.handler = Some(StageHandler::Command);
+        baseline.state = StageState::Succeeded;
+        baseline.timing = Some(StageTiming::new(42_666, 0, 42_663));
+
+        let assess = projection.stage_entry("assess", 1, seq(2));
+        assess.handler = Some(StageHandler::Agent);
+        assess.state = StageState::Succeeded;
+        assess.timing = Some(StageTiming::new(86_025, 78_230, 7_588));
+
+        let plan = projection.stage_entry("plan", 1, seq(3));
+        plan.handler = Some(StageHandler::Agent);
+        plan.started_at = Some(at(146));
+        plan.state = StageState::Running;
+        plan.live_inference_ms = 700_000;
+        plan.live_tool_ms = 150_000;
+
+        let timing = projection.live_run_timing(at(1_013)).unwrap();
+
+        assert_eq!(timing.wall_time_ms, 1_013_000);
+        assert_eq!(timing.inference_time_ms, 778_230);
+        assert_eq!(timing.tool_time_ms, 200_251);
+        // Before this change the in-flight stage contributed nothing and the
+        // run reported 128,481 ms of active time against 1,013,000 ms of wall.
+        assert_eq!(timing.active_time_ms, 978_481);
+    }
+
+    #[test]
+    fn live_run_timing_may_exceed_run_wall_when_branches_overlap() {
+        let mut projection = projection();
+        projection.start = Some(StartRecord {
+            start_time: at(0),
+            run_branch: None,
+            base_sha:   None,
+        });
+
+        for (index, node) in ["branch-a", "branch-b", "branch-c"].iter().enumerate() {
+            let stage = projection.stage_entry(node, 1, seq(u32::try_from(index).unwrap() + 1));
+            stage.handler = Some(StageHandler::Agent);
+            stage.state = StageState::Succeeded;
+            stage.timing = Some(StageTiming::new(60_000, 60_000, 0));
+        }
+
+        let timing = projection.live_run_timing(at(60)).unwrap();
+
+        assert_eq!(timing.wall_time_ms, 60_000);
+        assert_eq!(
+            timing.active_time_ms, 180_000,
+            "concurrent branches legitimately sum past run wall time"
+        );
+    }
+}
+
+#[cfg(test)]
+mod live_timing_legacy_tests {
+    use chrono::{DateTime, TimeZone, Utc};
+
+    use crate::{StageProjection, StageState, StageTiming, first_event_seq};
+
+    fn at(seconds: i64) -> DateTime<Utc> {
+        Utc.timestamp_opt(1_700_000_000 + seconds, 0).unwrap()
+    }
+
+    #[test]
+    fn a_legacy_stage_without_a_recorded_handler_uses_its_accumulators() {
+        let mut stage = StageProjection::new(first_event_seq(1));
+        stage.handler = None;
+        stage.started_at = Some(at(0));
+        stage.state = StageState::Running;
+        stage.live_inference_ms = 30_000;
+
+        assert_eq!(
+            stage.live_timing(at(120)),
+            StageTiming::new(120_000, 30_000, 0)
+        );
+    }
+
+    #[test]
+    fn a_legacy_stage_with_no_accumulators_reports_no_active_time() {
+        let mut stage = StageProjection::new(first_event_seq(1));
+        stage.handler = None;
+        stage.started_at = Some(at(0));
+        stage.state = StageState::Running;
+
+        assert_eq!(stage.live_timing(at(120)), StageTiming::new(120_000, 0, 0));
+    }
+}
diff --git a/lib/foundation/fabro-types/src/timing.rs b/lib/foundation/fabro-types/src/timing.rs
index 0d1e555e8..4fe45a36f 100644
--- a/lib/foundation/fabro-types/src/timing.rs
+++ b/lib/foundation/fabro-types/src/timing.rs
@@ -62,6 +62,32 @@ impl StageTiming {
         Self::new(0, inference_time_ms, tool_time_ms)
     }
 
+    /// Scale the breakdown down so `active_time_ms` does not exceed
+    /// `wall_time_ms`, preserving the inference/tool ratio.
+    ///
+    /// Only meaningful for live estimates of a single in-flight stage, where
+    /// an open bracket left behind by a killed worker would otherwise tick up
+    /// without bound. Finalized timings come from the worker's stopwatch and
+    /// already satisfy the invariant.
+    ///
+    /// Deliberately *not* applied at run level: concurrent branches can
+    /// legitimately sum past run wall time.
+    #[must_use]
+    pub fn clamped_to_wall(&self) -> Self {
+        if self.active_time_ms <= self.wall_time_ms {
+            return *self;
+        }
+        // Preserve the split rather than truncating one side, so a clamped
+        // stage still shows where its time went. Widen for the multiply: the
+        // quotient is bounded by `wall_time_ms` because `active_time_ms`
+        // exceeds it here, so it always fits back into u64.
+        let scaled = u128::from(self.inference_time_ms) * u128::from(self.wall_time_ms)
+            / u128::from(self.active_time_ms);
+        let inference_time_ms = u64::try_from(scaled).unwrap_or(self.wall_time_ms);
+        let tool_time_ms = self.wall_time_ms.saturating_sub(inference_time_ms);
+        Self::new(self.wall_time_ms, inference_time_ms, tool_time_ms)
+    }
+
     /// Sum two timings field-by-field. Used to aggregate visits of one node
     /// and to accumulate run-level rollups.
     #[must_use]
diff --git a/lib/packages/fabro-api-client/src/.openapi-generator/FILES b/lib/packages/fabro-api-client/src/.openapi-generator/FILES
index e3a1a7c0e..4ae265b76 100644
--- a/lib/packages/fabro-api-client/src/.openapi-generator/FILES
+++ b/lib/packages/fabro-api-client/src/.openapi-generator/FILES
@@ -487,6 +487,7 @@ models/stage-projection.ts
 models/stage-state.ts
 models/stage-summary.ts
 models/stage-timing.ts
+models/stage-tool-batch-projection.ts
 models/start-record.ts
 models/start-run-request.ts
 models/steer-run-request.ts
diff --git a/lib/packages/fabro-api-client/src/models/index.ts b/lib/packages/fabro-api-client/src/models/index.ts
index 5cd29601d..029a2d3ab 100644
--- a/lib/packages/fabro-api-client/src/models/index.ts
+++ b/lib/packages/fabro-api-client/src/models/index.ts
@@ -457,6 +457,7 @@ export * from './stage-projection';
 export * from './stage-state';
 export * from './stage-summary';
 export * from './stage-timing';
+export * from './stage-tool-batch-projection';
 export * from './start-record';
 export * from './start-run-request';
 export * from './steer-run-request';
diff --git a/lib/packages/fabro-api-client/src/models/run-timing.ts b/lib/packages/fabro-api-client/src/models/run-timing.ts
index fb585b0e9..d4fa62262 100644
--- a/lib/packages/fabro-api-client/src/models/run-timing.ts
+++ b/lib/packages/fabro-api-client/src/models/run-timing.ts
@@ -15,7 +15,7 @@
 
 
 /**
- * Timing rollup for an entire run. Active fields sum work across stage visits, so `active_time_ms` can exceed `wall_time_ms` when parallel branches run concurrently.
+ * Timing rollup for an entire run. Active fields sum work across stage visits, so `active_time_ms` can exceed `wall_time_ms` when parallel branches run concurrently.  For a running run, stages still in flight contribute a live estimate rather than nothing, so wall and active both advance continuously. Unlike `StageTiming`, active is not clamped to wall here — concurrent branches can legitimately sum past run wall time.
  */
 export interface RunTiming {
     'wall_time_ms': number;
diff --git a/lib/packages/fabro-api-client/src/models/stage-projection.ts b/lib/packages/fabro-api-client/src/models/stage-projection.ts
index 57fd342ca..8cb88c0ac 100644
--- a/lib/packages/fabro-api-client/src/models/stage-projection.ts
+++ b/lib/packages/fabro-api-client/src/models/stage-projection.ts
@@ -60,6 +60,9 @@ import type { StageState } from './stage-state';
 import type { StageTiming } from './stage-timing';
 // May contain unused imports in some cases
 // @ts-ignore
+import type { StageToolBatchProjection } from './stage-tool-batch-projection';
+// May contain unused imports in some cases
+// @ts-ignore
 import type { SubAgentProjection } from './sub-agent-projection';
 // May contain unused imports in some cases
 // @ts-ignore
@@ -96,6 +99,15 @@ export interface StageProjection {
      */
     'started_at'?: string | null;
     'timing'?: StageTiming | null;
+    /**
+     * Inference time accumulated from closed brackets during the current attempt. Live estimate only — the authoritative value arrives with the terminal event and lands in `timing`. Excludes the currently open bracket, whose span is measured from `inference.started_at`.
+     */
+    'live_inference_ms'?: number;
+    /**
+     * Tool time accumulated from closed tool batches during the current attempt. A batch spans the first dispatched call through the completion that drains the last outstanding one, so tools running concurrently within a turn are counted once.
+     */
+    'live_tool_ms'?: number;
+    'tool_batch'?: StageToolBatchProjection | null;
     'usage': BilledTokenCounts;
     'model'?: BillingModelRef | null;
     'todos'?: TodoListProjection | null;
diff --git a/lib/packages/fabro-api-client/src/models/stage-timing.ts b/lib/packages/fabro-api-client/src/models/stage-timing.ts
index d9915c409..5bdd92bb4 100644
--- a/lib/packages/fabro-api-client/src/models/stage-timing.ts
+++ b/lib/packages/fabro-api-client/src/models/stage-timing.ts
@@ -15,7 +15,7 @@
 
 
 /**
- * Timing breakdown for one stage visit. Fields are all milliseconds. `wall_time_ms` is elapsed clock time; `inference_time_ms` is Fabro- observed LLM request/stream elapsed time; `tool_time_ms` is tool or command execution elapsed time; `active_time_ms` equals `inference_time_ms + tool_time_ms`.
+ * Timing breakdown for one stage visit. Fields are all milliseconds. `wall_time_ms` is elapsed clock time; `inference_time_ms` is Fabro- observed LLM request/stream elapsed time; `tool_time_ms` is tool or command execution elapsed time; `active_time_ms` equals `inference_time_ms + tool_time_ms`.  For a terminal stage these come from the worker\'s own stopwatch and are authoritative. For a stage still in flight they are a live estimate reconstructed from the event log, and `active_time_ms` is clamped to `wall_time_ms`. The estimate is replaced by the authoritative breakdown when the stage reaches a terminal event.
  */
 export interface StageTiming {
     'wall_time_ms': number;
diff --git a/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts b/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
new file mode 100644
index 000000000..a6bd7718c
--- /dev/null
+++ b/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
@@ -0,0 +1,29 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Fabro Run API
+ * HTTP API for managing Fabro workflow run executions.
+ *
+ * The version of the OpenAPI document: 0.1.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+
+/**
+ * One open tool batch: tool calls dispatched together that have not all reported completion. `open_call_ids` is a set rather than a count so a duplicated completion in a replayed log cannot drain the batch early.
+ */
+export interface StageToolBatchProjection {
+    /**
+     * When the batch opened — the first dispatched call observed while no other calls were outstanding.
+     */
+    'started_at': string;
+    /**
+     * Calls dispatched but not yet completed, by tool call id.
+     */
+    'open_call_ids': Array<string>;
+}

From dd9f75fb05d55b29b5f2db10d8e0153acc0e95eb Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Sat, 25 Jul 2026 23:43:43 -0400
Subject: [PATCH 02/36] fix(timing): harden live active projections

---
 apps/fabro-web/app/lib/queries.ts             |  12 +-
 apps/fabro-web/app/lib/query-keys.test.ts     |  15 +-
 apps/fabro-web/app/lib/run-events.test.tsx    |  20 ++
 apps/fabro-web/app/lib/run-events.ts          |  29 ++-
 apps/fabro-web/app/routes/run-detail.tsx      |   6 +-
 ...05-21-wall-and-active-time-metrics-plan.md |   8 +-
 docs/public/api-reference/fabro-api.yaml      |   9 +
 .../fabro-server/src/server/handler/runs.rs   |  30 ++-
 lib/apps/fabro-server/src/server/tests.rs     |  89 +++++++++
 lib/components/fabro-store/src/run_state.rs   | 182 +++++++++++++++---
 lib/foundation/fabro-api/build.rs             |   5 +
 lib/foundation/fabro-api/src/lib.rs           |   8 +-
 .../tests/stage_projection_round_trip.rs      |  31 ++-
 lib/foundation/fabro-types/src/lib.rs         |   2 +-
 .../fabro-types/src/run_projection.rs         | 109 ++++++++---
 lib/foundation/fabro-types/src/timing.rs      |  48 ++++-
 .../src/models/stage-tool-batch-projection.ts |   6 +-
 17 files changed, 523 insertions(+), 86 deletions(-)

diff --git a/apps/fabro-web/app/lib/queries.ts b/apps/fabro-web/app/lib/queries.ts
index 3c8eb8a1d..aa7328b5e 100644
--- a/apps/fabro-web/app/lib/queries.ts
+++ b/apps/fabro-web/app/lib/queries.ts
@@ -73,6 +73,7 @@ import {
   type RunFileSelection,
   type RunGraphDirection,
 } from "./query-keys";
+import { isTerminalRunStatus } from "./run-actions";
 
 const immutableOptions: SWRConfiguration = {
   revalidateIfStale: false,
@@ -179,10 +180,19 @@ export function useRunsPage(opts: RunsPageOptions = {}, enabled = true) {
   );
 }
 
-export function useRun(id: string | undefined) {
+export function useRun(id: string | undefined, refreshInterval?: number) {
   return useSWR<Run | null>(
     id ? queryKeys.runs.detail(id) : null,
     () => apiNullableData(() => runsApi.retrieveRun(id!)),
+    refreshInterval
+      ? {
+          refreshInterval: (run) =>
+            run?.timestamps.started_at &&
+            !isTerminalRunStatus(run.lifecycle.status.kind)
+              ? refreshInterval
+              : 0,
+        }
+      : undefined,
   );
 }
 
diff --git a/apps/fabro-web/app/lib/query-keys.test.ts b/apps/fabro-web/app/lib/query-keys.test.ts
index ac441b998..52a5ccef3 100644
--- a/apps/fabro-web/app/lib/query-keys.test.ts
+++ b/apps/fabro-web/app/lib/query-keys.test.ts
@@ -87,8 +87,6 @@ describe("queryKeys", () => {
   test("agent activity events invalidate per-stage resources", () => {
     for (const event of [
       "stage.prompt",
-      "agent.tool.started",
-      "agent.tool.completed",
       "command.started",
       "command.completed",
     ]) {
@@ -97,8 +95,19 @@ describe("queryKeys", () => {
         queryKeys.runs.stageContextWindow("run-1", "stage-1"),
       ]);
     }
+    for (const event of ["agent.tool.started", "agent.tool.completed"]) {
+      expect(queryKeysForRunEvent("run-1", event, "stage-1")).toEqual([
+        queryKeys.runs.detail("run-1"),
+        queryKeys.runs.state("run-1"),
+        queryKeys.runs.billing("run-1"),
+        queryKeys.runs.stageEvents("run-1", "stage-1"),
+        queryKeys.runs.stageContextWindow("run-1", "stage-1"),
+      ]);
+    }
     expect(queryKeysForRunEvent("run-1", "agent.message", "stage-1")).toEqual([
+      queryKeys.runs.detail("run-1"),
       queryKeys.runs.state("run-1"),
+      queryKeys.runs.billing("run-1"),
       queryKeys.runs.stageEvents("run-1", "stage-1"),
       queryKeys.runs.stageContextWindow("run-1", "stage-1"),
     ]);
@@ -106,7 +115,9 @@ describe("queryKeys", () => {
 
   test("agent message without a node_id still invalidates projected state", () => {
     expect(queryKeysForRunEvent("run-1", "agent.message")).toEqual([
+      queryKeys.runs.detail("run-1"),
       queryKeys.runs.state("run-1"),
+      queryKeys.runs.billing("run-1"),
     ]);
   });
 });
diff --git a/apps/fabro-web/app/lib/run-events.test.tsx b/apps/fabro-web/app/lib/run-events.test.tsx
index e984be74d..4fce18b4d 100644
--- a/apps/fabro-web/app/lib/run-events.test.tsx
+++ b/apps/fabro-web/app/lib/run-events.test.tsx
@@ -85,6 +85,8 @@ describe("queryKeysForRunEvent", () => {
 
   test("interrupt settlement invalidates projected control state and stage activity", () => {
     expect(queryKeysForRunEvent("run-1", "agent.round.interrupted", "nap@1")).toEqual([
+      queryKeys.runs.detail("run-1"),
+      queryKeys.runs.billing("run-1"),
       queryKeys.runs.state("run-1"),
       queryKeys.runs.events("run-1", 1000),
       queryKeys.runs.stageEvents("run-1", "nap@1"),
@@ -134,22 +136,40 @@ describe("queryKeysForRunEvent", () => {
       "agent.error",
     ]) {
       expect(queryKeysForRunEvent("run-1", event, "code@1")).toEqual([
+        queryKeys.runs.detail("run-1"),
         queryKeys.runs.state("run-1"),
+        queryKeys.runs.billing("run-1"),
         queryKeys.runs.stageEvents("run-1", "code@1"),
       ]);
     }
     expect(
       queryKeysForRunEvent("run-1", "agent.message", "code@1"),
     ).toEqual([
+      queryKeys.runs.detail("run-1"),
       queryKeys.runs.state("run-1"),
+      queryKeys.runs.billing("run-1"),
       queryKeys.runs.stageEvents("run-1", "code@1"),
       queryKeys.runs.stageContextWindow("run-1", "code@1"),
     ]);
     expect(queryKeysForRunEvent("run-1", "agent.session.ended")).toEqual([
+      queryKeys.runs.detail("run-1"),
       queryKeys.runs.state("run-1"),
+      queryKeys.runs.billing("run-1"),
     ]);
   });
 
+  test("tool timing events invalidate live summaries and stage resources", () => {
+    for (const event of ["agent.tool.started", "agent.tool.completed"]) {
+      expect(queryKeysForRunEvent("run-1", event, "code@1")).toEqual([
+        queryKeys.runs.detail("run-1"),
+        queryKeys.runs.state("run-1"),
+        queryKeys.runs.billing("run-1"),
+        queryKeys.runs.stageEvents("run-1", "code@1"),
+        queryKeys.runs.stageContextWindow("run-1", "code@1"),
+      ]);
+    }
+  });
+
   test("watchdog timeout refreshes the stage events for that stage", () => {
     expect(
       queryKeysForRunEvent("run-1", "watchdog.timeout", "code@1"),
diff --git a/apps/fabro-web/app/lib/run-events.ts b/apps/fabro-web/app/lib/run-events.ts
index d0d4f4b4d..523774e18 100644
--- a/apps/fabro-web/app/lib/run-events.ts
+++ b/apps/fabro-web/app/lib/run-events.ts
@@ -118,6 +118,10 @@ const INFERENCE_EVENTS = new Set([
   "agent.error",
   "agent.session.ended",
 ]);
+const TOOL_TIMING_EVENTS = new Set([
+  "agent.tool.started",
+  "agent.tool.completed",
+]);
 // Todo / task mutation events refresh `getRunState` consumers (so per-stage
 // todo projections update live) and the run events list.
 const TODO_EVENTS = new Set([
@@ -184,6 +188,12 @@ export function queryKeysForRunEvent(
     if (AGENT_CONTROL_STATE_EVENTS.has(event)) {
       keys.unshift(queryKeys.runs.state(runId));
     }
+    if (event === "agent.round.interrupted") {
+      keys.unshift(
+        queryKeys.runs.detail(runId),
+        queryKeys.runs.billing(runId),
+      );
+    }
     if (stageId) {
       keys.push(queryKeys.runs.stageEvents(runId, stageId));
       keys.push(queryKeys.runs.stageContextWindow(runId, stageId));
@@ -192,7 +202,11 @@ export function queryKeysForRunEvent(
   }
 
   if (INFERENCE_EVENTS.has(event)) {
-    const keys: Key[] = [queryKeys.runs.state(runId)];
+    const keys: Key[] = [
+      queryKeys.runs.detail(runId),
+      queryKeys.runs.state(runId),
+      queryKeys.runs.billing(runId),
+    ];
     if (stageId) {
       keys.push(queryKeys.runs.stageEvents(runId, stageId));
       if (event === "agent.message") {
@@ -202,6 +216,19 @@ export function queryKeysForRunEvent(
     return keys;
   }
 
+  if (TOOL_TIMING_EVENTS.has(event)) {
+    const keys: Key[] = [
+      queryKeys.runs.detail(runId),
+      queryKeys.runs.state(runId),
+      queryKeys.runs.billing(runId),
+    ];
+    if (stageId) {
+      keys.push(queryKeys.runs.stageEvents(runId, stageId));
+      keys.push(queryKeys.runs.stageContextWindow(runId, stageId));
+    }
+    return keys;
+  }
+
   if (event === "watchdog.timeout") {
     return stageId ? [queryKeys.runs.stageEvents(runId, stageId)] : [];
   }
diff --git a/apps/fabro-web/app/routes/run-detail.tsx b/apps/fabro-web/app/routes/run-detail.tsx
index 97ce00702..ad2d78986 100644
--- a/apps/fabro-web/app/routes/run-detail.tsx
+++ b/apps/fabro-web/app/routes/run-detail.tsx
@@ -69,6 +69,8 @@ import {
 
 export const handle = { hideHeader: true };
 
+const RUN_TIMING_REFRESH_INTERVAL_MS = 30_000;
+
 type LifecycleTrigger = () => Promise<LifecycleMutationResult | undefined>;
 
 export function meta({ data }: any) {
@@ -78,7 +80,7 @@ export function meta({ data }: any) {
 
 export default function RunDetail({ params }: { params: { id: string } }) {
   const demoMode = useDemoMode();
-  const runQuery = useRun(params.id);
+  const runQuery = useRun(params.id, RUN_TIMING_REFRESH_INTERVAL_MS);
   const runStateQuery = useRunState(params.id);
   const summary = runQuery.data;
   const run = summary ? buildRunDetailRun(summary) : null;
@@ -116,7 +118,7 @@ export default function RunDetail({ params }: { params: { id: string } }) {
     childrenCount,
   });
   const steerBarRef = useRef<SteerBarHandle | null>(null);
-  const now = useTickingNow(30_000);
+  const now = useTickingNow(RUN_TIMING_REFRESH_INTERVAL_MS);
   const { fullHeight, hideSteerBar } = childRouteLayoutFlags(matches);
 
   useRunEvents(params.id);
diff --git a/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md b/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md
index 3683e5879..c0980ed01 100644
--- a/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md
+++ b/docs/plans/2026-05-21-wall-and-active-time-metrics-plan.md
@@ -155,8 +155,9 @@ git diff --check
 
 - Inference time is Fabro-observed LLM request/stream elapsed time, not
   provider-reported model-only compute time.
-- LLM retry backoff, queueing outside a request/stream, human waits, steering
-  waits, and scheduler gaps are wall time but not active time.
+- Queueing outside a request/stream, human waits, steering waits, and scheduler
+  gaps are wall time but not active time. Retry delay inside an open LLM request
+  bracket follows the executor stopwatch and counts as inference time.
 - ~~Active timing is finalized-event based in v1; live active-time ticking can
   be added later if it becomes necessary.~~ **Superseded 2026-07-25.** It became
   necessary: a run parked in one long agent stage reported ~12% of its wall time
@@ -164,7 +165,6 @@ git diff --check
   accumulate inference and tool brackets from the event log and expose
   `StageProjection::live_timing(now)`, the active-time twin of
   `live_wall_time_ms`. Finalized values remain authoritative and still replace
-  the live estimate at terminal events. See
-  `.ai/plans/live-active-time-accumulation.md`.
+  the live estimate at terminal events. Implemented in PR #647.
 - No compatibility layer is required for existing API clients or stored run
   event data.
diff --git a/docs/public/api-reference/fabro-api.yaml b/docs/public/api-reference/fabro-api.yaml
index 568aa30e5..f2460a69b 100644
--- a/docs/public/api-reference/fabro-api.yaml
+++ b/docs/public/api-reference/fabro-api.yaml
@@ -10772,9 +10772,16 @@ components:
         duplicated completion in a replayed log cannot drain the batch early.
       type: object
       required:
+        - session_id
         - started_at
         - open_call_ids
       properties:
+        session_id:
+          type: string
+          description: >
+            Root agent session that dispatched the batch. Transitions are
+            gated on it so delayed events from a replaced session cannot
+            mutate the current batch.
         started_at:
           type: string
           format: date-time
@@ -10783,6 +10790,8 @@ components:
             other calls were outstanding.
         open_call_ids:
           type: array
+          minItems: 1
+          uniqueItems: true
           items:
             type: string
           description: Calls dispatched but not yet completed, by tool call id.
diff --git a/lib/apps/fabro-server/src/server/handler/runs.rs b/lib/apps/fabro-server/src/server/handler/runs.rs
index 0e2c8cbcb..4b9acdf1c 100644
--- a/lib/apps/fabro-server/src/server/handler/runs.rs
+++ b/lib/apps/fabro-server/src/server/handler/runs.rs
@@ -11,7 +11,7 @@ use axum_extra::extract::Query as ExtraQuery;
 use base64::Engine as _;
 use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
 use bytes::Bytes;
-use chrono::Utc;
+use chrono::{DateTime, Utc};
 use fabro_api::types::{
     BoardColumn, RunManifest, SubmitAnswerRequest, UpdateRunParentRequest, UpdateRunRequest,
 };
@@ -23,7 +23,7 @@ use fabro_store::{
 };
 use fabro_types::settings::ResolveError;
 use fabro_types::{
-    AutomationRef, Principal, RunClientProvenance, RunId, RunProvenance, RunServerProvenance,
+    AutomationRef, Principal, Run, RunClientProvenance, RunId, RunProvenance, RunServerProvenance,
     RunStatusKind, StageContextWindow, StageContextWindowStaleness,
     StageContextWindowUnavailableReason, StageHandler, StageModelUsage, StageProjection,
     SystemActorKind, WorkflowSettings, parse_blob_ref,
@@ -298,7 +298,7 @@ async fn validate_parent_link(
 }
 
 async fn updated_run_response(state: &AppState, run_id: &RunId) -> Response {
-    match state.stores.run_summaries.get(run_id, Utc::now()).await {
+    match run_summary_at(state, run_id, Utc::now()).await {
         Ok(Some(summary)) => (
             StatusCode::OK,
             Json(state.decorate_run_summary(summary).await),
@@ -311,6 +311,28 @@ async fn updated_run_response(state: &AppState, run_id: &RunId) -> Response {
     }
 }
 
+/// Read the durable summary and overlay its timing from the live projection.
+///
+/// The SQLite read model stores active timing as of the most recent event.
+/// An open inference or tool bracket keeps accruing between events, so detail
+/// reads need the projection's current estimate while the run is non-terminal.
+async fn run_summary_at(
+    state: &AppState,
+    run_id: &RunId,
+    now: DateTime<Utc>,
+) -> fabro_store::Result<Option<Run>> {
+    let Some(mut summary) = state.stores.run_summaries.get(run_id, now).await? else {
+        return Ok(None);
+    };
+    if summary.timestamps.completed_at.is_none() {
+        let cached = state.stores.runs.get_cached_run(run_id).await?;
+        if let Some(timing) = cached.and_then(|cached| cached.projection.live_run_timing(now)) {
+            summary.timing = Some(timing);
+        }
+    }
+    Ok(Some(summary))
+}
+
 async fn list_runs(
     _auth: RequiredRunManagementActor,
     State(state): State<Arc<AppState>>,
@@ -934,7 +956,7 @@ async fn get_run_status(
     RequireRunManagementTarget(id, _actor): RequireRunManagementTarget,
     State(state): State<Arc<AppState>>,
 ) -> Response {
-    match state.stores.run_summaries.get(&id, Utc::now()).await {
+    match run_summary_at(&state, &id, Utc::now()).await {
         Ok(Some(run)) => {
             (StatusCode::OK, Json(state.decorate_run_summary(run).await)).into_response()
         }
diff --git a/lib/apps/fabro-server/src/server/tests.rs b/lib/apps/fabro-server/src/server/tests.rs
index 71b4dfebf..790089ab1 100644
--- a/lib/apps/fabro-server/src/server/tests.rs
+++ b/lib/apps/fabro-server/src/server/tests.rs
@@ -5503,6 +5503,50 @@ async fn list_run_stages_exposes_execution_identity_for_resumed_stage() {
     assert_eq!(second["resumed_from_stage_id"], "work@1");
 }
 
+#[tokio::test]
+async fn run_billing_includes_live_stage_timing_in_rows_and_totals() {
+    let state = test_app_state_with_isolated_storage();
+    let app = crate::test_support::build_test_router(Arc::clone(&state));
+    let run_id = RunId::new();
+    create_durable_run_with_events(&state, run_id, &[
+        workflow_event::Event::RunSubmitted {
+            definition_blob: None,
+        },
+        workflow_event::Event::RunStarting,
+        workflow_event::Event::RunRunning,
+        workflow_run_started_event(run_id),
+    ])
+    .await;
+    append_scoped_stage_event(
+        &state,
+        run_id,
+        "work",
+        1,
+        &stage_started_event("work", "command"),
+    )
+    .await;
+
+    tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+    let response = app
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri(api(&format!("/runs/{run_id}/billing")))
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let body = response_json!(response, StatusCode::OK).await;
+    let stages = body["stages"].as_array().unwrap();
+
+    assert_eq!(stages.len(), 1);
+    let row_timing = &stages[0]["timing"];
+    assert!(row_timing["active_time_ms"].as_u64().unwrap() > 0);
+    assert_eq!(row_timing["tool_time_ms"], row_timing["active_time_ms"]);
+    assert_eq!(&body["totals"]["timing"], row_timing);
+}
+
 /// `checkpoint.completed_nodes` records every visit, so a looped node appears
 /// once per re-entry. Billing must dedup so a retried node renders as one row
 /// and `runtime_secs` is summed across all visits exactly once.
@@ -7800,6 +7844,51 @@ async fn get_run_status_returns_status() {
     assert!(body["labels"].is_object());
 }
 
+#[tokio::test]
+async fn get_run_status_advances_live_active_timing_between_events() {
+    let state = test_app_state_with_isolated_storage();
+    let app = crate::test_support::build_test_router(Arc::clone(&state));
+    let run_id = RunId::new();
+    create_durable_run_with_events(&state, run_id, &[
+        workflow_event::Event::RunSubmitted {
+            definition_blob: None,
+        },
+        workflow_event::Event::RunStarting,
+        workflow_event::Event::RunRunning,
+        workflow_run_started_event(run_id),
+    ])
+    .await;
+    append_scoped_stage_event(
+        &state,
+        run_id,
+        "work",
+        1,
+        &stage_started_event("work", "command"),
+    )
+    .await;
+
+    // The SQLite summary stores timing at the StageStarted event. A later
+    // detail read must overlay the in-flight command's active time from the
+    // projection even though no newer event has arrived.
+    tokio::time::sleep(std::time::Duration::from_millis(20)).await;
+    let response = app
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri(api(&format!("/runs/{run_id}")))
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let body = response_json!(response, StatusCode::OK).await;
+    let timing = &body["timing"];
+
+    assert!(timing["active_time_ms"].as_u64().unwrap() > 0);
+    assert_eq!(timing["tool_time_ms"], timing["active_time_ms"]);
+    assert!(timing["wall_time_ms"].as_u64().unwrap() >= timing["active_time_ms"].as_u64().unwrap());
+}
+
 #[tokio::test]
 async fn get_run_status_not_found() {
     let app = test_app_with();
diff --git a/lib/components/fabro-store/src/run_state.rs b/lib/components/fabro-store/src/run_state.rs
index df05f84b3..14e86124a 100644
--- a/lib/components/fabro-store/src/run_state.rs
+++ b/lib/components/fabro-store/src/run_state.rs
@@ -19,6 +19,7 @@ use fabro_types::{
     SandboxProviderKind, StageCompletion, StageHandler, StageId, StageInferenceProjection,
     StageModelUsage, StageOutcome, StageProjection, StageState, StartRecord, SubAgentProjection,
     SubAgentStatus, TodoListKind, TodoListProjection, TodoProjection, WorkflowRef, first_event_seq,
+    timing,
 };
 use fabro_util::error::render_compact_with_causes;
 
@@ -405,7 +406,7 @@ impl RunProjectionReducer for RunProjection {
                 };
                 stage.response = response;
                 stage.completion = Some(completion);
-                stage.timing = Some(props.timing);
+                stage.set_authoritative_timing(props.timing);
                 if let Some(billing) = &props.billing {
                     stage.usage.replace_with_billed_usage(billing);
                     stage.model = Some(billing.model().clone());
@@ -428,7 +429,7 @@ impl RunProjectionReducer for RunProjection {
                     failure_reason,
                     timestamp: ts,
                 });
-                stage.timing = Some(props.timing);
+                stage.set_authoritative_timing(props.timing);
                 if let Some(billing) = &props.billing {
                     stage.usage.replace_with_billed_usage(billing);
                     stage.model = Some(billing.model().clone());
@@ -481,7 +482,7 @@ impl RunProjectionReducer for RunProjection {
                 close_inference_bracket(self, stored, props.visit, event.seq, ts);
             }
             EventBody::AgentSessionEnded(_) => {
-                close_inference_brackets_for_session(self, stored, ts);
+                close_active_brackets_for_session(self, stored, ts);
             }
             EventBody::AgentSessionActivated(props) => {
                 let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
@@ -746,7 +747,11 @@ impl RunProjectionReducer for RunProjection {
                 });
             }
             EventBody::AgentToolStarted(props) => {
-                let is_root_session = stored.parent_session_id.is_none();
+                let root_session_id = if stored.parent_session_id.is_none() {
+                    stored.session_id.clone()
+                } else {
+                    None
+                };
                 let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
                 else {
                     return Ok(());
@@ -770,19 +775,22 @@ impl RunProjectionReducer for RunProjection {
                 // A subagent's tools run inside the root session's tool call,
                 // so the root batch already covers them. Timing them again
                 // would double-count that span.
-                if is_root_session {
-                    stage.open_tool_call(props.tool_call_id.clone(), ts);
+                if let Some(session_id) = root_session_id {
+                    stage.open_tool_call(session_id, props.tool_call_id.clone(), ts);
                 }
             }
             EventBody::AgentToolCompleted(props) => {
                 if stored.parent_session_id.is_some() {
                     return Ok(());
                 }
+                let Some(session_id) = stored.session_id.as_deref() else {
+                    return Ok(());
+                };
                 let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
                 else {
                     return Ok(());
                 };
-                stage.close_tool_call(&props.tool_call_id, ts);
+                stage.close_tool_call(session_id, &props.tool_call_id, ts);
             }
             _ => {}
         }
@@ -1123,16 +1131,10 @@ fn close_bracket_on_stage(stage: &mut StageProjection, ts: DateTime<Utc>) {
     let Some(inference) = stage.inference.take() else {
         return;
     };
-    stage.accumulate_inference_ms(elapsed_ms(inference.started_at, ts));
+    stage.accumulate_inference_ms(timing::elapsed_ms(inference.started_at, ts));
 }
 
-/// Non-negative milliseconds between two instants, saturating at zero so a
-/// clock skew or an out-of-order replay cannot produce a negative span.
-fn elapsed_ms(from: DateTime<Utc>, to: DateTime<Utc>) -> u64 {
-    u64::try_from(to.signed_duration_since(from).num_milliseconds().max(0)).unwrap_or(0)
-}
-
-/// Close every bracket opened by the session that just ended.
+/// Close every active bracket opened by the session that just ended.
 ///
 /// `agent.session.ended` is the only ordering-safe backstop for terminal
 /// cancel and wall-clock timeout, which tear the session down through
@@ -1147,7 +1149,7 @@ fn elapsed_ms(from: DateTime<Utc>, to: DateTime<Utc>) -> u64 {
 /// opened. Implemented as a normal stage lookup it would find no target and
 /// silently no-op, leaving the bracket open forever on exactly the path it
 /// exists to cover.
-fn close_inference_brackets_for_session(
+fn close_active_brackets_for_session(
     state: &mut RunProjection,
     stored: &RunEvent,
     ts: DateTime<Utc>,
@@ -1166,6 +1168,7 @@ fn close_inference_brackets_for_session(
         if opened_here {
             close_bracket_on_stage(stage, ts);
         }
+        stage.close_tool_batch_for_session(session_id, ts);
     }
 }
 
@@ -1475,14 +1478,15 @@ fn finalize_unfinished_stages_after_run_failed(
         StageState::Failed
     };
 
-    for (_, stage) in state.iter_stages_mut() {
+    for (_, stage) in state.iter_stages_unordered_mut() {
         if stage.state.is_terminal() {
             continue;
         }
 
-        // Close any bracket still open so its span is not dropped on the
+        // Close any brackets still open so their spans are not dropped on the
         // floor when the live estimate is frozen into `timing` below.
         close_bracket_on_stage(stage, timestamp);
+        stage.close_open_tool_batch(timestamp);
 
         // Freeze the live estimate before flipping to a terminal state:
         // `live_timing` reads `effective_state` and would return wall-only
@@ -1490,7 +1494,9 @@ fn finalize_unfinished_stages_after_run_failed(
         let frozen = stage.live_timing(timestamp);
         stage.state = terminal_state;
         if stage.timing.is_none() && stage.started_at.is_some() {
-            stage.timing = Some(frozen);
+            stage.set_authoritative_timing(frozen);
+        } else {
+            stage.clear_live_timing();
         }
     }
 }
@@ -1641,12 +1647,16 @@ mod tests {
             StageId::new("plan", 1)
         }
 
-        fn agent_event(seq: u32, ts: &str, body: EventBody) -> EventEnvelope {
+        fn session_event(seq: u32, ts: &str, session_id: &str, body: EventBody) -> EventEnvelope {
             let mut event = test_stage_event_at(seq, ts, body, stage_id());
-            event.event.session_id = Some("session-1".to_string());
+            event.event.session_id = Some(session_id.to_string());
             event
         }
 
+        fn agent_event(seq: u32, ts: &str, body: EventBody) -> EventEnvelope {
+            session_event(seq, ts, "session-1", body)
+        }
+
         /// An event from a sub-agent session nested under the root session.
         fn child_event(seq: u32, ts: &str, body: EventBody) -> EventEnvelope {
             let mut event = agent_event(seq, ts, body);
@@ -1855,6 +1865,81 @@ mod tests {
             assert!(stage(&state).tool_batch.is_some());
         }
 
+        #[test]
+        fn a_foreign_session_completion_does_not_mutate_the_open_batch() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(
+                    2,
+                    "2026-04-07T12:00:00Z",
+                    tool_started("call-a"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&session_event(
+                    3,
+                    "2026-04-07T12:00:05Z",
+                    "session-2",
+                    tool_completed("call-a"),
+                ))
+                .unwrap();
+
+            let batch = stage(&state).tool_batch.as_ref().unwrap();
+            assert_eq!(batch.session_id, "session-1");
+            assert!(batch.open_call_ids.contains("call-a"));
+            assert_eq!(stage(&state).live_tool_ms, 0);
+        }
+
+        #[test]
+        fn a_replacement_session_starts_a_separate_tool_batch() {
+            let mut state = started_state();
+            state
+                .apply_event(&agent_event(
+                    2,
+                    "2026-04-07T12:00:00Z",
+                    tool_started("old-call"),
+                ))
+                .unwrap();
+            state
+                .apply_event(&session_event(
+                    3,
+                    "2026-04-07T12:00:05Z",
+                    "session-2",
+                    tool_started("new-call"),
+                ))
+                .unwrap();
+
+            assert_eq!(stage(&state).live_tool_ms, 5_000);
+            let batch = stage(&state).tool_batch.as_ref().unwrap();
+            assert_eq!(batch.session_id, "session-2");
+            assert_eq!(
+                batch.open_call_ids,
+                ["new-call".to_string()].into_iter().collect()
+            );
+
+            // A delayed completion from the old session cannot close the new
+            // session's batch even when call ids happen to collide.
+            state
+                .apply_event(&agent_event(
+                    4,
+                    "2026-04-07T12:00:07Z",
+                    tool_completed("new-call"),
+                ))
+                .unwrap();
+            assert!(stage(&state).tool_batch.is_some());
+
+            state
+                .apply_event(&session_event(
+                    5,
+                    "2026-04-07T12:00:09Z",
+                    "session-2",
+                    tool_completed("new-call"),
+                ))
+                .unwrap();
+            assert_eq!(stage(&state).live_tool_ms, 9_000);
+            assert!(stage(&state).tool_batch.is_none());
+        }
+
         #[test]
         fn subagent_tool_calls_do_not_double_count_against_the_root_batch() {
             let mut state = started_state();
@@ -1892,14 +1977,21 @@ mod tests {
         }
 
         #[test]
-        fn session_end_accumulates_rather_than_discarding_the_bracket() {
+        fn session_end_accumulates_every_open_active_bracket() {
             let mut state = started_state();
             state
                 .apply_event(&agent_event(2, "2026-04-07T12:00:05Z", llm_started()))
                 .unwrap();
+            state
+                .apply_event(&agent_event(
+                    3,
+                    "2026-04-07T12:00:07Z",
+                    tool_started("call-a"),
+                ))
+                .unwrap();
 
             let mut ended = test_stage_event_at(
-                3,
+                4,
                 "2026-04-07T12:00:20Z",
                 EventBody::AgentSessionEnded(AgentSessionEndedProps {}),
                 stage_id(),
@@ -1908,7 +2000,9 @@ mod tests {
             state.apply_event(&ended).unwrap();
 
             assert_eq!(stage(&state).live_inference_ms, 15_000);
+            assert_eq!(stage(&state).live_tool_ms, 13_000);
             assert!(stage(&state).inference.is_none());
+            assert!(stage(&state).tool_batch.is_none());
         }
 
         #[test]
@@ -1986,6 +2080,48 @@ mod tests {
                 stage.timing.unwrap(),
                 "a terminal stage reports its finalized breakdown, not a live estimate"
             );
+            assert_eq!(stage.live_inference_ms, 0);
+            assert_eq!(stage.live_tool_ms, 0);
+            assert!(stage.inference.is_none());
+            assert!(stage.tool_batch.is_none());
+        }
+
+        #[test]
+        fn run_failure_freezes_open_work_and_clears_live_bookkeeping() {
+            let mut state = started_state();
+            state.status = RunStatus::Running;
+            state
+                .apply_event(&agent_event(2, "2026-04-07T12:00:01Z", llm_started()))
+                .unwrap();
+            state
+                .apply_event(&agent_event(3, "2026-04-07T12:00:04Z", agent_message()))
+                .unwrap();
+            state
+                .apply_event(&agent_event(
+                    4,
+                    "2026-04-07T12:00:05Z",
+                    tool_started("call-a"),
+                ))
+                .unwrap();
+
+            let mut failed = test_event(
+                5,
+                EventBody::RunFailed(run_failed_props(FailureReason::WorkflowError)),
+                None,
+            );
+            failed.event.ts = test_dt("2026-04-07T12:00:10Z");
+            state.apply_event(&failed).unwrap();
+
+            let stage = stage(&state);
+            assert_eq!(
+                stage.timing,
+                Some(fabro_types::StageTiming::new(10_000, 3_000, 5_000))
+            );
+            assert_eq!(stage.state, StageState::Failed);
+            assert_eq!(stage.live_inference_ms, 0);
+            assert_eq!(stage.live_tool_ms, 0);
+            assert!(stage.inference.is_none());
+            assert!(stage.tool_batch.is_none());
         }
     }
 
diff --git a/lib/foundation/fabro-api/build.rs b/lib/foundation/fabro-api/build.rs
index fc943e99d..740585545 100644
--- a/lib/foundation/fabro-api/build.rs
+++ b/lib/foundation/fabro-api/build.rs
@@ -361,6 +361,11 @@ fn main() {
             "fabro_types::StageInferenceProjection",
             &[],
         ),
+        (
+            "StageToolBatchProjection",
+            "fabro_types::StageToolBatchProjection",
+            &[],
+        ),
         ("LlmOutputKind", "fabro_types::LlmOutputKind", &[]),
         ("PermissionLevel", "fabro_types::PermissionLevel", &[]),
         (
diff --git a/lib/foundation/fabro-api/src/lib.rs b/lib/foundation/fabro-api/src/lib.rs
index 4312acb91..b9a6a7185 100644
--- a/lib/foundation/fabro-api/src/lib.rs
+++ b/lib/foundation/fabro-api/src/lib.rs
@@ -69,10 +69,10 @@ pub mod types {
         StageContextWindowCategory, StageContextWindowCountMethod, StageContextWindowProjection,
         StageContextWindowStaleness, StageContextWindowUnavailableReason,
         StageContextWindowWarning, StageHandler, StageId, StageInferenceProjection,
-        StageModelUsage, StageOutcome, StageProjection, StageState, SubAgentProjection,
-        SubAgentStatus, SystemActorKind, SystemIntegrationStatus, SystemIntegrationsResponse,
-        TodoListProjection, TurnId, UpdateVariableRequest, UserPrincipal, Variable,
-        VariableListResponse, WorkflowSettings,
+        StageModelUsage, StageOutcome, StageProjection, StageState, StageToolBatchProjection,
+        SubAgentProjection, SubAgentStatus, SystemActorKind, SystemIntegrationStatus,
+        SystemIntegrationsResponse, TodoListProjection, TurnId, UpdateVariableRequest,
+        UserPrincipal, Variable, VariableListResponse, WorkflowSettings,
     };
 
     pub use crate::generated::types::*;
diff --git a/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs b/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
index 5faed1bd3..22a544e69 100644
--- a/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
+++ b/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
@@ -18,6 +18,7 @@ use fabro_api::types::{
     StageContextWindowUnavailableReason as ApiStageContextWindowUnavailableReason,
     StageContextWindowWarning as ApiStageContextWindowWarning,
     StageInferenceProjection as ApiStageInferenceProjection, StageProjection as ApiStageProjection,
+    StageToolBatchProjection as ApiStageToolBatchProjection,
     SubAgentProjection as ApiSubAgentProjection, SubAgentStatus as ApiSubAgentStatus,
     TodoListProjection as ApiTodoListProjection,
 };
@@ -29,8 +30,8 @@ use fabro_types::{
     ParallelBranchResult, PermissionLevel, SkillsProjection, StageContextWindow,
     StageContextWindowBreakdownItem, StageContextWindowCategory, StageContextWindowCountMethod,
     StageContextWindowProjection, StageContextWindowStaleness, StageContextWindowUnavailableReason,
-    StageContextWindowWarning, StageInferenceProjection, StageProjection, SubAgentProjection,
-    SubAgentStatus, TodoListKind, TodoListProjection,
+    StageContextWindowWarning, StageInferenceProjection, StageProjection, StageToolBatchProjection,
+    SubAgentProjection, SubAgentStatus, TodoListKind, TodoListProjection,
 };
 use serde_json::json;
 
@@ -68,9 +69,32 @@ fn stage_projection_reuses_nested_agent_state_types() {
     );
     assert_same_type::<ApiStageContextWindowWarning, StageContextWindowWarning>();
     assert_same_type::<ApiStageInferenceProjection, StageInferenceProjection>();
+    assert_same_type::<ApiStageToolBatchProjection, StageToolBatchProjection>();
     assert_same_type::<ApiLlmOutputKind, LlmOutputKind>();
 }
 
+#[test]
+fn stage_tool_batch_projection_matches_openapi_json_shape() {
+    let batch = StageToolBatchProjection {
+        session_id:    "ses_root".to_string(),
+        started_at:    "2026-04-29T12:34:00Z".parse().unwrap(),
+        open_call_ids: ["call_1".to_string(), "call_2".to_string()]
+            .into_iter()
+            .collect(),
+    };
+    let value = serde_json::to_value(&batch).unwrap();
+    assert_eq!(
+        value,
+        json!({
+            "session_id": "ses_root",
+            "started_at": "2026-04-29T12:34:00Z",
+            "open_call_ids": ["call_1", "call_2"]
+        })
+    );
+    let api_batch: ApiStageToolBatchProjection = serde_json::from_value(value).unwrap();
+    assert_eq!(api_batch, batch);
+}
+
 #[test]
 fn stage_inference_projection_matches_openapi_json_shape() {
     let inference = StageInferenceProjection {
@@ -148,6 +172,9 @@ fn stage_projection_without_inference_round_trips() {
 
     let stage: StageProjection = serde_json::from_value(value.clone()).unwrap();
     assert!(stage.inference.is_none());
+    assert!(stage.tool_batch.is_none());
+    assert_eq!(stage.live_inference_ms, 0);
+    assert_eq!(stage.live_tool_ms, 0);
     assert_eq!(serde_json::to_value(stage).unwrap(), value);
 }
 
diff --git a/lib/foundation/fabro-types/src/lib.rs b/lib/foundation/fabro-types/src/lib.rs
index 68f5644a2..b7f3b0474 100644
--- a/lib/foundation/fabro-types/src/lib.rs
+++ b/lib/foundation/fabro-types/src/lib.rs
@@ -125,7 +125,7 @@ pub use run_projection::{
     StageContextWindowBreakdownItem, StageContextWindowCategory, StageContextWindowCountMethod,
     StageContextWindowProjection, StageContextWindowStaleness, StageContextWindowUnavailableReason,
     StageContextWindowWarning, StageInferenceProjection, StageModelUsage, StageProjection,
-    SubAgentProjection, SubAgentStatus, first_event_seq,
+    StageToolBatchProjection, SubAgentProjection, SubAgentStatus, first_event_seq,
 };
 pub use run_sandbox::{
     RunSandbox, RunSandboxFailure, RunSandboxInstance, RunSandboxKind, RunSandboxPlan,
diff --git a/lib/foundation/fabro-types/src/run_projection.rs b/lib/foundation/fabro-types/src/run_projection.rs
index 0576d32f6..e2b9ad3f6 100644
--- a/lib/foundation/fabro-types/src/run_projection.rs
+++ b/lib/foundation/fabro-types/src/run_projection.rs
@@ -12,7 +12,7 @@ use crate::{
     AgentToolSummary, BilledTokenCounts, Checkpoint, Conclusion, InterviewQuestionRecord,
     InvalidTransition, LlmOutputKind, ModelRef, PermissionLevel, PullRequestLink, RunApproval,
     RunControlAction, RunDiff, RunId, RunSandbox, RunSpec, RunStatus, RunTiming, StageCompletion,
-    StageHandler, StageId, StageState, StageTiming, StartRecord, TodoListProjection,
+    StageHandler, StageId, StageState, StageTiming, StartRecord, TodoListProjection, timing,
 };
 
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
@@ -433,6 +433,10 @@ fn is_zero_ms(value: &u64) -> bool {
 /// duplicated log must not let a repeated completion drain the batch early.
 #[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub struct StageToolBatchProjection {
+    /// Root agent session that dispatched the batch. Later transitions are
+    /// gated on it so delayed events from a replaced session cannot mutate
+    /// the current session's batch.
+    pub session_id:    String,
     /// When the batch opened — the first `agent.tool.started` observed while
     /// no other calls were outstanding.
     pub started_at:    DateTime<Utc>,
@@ -603,10 +607,9 @@ impl StageProjection {
             state,
             StageState::Running | StageState::Retrying | StageState::Pending
         ) {
-            return self.started_at.map(|started| {
-                u64::try_from(now.signed_duration_since(started).num_milliseconds().max(0))
-                    .unwrap_or(0)
-            });
+            return self
+                .started_at
+                .map(|started| timing::elapsed_ms(started, now));
         }
         self.timing.map(|timing| timing.wall_time_ms)
     }
@@ -645,9 +648,6 @@ impl StageProjection {
         }
 
         let wall_time_ms = self.live_wall_time_ms(now).unwrap_or(0);
-        let elapsed = |since: DateTime<Utc>| {
-            u64::try_from(now.signed_duration_since(since).num_milliseconds().max(0)).unwrap_or(0)
-        };
 
         // `handler` is absent on projections built from events written before
         // stage execution identity. Treat those as agent stages, matching
@@ -660,11 +660,11 @@ impl StageProjection {
                 let open_inference = self
                     .inference
                     .as_ref()
-                    .map_or(0, |inference| elapsed(inference.started_at));
+                    .map_or(0, |inference| timing::elapsed_ms(inference.started_at, now));
                 let open_tool = self
                     .tool_batch
                     .as_ref()
-                    .map_or(0, |batch| elapsed(batch.started_at));
+                    .map_or(0, |batch| timing::elapsed_ms(batch.started_at, now));
                 (
                     self.live_inference_ms.saturating_add(open_inference),
                     self.live_tool_ms.saturating_add(open_tool),
@@ -693,9 +693,26 @@ impl StageProjection {
     }
 
     /// Record a dispatched tool call, opening a batch if none is outstanding.
-    pub fn open_tool_call(&mut self, tool_call_id: String, started_at: DateTime<Utc>) {
+    ///
+    /// If a replacement root session starts work before the old session's end
+    /// event arrives, freeze the old batch at this boundary before opening
+    /// the new one. This keeps the sessions separate without dropping time.
+    pub fn open_tool_call(
+        &mut self,
+        session_id: String,
+        tool_call_id: String,
+        started_at: DateTime<Utc>,
+    ) {
+        let replaces_open_batch = self
+            .tool_batch
+            .as_ref()
+            .is_some_and(|batch| batch.session_id != session_id);
+        if replaces_open_batch {
+            self.close_open_tool_batch(started_at);
+        }
         self.tool_batch
             .get_or_insert_with(|| StageToolBatchProjection {
+                session_id,
                 started_at,
                 open_call_ids: BTreeSet::new(),
             })
@@ -705,21 +722,52 @@ impl StageProjection {
 
     /// Retire a tool call. Folds the batch into the live accumulator once the
     /// last outstanding call reports, so concurrent calls count once.
-    pub fn close_tool_call(&mut self, tool_call_id: &str, now: DateTime<Utc>) {
+    pub fn close_tool_call(&mut self, session_id: &str, tool_call_id: &str, now: DateTime<Utc>) {
         let Some(batch) = self.tool_batch.as_mut() else {
             return;
         };
-        batch.open_call_ids.remove(tool_call_id);
-        if !batch.open_call_ids.is_empty() {
+        if batch.session_id != session_id
+            || !batch.open_call_ids.remove(tool_call_id)
+            || !batch.open_call_ids.is_empty()
+        {
             return;
         }
-        let elapsed = u64::try_from(
-            now.signed_duration_since(batch.started_at)
-                .num_milliseconds()
-                .max(0),
-        )
-        .unwrap_or(0);
-        self.live_tool_ms = self.live_tool_ms.saturating_add(elapsed);
+        self.close_open_tool_batch(now);
+    }
+
+    /// Close a tool batch only when it belongs to `session_id`.
+    pub fn close_tool_batch_for_session(&mut self, session_id: &str, now: DateTime<Utc>) {
+        let opened_here = self
+            .tool_batch
+            .as_ref()
+            .is_some_and(|batch| batch.session_id == session_id);
+        if opened_here {
+            self.close_open_tool_batch(now);
+        }
+    }
+
+    /// Fold any open tool batch into the live accumulator.
+    pub fn close_open_tool_batch(&mut self, now: DateTime<Utc>) {
+        let Some(batch) = self.tool_batch.take() else {
+            return;
+        };
+        self.live_tool_ms = self
+            .live_tool_ms
+            .saturating_add(timing::elapsed_ms(batch.started_at, now));
+    }
+
+    /// Install a worker-provided terminal timing and discard transient live
+    /// bookkeeping that is no longer authoritative.
+    pub fn set_authoritative_timing(&mut self, timing: StageTiming) {
+        self.timing = Some(timing);
+        self.clear_live_timing();
+    }
+
+    /// Discard transient timing accumulators and open brackets.
+    pub fn clear_live_timing(&mut self) {
+        self.live_inference_ms = 0;
+        self.live_tool_ms = 0;
+        self.inference = None;
         self.tool_batch = None;
     }
 
@@ -1138,20 +1186,15 @@ mod iter_stages_tests {
 #[cfg(test)]
 mod live_timing_tests {
     use std::collections::HashMap;
-    use std::num::NonZeroU32;
 
     use chrono::{DateTime, TimeZone, Utc};
 
     use super::{RunProjection, StageToolBatchProjection};
     use crate::{
         Graph, ModelRef, RunId, RunSpec, StageHandler, StageInferenceProjection, StageProjection,
-        StageState, StageTiming, StartRecord, WorkflowSettings, test_support,
+        StageState, StageTiming, StartRecord, WorkflowSettings, first_event_seq, test_support,
     };
 
-    fn seq(n: u32) -> NonZeroU32 {
-        NonZeroU32::new(n).unwrap()
-    }
-
     fn at(seconds: i64) -> DateTime<Utc> {
         Utc.timestamp_opt(1_700_000_000 + seconds, 0).unwrap()
     }
@@ -1180,7 +1223,7 @@ mod live_timing_tests {
 
     /// In-flight stage that started at `at(0)`.
     fn running(handler: StageHandler) -> StageProjection {
-        let mut stage = StageProjection::new(seq(1));
+        let mut stage = StageProjection::new(first_event_seq(1));
         stage.handler = Some(handler);
         stage.started_at = Some(at(0));
         stage.state = StageState::Running;
@@ -1225,6 +1268,7 @@ mod live_timing_tests {
         // Inference open for 20s, tools open for 10s, at t=120s.
         stage.inference = Some(open_bracket(at(100)));
         stage.tool_batch = Some(StageToolBatchProjection {
+            session_id:    "session-1".to_string(),
             started_at:    at(110),
             open_call_ids: ["call-1".to_string()].into_iter().collect(),
         });
@@ -1330,17 +1374,17 @@ mod live_timing_tests {
             base_sha:   None,
         });
 
-        let baseline = projection.stage_entry("baseline", 1, seq(1));
+        let baseline = projection.stage_entry("baseline", 1, first_event_seq(1));
         baseline.handler = Some(StageHandler::Command);
         baseline.state = StageState::Succeeded;
         baseline.timing = Some(StageTiming::new(42_666, 0, 42_663));
 
-        let assess = projection.stage_entry("assess", 1, seq(2));
+        let assess = projection.stage_entry("assess", 1, first_event_seq(2));
         assess.handler = Some(StageHandler::Agent);
         assess.state = StageState::Succeeded;
         assess.timing = Some(StageTiming::new(86_025, 78_230, 7_588));
 
-        let plan = projection.stage_entry("plan", 1, seq(3));
+        let plan = projection.stage_entry("plan", 1, first_event_seq(3));
         plan.handler = Some(StageHandler::Agent);
         plan.started_at = Some(at(146));
         plan.state = StageState::Running;
@@ -1367,7 +1411,8 @@ mod live_timing_tests {
         });
 
         for (index, node) in ["branch-a", "branch-b", "branch-c"].iter().enumerate() {
-            let stage = projection.stage_entry(node, 1, seq(u32::try_from(index).unwrap() + 1));
+            let stage =
+                projection.stage_entry(node, 1, first_event_seq(u32::try_from(index).unwrap() + 1));
             stage.handler = Some(StageHandler::Agent);
             stage.state = StageState::Succeeded;
             stage.timing = Some(StageTiming::new(60_000, 60_000, 0));
diff --git a/lib/foundation/fabro-types/src/timing.rs b/lib/foundation/fabro-types/src/timing.rs
index 4fe45a36f..812a72ef2 100644
--- a/lib/foundation/fabro-types/src/timing.rs
+++ b/lib/foundation/fabro-types/src/timing.rs
@@ -18,6 +18,16 @@
 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
+/// Non-negative milliseconds between two instants.
+///
+/// Clock skew or an out-of-order replay can put `end` before `start`; those
+/// spans contribute zero rather than wrapping into a large unsigned value.
+#[must_use]
+pub fn elapsed_ms(start: DateTime<Utc>, end: DateTime<Utc>) -> u64 {
+    u64::try_from(end.signed_duration_since(start).num_milliseconds().max(0))
+        .expect("non-negative chrono millisecond durations fit in u64")
+}
+
 /// Timing breakdown for one stage visit.
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
 pub struct StageTiming {
@@ -74,16 +84,18 @@ impl StageTiming {
     /// legitimately sum past run wall time.
     #[must_use]
     pub fn clamped_to_wall(&self) -> Self {
-        if self.active_time_ms <= self.wall_time_ms {
+        let active_time_ms = u128::from(self.inference_time_ms) + u128::from(self.tool_time_ms);
+        if active_time_ms <= u128::from(self.wall_time_ms) {
             return *self;
         }
         // Preserve the split rather than truncating one side, so a clamped
         // stage still shows where its time went. Widen for the multiply: the
-        // quotient is bounded by `wall_time_ms` because `active_time_ms`
-        // exceeds it here, so it always fits back into u64.
-        let scaled = u128::from(self.inference_time_ms) * u128::from(self.wall_time_ms)
-            / u128::from(self.active_time_ms);
-        let inference_time_ms = u64::try_from(scaled).unwrap_or(self.wall_time_ms);
+        // quotient is bounded by `wall_time_ms` because the exact, widened
+        // active total exceeds it here, so it always fits back into u64.
+        let scaled =
+            u128::from(self.inference_time_ms) * u128::from(self.wall_time_ms) / active_time_ms;
+        let inference_time_ms =
+            u64::try_from(scaled).expect("scaled inference time is bounded by wall time");
         let tool_time_ms = self.wall_time_ms.saturating_sub(inference_time_ms);
         Self::new(self.wall_time_ms, inference_time_ms, tool_time_ms)
     }
@@ -166,8 +178,7 @@ impl RunTiming {
     /// Milliseconds elapsed from `start` to `now`, clamped at zero.
     #[must_use]
     pub fn wall_time_ms_since(start: DateTime<Utc>, now: DateTime<Utc>) -> u64 {
-        u64::try_from(now.signed_duration_since(start).num_milliseconds().max(0))
-            .expect("non-negative milliseconds fit in u64")
+        elapsed_ms(start, now)
     }
 }
 
@@ -184,7 +195,9 @@ impl From<StageTiming> for RunTiming {
 
 #[cfg(test)]
 mod tests {
-    use super::{RunTiming, StageTiming};
+    use chrono::{TimeZone, Utc};
+
+    use super::{RunTiming, StageTiming, elapsed_ms};
 
     #[test]
     fn stage_timing_new_derives_active_as_sum_of_inference_and_tool() {
@@ -215,6 +228,23 @@ mod tests {
         assert_eq!(sum.active_time_ms, 175);
     }
 
+    #[test]
+    fn stage_timing_clamp_uses_the_unsaturated_active_total() {
+        let timing = StageTiming::new(u64::MAX, u64::MAX, u64::MAX).clamped_to_wall();
+
+        assert_eq!(timing.inference_time_ms, u64::MAX / 2);
+        assert_eq!(timing.tool_time_ms, u64::MAX.saturating_sub(u64::MAX / 2));
+        assert_eq!(timing.active_time_ms, u64::MAX);
+    }
+
+    #[test]
+    fn elapsed_ms_clamps_out_of_order_instants_to_zero() {
+        let later = Utc.timestamp_opt(100, 0).unwrap();
+        let earlier = Utc.timestamp_opt(99, 0).unwrap();
+
+        assert_eq!(elapsed_ms(later, earlier), 0);
+    }
+
     #[test]
     fn run_timing_wall_only_zeroes_breakdown_and_active() {
         let timing = RunTiming::wall_only(1500);
diff --git a/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts b/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
index a6bd7718c..c382b5dd1 100644
--- a/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
+++ b/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
@@ -18,6 +18,10 @@
  * One open tool batch: tool calls dispatched together that have not all reported completion. `open_call_ids` is a set rather than a count so a duplicated completion in a replayed log cannot drain the batch early.
  */
 export interface StageToolBatchProjection {
+    /**
+     * Root agent session that dispatched the batch. Transitions are gated on it so delayed events from a replaced session cannot mutate the current batch.
+     */
+    'session_id': string;
     /**
      * When the batch opened — the first dispatched call observed while no other calls were outstanding.
      */
@@ -25,5 +29,5 @@ export interface StageToolBatchProjection {
     /**
      * Calls dispatched but not yet completed, by tool call id.
      */
-    'open_call_ids': Array<string>;
+    'open_call_ids': Set<string>;
 }

From 0b24649e7617d372d1ff1738ee258719fb767240 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Sun, 26 Jul 2026 09:25:47 -0400
Subject: [PATCH 03/36] fix(cli): keep offline validation catalog-free

---
 lib/apps/fabro-cli/src/commands/run/create.rs |   7 +-
 lib/apps/fabro-cli/src/commands/run/runner.rs |   7 +-
 lib/apps/fabro-cli/src/commands/validate.rs   |   6 +-
 lib/apps/fabro-cli/tests/it/cmd/create.rs     |  46 +++++++
 lib/apps/fabro-cli/tests/it/cmd/validate.rs   |  33 +++++
 .../fabro-mcp-server/src/manifest_builder.rs  |   2 +-
 .../fabro-server/src/manifest_validation.rs   |  23 +++-
 lib/apps/fabro-server/src/run_manifest.rs     |  40 +++---
 .../fabro-server/src/run_tool_manifest.rs     |  11 +-
 .../fabro-server/src/server/handler/graph.rs  |   2 +-
 .../fabro-server/src/server/handler/runs.rs   |  22 ++-
 .../src/handler/manager_loop.rs               |  42 +++---
 .../fabro-workflow/src/operations/create.rs   | 109 +++++++++++----
 .../fabro-workflow/src/operations/mod.rs      |   2 +-
 .../fabro-workflow/src/operations/validate.rs |  73 +++++++---
 .../fabro-workflow/src/pipeline/mod.rs        |   8 +-
 .../fabro-workflow/src/pipeline/transform.rs  | 128 +++++++++++-------
 .../fabro-workflow/src/pipeline/types.rs      |  34 ++++-
 .../fabro-workflow/src/pipeline/validate.rs   |  47 ++++---
 .../fabro-workflow/tests/it/integration.rs    |  23 ++--
 20 files changed, 449 insertions(+), 216 deletions(-)

diff --git a/lib/apps/fabro-cli/src/commands/run/create.rs b/lib/apps/fabro-cli/src/commands/run/create.rs
index ad4360384..159160d7e 100644
--- a/lib/apps/fabro-cli/src/commands/run/create.rs
+++ b/lib/apps/fabro-cli/src/commands/run/create.rs
@@ -61,11 +61,8 @@ pub(crate) async fn create_run(
         None
     };
 
-    let mut validation = manifest_validation::validate_manifest(
-        &RunLayer::default(),
-        &built.manifest,
-        ctx.catalog()?,
-    )?;
+    let mut validation =
+        manifest_validation::validate_manifest(&RunLayer::default(), &built.manifest)?;
     manifest_validation::promote_template_undefined_variables_to_errors(&mut validation);
     let diagnostics = api_diagnostics_to_local(&validation.workflow.diagnostics);
     if !quiet {
diff --git a/lib/apps/fabro-cli/src/commands/run/runner.rs b/lib/apps/fabro-cli/src/commands/run/runner.rs
index 4e6b72b8b..4c6fcf578 100644
--- a/lib/apps/fabro-cli/src/commands/run/runner.rs
+++ b/lib/apps/fabro-cli/src/commands/run/runner.rs
@@ -263,12 +263,7 @@ impl fabro_tool::RunManifestBuilder for WorkerRunManifestBuilder {
         cwd: &Path,
         user_settings_path: &Path,
     ) -> fabro_tool::ToolResult<RunManifest> {
-        run_tool_manifest::build_run_tool_manifest(
-            spec,
-            cwd,
-            user_settings_path,
-            Arc::clone(&self.catalog),
-        )
+        run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, &self.catalog)
     }
 }
 
diff --git a/lib/apps/fabro-cli/src/commands/validate.rs b/lib/apps/fabro-cli/src/commands/validate.rs
index b87460f28..e157b50b3 100644
--- a/lib/apps/fabro-cli/src/commands/validate.rs
+++ b/lib/apps/fabro-cli/src/commands/validate.rs
@@ -23,11 +23,7 @@ pub(crate) fn run(
         user_settings_path: Some(active_settings_path(None)),
         ..Default::default()
     })?;
-    let response = manifest_validation::validate_manifest(
-        &RunLayer::default(),
-        &built.manifest,
-        base_ctx.catalog()?,
-    )?;
+    let response = manifest_validation::validate_manifest(&RunLayer::default(), &built.manifest)?;
     let diagnostics = api_diagnostics_to_local(&response.workflow.diagnostics);
 
     if base_ctx.json_output() {
diff --git a/lib/apps/fabro-cli/tests/it/cmd/create.rs b/lib/apps/fabro-cli/tests/it/cmd/create.rs
index 5a9a4402f..462a0996f 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/create.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/create.rs
@@ -101,6 +101,52 @@ fn create_uses_explicit_server_target_and_prints_remote_run_id() {
     assert_eq!(output_stdout(&output).trim(), run_id.as_str());
 }
 
+#[test]
+fn create_defers_provider_validation_to_the_server() {
+    let context = test_context!();
+    let server = MockServer::start();
+    let run_id = unique_run_id();
+    let mock = server.mock(|when, then| {
+        when.method("POST")
+            .path("/api/v1/runs")
+            .body_includes(r#"provider=\"server-only\""#);
+        then.status(201)
+            .header("Content-Type", "application/json")
+            .body(run_status_response(run_id.as_str(), "submitted").to_string());
+    });
+    let workflow_path = context.temp_dir.join("server-model.fabro");
+    context.write_temp(
+        "server-model.fabro",
+        r#"digraph ServerModel {
+            graph [goal="Use a server-owned model"]
+            start [shape=Mdiamond]
+            work [prompt="Do work", model="private-model", provider="server-only"]
+            exit [shape=Msquare]
+            start -> work -> exit
+        }"#,
+    );
+
+    let output = context
+        .create_cmd()
+        .args([
+            "--server",
+            &format!("{}/api/v1", server.base_url()),
+            "--dry-run",
+            workflow_path.to_str().unwrap(),
+        ])
+        .output()
+        .expect("command should execute");
+
+    assert!(
+        output.status.success(),
+        "local validation should not reject a server-owned provider\nstdout:\n{}\nstderr:\n{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr)
+    );
+    mock.assert();
+    assert_eq!(output_stdout(&output).trim(), run_id.as_str());
+}
+
 #[test]
 fn create_uses_configured_server_target_without_server_flag() {
     let context = test_context!();
diff --git a/lib/apps/fabro-cli/tests/it/cmd/validate.rs b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
index 190c2817b..2bbec8c76 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/validate.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
@@ -69,6 +69,39 @@ fn simple_does_not_connect_to_configured_server() {
     );
 }
 
+#[test]
+#[expect(
+    clippy::disallowed_methods,
+    reason = "sync CLI test writes one workflow fixture before spawning the subprocess"
+)]
+fn server_owned_provider_is_not_rejected_by_offline_validation() {
+    let cli = LightweightCli::new();
+    let workflow = cli.home().join("server-model.fabro");
+    std::fs::write(
+        &workflow,
+        r#"digraph ServerModel {
+            graph [goal="Use a server-owned model"]
+            start [shape=Mdiamond]
+            work [prompt="Do work", model="private-model", provider="server-only"]
+            exit [shape=Msquare]
+            start -> work -> exit
+        }"#,
+    )
+    .expect("workflow fixture should be written");
+    let mut cmd = cli.command();
+    cmd.env("FABRO_SERVER", "http://127.0.0.1:9")
+        .arg("validate")
+        .arg(&workflow);
+
+    let output = cmd.output().expect("validate should execute");
+    assert!(
+        output.status.success(),
+        "offline validation should leave provider availability to the server\nstdout:\n{}\nstderr:\n{}",
+        String::from_utf8_lossy(&output.stdout),
+        String::from_utf8_lossy(&output.stderr),
+    );
+}
+
 #[test]
 fn branching() {
     let context = test_context!();
diff --git a/lib/apps/fabro-mcp-server/src/manifest_builder.rs b/lib/apps/fabro-mcp-server/src/manifest_builder.rs
index 53e899f1e..8c1cb8125 100644
--- a/lib/apps/fabro-mcp-server/src/manifest_builder.rs
+++ b/lib/apps/fabro-mcp-server/src/manifest_builder.rs
@@ -32,5 +32,5 @@ fn build_mcp_run_manifest(
         Catalog::from_builtin_with_overrides(&llm_catalog_settings)
             .map_err(|err| ToolError::message(err.to_string()))?,
     );
-    run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, catalog)
+    run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, &catalog)
 }
diff --git a/lib/apps/fabro-server/src/manifest_validation.rs b/lib/apps/fabro-server/src/manifest_validation.rs
index baca3f014..3016fde65 100644
--- a/lib/apps/fabro-server/src/manifest_validation.rs
+++ b/lib/apps/fabro-server/src/manifest_validation.rs
@@ -12,21 +12,34 @@ use crate::run_manifest;
 pub fn validate_manifest(
     manifest_run_defaults: &RunLayer,
     manifest: &types::RunManifest,
-    catalog: Arc<Catalog>,
 ) -> Result<types::ValidateResponse> {
     validate_manifest_with_environment_defaults(
         manifest_run_defaults,
         &fabro_environment::seeded_catalog_layer(),
         manifest,
-        catalog,
     )
 }
 
+pub fn validate_manifest_with_catalog(
+    manifest_run_defaults: &RunLayer,
+    manifest: &types::RunManifest,
+    catalog: &Arc<Catalog>,
+) -> Result<types::ValidateResponse> {
+    let prepared = run_manifest::prepare_manifest_with_environment_defaults(
+        manifest_run_defaults,
+        &fabro_environment::seeded_catalog_layer(),
+        &HashMap::new(),
+        manifest,
+    )?;
+    let validated =
+        run_manifest::validate_prepared_manifest(&prepared, catalog).map_err(anyhow::Error::new)?;
+    Ok(run_manifest::validate_response(&prepared, &validated))
+}
+
 pub fn validate_manifest_with_environment_defaults(
     manifest_run_defaults: &RunLayer,
     manifest_environment_defaults: &MergeMap<EnvironmentLayer>,
     manifest: &types::RunManifest,
-    catalog: Arc<Catalog>,
 ) -> Result<types::ValidateResponse> {
     let prepared = run_manifest::prepare_manifest_with_environment_defaults(
         manifest_run_defaults,
@@ -34,8 +47,8 @@ pub fn validate_manifest_with_environment_defaults(
         &HashMap::new(),
         manifest,
     )?;
-    let validated =
-        run_manifest::validate_prepared_manifest(&prepared, catalog).map_err(anyhow::Error::new)?;
+    let validated = run_manifest::validate_prepared_manifest_structural(&prepared)
+        .map_err(anyhow::Error::new)?;
     Ok(run_manifest::validate_response(&prepared, &validated))
 }
 
diff --git a/lib/apps/fabro-server/src/run_manifest.rs b/lib/apps/fabro-server/src/run_manifest.rs
index 65cc6d36e..76a81db51 100644
--- a/lib/apps/fabro-server/src/run_manifest.rs
+++ b/lib/apps/fabro-server/src/run_manifest.rs
@@ -35,7 +35,8 @@ use fabro_util::check_report::{CheckDetail, CheckReport, CheckResult, CheckSecti
 use fabro_validate::Severity;
 use fabro_workflow::Error as WorkflowError;
 use fabro_workflow::operations::{
-    CreateRunInput, ValidateInput, WorkflowInput, validate, validate_with_ready_providers,
+    CreateRunInput, ValidateInput, WorkflowInput, validate, validate_with_catalog,
+    validate_with_ready_providers,
 };
 use fabro_workflow::pipeline::Validated;
 use fabro_workflow::run_materialization::materialize_run_with_ready_providers;
@@ -187,34 +188,40 @@ pub(crate) fn prepare_manifest_with_environment_defaults(
 
 pub(crate) fn validate_prepared_manifest(
     prepared: &PreparedManifest,
-    catalog: Arc<Catalog>,
+    catalog: &Arc<Catalog>,
 ) -> Result<Validated, WorkflowError> {
     validate_prepared_manifest_with_vars(prepared, catalog, HashMap::new())
 }
 
+pub(crate) fn validate_prepared_manifest_structural(
+    prepared: &PreparedManifest,
+) -> Result<Validated, WorkflowError> {
+    validate(manifest_validate_input(prepared, HashMap::new()))
+}
+
 pub(crate) fn validate_prepared_manifest_with_vars(
     prepared: &PreparedManifest,
-    catalog: Arc<Catalog>,
+    catalog: &Arc<Catalog>,
     vars: HashMap<String, String>,
 ) -> Result<Validated, WorkflowError> {
-    validate(manifest_validate_input(prepared, catalog, vars))
+    validate_with_catalog(manifest_validate_input(prepared, vars), catalog)
 }
 
 pub(crate) fn validate_prepared_manifest_for_preflight(
     prepared: &PreparedManifest,
-    catalog: Arc<Catalog>,
+    catalog: &Arc<Catalog>,
     vars: HashMap<String, String>,
     ready_providers: &[ProviderId],
 ) -> Result<Validated, WorkflowError> {
     validate_with_ready_providers(
-        manifest_validate_input(prepared, catalog, vars),
+        manifest_validate_input(prepared, vars),
+        catalog,
         ready_providers,
     )
 }
 
 fn manifest_validate_input(
     prepared: &PreparedManifest,
-    catalog: Arc<Catalog>,
     vars: HashMap<String, String>,
 ) -> ValidateInput {
     ValidateInput {
@@ -223,7 +230,6 @@ fn manifest_validate_input(
         vars,
         cwd: prepared.cwd.clone(),
         custom_transforms: Vec::new(),
-        catalog,
     }
 }
 
@@ -1548,7 +1554,7 @@ digraph Demo {{
         .unwrap();
         let validated = validate_prepared_manifest_for_preflight(
             &prepared,
-            state.catalog(),
+            &state.catalog(),
             HashMap::new(),
             &ready_providers,
         )
@@ -1633,7 +1639,7 @@ enabled = {clone_enabled}
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
         let resolved = materialize_run(
             prepared.settings.clone(),
             validated.graph(),
@@ -2193,7 +2199,7 @@ name = "Control Plane"
             &invalid_manifest(),
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
 
         assert!(validated.has_errors());
 
@@ -2238,7 +2244,7 @@ issues = "read"
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
         assert!(!validated.has_errors());
 
         let (response, _ok) = resolve_and_run_preflight(state.as_ref(), &prepared, &validated)
@@ -2288,7 +2294,7 @@ id = "local"
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
 
         assert!(!validated.has_errors());
 
@@ -2397,7 +2403,7 @@ id = "daytona"
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
 
         let (response, _ok) = resolve_and_run_preflight(state.as_ref(), &prepared, &validated)
             .await
@@ -2465,7 +2471,7 @@ digraph Demo {
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
 
         let (response, ok) = resolve_and_run_preflight(state.as_ref(), &prepared, &validated)
             .await
@@ -2579,7 +2585,7 @@ digraph Demo {
             &manifest,
         )
         .unwrap();
-        let Err(error) = validate_prepared_manifest(&prepared, test_catalog()) else {
+        let Err(error) = validate_prepared_manifest(&prepared, &test_catalog()) else {
             panic!("unknown provider should fail static validation");
         };
 
@@ -2646,7 +2652,7 @@ digraph Demo {
         assert!(ready_providers.is_empty());
         let validated = validate_prepared_manifest_for_preflight(
             &prepared,
-            state.catalog(),
+            &state.catalog(),
             HashMap::new(),
             &ready_providers,
         )
diff --git a/lib/apps/fabro-server/src/run_tool_manifest.rs b/lib/apps/fabro-server/src/run_tool_manifest.rs
index 8e38e8317..66204e208 100644
--- a/lib/apps/fabro-server/src/run_tool_manifest.rs
+++ b/lib/apps/fabro-server/src/run_tool_manifest.rs
@@ -14,7 +14,7 @@ pub fn build_run_tool_manifest(
     spec: &ValidatedCreateRunSpec,
     cwd: &Path,
     user_settings_path: &Path,
-    catalog: Arc<Catalog>,
+    catalog: &Arc<Catalog>,
 ) -> ToolResult<types::RunManifest> {
     let built = fabro_manifest::build_run_manifest(ManifestBuildInput {
         workflow:             PathBuf::from(&spec.workflow),
@@ -29,9 +29,12 @@ pub fn build_run_tool_manifest(
     })
     .map_err(|err| ToolError::from_anyhow(&err))?;
 
-    let mut validation =
-        manifest_validation::validate_manifest(&RunLayer::default(), &built.manifest, catalog)
-            .map_err(|err| ToolError::from_anyhow(&err))?;
+    let mut validation = manifest_validation::validate_manifest_with_catalog(
+        &RunLayer::default(),
+        &built.manifest,
+        catalog,
+    )
+    .map_err(|err| ToolError::from_anyhow(&err))?;
     manifest_validation::promote_template_undefined_variables_to_errors(&mut validation);
     if !validation.ok {
         return Err(ToolError::message("workflow manifest validation failed"));
diff --git a/lib/apps/fabro-server/src/server/handler/graph.rs b/lib/apps/fabro-server/src/server/handler/graph.rs
index 364b19cad..ea95b674a 100644
--- a/lib/apps/fabro-server/src/server/handler/graph.rs
+++ b/lib/apps/fabro-server/src/server/handler/graph.rs
@@ -52,7 +52,7 @@ async fn render_graph_from_manifest(
         Ok(prepared) => prepared,
         Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
     };
-    let validated = match run_manifest::validate_prepared_manifest(&prepared, state.catalog()) {
+    let validated = match run_manifest::validate_prepared_manifest(&prepared, &state.catalog()) {
         Ok(validated) => validated,
         Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
     };
diff --git a/lib/apps/fabro-server/src/server/handler/runs.rs b/lib/apps/fabro-server/src/server/handler/runs.rs
index 0e2c8cbcb..a0cbcbf70 100644
--- a/lib/apps/fabro-server/src/server/handler/runs.rs
+++ b/lib/apps/fabro-server/src/server/handler/runs.rs
@@ -829,7 +829,7 @@ async fn run_preflight(
     let (llm_result, ready_providers) = state.resolve_llm_client_with_ready_ids().await;
     let mut validated = match run_manifest::validate_prepared_manifest_for_preflight(
         &prepared,
-        state.catalog(),
+        &state.catalog(),
         vars,
         &ready_providers,
     ) {
@@ -879,17 +879,15 @@ async fn validate_run_manifest(
         return ApiError::bad_request(format!("Run config variable interpolation failed: {err}"))
             .into_response();
     }
-    let validated = match run_manifest::validate_prepared_manifest_with_vars(
-        &prepared,
-        state.catalog(),
-        vars,
-    ) {
-        Ok(validated) => validated,
-        Err(WorkflowError::Parse(_)) => {
-            return ApiError::bad_request("Validation failed").into_response();
-        }
-        Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
-    };
+    let validated =
+        match run_manifest::validate_prepared_manifest_with_vars(&prepared, &state.catalog(), vars)
+        {
+            Ok(validated) => validated,
+            Err(WorkflowError::Parse(_)) => {
+                return ApiError::bad_request("Validation failed").into_response();
+            }
+            Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
+        };
     (
         StatusCode::OK,
         Json(run_manifest::validate_response(&prepared, &validated)),
diff --git a/lib/components/fabro-workflow/src/handler/manager_loop.rs b/lib/components/fabro-workflow/src/handler/manager_loop.rs
index 98804d5e9..ddefe84be 100644
--- a/lib/components/fabro-workflow/src/handler/manager_loop.rs
+++ b/lib/components/fabro-workflow/src/handler/manager_loop.rs
@@ -16,7 +16,7 @@ use crate::artifact_upload::ArtifactSink;
 use crate::condition::evaluate_condition;
 use crate::context::{Context, WorkflowContext, context_diff_public, keys};
 use crate::error::Error;
-use crate::operations::{ValidateInput, WorkflowInput, validate};
+use crate::operations::{ValidateInput, WorkflowInput, validate_with_catalog};
 use crate::outcome::{Outcome, OutcomeExt, StageOutcome};
 use crate::pipeline::types::Initialized;
 use crate::run_options::RunOptions;
@@ -65,17 +65,19 @@ fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<ParsedChi
         .get("stack.child_dot_source")
         .and_then(|v| v.as_str())
     {
-        let mut validated = validate(ValidateInput {
-            workflow:          WorkflowInput::DotSource {
-                source:   dot.to_string(),
-                base_dir: None,
+        let mut validated = validate_with_catalog(
+            ValidateInput {
+                workflow:          WorkflowInput::DotSource {
+                    source:   dot.to_string(),
+                    base_dir: None,
+                },
+                settings:          WorkflowSettings::default(),
+                vars:              std::collections::HashMap::new(),
+                cwd:               cwd.clone(),
+                custom_transforms: Vec::new(),
             },
-            settings:          WorkflowSettings::default(),
-            vars:              std::collections::HashMap::new(),
-            cwd:               cwd.clone(),
-            custom_transforms: Vec::new(),
-            catalog:           Arc::clone(&services.run.catalog),
-        })?;
+            &services.run.catalog,
+        )?;
         validated.promote_template_undefined_variables_to_errors();
         validated.raise_on_errors()?;
         let (graph, _, _) = validated.into_parts();
@@ -113,14 +115,16 @@ fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<ParsedChi
             WorkflowInput::Bundled(workflow) => Some(workflow.path.clone()),
             WorkflowInput::Path(_) | WorkflowInput::DotSource { .. } => None,
         };
-        let mut validated = validate(ValidateInput {
-            workflow,
-            settings: WorkflowSettings::default(),
-            vars: std::collections::HashMap::new(),
-            cwd,
-            custom_transforms: Vec::new(),
-            catalog: Arc::clone(&services.run.catalog),
-        })?;
+        let mut validated = validate_with_catalog(
+            ValidateInput {
+                workflow,
+                settings: WorkflowSettings::default(),
+                vars: std::collections::HashMap::new(),
+                cwd,
+                custom_transforms: Vec::new(),
+            },
+            &services.run.catalog,
+        )?;
         validated.promote_template_undefined_variables_to_errors();
         validated.raise_on_errors()?;
         let (graph, _, _) = validated.into_parts();
diff --git a/lib/components/fabro-workflow/src/operations/create.rs b/lib/components/fabro-workflow/src/operations/create.rs
index 2ec40d443..4fff69898 100644
--- a/lib/components/fabro-workflow/src/operations/create.rs
+++ b/lib/components/fabro-workflow/src/operations/create.rs
@@ -24,7 +24,9 @@ use crate::error::Error;
 use crate::event::{Event, append_event, to_run_event_at};
 use crate::file_resolver::FileResolver;
 use crate::pipeline::types::PersistOptions;
-use crate::pipeline::{self, Persisted, TransformOptions, Validated};
+use crate::pipeline::{
+    self, ModelResolutionOptions, Persisted, TransformOptions, Transformed, Validated,
+};
 use crate::records::RunSpec;
 use crate::run_lookup::default_scratch_base;
 use crate::run_materialization::materialize_run;
@@ -340,6 +342,69 @@ pub(super) fn preprocess_and_validate(
     catalog_fallback: bool,
     catalog: &Arc<Catalog>,
 ) -> Result<Validated, Error> {
+    let model_resolution = ModelResolutionOptions {
+        catalog: Arc::clone(catalog),
+        default_provider,
+        eligible_providers: eligible_providers.iter().cloned().collect(),
+        catalog_fallback,
+    };
+    let transformed = preprocess(
+        dot_source,
+        source_name,
+        current_dir,
+        file_resolver,
+        custom_transforms,
+        template_context,
+        goal_override,
+        render_mode,
+        Some(model_resolution),
+    )?;
+    Ok(pipeline::validate_with_catalog(
+        transformed,
+        catalog.as_ref(),
+        &[],
+    ))
+}
+
+pub(super) fn preprocess_and_validate_structural(
+    dot_source: &str,
+    source_name: Option<String>,
+    current_dir: Option<PathBuf>,
+    file_resolver: Option<Arc<dyn FileResolver>>,
+    custom_transforms: Vec<Box<dyn Transform>>,
+    template_context: TemplateContext,
+    goal_override: Option<&str>,
+    render_mode: RenderMode,
+) -> Result<Validated, Error> {
+    let transformed = preprocess(
+        dot_source,
+        source_name,
+        current_dir,
+        file_resolver,
+        custom_transforms,
+        template_context,
+        goal_override,
+        render_mode,
+        None,
+    )?;
+    Ok(pipeline::validate(transformed, &[]))
+}
+
+#[expect(
+    clippy::too_many_arguments,
+    reason = "pipeline stages have distinct source, rendering, and model-resolution inputs"
+)]
+fn preprocess(
+    dot_source: &str,
+    source_name: Option<String>,
+    current_dir: Option<PathBuf>,
+    file_resolver: Option<Arc<dyn FileResolver>>,
+    custom_transforms: Vec<Box<dyn Transform>>,
+    template_context: TemplateContext,
+    goal_override: Option<&str>,
+    render_mode: RenderMode,
+    model_resolution: Option<ModelResolutionOptions>,
+) -> Result<Transformed, Error> {
     let mut parsed = pipeline::parse(dot_source)?;
     apply_goal_override(&mut parsed.graph, goal_override);
 
@@ -350,12 +415,9 @@ pub(super) fn preprocess_and_validate(
         source_name,
         render_mode,
         custom_transforms,
-        catalog: Arc::clone(catalog),
-        default_provider,
-        eligible_providers: eligible_providers.iter().cloned().collect(),
-        catalog_fallback,
+        model_resolution,
     })?;
-    Ok(pipeline::validate(transformed, catalog.as_ref(), &[]))
+    Ok(transformed)
 }
 
 pub(super) fn template_context(
@@ -462,7 +524,7 @@ mod tests {
     use object_store::memory::InMemory;
 
     use super::*;
-    use crate::operations::{ValidateInput, validate};
+    use crate::operations::{ValidateInput, validate, validate_with_catalog};
     use crate::pipeline::types::{GOAL_SELF_REFERENCE_RULE, TEMPLATE_UNDEFINED_VARIABLE_RULE};
     use crate::workflow_bundle::BundledWorkflow;
     fn memory_store() -> Arc<Database> {
@@ -553,17 +615,19 @@ reasoning = false
     }
 
     fn validate_dot(dot_source: &str, settings: WorkflowSettings) -> Validated {
-        validate(ValidateInput {
-            workflow: WorkflowInput::DotSource {
-                source:   dot_source.to_string(),
-                base_dir: None,
+        validate_with_catalog(
+            ValidateInput {
+                workflow: WorkflowInput::DotSource {
+                    source:   dot_source.to_string(),
+                    base_dir: None,
+                },
+                settings,
+                vars: HashMap::new(),
+                cwd: PathBuf::from("."),
+                custom_transforms: Vec::new(),
             },
-            settings,
-            vars: HashMap::new(),
-            cwd: PathBuf::from("."),
-            custom_transforms: Vec::new(),
-            catalog: test_catalog(),
-        })
+            &test_catalog(),
+        )
         .unwrap()
     }
 
@@ -852,7 +916,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               PathBuf::from("."),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         });
 
         assert!(result.is_err());
@@ -901,7 +964,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               dir.path().to_path_buf(),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
         let file_missing = validate(ValidateInput {
@@ -920,7 +982,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               dir.path().to_path_buf(),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
         assert_eq!(
@@ -944,7 +1005,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               dir.path().to_path_buf(),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
         let file_goal = validate(ValidateInput {
@@ -963,7 +1023,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               dir.path().to_path_buf(),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
         assert_eq!(
@@ -1055,7 +1114,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               PathBuf::from("."),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         });
         assert!(result.is_err());
     }
@@ -1100,7 +1158,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               PathBuf::from("."),
             custom_transforms: vec![Box::new(TagTransform)],
-            catalog:           test_catalog(),
         })
         .unwrap();
         validated.raise_on_errors().unwrap();
@@ -1135,7 +1192,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               dir.path().to_path_buf(),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
         validated.raise_on_errors().unwrap();
@@ -1177,7 +1233,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               dir.path().to_path_buf(),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
 
@@ -1227,7 +1282,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               PathBuf::from("."),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
 
@@ -1278,7 +1332,6 @@ reasoning = false
             vars:              HashMap::new(),
             cwd:               PathBuf::from("."),
             custom_transforms: Vec::new(),
-            catalog:           test_catalog(),
         })
         .unwrap();
 
diff --git a/lib/components/fabro-workflow/src/operations/mod.rs b/lib/components/fabro-workflow/src/operations/mod.rs
index 38b7d9aaa..9523c5ff5 100644
--- a/lib/components/fabro-workflow/src/operations/mod.rs
+++ b/lib/components/fabro-workflow/src/operations/mod.rs
@@ -22,7 +22,7 @@ pub use rewind::{RewindInput, RewindOutcome, rewind};
 pub use source::WorkflowInput;
 pub use start::{StartServices, Started, start};
 pub use timeline::{ForkTarget, RunTimeline, TimelineEntry, build_timeline, timeline};
-pub use validate::{ValidateInput, validate, validate_with_ready_providers};
+pub use validate::{ValidateInput, validate, validate_with_catalog, validate_with_ready_providers};
 
 pub use crate::pipeline::{LlmSpec, SandboxEnvSpec};
 pub use crate::transforms::RenderMode;
diff --git a/lib/components/fabro-workflow/src/operations/validate.rs b/lib/components/fabro-workflow/src/operations/validate.rs
index c2b990f5c..7ac5e4531 100644
--- a/lib/components/fabro-workflow/src/operations/validate.rs
+++ b/lib/components/fabro-workflow/src/operations/validate.rs
@@ -5,7 +5,9 @@ use std::sync::Arc;
 use fabro_model::{Catalog, ProviderId};
 use fabro_types::WorkflowSettings;
 
-use super::create::{preprocess_and_validate, template_context};
+use super::create::{
+    preprocess_and_validate, preprocess_and_validate_structural, template_context,
+};
 use super::source::{ResolveWorkflowInput, WorkflowInput, resolve_workflow};
 use crate::error::Error;
 use crate::operations::RenderMode;
@@ -20,20 +22,50 @@ pub struct ValidateInput {
     pub vars:              HashMap<String, String>,
     pub cwd:               PathBuf,
     pub custom_transforms: Vec<Box<dyn Transform>>,
-    pub catalog:           Arc<Catalog>,
 }
 
-/// Parse, transform, and validate a DOT source string.
+/// Parse, transform, and structurally validate a DOT source string without a
+/// model catalog.
 ///
 /// Returns `Validated` even when validation produced errors. Call
 /// `validated.raise_on_errors()` if the caller wants to fail fast.
 pub fn validate(input: ValidateInput) -> Result<Validated, Error> {
-    let eligible_providers = input
-        .catalog
-        .all_provider_ids()
-        .into_iter()
-        .collect::<Vec<_>>();
-    validate_with_eligible_providers(input, &eligible_providers, false)
+    let ValidateInput {
+        workflow,
+        settings,
+        vars,
+        cwd,
+        custom_transforms,
+    } = input;
+    let resolved = resolve_workflow(ResolveWorkflowInput {
+        workflow,
+        settings,
+        cwd,
+    })
+    .map_err(|err| Error::Parse(err.to_string()))?;
+
+    preprocess_and_validate_structural(
+        &resolved.raw_source,
+        resolved
+            .dot_path
+            .as_ref()
+            .map(|path| path.display().to_string()),
+        resolved.current_dir,
+        resolved.file_resolver,
+        custom_transforms,
+        template_context(Some(&resolved.settings), vars),
+        resolved.goal_override.as_deref(),
+        RenderMode::Structural,
+    )
+}
+
+/// Parse, transform, and validate a DOT source string against `catalog`.
+pub fn validate_with_catalog(
+    input: ValidateInput,
+    catalog: &Arc<Catalog>,
+) -> Result<Validated, Error> {
+    let eligible_providers = catalog.all_provider_ids().into_iter().collect::<Vec<_>>();
+    validate_with_eligible_providers(input, catalog, &eligible_providers, false)
 }
 
 /// Parse, transform, and validate, resolving models against the ready
@@ -41,20 +73,29 @@ pub fn validate(input: ValidateInput) -> Result<Validated, Error> {
 /// provider-readiness selection failures.
 pub fn validate_with_ready_providers(
     input: ValidateInput,
+    catalog: &Arc<Catalog>,
     ready_providers: &[ProviderId],
 ) -> Result<Validated, Error> {
-    validate_with_eligible_providers(input, ready_providers, true)
+    validate_with_eligible_providers(input, catalog, ready_providers, true)
 }
 
 fn validate_with_eligible_providers(
     input: ValidateInput,
+    catalog: &Arc<Catalog>,
     eligible_providers: &[ProviderId],
     catalog_fallback: bool,
 ) -> Result<Validated, Error> {
+    let ValidateInput {
+        workflow,
+        settings,
+        vars,
+        cwd,
+        custom_transforms,
+    } = input;
     let resolved = resolve_workflow(ResolveWorkflowInput {
-        workflow: input.workflow,
-        settings: input.settings,
-        cwd:      input.cwd,
+        workflow,
+        settings,
+        cwd,
     })
     .map_err(|err| Error::Parse(err.to_string()))?;
 
@@ -66,8 +107,8 @@ fn validate_with_eligible_providers(
             .map(|path| path.display().to_string()),
         resolved.current_dir,
         resolved.file_resolver,
-        input.custom_transforms,
-        template_context(Some(&resolved.settings), input.vars),
+        custom_transforms,
+        template_context(Some(&resolved.settings), vars),
         resolved.goal_override.as_deref(),
         RenderMode::Structural,
         resolved
@@ -80,6 +121,6 @@ fn validate_with_eligible_providers(
             .map(fabro_model::ProviderId::new),
         eligible_providers,
         catalog_fallback,
-        &input.catalog,
+        catalog,
     )
 }
diff --git a/lib/components/fabro-workflow/src/pipeline/mod.rs b/lib/components/fabro-workflow/src/pipeline/mod.rs
index d0ba5ae1b..c1cc3b4f9 100644
--- a/lib/components/fabro-workflow/src/pipeline/mod.rs
+++ b/lib/components/fabro-workflow/src/pipeline/mod.rs
@@ -22,8 +22,8 @@ pub use pull_request::{
 };
 pub use transform::transform;
 pub use types::{
-    Concluded, Executed, FinalizeOptions, Finalized, InitOptions, Initialized, LlmSpec, Parsed,
-    Persisted, PullRequestOptions, ResumeState, SandboxEnvSpec, TEMPLATE_UNDEFINED_VARIABLE_RULE,
-    TransformOptions, Transformed, Validated,
+    Concluded, Executed, FinalizeOptions, Finalized, InitOptions, Initialized, LlmSpec,
+    ModelResolutionOptions, Parsed, Persisted, PullRequestOptions, ResumeState, SandboxEnvSpec,
+    TEMPLATE_UNDEFINED_VARIABLE_RULE, TransformOptions, Transformed, Validated,
 };
-pub use validate::validate;
+pub use validate::{validate, validate_with_catalog};
diff --git a/lib/components/fabro-workflow/src/pipeline/transform.rs b/lib/components/fabro-workflow/src/pipeline/transform.rs
index b399d6637..d73b26275 100644
--- a/lib/components/fabro-workflow/src/pipeline/transform.rs
+++ b/lib/components/fabro-workflow/src/pipeline/transform.rs
@@ -63,13 +63,17 @@ pub fn transform(parsed: Parsed, options: &TransformOptions) -> Result<Transform
     .apply_with_diagnostics(graph)?;
     diagnostics.extend(transform_diagnostics);
     let graph = StylesheetApplicationTransform.apply(graph)?;
-    let graph = ModelResolutionTransform::for_eligible(
-        Arc::clone(&options.catalog),
-        options.eligible_providers.clone(),
-    )
-    .with_default_provider(options.default_provider.clone())
-    .with_catalog_fallback(options.catalog_fallback)
-    .apply(graph)?;
+    let graph = if let Some(model_resolution) = &options.model_resolution {
+        ModelResolutionTransform::for_eligible(
+            Arc::clone(&model_resolution.catalog),
+            model_resolution.eligible_providers.clone(),
+        )
+        .with_default_provider(model_resolution.default_provider.clone())
+        .with_catalog_fallback(model_resolution.catalog_fallback)
+        .apply(graph)?
+    } else {
+        graph
+    };
 
     // Custom transforms
     let graph = options
@@ -97,7 +101,9 @@ mod tests {
     use super::*;
     use crate::file_resolver::FilesystemFileResolver;
     use crate::pipeline::parse::parse;
-    use crate::pipeline::types::{GOAL_SELF_REFERENCE_RULE, TEMPLATE_UNDEFINED_VARIABLE_RULE};
+    use crate::pipeline::types::{
+        GOAL_SELF_REFERENCE_RULE, ModelResolutionOptions, TEMPLATE_UNDEFINED_VARIABLE_RULE,
+    };
 
     fn write_file(path: &Path, contents: &str) {
         if let Some(parent) = path.parent() {
@@ -112,16 +118,13 @@ mod tests {
 
     fn transform_options() -> TransformOptions {
         TransformOptions {
-            current_dir:        None,
-            file_resolver:      None,
-            template_context:   fabro_template::TemplateContext::new(),
-            source_name:        None,
-            render_mode:        crate::operations::RenderMode::Strict,
-            custom_transforms:  vec![],
-            catalog:            test_catalog(),
-            default_provider:   None,
-            eligible_providers: Catalog::builtin().all_provider_ids(),
-            catalog_fallback:   false,
+            current_dir:       None,
+            file_resolver:     None,
+            template_context:  fabro_template::TemplateContext::new(),
+            source_name:       None,
+            render_mode:       crate::operations::RenderMode::Strict,
+            custom_transforms: vec![],
+            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
         }
     }
 
@@ -177,16 +180,13 @@ mod tests {
         )
         .unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:        Some(dir.path().to_path_buf()),
-            file_resolver:      Some(Arc::new(FilesystemFileResolver::new(None))),
-            template_context:   fabro_template::TemplateContext::new(),
-            source_name:        None,
-            render_mode:        crate::operations::RenderMode::Strict,
-            custom_transforms:  vec![],
-            catalog:            test_catalog(),
-            default_provider:   None,
-            eligible_providers: Catalog::builtin().all_provider_ids(),
-            catalog_fallback:   false,
+            current_dir:       Some(dir.path().to_path_buf()),
+            file_resolver:     Some(Arc::new(FilesystemFileResolver::new(None))),
+            template_context:  fabro_template::TemplateContext::new(),
+            source_name:       None,
+            render_mode:       crate::operations::RenderMode::Strict,
+            custom_transforms: vec![],
+            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
         })
         .unwrap();
 
@@ -227,21 +227,18 @@ mod tests {
         )
         .unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:        Some(dir.path().to_path_buf()),
-            file_resolver:      Some(Arc::new(FilesystemFileResolver::new(None))),
-            template_context:   fabro_template::TemplateContext::new().with_inputs(HashMap::from(
-                [(
+            current_dir:       Some(dir.path().to_path_buf()),
+            file_resolver:     Some(Arc::new(FilesystemFileResolver::new(None))),
+            template_context:  fabro_template::TemplateContext::new().with_inputs(HashMap::from([
+                (
                     "task".to_string(),
                     toml::Value::String("Launch".to_string()),
-                )],
-            )),
-            source_name:        None,
-            render_mode:        crate::operations::RenderMode::Strict,
-            custom_transforms:  vec![],
-            catalog:            test_catalog(),
-            default_provider:   None,
-            eligible_providers: Catalog::builtin().all_provider_ids(),
-            catalog_fallback:   false,
+                ),
+            ])),
+            source_name:       None,
+            render_mode:       crate::operations::RenderMode::Strict,
+            custom_transforms: vec![],
+            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
         })
         .unwrap();
 
@@ -349,6 +346,38 @@ mod tests {
         );
     }
 
+    #[test]
+    fn structural_transform_preserves_catalog_owned_model_selection() {
+        let dot = r#"digraph Test {
+            graph [goal="Test"]
+            start [shape=Mdiamond]
+            work [prompt="Do work", model="private-model", provider="server-only"]
+            exit [shape=Msquare]
+            start -> work -> exit
+        }"#;
+        let parsed = parse(dot).unwrap();
+        let transformed = transform(parsed, &TransformOptions {
+            current_dir:       None,
+            file_resolver:     None,
+            template_context:  fabro_template::TemplateContext::new(),
+            source_name:       None,
+            render_mode:       crate::operations::RenderMode::Strict,
+            custom_transforms: vec![],
+            model_resolution:  None,
+        })
+        .unwrap();
+        let work = &transformed.graph.nodes["work"];
+
+        assert_eq!(
+            work.attrs.get("model").and_then(AttrValue::as_str),
+            Some("private-model")
+        );
+        assert_eq!(
+            work.attrs.get("provider").and_then(AttrValue::as_str),
+            Some("server-only")
+        );
+    }
+
     #[test]
     fn transform_reports_goal_self_reference_once_across_passes() {
         // FileInlining renders the goal for prompt context, but TemplateTransform
@@ -365,16 +394,13 @@ mod tests {
         )
         .unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:        Some(dir.path().to_path_buf()),
-            file_resolver:      Some(Arc::new(FilesystemFileResolver::new(None))),
-            template_context:   fabro_template::TemplateContext::new(),
-            source_name:        None,
-            render_mode:        crate::operations::RenderMode::Structural,
-            custom_transforms:  vec![],
-            catalog:            test_catalog(),
-            default_provider:   None,
-            eligible_providers: Catalog::builtin().all_provider_ids(),
-            catalog_fallback:   false,
+            current_dir:       Some(dir.path().to_path_buf()),
+            file_resolver:     Some(Arc::new(FilesystemFileResolver::new(None))),
+            template_context:  fabro_template::TemplateContext::new(),
+            source_name:       None,
+            render_mode:       crate::operations::RenderMode::Structural,
+            custom_transforms: vec![],
+            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
         })
         .unwrap();
 
diff --git a/lib/components/fabro-workflow/src/pipeline/types.rs b/lib/components/fabro-workflow/src/pipeline/types.rs
index 425cba9aa..29f5fbf9e 100644
--- a/lib/components/fabro-workflow/src/pipeline/types.rs
+++ b/lib/components/fabro-workflow/src/pipeline/types.rs
@@ -359,13 +359,20 @@ pub struct Finalized {
 
 /// Options for the TRANSFORM phase.
 pub struct TransformOptions {
-    pub current_dir:        Option<PathBuf>,
-    pub file_resolver:      Option<Arc<dyn FileResolver>>,
-    pub template_context:   TemplateContext,
-    pub source_name:        Option<String>,
-    pub render_mode:        RenderMode,
-    pub custom_transforms:  Vec<Box<dyn Transform>>,
-    pub catalog:            Arc<fabro_model::Catalog>,
+    pub current_dir:       Option<PathBuf>,
+    pub file_resolver:     Option<Arc<dyn FileResolver>>,
+    pub template_context:  TemplateContext,
+    pub source_name:       Option<String>,
+    pub render_mode:       RenderMode,
+    pub custom_transforms: Vec<Box<dyn Transform>>,
+    /// Catalog-backed model resolution to perform. `None` preserves authored
+    /// model and provider selectors for catalog-free structural validation.
+    pub model_resolution:  Option<ModelResolutionOptions>,
+}
+
+/// Catalog-backed model resolution options for the TRANSFORM phase.
+pub struct ModelResolutionOptions {
+    pub catalog:            Arc<Catalog>,
     pub default_provider:   Option<ProviderId>,
     pub eligible_providers: HashSet<ProviderId>,
     /// Fall back to the full catalog when the eligible providers cannot
@@ -373,6 +380,19 @@ pub struct TransformOptions {
     pub catalog_fallback:   bool,
 }
 
+impl ModelResolutionOptions {
+    #[must_use]
+    pub fn new(catalog: Arc<Catalog>) -> Self {
+        let eligible_providers = catalog.all_provider_ids();
+        Self {
+            catalog,
+            default_provider: None,
+            eligible_providers,
+            catalog_fallback: false,
+        }
+    }
+}
+
 /// Options for the FINALIZE phase.
 pub struct FinalizeOptions {
     pub run_dir:          PathBuf,
diff --git a/lib/components/fabro-workflow/src/pipeline/validate.rs b/lib/components/fabro-workflow/src/pipeline/validate.rs
index f0cd51dbd..00601b4a4 100644
--- a/lib/components/fabro-workflow/src/pipeline/validate.rs
+++ b/lib/components/fabro-workflow/src/pipeline/validate.rs
@@ -1,15 +1,28 @@
-use fabro_model::Catalog;
 use fabro_validate::LintRule;
 
 use super::types::{Transformed, Validated};
 
-/// VALIDATE phase: run lint rules against the transformed graph.
+/// VALIDATE phase: run catalog-free lint rules against the transformed graph.
 ///
 /// **Infallible.** Always returns `Validated` with diagnostics. Caller decides
 /// whether to fail via `validated.raise_on_errors()`.
-pub fn validate(
+pub fn validate(transformed: Transformed, extra_rules: &[&dyn LintRule]) -> Validated {
+    let Transformed {
+        graph,
+        source,
+        mut diagnostics,
+    } = transformed;
+    diagnostics.extend(fabro_validate::validate(&graph, extra_rules));
+    Validated::new(graph, source, diagnostics)
+}
+
+/// VALIDATE phase: run catalog-free and catalog-backed lint rules.
+///
+/// **Infallible.** Always returns `Validated` with diagnostics. Caller decides
+/// whether to fail via `validated.raise_on_errors()`.
+pub fn validate_with_catalog(
     transformed: Transformed,
-    catalog: &Catalog,
+    catalog: &fabro_model::Catalog,
     extra_rules: &[&dyn LintRule],
 ) -> Validated {
     let Transformed {
@@ -27,34 +40,24 @@ pub fn validate(
 
 #[cfg(test)]
 mod tests {
-    use fabro_model::Catalog;
-
     use super::*;
     use crate::pipeline::parse::parse;
     use crate::pipeline::transform;
     use crate::pipeline::types::TransformOptions;
 
-    fn test_catalog() -> std::sync::Arc<Catalog> {
-        std::sync::Arc::new(Catalog::from_builtin().unwrap())
-    }
-
     fn run_pipeline(dot: &str) -> Validated {
-        let catalog = test_catalog();
         let parsed = parse(dot).unwrap();
         let transformed = transform::transform(parsed, &TransformOptions {
-            current_dir:        None,
-            file_resolver:      None,
-            template_context:   fabro_template::TemplateContext::new(),
-            source_name:        None,
-            render_mode:        crate::operations::RenderMode::Strict,
-            custom_transforms:  vec![],
-            catalog:            std::sync::Arc::clone(&catalog),
-            default_provider:   None,
-            eligible_providers: catalog.all_provider_ids(),
-            catalog_fallback:   false,
+            current_dir:       None,
+            file_resolver:     None,
+            template_context:  fabro_template::TemplateContext::new(),
+            source_name:       None,
+            render_mode:       crate::operations::RenderMode::Strict,
+            custom_transforms: vec![],
+            model_resolution:  None,
         })
         .unwrap();
-        validate(transformed, catalog.as_ref(), &[])
+        validate(transformed, &[])
     }
 
     #[test]
diff --git a/lib/components/fabro-workflow/tests/it/integration.rs b/lib/components/fabro-workflow/tests/it/integration.rs
index dc13bcbf8..b07f600fe 100644
--- a/lib/components/fabro-workflow/tests/it/integration.rs
+++ b/lib/components/fabro-workflow/tests/it/integration.rs
@@ -4853,7 +4853,9 @@ async fn manager_loop_child_workflow_e2e() {
 
 #[tokio::test]
 async fn import_e2e_through_engine() {
-    use fabro_workflow::pipeline::{TransformOptions, transform, validate};
+    use fabro_workflow::pipeline::{
+        ModelResolutionOptions, TransformOptions, transform, validate_with_catalog,
+    };
 
     let dir = tempfile::tempdir().unwrap();
     let catalog = std::sync::Arc::new(
@@ -4897,21 +4899,18 @@ async fn import_e2e_through_engine() {
     )
     .expect("parse should succeed");
     let transformed = transform(parsed, &TransformOptions {
-        current_dir:        Some(dir.path().to_path_buf()),
-        file_resolver:      Some(std::sync::Arc::new(
+        current_dir:       Some(dir.path().to_path_buf()),
+        file_resolver:     Some(std::sync::Arc::new(
             fabro_workflow::file_resolver::FilesystemFileResolver::new(None),
         )),
-        template_context:   fabro_template::TemplateContext::new(),
-        source_name:        None,
-        render_mode:        fabro_workflow::operations::RenderMode::Strict,
-        custom_transforms:  vec![],
-        catalog:            std::sync::Arc::clone(&catalog),
-        default_provider:   None,
-        eligible_providers: catalog.all_provider_ids(),
-        catalog_fallback:   false,
+        template_context:  fabro_template::TemplateContext::new(),
+        source_name:       None,
+        render_mode:       fabro_workflow::operations::RenderMode::Strict,
+        custom_transforms: vec![],
+        model_resolution:  Some(ModelResolutionOptions::new(std::sync::Arc::clone(&catalog))),
     })
     .unwrap();
-    let validated = validate(transformed, catalog.as_ref(), &[]);
+    let validated = validate_with_catalog(transformed, catalog.as_ref(), &[]);
     validated
         .raise_on_errors()
         .expect("validation should pass after imports expand");

From 59b1c2e59ffca7cf5f491c4fe65e7650afb48a28 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 13:53:54 -0400
Subject: [PATCH 04/36] Reject nodes referenced by an edge but never declared
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The DOT parser created a node for every edge endpoint, and nothing
recorded whether a node came from a declaration or was synthesized from
an edge. The edge_target_exists rule only checked whether the node id
was present in the graph, which was always true by then, so a misspelled
endpoint became an attribute-free node that defaulted to shape=box — an
LLM stage. Validation emitted a prompt_on_llm_nodes warning and exited 0.

Node now carries `implicit`, set only when the parser synthesizes the
node from an edge endpoint. A declaration anywhere in the workflow
clears it, so order does not matter and subgraph declarations count.
Node::new leaves it false, so programmatic construction and graphs
deserialized from older checkpoints read as declared.

edge_target_exists treats an endpoint as valid only when it exists and
is declared, reporting each undeclared node once. The near-identical
missing-source and missing-target branches collapse into one path. The
import transform copies the flag onto spliced nodes so an edge-only node
inside an imported fragment is caught too.

parse_and_validate_human_gate had two edge-only nodes and now declares
them; it was an instance of the bug rather than a casualty of the fix.
No shipped workflow, docs example, or CLI fixture relied on the old
behavior.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/public/reference/dot-language.mdx        |   2 +-
 lib/apps/fabro-cli/tests/it/cmd/validate.rs   |  20 +++
 .../fabro-graphviz/src/parser/semantic.rs     |  93 +++++++++-
 .../src/rules/edge_target_exists.rs           | 168 ++++++++++++++----
 .../fabro-workflow/src/transforms/import.rs   |  49 +++++
 .../fabro-workflow/tests/it/integration.rs    |   3 +
 lib/foundation/fabro-types/src/graph.rs       |  18 +-
 .../fabro-types/src/run_event/mod.rs          |   7 +-
 test/edge_only_node.fabro                     |  10 ++
 9 files changed, 326 insertions(+), 44 deletions(-)
 create mode 100644 test/edge_only_node.fabro

diff --git a/docs/public/reference/dot-language.mdx b/docs/public/reference/dot-language.mdx
index 8c350d1ba..ee44c3668 100644
--- a/docs/public/reference/dot-language.mdx
+++ b/docs/public/reference/dot-language.mdx
@@ -113,7 +113,7 @@ plan [label="Plan", prompt="Create an implementation plan."]
 
 **Node identifiers** must start with a letter or underscore, followed by letters, digits, or underscores (e.g. `run_tests`, `gate_1`, `_private`).
 
-Nodes referenced in edges are auto-created if not explicitly declared.
+Every node used by an edge needs its own declaration. Validation fails when an edge names a node the workflow never declares, because that is nearly always a typo or a rename that missed an edge. The declaration can come before or after the edges that use it, and it can live in a subgraph.
 
 ### Edge declarations
 
diff --git a/lib/apps/fabro-cli/tests/it/cmd/validate.rs b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
index 190c2817b..98b0f9cfe 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/validate.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
@@ -278,6 +278,26 @@ fn validate_reports_missing_template_dependency() {
     ");
 }
 
+/// A node named only by an edge is almost always a typo, so validation must
+/// fail instead of quietly running it as a default agent stage.
+#[test]
+fn edge_only_node() {
+    let context = test_context!();
+    let mut cmd = context.validate();
+    cmd.arg(fixture("edge_only_node.fabro"));
+    fabro_snapshot!(context.filters(), cmd, @"
+    success: false
+    exit_code: 1
+    ----- stdout -----
+    ----- stderr -----
+    Workflow: EdgeOnlyNode (3 nodes, 2 edges)
+    Graph: [FIXTURES]/edge_only_node.fabro
+    error [node: misspelled_node]: Node 'misspelled_node' is referenced by edge 'start -> misspelled_node' but has no node declaration (edge_target_exists)
+    warning [node: misspelled_node]: LLM node 'misspelled_node' has no prompt or label attribute (prompt_on_llm_nodes)
+      × Validation failed
+    ");
+}
+
 #[test]
 fn invalid() {
     let context = test_context!();
diff --git a/lib/components/fabro-graphviz/src/parser/semantic.rs b/lib/components/fabro-graphviz/src/parser/semantic.rs
index 8ac364cab..4e9433e6b 100644
--- a/lib/components/fabro-graphviz/src/parser/semantic.rs
+++ b/lib/components/fabro-graphviz/src/parser/semantic.rs
@@ -57,6 +57,14 @@ fn derive_class_from_label(label: &str) -> String {
         .collect()
 }
 
+/// How a statement named a node. A node stays implicit only while every
+/// mention of it is an edge endpoint, so declaration order does not matter.
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum Mention {
+    Declaration,
+    EdgeEndpoint,
+}
+
 struct SemanticState {
     graph:         Graph,
     node_defaults: HashMap<String, AttrValue>,
@@ -72,13 +80,25 @@ impl SemanticState {
         }
     }
 
-    fn ensure_node(&mut self, id: &str) {
+    /// Insert the node if this is the first statement to mention it, and record
+    /// whether the workflow ever declares it.
+    fn ensure_node(&mut self, id: &str, mention: Mention) {
         if !self.graph.nodes.contains_key(id) {
             let mut node = Node::new(id);
             for (k, v) in &self.node_defaults {
                 node.attrs.insert(k.clone(), v.clone());
             }
+            node.implicit = mention == Mention::EdgeEndpoint;
             self.graph.nodes.insert(id.to_string(), node);
+            return;
+        }
+        if mention == Mention::Declaration {
+            let node = self
+                .graph
+                .nodes
+                .get_mut(id)
+                .expect("contains_key returned true, so get_mut cannot return None");
+            node.implicit = false;
         }
     }
 
@@ -90,7 +110,7 @@ impl SemanticState {
     }
 
     fn process_node(&mut self, node_stmt: &NodeStmt, subgraph_class: Option<&str>) {
-        self.ensure_node(&node_stmt.id);
+        self.ensure_node(&node_stmt.id, Mention::Declaration);
         let node = self
             .graph
             .nodes
@@ -127,7 +147,7 @@ impl SemanticState {
 
     fn process_edge(&mut self, edge_stmt: &EdgeStmt, subgraph_class: Option<&str>) {
         for id in &edge_stmt.nodes {
-            self.ensure_node(id);
+            self.ensure_node(id, Mention::EdgeEndpoint);
             if let Some(cls) = subgraph_class {
                 let node =
                     self.graph.nodes.get_mut(id).expect(
@@ -527,5 +547,72 @@ mod tests {
         let graph = ast_to_graph(&dot).unwrap();
         assert!(graph.nodes.contains_key("a"));
         assert!(graph.nodes.contains_key("b"));
+        assert!(graph.nodes["a"].implicit);
+        assert!(graph.nodes["b"].implicit);
+    }
+
+    #[test]
+    fn ast_to_graph_marks_declared_nodes_explicit() {
+        let dot = DotGraph {
+            name:       "Declared".into(),
+            statements: vec![
+                Statement::Node(NodeStmt {
+                    id:    "a".into(),
+                    attrs: None,
+                }),
+                Statement::Edge(EdgeStmt {
+                    nodes: vec!["a".into(), "b".into()],
+                    attrs: None,
+                }),
+            ],
+        };
+
+        let graph = ast_to_graph(&dot).unwrap();
+        assert!(!graph.nodes["a"].implicit);
+        assert!(graph.nodes["b"].implicit);
+    }
+
+    #[test]
+    fn ast_to_graph_declaration_after_edge_still_counts() {
+        let dot = DotGraph {
+            name:       "DeclaredLater".into(),
+            statements: vec![
+                Statement::Edge(EdgeStmt {
+                    nodes: vec!["a".into(), "b".into()],
+                    attrs: None,
+                }),
+                Statement::Node(NodeStmt {
+                    id:    "b".into(),
+                    attrs: Some(vec![("prompt".into(), AstValue::Str("Do it".into()))]),
+                }),
+            ],
+        };
+
+        let graph = ast_to_graph(&dot).unwrap();
+        assert!(!graph.nodes["b"].implicit);
+    }
+
+    #[test]
+    fn ast_to_graph_subgraph_declaration_counts() {
+        let dot = DotGraph {
+            name:       "SubgraphDeclared".into(),
+            statements: vec![
+                Statement::Edge(EdgeStmt {
+                    nodes: vec!["start".into(), "plan".into()],
+                    attrs: None,
+                }),
+                Statement::Subgraph(SubgraphStmt {
+                    name:       Some("cluster_loop".into()),
+                    statements: vec![Statement::Node(NodeStmt {
+                        id:    "plan".into(),
+                        attrs: None,
+                    })],
+                }),
+            ],
+        };
+
+        let graph = ast_to_graph(&dot).unwrap();
+        assert!(!graph.nodes["plan"].implicit);
+        assert!(graph.nodes["start"].implicit);
     }
 }
diff --git a/lib/components/fabro-validate/src/rules/edge_target_exists.rs b/lib/components/fabro-validate/src/rules/edge_target_exists.rs
index 8cfe67282..adc70283b 100644
--- a/lib/components/fabro-validate/src/rules/edge_target_exists.rs
+++ b/lib/components/fabro-validate/src/rules/edge_target_exists.rs
@@ -1,3 +1,5 @@
+use std::collections::HashSet;
+
 use fabro_graphviz::graph::Graph;
 
 use crate::{Diagnostic, LintRule, Severity};
@@ -8,6 +10,33 @@ pub(super) fn rule() -> Box<dyn LintRule> {
 
 struct Rule;
 
+impl Rule {
+    /// An edge endpoint is only usable when the workflow declares it. A node
+    /// the parser synthesized from the edge itself carries no attributes, so it
+    /// would silently run as a default agent stage.
+    fn is_declared(graph: &Graph, node_id: &str) -> bool {
+        graph.nodes.get(node_id).is_some_and(|node| !node.implicit)
+    }
+
+    fn diagnostic(&self, node_id: &str, from: &str, to: &str) -> Diagnostic {
+        Diagnostic {
+            rule: self.name().to_string(),
+            severity: Severity::Error,
+            message: format!(
+                "Node '{node_id}' is referenced by edge '{from} -> {to}' but has no node \
+                 declaration"
+            ),
+            node_id: Some(node_id.to_string()),
+            edge: Some((from.to_string(), to.to_string())),
+            fix: Some(format!(
+                "Declare node '{node_id}' or correct the edge endpoint"
+            )),
+
+            ..Diagnostic::default()
+        }
+    }
+}
+
 impl LintRule for Rule {
     fn name(&self) -> &'static str {
         "edge_target_exists"
@@ -15,36 +44,12 @@ impl LintRule for Rule {
 
     fn apply(&self, graph: &Graph) -> Vec<Diagnostic> {
         let mut diagnostics = Vec::new();
+        let mut reported = HashSet::new();
         for edge in &graph.edges {
-            if !graph.nodes.contains_key(&edge.to) {
-                diagnostics.push(Diagnostic {
-                    rule: self.name().to_string(),
-                    severity: Severity::Error,
-                    message: format!(
-                        "Edge from '{}' targets non-existent node '{}'",
-                        edge.from, edge.to
-                    ),
-                    node_id: None,
-                    edge: Some((edge.from.clone(), edge.to.clone())),
-                    fix: Some(format!("Define node '{}' or fix the edge target", edge.to)),
-
-                    ..Diagnostic::default()
-                });
-            }
-            if !graph.nodes.contains_key(&edge.from) {
-                diagnostics.push(Diagnostic {
-                    rule: self.name().to_string(),
-                    severity: Severity::Error,
-                    message: format!("Edge source '{}' references non-existent node", edge.from),
-                    node_id: None,
-                    edge: Some((edge.from.clone(), edge.to.clone())),
-                    fix: Some(format!(
-                        "Define node '{}' or fix the edge source",
-                        edge.from
-                    )),
-
-                    ..Diagnostic::default()
-                });
+            for endpoint in [&edge.to, &edge.from] {
+                if !Self::is_declared(graph, endpoint) && reported.insert(endpoint) {
+                    diagnostics.push(self.diagnostic(endpoint, &edge.from, &edge.to));
+                }
             }
         }
         diagnostics
@@ -53,11 +58,112 @@ impl LintRule for Rule {
 
 #[cfg(test)]
 mod tests {
-    use fabro_graphviz::graph::Edge;
+    use fabro_graphviz::graph::{Edge, Graph};
+    use fabro_graphviz::parser;
 
     use super::Rule;
     use crate::rules::test_support::minimal_graph;
-    use crate::{LintRule, Severity};
+    use crate::{Diagnostic, LintRule, Severity};
+
+    fn parse(dot: &str) -> Graph {
+        parser::parse(dot).expect("fixture should parse")
+    }
+
+    fn undeclared_nodes(graph: &Graph) -> Vec<String> {
+        Rule.apply(graph)
+            .iter()
+            .map(|d| d.node_id.clone().expect("diagnostic should name a node"))
+            .collect()
+    }
+
+    #[test]
+    fn edge_only_node_is_rejected() {
+        let graph = parse(
+            r"digraph EdgeOnly {
+                start [shape=Mdiamond]
+                exit  [shape=Msquare]
+                start -> misspelled_node
+                misspelled_node -> exit
+            }",
+        );
+
+        let diagnostics = Rule.apply(&graph);
+        assert_eq!(diagnostics.len(), 1, "diagnostics: {diagnostics:?}");
+        let Diagnostic {
+            severity,
+            node_id,
+            edge,
+            ..
+        } = &diagnostics[0];
+        assert_eq!(*severity, Severity::Error);
+        assert_eq!(node_id.as_deref(), Some("misspelled_node"));
+        assert_eq!(
+            edge.clone(),
+            Some(("start".to_string(), "misspelled_node".to_string()))
+        );
+    }
+
+    #[test]
+    fn declaration_after_the_edge_is_accepted() {
+        let graph = parse(
+            r#"digraph DeclaredLater {
+                start -> work
+                work [prompt="Do the work"]
+                work -> exit
+                start [shape=Mdiamond]
+                exit  [shape=Msquare]
+            }"#,
+        );
+
+        assert!(Rule.apply(&graph).is_empty());
+    }
+
+    #[test]
+    fn chained_edges_report_every_undeclared_endpoint() {
+        let graph = parse(
+            r"digraph Chained {
+                start [shape=Mdiamond]
+                exit  [shape=Msquare]
+                start -> first -> second -> exit
+            }",
+        );
+
+        assert_eq!(undeclared_nodes(&graph), vec!["first", "second"]);
+    }
+
+    #[test]
+    fn a_node_is_reported_once_no_matter_how_many_edges_use_it() {
+        let graph = parse(
+            r"digraph Repeated {
+                start [shape=Mdiamond]
+                exit  [shape=Msquare]
+                start -> typo
+                typo -> exit
+                typo -> start
+            }",
+        );
+
+        assert_eq!(undeclared_nodes(&graph), vec!["typo"]);
+    }
+
+    #[test]
+    fn subgraph_declaration_is_accepted() {
+        let graph = parse(
+            r#"digraph Subgraphed {
+                start [shape=Mdiamond]
+                exit  [shape=Msquare]
+
+                subgraph cluster_loop {
+                    label = "Loop A"
+                    plan [prompt="Plan the work"]
+                }
+
+                start -> plan -> exit
+            }"#,
+        );
+
+        assert!(Rule.apply(&graph).is_empty());
+    }
 
     #[test]
     fn edge_target_exists_rule_missing_target() {
diff --git a/lib/components/fabro-workflow/src/transforms/import.rs b/lib/components/fabro-workflow/src/transforms/import.rs
index b5406ddc6..cfda146c3 100644
--- a/lib/components/fabro-workflow/src/transforms/import.rs
+++ b/lib/components/fabro-workflow/src/transforms/import.rs
@@ -346,6 +346,7 @@ impl ImportTransform {
 
             let prefixed_id = format!("{placeholder_id}.{node_id}");
             let mut merged_node = Node::new(&prefixed_id);
+            merged_node.implicit = node.implicit;
             merged_node.attrs.clone_from(&placeholder.default_attrs);
             merged_node.attrs.extend(node.attrs);
             Self::remap_retry_target(&mut merged_node.attrs, placeholder_id);
@@ -951,6 +952,54 @@ mod tests {
         );
     }
 
+    #[test]
+    fn imported_node_declarations_survive_splicing() {
+        let dir = tempfile::tempdir().unwrap();
+        write_file(&dir.path().join("validate.fabro"), basic_import_source());
+
+        let graph = apply_import(
+            r#"digraph Deploy {
+                start [shape=Mdiamond]
+                validate [import="./validate.fabro"]
+                exit [shape=Msquare]
+                start -> validate -> exit
+            }"#,
+            dir.path(),
+            None,
+        );
+
+        assert!(!graph.nodes["validate.lint"].implicit);
+        assert!(!graph.nodes["validate.test"].implicit);
+    }
+
+    #[test]
+    fn edge_only_node_in_imported_fragment_stays_undeclared() {
+        let dir = tempfile::tempdir().unwrap();
+        write_file(
+            &dir.path().join("validate.fabro"),
+            r#"digraph validate {
+                start [shape=Mdiamond]
+                lint [prompt="Run clippy"]
+                exit [shape=Msquare]
+                start -> lint -> typo -> exit
+            }"#,
+        );
+
+        let graph = apply_import(
+            r#"digraph Deploy {
+                start [shape=Mdiamond]
+                validate [import="./validate.fabro"]
+                exit [shape=Msquare]
+                start -> validate -> exit
+            }"#,
+            dir.path(),
+            None,
+        );
+
+        assert!(graph.nodes["validate.typo"].implicit);
+        assert!(!graph.nodes["validate.lint"].implicit);
+    }
+
     #[test]
     fn import_reports_structural_diagnostic_for_imported_prompt_templates() {
         let dir = tempfile::tempdir().unwrap();
diff --git a/lib/components/fabro-workflow/tests/it/integration.rs b/lib/components/fabro-workflow/tests/it/integration.rs
index dc13bcbf8..ec716adbc 100644
--- a/lib/components/fabro-workflow/tests/it/integration.rs
+++ b/lib/components/fabro-workflow/tests/it/integration.rs
@@ -388,6 +388,9 @@ fn parse_and_validate_human_gate() {
             type="human"
         ]
 
+        ship_it [prompt="Ship the change"]
+        fixes   [prompt="Apply the requested fixes"]
+
         start -> review_gate
         review_gate -> ship_it [label="[A] Approve"]
         review_gate -> fixes   [label="[F] Fix"]
diff --git a/lib/foundation/fabro-types/src/graph.rs b/lib/foundation/fabro-types/src/graph.rs
index 7ef9bad99..3ed6851a6 100644
--- a/lib/foundation/fabro-types/src/graph.rs
+++ b/lib/foundation/fabro-types/src/graph.rs
@@ -119,20 +119,26 @@ pub fn shape_to_handler_type(shape: &str) -> Option<&'static str> {
 /// A node in the workflow graph.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Node {
-    pub id:      String,
-    pub attrs:   HashMap<String, AttrValue>,
+    pub id:       String,
+    pub attrs:    HashMap<String, AttrValue>,
     /// CSS-like classes for model stylesheet targeting (from `class` attr and
     /// subgraph derivation).
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub classes: Vec<String>,
+    pub classes:  Vec<String>,
+    /// True when the node was synthesized from an edge endpoint instead of a
+    /// node declaration. Validation rejects these because an edge-only node in
+    /// an executable workflow is almost always a typo.
+    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
+    pub implicit: bool,
 }
 
 impl Node {
     pub fn new(id: impl Into<String>) -> Self {
         Self {
-            id:      id.into(),
-            attrs:   HashMap::new(),
-            classes: Vec::new(),
+            id:       id.into(),
+            attrs:    HashMap::new(),
+            classes:  Vec::new(),
+            implicit: false,
         }
     }
 
diff --git a/lib/foundation/fabro-types/src/run_event/mod.rs b/lib/foundation/fabro-types/src/run_event/mod.rs
index d4c8e55c1..e4e99e59f 100644
--- a/lib/foundation/fabro-types/src/run_event/mod.rs
+++ b/lib/foundation/fabro-types/src/run_event/mod.rs
@@ -995,9 +995,10 @@ mod tests {
         let graph = Graph {
             name:  "test".to_string(),
             nodes: HashMap::from([("start".to_string(), Node {
-                id:      "start".to_string(),
-                attrs:   HashMap::new(),
-                classes: Vec::new(),
+                id:       "start".to_string(),
+                attrs:    HashMap::new(),
+                classes:  Vec::new(),
+                implicit: false,
             })]),
             edges: vec![Edge {
                 from:  "start".to_string(),
diff --git a/test/edge_only_node.fabro b/test/edge_only_node.fabro
new file mode 100644
index 000000000..3d45b3346
--- /dev/null
+++ b/test/edge_only_node.fabro
@@ -0,0 +1,10 @@
+digraph EdgeOnlyNode {
+    graph [goal="Reference a node that was never declared"]
+
+    /* `misspelled_node` is only ever named by an edge, never declared. */
+    start [shape=Mdiamond, label="Start"]
+    exit [shape=Msquare, label="Exit"]
+
+    start -> misspelled_node
+    misspelled_node -> exit
+}

From c501c67185892cad0714859eedb4676e1552d7a6 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 14:06:31 -0400
Subject: [PATCH 05/36] Show each diagnostic's suggested fix in CLI output
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Diagnostics have carried a `fix` field all along, but the CLI renderer
never printed it — the suggestion was only reachable through --json. The
actionable half of every validation failure was invisible to the person
running the command.

print_diagnostics now emits the fix as a dim-labelled continuation line
under any diagnostic that has one, at both error and warning severity.
Gating it behind --verbose would defeat the point, and printing it only
for errors would read as "this warning has no fix" — the warning
suggestions are useful on their own. Diagnostics that set no fix simply
omit the line.

The severity match moved into print_diagnostic so the fix line is
appended once in the loop rather than copied into all five arms; the
rest of the diff is reindentation.

print_diagnostics is shared by validate, preflight, graph, exec, and
dry-run, so this covers all five. Eleven inline snapshots across four
files gain a fix line; every change is additive.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/apps/fabro-cli/src/shared/utilities.rs    | 98 ++++++++++---------
 lib/apps/fabro-cli/tests/it/cmd/graph.rs      |  4 +
 lib/apps/fabro-cli/tests/it/cmd/preflight.rs  |  4 +
 lib/apps/fabro-cli/tests/it/cmd/validate.rs   |  9 ++
 .../tests/it/workflow/dry_run_examples.rs     |  1 +
 5 files changed, 72 insertions(+), 44 deletions(-)

diff --git a/lib/apps/fabro-cli/src/shared/utilities.rs b/lib/apps/fabro-cli/src/shared/utilities.rs
index e9cd32bf6..8cfb05af7 100644
--- a/lib/apps/fabro-cli/src/shared/utilities.rs
+++ b/lib/apps/fabro-cli/src/shared/utilities.rs
@@ -49,54 +49,64 @@ where
 
 pub(crate) fn print_diagnostics(diagnostics: &[Diagnostic], styles: &Styles, printer: Printer) {
     for d in diagnostics {
-        let location = match (&d.node_id, &d.edge) {
-            (Some(node), _) => format!(" [node: {node}]"),
-            (_, Some((from, to))) => format!(" [edge: {from} -> {to}]"),
-            _ => String::new(),
-        };
-        let source_prefix = source_prefix(d);
-        match d.severity {
-            Severity::Error if source_prefix.is_empty() => fabro_util::printerr!(
-                printer,
-                "{}{location}: {} ({})",
-                styles.red.apply_to("error"),
-                d.message,
-                styles.dim.apply_to(&d.rule),
-            ),
-            Severity::Error => fabro_util::printerr!(
-                printer,
-                "{}: {source_prefix}{}{location} ({})",
-                styles.red.apply_to("error"),
-                d.message,
-                styles.dim.apply_to(&d.rule),
-            ),
-            Severity::Warning if source_prefix.is_empty() => fabro_util::printerr!(
-                printer,
-                "{}{location}: {} ({})",
-                styles.yellow.apply_to("warning"),
-                d.message,
-                styles.dim.apply_to(&d.rule),
-            ),
-            Severity::Warning => fabro_util::printerr!(
-                printer,
-                "{}: {source_prefix}{}{location} ({})",
-                styles.yellow.apply_to("warning"),
-                d.message,
-                styles.dim.apply_to(&d.rule),
-            ),
-            Severity::Info => fabro_util::printerr!(
-                printer,
-                "{}",
-                styles.dim.apply_to(if source_prefix.is_empty() {
-                    format!("info{location}: {} ({})", d.message, d.rule)
-                } else {
-                    format!("info: {source_prefix}{}{location} ({})", d.message, d.rule)
-                }),
-            ),
+        print_diagnostic(d, styles, printer);
+        // The fix is the actionable half of a diagnostic, so it follows every
+        // severity rather than hiding behind --verbose. Rules that have nothing
+        // useful to suggest leave it unset.
+        if let Some(fix) = &d.fix {
+            fabro_util::printerr!(printer, "  {} {fix}", styles.dim.apply_to("fix:"));
         }
     }
 }
 
+fn print_diagnostic(d: &Diagnostic, styles: &Styles, printer: Printer) {
+    let location = match (&d.node_id, &d.edge) {
+        (Some(node), _) => format!(" [node: {node}]"),
+        (_, Some((from, to))) => format!(" [edge: {from} -> {to}]"),
+        _ => String::new(),
+    };
+    let source_prefix = source_prefix(d);
+    match d.severity {
+        Severity::Error if source_prefix.is_empty() => fabro_util::printerr!(
+            printer,
+            "{}{location}: {} ({})",
+            styles.red.apply_to("error"),
+            d.message,
+            styles.dim.apply_to(&d.rule),
+        ),
+        Severity::Error => fabro_util::printerr!(
+            printer,
+            "{}: {source_prefix}{}{location} ({})",
+            styles.red.apply_to("error"),
+            d.message,
+            styles.dim.apply_to(&d.rule),
+        ),
+        Severity::Warning if source_prefix.is_empty() => fabro_util::printerr!(
+            printer,
+            "{}{location}: {} ({})",
+            styles.yellow.apply_to("warning"),
+            d.message,
+            styles.dim.apply_to(&d.rule),
+        ),
+        Severity::Warning => fabro_util::printerr!(
+            printer,
+            "{}: {source_prefix}{}{location} ({})",
+            styles.yellow.apply_to("warning"),
+            d.message,
+            styles.dim.apply_to(&d.rule),
+        ),
+        Severity::Info => fabro_util::printerr!(
+            printer,
+            "{}",
+            styles.dim.apply_to(if source_prefix.is_empty() {
+                format!("info{location}: {} ({})", d.message, d.rule)
+            } else {
+                format!("info: {source_prefix}{}{location} ({})", d.message, d.rule)
+            }),
+        ),
+    }
+}
+
 fn source_prefix(diagnostic: &Diagnostic) -> String {
     match (
         diagnostic.source_path.as_deref(),
diff --git a/lib/apps/fabro-cli/tests/it/cmd/graph.rs b/lib/apps/fabro-cli/tests/it/cmd/graph.rs
index 6b801928a..fbf48599f 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/graph.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/graph.rs
@@ -95,7 +95,9 @@ fn graph_allow_invalid_renders_after_diagnostics() {
     ----- stdout -----
     ----- stderr -----
     error: Pipeline must have exactly one start node (shape=Mdiamond or id start/Start) (start_node)
+      fix: Add a node with shape=Mdiamond or id 'start'
     error [node: exit]: Exit node 'exit' has 1 outgoing edge(s) but must have none (exit_no_outgoing)
+      fix: Remove outgoing edges from the exit node
     ");
 
     let svg = read_text(&output_path);
@@ -119,7 +121,9 @@ fn graph_invalid_workflow_fails_after_diagnostics() {
     ----- stdout -----
     ----- stderr -----
     error: Pipeline must have exactly one start node (shape=Mdiamond or id start/Start) (start_node)
+      fix: Add a node with shape=Mdiamond or id 'start'
     error [node: exit]: Exit node 'exit' has 1 outgoing edge(s) but must have none (exit_no_outgoing)
+      fix: Remove outgoing edges from the exit node
       × Validation failed
     ");
 }
diff --git a/lib/apps/fabro-cli/tests/it/cmd/preflight.rs b/lib/apps/fabro-cli/tests/it/cmd/preflight.rs
index 8bb035f3a..4a2e44c8a 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/preflight.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/preflight.rs
@@ -52,7 +52,9 @@ fn preflight_invalid_workflow_fails_with_validation_output() {
     Workflow: Invalid (2 nodes, 1 edges)
     Graph: [FIXTURES]/invalid.fabro
     error: Pipeline must have exactly one start node (shape=Mdiamond or id start/Start) (start_node)
+      fix: Add a node with shape=Mdiamond or id 'start'
     error [node: exit]: Exit node 'exit' has 1 outgoing edge(s) but must have none (exit_no_outgoing)
+      fix: Remove outgoing edges from the exit node
       × Validation failed
     ");
 }
@@ -74,7 +76,9 @@ fn preflight_rejects_unbound_template_inputs() {
     Goal: Demo
 
     error: [FIXTURES]/templated_unbound.fabro:2:26: undefined template variable `inputs.app_dir` in graph attribute `goal` (template_undefined_variable)
+      fix: bind `inputs.app_dir` via `[run.inputs]` in workflow.toml, or pass `--input inputs.app_dir=<value>`
     error: [FIXTURES]/templated_unbound.fabro:7:44: undefined template variable `inputs.app_dir` in node `work` attribute `prompt` [node: work] (template_undefined_variable)
+      fix: bind `inputs.app_dir` via `[run.inputs]` in workflow.toml, or pass `--input inputs.app_dir=<value>`
       × Validation failed
     ");
 }
diff --git a/lib/apps/fabro-cli/tests/it/cmd/validate.rs b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
index 98b0f9cfe..caeab11ca 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/validate.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
@@ -82,6 +82,7 @@ fn branching() {
     Workflow: Branch (6 nodes, 6 edges)
     Graph: [FIXTURES]/branching.fabro
     warning [node: implement]: Node 'implement' has goal_gate=true but no retry_target or fallback_retry_target (goal_gate_has_retry)
+      fix: Add retry_target or fallback_retry_target attribute
     Validation: OK
     ");
 }
@@ -163,7 +164,9 @@ fn bare_fabro_with_unbound_inputs_validates_structurally_with_warning() {
     Workflow: TemplatedUnbound (3 nodes, 2 edges)
     Graph: [FIXTURES]/templated_unbound.fabro
     warning: [FIXTURES]/templated_unbound.fabro:2:26: undefined template variable `inputs.app_dir` in graph attribute `goal` (template_undefined_variable)
+      fix: bind `inputs.app_dir` via `[run.inputs]` in workflow.toml, or pass `--input inputs.app_dir=<value>`
     warning: [FIXTURES]/templated_unbound.fabro:7:44: undefined template variable `inputs.app_dir` in node `work` attribute `prompt` [node: work] (template_undefined_variable)
+      fix: bind `inputs.app_dir` via `[run.inputs]` in workflow.toml, or pass `--input inputs.app_dir=<value>`
     Validation: OK
     ");
 }
@@ -186,6 +189,7 @@ fn bare_fabro_with_unbound_inputs_in_imported_prompt_validates_structurally_with
     Workflow: TemplatedUnboundImported (3 nodes, 2 edges)
     Graph: [FIXTURES]/templated_unbound_imported/workflow.fabro
     warning: [FIXTURES]/templated_unbound_imported/work.md:1:12: undefined template variable `inputs.app_dir` in node `work` attribute `prompt` [node: work] (template_undefined_variable)
+      fix: bind `inputs.app_dir` via `[run.inputs]` in workflow.toml, or pass `--input inputs.app_dir=<value>`
     Validation: OK
     ");
 }
@@ -207,6 +211,7 @@ fn bare_fabro_with_unbound_inputs_in_template_partial_validates_structurally_wit
     Workflow: TemplatedUnboundPartial (3 nodes, 2 edges)
     Graph: [FIXTURES]/templated_unbound_partial/workflow.fabro
     warning: [FIXTURES]/templated_unbound_partial/test-include.partial.md:1:4: undefined template variable `inputs.hello` in node `test_imported_include` attribute `prompt` [node: test_imported_include] (template_undefined_variable)
+      fix: bind `inputs.hello` via `[run.inputs]` in workflow.toml, or pass `--input inputs.hello=<value>`
     Validation: OK
     ");
 }
@@ -293,7 +298,9 @@ fn edge_only_node() {
     Workflow: EdgeOnlyNode (3 nodes, 2 edges)
     Graph: [FIXTURES]/edge_only_node.fabro
     error [node: misspelled_node]: Node 'misspelled_node' is referenced by edge 'start -> misspelled_node' but has no node declaration (edge_target_exists)
+      fix: Declare node 'misspelled_node' or correct the edge endpoint
     warning [node: misspelled_node]: LLM node 'misspelled_node' has no prompt or label attribute (prompt_on_llm_nodes)
+      fix: Add a prompt or label attribute
       × Validation failed
     ");
 }
@@ -311,7 +318,9 @@ fn invalid() {
     Workflow: Invalid (2 nodes, 1 edges)
     Graph: [FIXTURES]/invalid.fabro
     error: Pipeline must have exactly one start node (shape=Mdiamond or id start/Start) (start_node)
+      fix: Add a node with shape=Mdiamond or id 'start'
     error [node: exit]: Exit node 'exit' has 1 outgoing edge(s) but must have none (exit_no_outgoing)
+      fix: Remove outgoing edges from the exit node
       × Validation failed
     ");
 }
diff --git a/lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs b/lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs
index 658dd1fea..d6852765e 100644
--- a/lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs
+++ b/lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs
@@ -19,6 +19,7 @@ fn dry_run_branching() {
     Goal: Implement and validate a feature
 
     warning [node: implement]: Node 'implement' has goal_gate=true but no retry_target or fallback_retry_target (goal_gate_has_retry)
+      fix: Add retry_target or fallback_retry_target attribute
         Run: [ULID]
         Web UI: http://localhost:3000/runs/[ULID]
         Sandbox: local (ready in [TIME])

From 716ba1778069f5f916f34515de79a1f0c417511e Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 15:19:57 -0400
Subject: [PATCH 06/36] Show billed amount in runs list size tooltip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Size column in the runs list rendered SizeChip without the billed
total, so its tooltip read "Size M" while the run detail header showed
"Size M · $12.34 billed".

The tooltip was also unreachable: the row title link paints a
`before:absolute before:inset-0` overlay across the whole row, which sat
above the chip and swallowed hover. Wrapping the chip in `relative z-10`
lifts it above that overlay, matching how the created-by and pull request
cells already handle interactive content.

Runs without terminal billing keep the plain "Size M" label, same as the
header.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../app/components/runs-list/run-table-row.tsx        |  6 +++++-
 apps/fabro-web/app/data/runs.test.ts                  | 11 +++++++++++
 apps/fabro-web/app/data/runs.ts                       |  2 ++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/apps/fabro-web/app/components/runs-list/run-table-row.tsx b/apps/fabro-web/app/components/runs-list/run-table-row.tsx
index 850c36467..e7447bce5 100644
--- a/apps/fabro-web/app/components/runs-list/run-table-row.tsx
+++ b/apps/fabro-web/app/components/runs-list/run-table-row.tsx
@@ -116,7 +116,11 @@ export function RunTableRow({
       )}
       {show("size") && (
         <td className="whitespace-nowrap px-3 py-2.5 text-center">
-          {run.size != null && <SizeChip size={run.size} />}
+          {run.size != null && (
+            <span className="relative z-10 inline-flex">
+              <SizeChip size={run.size} totalUsdMicros={run.totalUsdMicros} />
+            </span>
+          )}
         </td>
       )}
       {show("changes") && (
diff --git a/apps/fabro-web/app/data/runs.test.ts b/apps/fabro-web/app/data/runs.test.ts
index 0ad593526..77fdc91e2 100644
--- a/apps/fabro-web/app/data/runs.test.ts
+++ b/apps/fabro-web/app/data/runs.test.ts
@@ -103,6 +103,17 @@ describe("mapRunListItem", () => {
 
     expect(mapRunListItem(summary).title).toBe("Untitled run");
   });
+
+  test("carries the billed total so the size chip can show it on hover", () => {
+    expect(mapRunListItem(makeRun()).totalUsdMicros).toBe(500000);
+  });
+
+  test("leaves the billed total undefined for runs without terminal billing", () => {
+    expect(mapRunListItem(makeRun({ billing: null })).totalUsdMicros).toBeUndefined();
+    expect(
+      mapRunListItem(makeRun({ billing: { total_usd_micros: null } })).totalUsdMicros,
+    ).toBeUndefined();
+  });
 });
 
 describe("mapRunToRunItem", () => {
diff --git a/apps/fabro-web/app/data/runs.ts b/apps/fabro-web/app/data/runs.ts
index 4fb704133..c5f29f6ae 100644
--- a/apps/fabro-web/app/data/runs.ts
+++ b/apps/fabro-web/app/data/runs.ts
@@ -46,6 +46,7 @@ export interface RunItem {
   createdBy: Principal;
   lastEventAt?: string;
   size?: RunSize;
+  totalUsdMicros?: number;
 }
 
 export const columnStatuses = [
@@ -119,6 +120,7 @@ export function mapRunListItem(item: Run): RunItem {
     additions: item.diff?.additions,
     deletions: item.diff?.deletions,
     size: item.size,
+    totalUsdMicros: item.billing?.total_usd_micros ?? undefined,
   };
 }
 

From 991f160a0b09f54f931fe27813ccc011779073ec Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 15:23:01 -0400
Subject: [PATCH 07/36] Drop "billed" from the size chip tooltip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The tooltip now reads "Size M · $12.34" instead of
"Size M · $12.34 billed".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 apps/fabro-web/app/components/size-chip.tsx | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/fabro-web/app/components/size-chip.tsx b/apps/fabro-web/app/components/size-chip.tsx
index e3d07ed40..d23210955 100644
--- a/apps/fabro-web/app/components/size-chip.tsx
+++ b/apps/fabro-web/app/components/size-chip.tsx
@@ -19,10 +19,10 @@ export function SizeChip({
   totalUsdMicros?: number | null;
 }) {
   const tone = SIZE_TONE[size];
-  const billed = totalUsdMicros != null ? ` · ${formatUsdMicros(totalUsdMicros)} billed` : "";
+  const amount = totalUsdMicros != null ? ` · ${formatUsdMicros(totalUsdMicros)}` : "";
   const tooltip = tone.note != null
-    ? `Size ${size} (${tone.note})${billed}`
-    : `Size ${size}${billed}`;
+    ? `Size ${size} (${tone.note})${amount}`
+    : `Size ${size}${amount}`;
   return (
     <Tooltip label={tooltip}>
       <span className={`rounded px-1.5 py-0.5 font-mono text-xs font-bold tabular-nums ${tone.className}`}>

From 53c580ce5fde89d4ef348bf091da8074c5a66aee Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 15:25:44 -0400
Subject: [PATCH 08/36] Swap the board card's elapsed time for a size chip

The board cards showed wall-clock duration in the footer's bottom-right
corner. Replace it with the same SizeChip the list view and run detail
header use, so the cost signal is consistent across all three views.

The chip inherits the tooltip, which names the tier and adds the cost
once a run has terminal billing.

Add SizeChip tests pinning the tooltip label for each tier.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../app/components/size-chip.test.tsx         | 40 +++++++++++++++++++
 apps/fabro-web/app/routes/runs.tsx            | 11 ++---
 2 files changed, 46 insertions(+), 5 deletions(-)
 create mode 100644 apps/fabro-web/app/components/size-chip.test.tsx

diff --git a/apps/fabro-web/app/components/size-chip.test.tsx b/apps/fabro-web/app/components/size-chip.test.tsx
new file mode 100644
index 000000000..b355f5db1
--- /dev/null
+++ b/apps/fabro-web/app/components/size-chip.test.tsx
@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import TestRenderer, { act } from "react-test-renderer";
+
+import { SizeChip } from "./size-chip";
+import { Tooltip } from "./ui";
+
+function tooltipLabel(element: React.ReactElement): string {
+  let renderer: TestRenderer.ReactTestRenderer | undefined;
+  act(() => {
+    renderer = TestRenderer.create(element);
+  });
+  return renderer!.root.findByType(Tooltip).props.label as string;
+}
+
+describe("SizeChip", () => {
+  test("renders the size letter", () => {
+    let renderer: TestRenderer.ReactTestRenderer | undefined;
+    act(() => {
+      renderer = TestRenderer.create(<SizeChip size="M" />);
+    });
+
+    expect(JSON.stringify(renderer!.toJSON())).toContain("M");
+  });
+
+  test("appends the cost to the tooltip", () => {
+    expect(tooltipLabel(<SizeChip size="M" totalUsdMicros={12_340_000} />))
+      .toBe("Size M · $12.34");
+  });
+
+  test("omits the cost when the run has no billing yet", () => {
+    expect(tooltipLabel(<SizeChip size="M" />)).toBe("Size M");
+    expect(tooltipLabel(<SizeChip size="M" totalUsdMicros={null} />)).toBe("Size M");
+  });
+
+  test("calls out the tiers that warrant attention", () => {
+    expect(tooltipLabel(<SizeChip size="L" totalUsdMicros={150_000_000} />))
+      .toBe("Size L (risky) · $150.00");
+    expect(tooltipLabel(<SizeChip size="XL" />)).toBe("Size XL (unhealthy)");
+  });
+});
diff --git a/apps/fabro-web/app/routes/runs.tsx b/apps/fabro-web/app/routes/runs.tsx
index 7da0719ea..fe21e36c8 100644
--- a/apps/fabro-web/app/routes/runs.tsx
+++ b/apps/fabro-web/app/routes/runs.tsx
@@ -26,6 +26,7 @@ import { ciConfig, columnForRun, columnStatusDisplay, columnStatuses, deriveCiSt
 import type { CiStatus, CheckRun, CheckStatus, RunItem } from "../data/runs";
 import { EmptyState } from "../components/state";
 import { PullRequestChip } from "../components/pull-request-chip";
+import { SizeChip } from "../components/size-chip";
 import {
   summarizeBatchLifecycleAction,
 } from "../components/runs-list/batch-lifecycle";
@@ -345,7 +346,7 @@ function PrCard({
 
 // All inline footer metadata on PrCard belongs in this one row. Adding a new
 // piece as a sibling `<div>` below the card body recreates a recurring bug
-// where stats stack onto separate lines instead of sitting next to elapsed/actions.
+// where stats stack onto separate lines instead of sitting next to size/actions.
 function PrCardFooter({ pr, actions }: { pr: RunItem; actions?: string[] }) {
   const hasActions = actions != null && actions.length > 0;
   const hasStats =
@@ -354,7 +355,7 @@ function PrCardFooter({ pr, actions }: { pr: RunItem; actions?: string[] }) {
     (pr.additions != null && pr.additions !== 0) ||
     (pr.deletions != null && pr.deletions !== 0);
 
-  if (!hasStats && !hasActions && pr.elapsed == null) return null;
+  if (!hasStats && !hasActions && pr.size == null) return null;
 
   return (
     <div className="mt-3 flex items-center gap-3 font-mono text-xs">
@@ -416,9 +417,9 @@ function PrCardFooter({ pr, actions }: { pr: RunItem; actions?: string[] }) {
           ))}
         </div>
       )}
-      {pr.elapsed != null && (
-        <span className={`text-fg-muted ${hasActions ? "" : "ml-auto"}`}>
-          {pr.elapsed}
+      {pr.size != null && (
+        <span className={`inline-flex ${hasActions ? "" : "ml-auto"}`}>
+          <SizeChip size={pr.size} totalUsdMicros={pr.totalUsdMicros} />
         </span>
       )}
     </div>

From 7841a77f2c0962439864ebdf8f04ba9441fba7fd Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 16:06:19 -0400
Subject: [PATCH 09/36] feat(web): show stage tokens and cost in the model
 popover

The model indicator on a stage page hovered to provider, model, and
reasoning effort only. Seeing what a stage actually spent meant leaving
for the Billing tab, which reports per node rather than per visit.

The stage list had no token data to show, so add a per-visit `billing`
block to `GET /runs/{id}/stages`. The Billing tab's pricing rule (a
provider-reported cost wins, otherwise the server catalog prices the
tokens) was private to `billing_rollup`; move it to
`StageProjection::billed_usage` and drive both call sites from it so the
two views cannot drift.

The popover's buckets use the Billing tab's labels verbatim. It stays
scoped to one visit, so a looped node's row on the Billing tab is the sum
of what each of its visits shows here.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 apps/fabro-web/app/lib/stage-sidebar.test.ts  |  22 +++
 apps/fabro-web/app/lib/stage-sidebar.ts       |   7 +
 .../app/routes/run-stages-details.test.tsx    |  87 ++++++++++-
 apps/fabro-web/app/routes/run-stages.tsx      |  61 +++++++-
 docs/public/api-reference/fabro-api.yaml      |  10 ++
 lib/apps/fabro-server/src/demo/mod.rs         |   1 +
 .../src/server/handler/billing.rs             |   6 +-
 lib/apps/fabro-server/src/server/tests.rs     | 141 ++++++++++++++++++
 .../fabro-workflow/src/billing_rollup.rs      |  29 +---
 .../fabro-types/src/run_projection.rs         |  86 ++++++++++-
 .../fabro-api-client/src/models/run-stage.ts  |   7 +
 11 files changed, 423 insertions(+), 34 deletions(-)

diff --git a/apps/fabro-web/app/lib/stage-sidebar.test.ts b/apps/fabro-web/app/lib/stage-sidebar.test.ts
index a71323654..e1cc9092b 100644
--- a/apps/fabro-web/app/lib/stage-sidebar.test.ts
+++ b/apps/fabro-web/app/lib/stage-sidebar.test.ts
@@ -17,6 +17,7 @@ function makeStage(nodeId: string, visit: number, status: StageState): Stage {
     duration: "--",
     startedAt: null,
     providerUsed: null,
+    billing: null,
   };
 }
 
@@ -38,6 +39,15 @@ describe("mapRunStagesToSidebarStages", () => {
             model: "gpt-5.5",
             reasoning_effort: "high",
           },
+          billing: {
+            input_tokens: 28_640,
+            output_tokens: 7_550,
+            total_tokens: 43_690,
+            reasoning_tokens: 1_200,
+            cache_read_tokens: 4_800,
+            cache_write_tokens: 1_500,
+            total_usd_micros: 720_000,
+          },
         },
         {
           id: "apply-changes@2",
@@ -46,6 +56,14 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "running",
           node_id: "apply",
           visit: 2,
+          billing: {
+            input_tokens: 0,
+            output_tokens: 0,
+            total_tokens: 0,
+            reasoning_tokens: 0,
+            cache_read_tokens: 0,
+            cache_write_tokens: 0,
+          },
         },
       ],
       meta: { has_more: false },
@@ -64,6 +82,10 @@ describe("mapRunStagesToSidebarStages", () => {
       model: "gpt-5.5",
       reasoning_effort: "high",
     });
+    // Each visit keeps its own tokens and cost, so the stage popover never
+    // shows a sibling visit's usage.
+    expect(result[0].billing?.total_usd_micros).toBe(720_000);
+    expect(result[1].billing?.total_usd_micros).toBeUndefined();
     expect(formatStageLabel(result[0])).toBe("Apply Changes");
 
     expect(result[1].id).toBe("apply-changes@2");
diff --git a/apps/fabro-web/app/lib/stage-sidebar.ts b/apps/fabro-web/app/lib/stage-sidebar.ts
index c165adee0..191681459 100644
--- a/apps/fabro-web/app/lib/stage-sidebar.ts
+++ b/apps/fabro-web/app/lib/stage-sidebar.ts
@@ -1,5 +1,6 @@
 import { StageState } from "@qltysh/fabro-api-client";
 import type {
+  BilledTokenCounts,
   PaginatedRunStageList,
   StageHandler,
   StageModelUsage,
@@ -27,6 +28,11 @@ export interface Stage {
   resumedFromStageId: string | null;
   startedAt: string | null;
   providerUsed: StageModelUsage | null;
+  /**
+   * Tokens and cost for this visit alone, priced the same way the Billing tab
+   * prices its per-node rows. All-zero counts mean the stage called no model.
+   */
+  billing: BilledTokenCounts | null;
 }
 
 export const ACTIVE_STAGE_STATES: ReadonlySet<StageState> = new Set([
@@ -102,6 +108,7 @@ export function mapRunStagesToSidebarStages(
         : "--",
       startedAt: stage.started_at ?? null,
       providerUsed: stage.provider_used ?? null,
+      billing: stage.billing ?? null,
     });
   }
   return stages;
diff --git a/apps/fabro-web/app/routes/run-stages-details.test.tsx b/apps/fabro-web/app/routes/run-stages-details.test.tsx
index da18f7e67..2f453c63e 100644
--- a/apps/fabro-web/app/routes/run-stages-details.test.tsx
+++ b/apps/fabro-web/app/routes/run-stages-details.test.tsx
@@ -1,9 +1,13 @@
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
 
-import type { ReasoningOutput } from "@qltysh/fabro-api-client";
+import type {
+  BilledTokenCounts,
+  ReasoningOutput,
+  StageModelUsage,
+} from "@qltysh/fabro-api-client";
 
-import { EventDetails } from "./run-stages";
+import { EventDetails, ModelUsagePopover } from "./run-stages";
 
 const RUN_START = "2026-04-09T12:00:00Z";
 
@@ -72,3 +76,82 @@ describe("EventDetails reasoning", () => {
     expect(html).toContain(`${"x".repeat(280)}…`);
   });
 });
+
+const PROVIDER_USED: StageModelUsage = {
+  mode: "agent",
+  provider: "moonshot",
+  model: "kimi-k3",
+  reasoning_effort: "max",
+};
+
+function billing(partial: Partial<BilledTokenCounts>): BilledTokenCounts {
+  return {
+    input_tokens: 0,
+    output_tokens: 0,
+    total_tokens: 0,
+    reasoning_tokens: 0,
+    cache_read_tokens: 0,
+    cache_write_tokens: 0,
+    ...partial,
+  };
+}
+
+function popoverMarkup(counts: BilledTokenCounts | null): string {
+  return renderToStaticMarkup(
+    <ModelUsagePopover providerUsed={PROVIDER_USED} billing={counts} />,
+  );
+}
+
+describe("ModelUsagePopover billing", () => {
+  test("shows the visit's token buckets and cost next to the model", () => {
+    const html = popoverMarkup(
+      billing({
+        input_tokens: 28_640,
+        output_tokens: 7_550,
+        reasoning_tokens: 1_200,
+        cache_read_tokens: 4_800,
+        cache_write_tokens: 1_500,
+        total_tokens: 43_690,
+        total_usd_micros: 720_000,
+      }),
+    );
+
+    expect(html).toContain("kimi-k3");
+    expect(html).toContain("Cache read");
+    expect(html).toContain("4.8k");
+    expect(html).toContain("Cache creation");
+    expect(html).toContain("1.5k");
+    expect(html).toContain("Uncached");
+    expect(html).toContain("28.6k");
+    // Output folds in reasoning tokens, matching the Billing tab.
+    expect(html).toContain("Output");
+    expect(html).toContain("8.8k");
+    expect(html).toContain("Cost");
+    expect(html).toContain("$0.72");
+  });
+
+  test("omits the token section for a stage that called no model", () => {
+    const html = popoverMarkup(billing({}));
+
+    expect(html).toContain("kimi-k3");
+    expect(html).not.toContain("Tokens");
+    expect(html).not.toContain("Cost");
+  });
+
+  test("still shows tokens when nothing priced the stage", () => {
+    const html = popoverMarkup(
+      billing({ input_tokens: 1_000, output_tokens: 500, total_tokens: 1_500 }),
+    );
+
+    expect(html).toContain("Uncached");
+    expect(html).toContain("1.0k");
+    expect(html).not.toContain("Cost");
+  });
+
+  test("renders the model rows alone when the stage list carried no billing", () => {
+    const html = popoverMarkup(null);
+
+    expect(html).toContain("kimi-k3");
+    expect(html).not.toContain("Tokens");
+  });
+});
diff --git a/apps/fabro-web/app/routes/run-stages.tsx b/apps/fabro-web/app/routes/run-stages.tsx
index 43f4410f1..246f3b2ed 100644
--- a/apps/fabro-web/app/routes/run-stages.tsx
+++ b/apps/fabro-web/app/routes/run-stages.tsx
@@ -67,6 +67,7 @@ import {
   formatBytes,
   formatDurationMs,
   formatTokenCount,
+  formatUsdMicros,
 } from "../lib/format";
 import { plural } from "../lib/plural";
 import {
@@ -93,6 +94,7 @@ import {
   type UnknownRecord,
 } from "../lib/unknown";
 import type {
+  BilledTokenCounts,
   EventEnvelope,
   ReasoningOutput,
   StageHandler,
@@ -866,10 +868,59 @@ export function formatStageModelUsageLabel(
   return effort ? `${model}[${effort}]` : model;
 }
 
-function ModelUsagePopover({
+const POPOVER_NUMBER = "block text-right font-mono tabular-nums";
+
+/**
+ * The disjoint token buckets behind a stage's usage, labelled and ordered to
+ * match the Billing tab's breakdown so the two views read the same. `Uncached`
+ * is input that missed the cache; `Output` folds in reasoning tokens.
+ */
+function stageTokenBuckets(billing: BilledTokenCounts) {
+  return [
+    { label: "Cache read", value: billing.cache_read_tokens },
+    { label: "Cache creation", value: billing.cache_write_tokens },
+    { label: "Uncached", value: billing.input_tokens },
+    {
+      label: "Output",
+      value: billing.output_tokens + billing.reasoning_tokens,
+    },
+  ];
+}
+
+/** Tokens and cost for this stage visit alone. */
+function StageBillingRows({ billing }: { billing: BilledTokenCounts }) {
+  const buckets = stageTokenBuckets(billing);
+  if (buckets.every((bucket) => bucket.value === 0)) return null;
+  const cost = formatUsdMicros(billing.total_usd_micros);
+  return (
+    <div className="mt-3">
+      <PopoverHeader>Tokens</PopoverHeader>
+      <PopoverRows>
+        {buckets.map((bucket) => (
+          <PopoverRow key={bucket.label} label={bucket.label}>
+            <span className={POPOVER_NUMBER}>
+              {bucket.value === 0
+                ? "0"
+                : formatTokenCount(bucket.value, { compactDecimal: true })}
+            </span>
+          </PopoverRow>
+        ))}
+        {cost && (
+          <PopoverRow label="Cost">
+            <span className={POPOVER_NUMBER}>{cost}</span>
+          </PopoverRow>
+        )}
+      </PopoverRows>
+    </div>
+  );
+}
+
+export function ModelUsagePopover({
   providerUsed,
+  billing,
 }: {
   providerUsed: StageModelUsage;
+  billing: BilledTokenCounts | null;
 }) {
   return (
     <>
@@ -892,6 +943,7 @@ function ModelUsagePopover({
           <PopoverRow label="Speed">{providerUsed.speed}</PopoverRow>
         )}
       </PopoverRows>
+      {billing && <StageBillingRows billing={billing} />}
     </>
   );
 }
@@ -1905,6 +1957,7 @@ function EventsToolbar({
   filteredCount,
   totalCount,
   providerUsed,
+  billing,
   events,
   runId,
   stageId,
@@ -1924,6 +1977,7 @@ function EventsToolbar({
   filteredCount: number;
   totalCount: number;
   providerUsed: StageModelUsage | null;
+  billing: BilledTokenCounts | null;
   events: EventEnvelope[];
   runId: string;
   stageId: string;
@@ -2004,7 +2058,9 @@ function EventsToolbar({
           className={`inline-flex items-center gap-1.5 text-xs text-fg-muted ${
             showFilters ? "" : "ml-auto"
           }`}
-          content={<ModelUsagePopover providerUsed={providerUsed} />}
+          content={
+            <ModelUsagePopover providerUsed={providerUsed} billing={billing} />
+          }
         >
           <CpuChipIcon className="size-3.5" aria-hidden="true" />
           <span className="font-mono">{modelUsageLabel}</span>
@@ -2359,6 +2415,7 @@ function RunStageActivityStage({
                 effectiveTab === "primary" ? turns.length : debugEvents.length
               }
               providerUsed={selectedStage.providerUsed}
+              billing={selectedStage.billing}
               events={stageEventsQuery.data ?? []}
               runId={runId}
               stageId={selectedStageId}
diff --git a/docs/public/api-reference/fabro-api.yaml b/docs/public/api-reference/fabro-api.yaml
index b028d89c0..fdc6028c2 100644
--- a/docs/public/api-reference/fabro-api.yaml
+++ b/docs/public/api-reference/fabro-api.yaml
@@ -12609,6 +12609,7 @@ components:
         - status
         - node_id
         - visit
+        - billing
       properties:
         id:
           $ref: "#/components/schemas/StageId"
@@ -12668,6 +12669,15 @@ components:
           format: date-time
           description: Wall-clock time the latest attempt of this stage started, if known.
           example: "2026-04-29T12:34:56Z"
+        billing:
+          $ref: "#/components/schemas/BilledTokenCounts"
+          description: >-
+            Token counts for this stage execution alone. `total_usd_micros` is
+            the provider-reported cost when there is one, otherwise the server
+            catalog's price for these tokens — the same pricing the
+            `/runs/{id}/billing` rows use. All-zero counts mean the stage made
+            no model calls. Unlike the billing rows, which sum every visit of a
+            node, this covers only this visit.
 
     # ── File Diff Schemas ──────────────────────────────────────────────
 
diff --git a/lib/apps/fabro-server/src/demo/mod.rs b/lib/apps/fabro-server/src/demo/mod.rs
index b9d51dcef..9e4afd482 100644
--- a/lib/apps/fabro-server/src/demo/mod.rs
+++ b/lib/apps/fabro-server/src/demo/mod.rs
@@ -1134,6 +1134,7 @@ mod runs {
             id: stage_id.clone(),
             name: name.to_owned(),
             handler,
+            billing: BilledTokenCounts::default(),
             status,
             wall_time_ms,
             node_id: stage_id.node_id().to_owned(),
diff --git a/lib/apps/fabro-server/src/server/handler/billing.rs b/lib/apps/fabro-server/src/server/handler/billing.rs
index a1888713c..cf5ad719d 100644
--- a/lib/apps/fabro-server/src/server/handler/billing.rs
+++ b/lib/apps/fabro-server/src/server/handler/billing.rs
@@ -2,6 +2,7 @@ use std::collections::HashMap;
 use std::sync::Arc;
 
 use chrono::{DateTime, Utc};
+use fabro_model::Catalog;
 use fabro_types::{
     Graph, RunProjection, StageHandler, StageId, StageProjection, StageState, StageTiming,
 };
@@ -22,6 +23,7 @@ fn run_stage_from_projection(
     stage_id: &StageId,
     stage: &StageProjection,
     graph: &Graph,
+    catalog: &Catalog,
     now: DateTime<Utc>,
 ) -> RunStage {
     let handler = stage.handler.unwrap_or_else(|| {
@@ -36,6 +38,7 @@ fn run_stage_from_projection(
         id: stage_id.clone(),
         name: stage_id.node_id().to_owned(),
         handler,
+        billing: stage.billed_usage(Some(catalog)).into_owned(),
         status: stage.effective_state(),
         wall_time_ms: stage.live_wall_time_ms(now),
         node_id: stage_id.node_id().to_owned(),
@@ -67,9 +70,10 @@ async fn list_run_stages(
 
     let now = Utc::now();
     let graph = projection.spec().graph();
+    let catalog = state.catalog();
     let stages = projection
         .iter_stages()
-        .map(|(stage_id, stage)| run_stage_from_projection(stage_id, stage, graph, now))
+        .map(|(stage_id, stage)| run_stage_from_projection(stage_id, stage, graph, &catalog, now))
         .collect::<Vec<_>>();
 
     (StatusCode::OK, Json(ListResponse::new(stages))).into_response()
diff --git a/lib/apps/fabro-server/src/server/tests.rs b/lib/apps/fabro-server/src/server/tests.rs
index 71b4dfebf..69f6fabc3 100644
--- a/lib/apps/fabro-server/src/server/tests.rs
+++ b/lib/apps/fabro-server/src/server/tests.rs
@@ -5791,6 +5791,147 @@ async fn run_billing_sums_usage_across_retry_visits_and_uses_latest_model() {
     assert_eq!(new_model["billing"]["input_tokens"], 200);
 }
 
+/// The stage popover reads `billing` off the stages list, so it must be scoped
+/// to one visit — unlike the Billing tab's rows, which sum every visit of a
+/// node. This exercises the same two-visit history as
+/// `run_billing_sums_usage_across_retry_visits_and_uses_latest_model`.
+#[tokio::test]
+async fn list_run_stages_reports_billing_per_visit() {
+    let state = test_app_state_with_isolated_storage();
+    let app = crate::test_support::build_test_router(Arc::clone(&state));
+    let run_id = RunId::new();
+
+    create_durable_run_with_events(&state, run_id, &[
+        workflow_event::Event::RunSubmitted {
+            definition_blob: None,
+        },
+        workflow_event::Event::RunStarting,
+        workflow_event::Event::RunRunning,
+    ])
+    .await;
+
+    append_scoped_stage_event(
+        &state,
+        run_id,
+        "verify",
+        1,
+        &workflow_event::Event::StageFailed {
+            node_id:    "verify".to_string(),
+            name:       "Verify".to_string(),
+            index:      1,
+            failure:    FailureDetail::new("try again", FailureCategory::TransientInfra),
+            will_retry: true,
+            timing:     fabro_types::StageTiming::wall_only(1200),
+            billing:    Some(test_billed_usage("gpt-old", 100, 10)),
+            actor:      None,
+        },
+    )
+    .await;
+    append_scoped_stage_event(
+        &state,
+        run_id,
+        "verify",
+        2,
+        &workflow_event::Event::StageCompleted {
+            node_id: "verify".to_string(),
+            name: "Verify".to_string(),
+            index: 1,
+            timing: fabro_types::StageTiming::wall_only(800),
+            status: "succeeded".to_string(),
+            preferred_label: None,
+            suggested_next_ids: Vec::new(),
+            billing: Some(test_billed_usage("gpt-new", 200, 20)),
+            failure: None,
+            notes: None,
+            files_touched: Vec::new(),
+            context_updates: None,
+            jump_to_node: None,
+            context_values: None,
+            node_visits: None,
+            loop_failure_signatures: None,
+            restart_failure_signatures: None,
+            response: None,
+            attempt: 2,
+            max_attempts: 2,
+        },
+    )
+    .await;
+
+    let response = app
+        .clone()
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri(api(&format!("/runs/{run_id}/stages")))
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let body = response_json!(response, StatusCode::OK).await;
+
+    let first = stage_entry(&body, "verify@1");
+    assert_eq!(first["billing"]["input_tokens"], 100);
+    assert_eq!(first["billing"]["output_tokens"], 10);
+    assert_eq!(first["billing"]["total_usd_micros"], 110);
+
+    let second = stage_entry(&body, "verify@2");
+    assert_eq!(second["billing"]["input_tokens"], 200);
+    assert_eq!(second["billing"]["output_tokens"], 20);
+    assert_eq!(second["billing"]["total_usd_micros"], 220);
+}
+
+#[tokio::test]
+async fn list_run_stages_reports_zero_billing_for_a_stage_that_called_no_model() {
+    let state = test_app_state_with_isolated_storage();
+    let app = crate::test_support::build_test_router(Arc::clone(&state));
+    let run_id = RunId::new();
+
+    create_durable_run_with_events(&state, run_id, &[
+        workflow_event::Event::RunSubmitted {
+            definition_blob: None,
+        },
+        workflow_event::Event::RunStarting,
+        workflow_event::Event::RunRunning,
+    ])
+    .await;
+    append_scoped_stage_event(
+        &state,
+        run_id,
+        "script",
+        1,
+        &workflow_event::Event::StageStarted {
+            graph_visit:           None,
+            resumed_from_stage_id: None,
+            node_id:               "script".to_string(),
+            name:                  "Script".to_string(),
+            index:                 0,
+            handler_type:          "command".to_string(),
+            attempt:               1,
+            max_attempts:          1,
+        },
+    )
+    .await;
+
+    let response = app
+        .oneshot(
+            Request::builder()
+                .method("GET")
+                .uri(api(&format!("/runs/{run_id}/stages")))
+                .body(Body::empty())
+                .unwrap(),
+        )
+        .await
+        .unwrap();
+    let body = response_json!(response, StatusCode::OK).await;
+
+    let billing = &stage_entry(&body, "script@1")["billing"];
+    assert_eq!(billing["input_tokens"], 0);
+    assert_eq!(billing["output_tokens"], 0);
+    // No model ran, so there is nothing to price — not a $0.00 cost.
+    assert!(billing.get("total_usd_micros").is_none());
+}
+
 #[tokio::test]
 async fn list_run_stages_shows_retrying_after_failed_event() {
     let state = test_app_state_with_isolated_storage();
diff --git a/lib/components/fabro-workflow/src/billing_rollup.rs b/lib/components/fabro-workflow/src/billing_rollup.rs
index 4ba8976bc..09256429f 100644
--- a/lib/components/fabro-workflow/src/billing_rollup.rs
+++ b/lib/components/fabro-workflow/src/billing_rollup.rs
@@ -1,32 +1,7 @@
-use std::borrow::Cow;
 use std::collections::HashMap;
 
 use fabro_model::Catalog;
-use fabro_types::{
-    BilledTokenCounts, ModelRef, RunProjection, RunTiming, StageProjection, StageTiming,
-};
-
-fn stage_usage_with_cost<'a>(
-    catalog: Option<&Catalog>,
-    stage: &'a StageProjection,
-) -> Cow<'a, BilledTokenCounts> {
-    let Some(catalog) = catalog else {
-        return Cow::Borrowed(&stage.usage);
-    };
-    let Some(model) = stage.model.as_ref() else {
-        return Cow::Borrowed(&stage.usage);
-    };
-    if stage.usage.total_usd_micros.is_some() {
-        return Cow::Borrowed(&stage.usage);
-    }
-
-    let Some(total_usd_micros) = catalog.price_tokens(model, &stage.usage.token_counts()) else {
-        return Cow::Borrowed(&stage.usage);
-    };
-    let mut usage = stage.usage.clone();
-    usage.total_usd_micros = Some(total_usd_micros);
-    Cow::Owned(usage)
-}
+use fabro_types::{BilledTokenCounts, ModelRef, RunProjection, RunTiming, StageTiming};
 
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProjectionBillingStage {
@@ -80,7 +55,7 @@ pub fn billing_rollup_from_projection(
         if is_boundary_stage(projection, stage_id.node_id()) {
             continue;
         }
-        let usage = stage_usage_with_cost(catalog, stage);
+        let usage = stage.billed_usage(catalog);
         let usage = usage.as_ref();
         if stage.completion.is_none() && stage.timing.is_none() && usage.is_zero() {
             continue;
diff --git a/lib/foundation/fabro-types/src/run_projection.rs b/lib/foundation/fabro-types/src/run_projection.rs
index 027cce2fc..987edf03d 100644
--- a/lib/foundation/fabro-types/src/run_projection.rs
+++ b/lib/foundation/fabro-types/src/run_projection.rs
@@ -3,7 +3,7 @@ use std::collections::{BTreeMap, HashMap};
 use std::num::NonZeroU32;
 
 use chrono::{DateTime, Utc};
-use fabro_model::{ReasoningEffort, Speed};
+use fabro_model::{Catalog, ReasoningEffort, Speed};
 use strum::{Display, EnumString, IntoStaticStr};
 
 use crate::run_event::{AgentSessionActivatedProps, StagePromptProps};
@@ -540,6 +540,28 @@ impl StageProjection {
         self.state
     }
 
+    /// This stage's token counts with a cost attached.
+    ///
+    /// A provider-reported cost always wins. Otherwise the catalog prices the
+    /// recorded tokens for the stage's model. The stored counts pass through
+    /// untouched when there is no catalog, no model, or no price for that
+    /// model, which leaves `total_usd_micros` as `None` rather than zero.
+    #[must_use]
+    pub fn billed_usage(&self, catalog: Option<&Catalog>) -> Cow<'_, BilledTokenCounts> {
+        if self.usage.total_usd_micros.is_some() {
+            return Cow::Borrowed(&self.usage);
+        }
+        let (Some(catalog), Some(model)) = (catalog, self.model.as_ref()) else {
+            return Cow::Borrowed(&self.usage);
+        };
+        let Some(total_usd_micros) = catalog.price_tokens(model, &self.usage.token_counts()) else {
+            return Cow::Borrowed(&self.usage);
+        };
+        let mut usage = self.usage.clone();
+        usage.total_usd_micros = Some(total_usd_micros);
+        Cow::Owned(usage)
+    }
+
     /// Live wall-clock time in milliseconds.
     ///
     /// While the stage is non-terminal (`Pending`, `Running`, or `Retrying`),
@@ -844,11 +866,13 @@ mod iter_stages_tests {
     use std::num::NonZeroU32;
 
     use chrono::Utc;
+    use fabro_model::{Catalog, ModelRef, ProviderId};
     use serde_json::json;
 
     use super::RunProjection;
     use crate::{
-        AgentControlState, Graph, RunId, RunSpec, StageProjection, WorkflowSettings, test_support,
+        AgentControlState, BilledTokenCounts, Graph, RunId, RunSpec, StageProjection,
+        WorkflowSettings, test_support,
     };
 
     fn seq(n: u32) -> NonZeroU32 {
@@ -970,4 +994,62 @@ mod iter_stages_tests {
             assert_eq!(order, vec!["build@1", "verify@1", "verify@2"]);
         }
     }
+
+    fn priced_stage(total_usd_micros: Option<i64>) -> StageProjection {
+        let mut stage = StageProjection::new(seq(1));
+        stage.usage = BilledTokenCounts {
+            input_tokens: 500_000,
+            output_tokens: 125_000,
+            total_tokens: 625_000,
+            total_usd_micros,
+            ..BilledTokenCounts::default()
+        };
+        stage.model = Some(ModelRef {
+            provider: ProviderId::openai(),
+            model_id: "gpt-5.4".into(),
+            speed:    None,
+        });
+        stage
+    }
+
+    #[test]
+    fn billed_usage_prices_uncosted_tokens_from_the_catalog() {
+        let stage = priced_stage(None);
+
+        assert_eq!(stage.billed_usage(None).total_usd_micros, None);
+        let priced = stage.billed_usage(Some(Catalog::builtin()));
+        assert!(
+            priced.total_usd_micros.is_some_and(|cost| cost > 0),
+            "expected a catalog price, got {:?}",
+            priced.total_usd_micros
+        );
+        // Pricing only fills in the cost; the token buckets pass through.
+        assert_eq!(priced.input_tokens, 500_000);
+        assert_eq!(priced.output_tokens, 125_000);
+    }
+
+    #[test]
+    fn billed_usage_keeps_a_provider_reported_cost_over_the_catalog_estimate() {
+        let stage = priced_stage(Some(42));
+
+        assert_eq!(
+            stage
+                .billed_usage(Some(Catalog::builtin()))
+                .total_usd_micros,
+            Some(42)
+        );
+    }
+
+    #[test]
+    fn billed_usage_leaves_a_modelless_stage_uncosted() {
+        let mut stage = priced_stage(None);
+        stage.model = None;
+
+        assert_eq!(
+            stage
+                .billed_usage(Some(Catalog::builtin()))
+                .total_usd_micros,
+            None
+        );
+    }
 }
diff --git a/lib/packages/fabro-api-client/src/models/run-stage.ts b/lib/packages/fabro-api-client/src/models/run-stage.ts
index aafd25f92..ce184f7e8 100644
--- a/lib/packages/fabro-api-client/src/models/run-stage.ts
+++ b/lib/packages/fabro-api-client/src/models/run-stage.ts
@@ -13,6 +13,9 @@
  */
 
 
+// May contain unused imports in some cases
+// @ts-ignore
+import type { BilledTokenCounts } from './billed-token-counts';
 // May contain unused imports in some cases
 // @ts-ignore
 import type { StageHandler } from './stage-handler';
@@ -62,4 +65,8 @@ export interface RunStage {
      * Wall-clock time the latest attempt of this stage started, if known.
      */
     'started_at'?: string | null;
+    /**
+     * Token counts for this stage execution alone. `total_usd_micros` is the provider-reported cost when there is one, otherwise the server catalog\'s price for these tokens — the same pricing the `/runs/{id}/billing` rows use. All-zero counts mean the stage made no model calls. Unlike the billing rows, which sum every visit of a node, this covers only this visit.
+     */
+    'billing': BilledTokenCounts;
 }

From 4d4eb2c4e68d0768a087857120bb16927f0a8fc5 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 16:45:47 -0400
Subject: [PATCH 10/36] Show run artifacts by file with version history
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The artifacts page grouped captures by stage, which is the storage key
`(stage, retry, path)` rather than anything a reader thinks in. A file
rewritten by four stages appeared as four separate rows under four
headings, with no indication they were the same file.

Group by path instead. Each file is one row showing its latest capture;
earlier captures disclose inline behind a chevron with the producing
stage, size, and the byte change that capture introduced.

Three fixes fall out of the regrouping:

- Order versions by the producing stage's `startedAt`. The previous sort
  was alphabetical by stage label, which scrambled history — a report
  that grew 8.42 KB -> 13.16 -> 14.32 -> 17.48 rendered newest-first
  under a heading implying it was the earliest.

- Drop captures from graph control nodes (`start`, `exit`) via the
  existing `isVisibleStage` helper. Those nodes run no work, so the
  files they match are pre-existing workspace files swept up by the
  capture globs, not run output. This is display-side only; the capture
  path still stores them.

- Show the retry badge at `retry > 1` rather than `retry > 0`. Attempts
  are 1-based, so the old condition matched every capture and rendered
  a "retry 1" badge on every group.

Grouping lives in a separate module so it is testable without React.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 apps/fabro-web/app/routes/run-artifacts.tsx   | 257 +++++++++---------
 .../app/routes/run-artifacts/group.test.ts    | 185 +++++++++++++
 .../app/routes/run-artifacts/group.ts         | 124 +++++++++
 3 files changed, 440 insertions(+), 126 deletions(-)
 create mode 100644 apps/fabro-web/app/routes/run-artifacts/group.test.ts
 create mode 100644 apps/fabro-web/app/routes/run-artifacts/group.ts

diff --git a/apps/fabro-web/app/routes/run-artifacts.tsx b/apps/fabro-web/app/routes/run-artifacts.tsx
index c44b6c633..df719716a 100644
--- a/apps/fabro-web/app/routes/run-artifacts.tsx
+++ b/apps/fabro-web/app/routes/run-artifacts.tsx
@@ -1,14 +1,15 @@
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
 import { useParams } from "react-router";
-import { ArrowDownTrayIcon, PaperClipIcon } from "@heroicons/react/24/outline";
-import type { RunArtifactEntry } from "@qltysh/fabro-api-client";
+import { ArrowDownTrayIcon, ChevronRightIcon, PaperClipIcon } from "@heroicons/react/24/outline";
 
 import { EmptyState, ErrorState, LoadingState } from "../components/state";
 import { StageSidebar } from "../components/stage-sidebar";
 import { stageArtifactDownloadUrl } from "../lib/api-client";
 import { formatBytes } from "../lib/format";
 import { useRunArtifacts, useRunStages } from "../lib/queries";
-import { formatStageLabel, mapRunStagesToSidebarStages } from "../lib/stage-sidebar";
+import { mapRunStagesToSidebarStages } from "../lib/stage-sidebar";
+import type { ArtifactFile, ArtifactVersion } from "./run-artifacts/group";
+import { groupArtifactsByFile } from "./run-artifacts/group";
 
 export const handle = { wide: true };
 
@@ -40,6 +41,9 @@ function RunArtifactsBody({
   artifactsQuery: ReturnType<typeof useRunArtifacts>;
   stages: ReturnType<typeof mapRunStagesToSidebarStages>;
 }) {
+  const entries = artifactsQuery.data?.data ?? [];
+  const files = useMemo(() => groupArtifactsByFile(entries, stages), [entries, stages]);
+
   if (artifactsQuery.error) {
     return (
       <ErrorState
@@ -52,8 +56,7 @@ function RunArtifactsBody({
   if (artifactsQuery.data === undefined) {
     return <LoadingState label="Loading artifacts…" />;
   }
-  const entries = artifactsQuery.data?.data ?? [];
-  if (entries.length === 0) {
+  if (files.length === 0) {
     return (
       <EmptyState
         icon={PaperClipIcon}
@@ -62,149 +65,151 @@ function RunArtifactsBody({
       />
     );
   }
-  return <ArtifactList runId={runId} entries={entries} stages={stages} />;
+  return <ArtifactList runId={runId} files={files} />;
 }
 
-interface StageGroup {
-  key: string;
-  stageId: string;
-  retry: number;
-  label: string;
-  entries: RunArtifactEntry[];
-  totalBytes: number;
-}
-
-function groupArtifacts(
-  entries: readonly RunArtifactEntry[],
-  stages: ReturnType<typeof mapRunStagesToSidebarStages>,
-): StageGroup[] {
-  const stageLabels = new Map<string, string>();
-  for (const stage of stages) {
-    stageLabels.set(stage.id, formatStageLabel(stage));
-  }
-
-  const groups = new Map<string, StageGroup>();
-  for (const entry of entries) {
-    const key = `${entry.stage_id}#${entry.retry}`;
-    const existing = groups.get(key);
-    if (existing) {
-      existing.entries.push(entry);
-      existing.totalBytes += entry.size;
-    } else {
-      groups.set(key, {
-        key,
-        stageId: entry.stage_id,
-        retry: entry.retry,
-        label: stageLabels.get(entry.stage_id) ?? entry.node_slug,
-        entries: [entry],
-        totalBytes: entry.size,
-      });
+function ArtifactList({ runId, files }: { runId: string; files: readonly ArtifactFile[] }) {
+  const { captures, latestBytes, storedBytes } = useMemo(() => {
+    let captures = 0;
+    let latestBytes = 0;
+    let storedBytes = 0;
+    for (const file of files) {
+      captures += file.versions.length;
+      latestBytes += file.latest.size;
+      for (const version of file.versions) storedBytes += version.size;
     }
-  }
+    return { captures, latestBytes, storedBytes };
+  }, [files]);
 
-  for (const group of groups.values()) {
-    group.entries.sort((a, b) => a.relative_path.localeCompare(b.relative_path));
-  }
-  const sortedGroups = Array.from(groups.values());
-  sortedGroups.sort((a, b) => {
-    const labelCmp = a.label.localeCompare(b.label);
-    return labelCmp !== 0 ? labelCmp : a.retry - b.retry;
-  });
-  return sortedGroups;
-}
-
-function ArtifactList({
-  runId,
-  entries,
-  stages,
-}: {
-  runId: string;
-  entries: readonly RunArtifactEntry[];
-  stages: ReturnType<typeof mapRunStagesToSidebarStages>;
-}) {
-  const groups = useMemo(() => groupArtifacts(entries, stages), [entries, stages]);
-  const totalBytes = useMemo(
-    () => entries.reduce((sum, entry) => sum + entry.size, 0),
-    [entries],
-  );
+  // Only mention versions once some file actually has more than one.
+  const versioned = captures > files.length;
 
   return (
     <div className="space-y-4">
-      <div className="flex items-baseline justify-between">
+      <div className="flex items-baseline justify-between gap-4">
         <h2 className="text-sm font-medium text-fg">
-          {entries.length} {entries.length === 1 ? "artifact" : "artifacts"}
+          {files.length} {files.length === 1 ? "file" : "files"}
+          {versioned && (
+            <span className="font-normal text-fg-muted"> · {captures} versions</span>
+          )}
         </h2>
         <span className="text-xs tabular-nums text-fg-muted">
-          {formatBytes(totalBytes)} total
+          {versioned
+            ? `${formatBytes(latestBytes)} latest · ${formatBytes(storedBytes)} stored`
+            : `${formatBytes(latestBytes)} total`}
         </span>
       </div>
 
-      {groups.map((group) => (
-        <StageGroupCard key={group.key} runId={runId} group={group} />
-      ))}
+      <section className="overflow-hidden rounded-md border border-line bg-panel-alt">
+        {files.map((file) => (
+          <ArtifactFileRow key={file.path} runId={runId} file={file} />
+        ))}
+      </section>
     </div>
   );
 }
 
-function StageGroupCard({ runId, group }: { runId: string; group: StageGroup }) {
+function ArtifactFileRow({ runId, file }: { runId: string; file: ArtifactFile }) {
+  const [expanded, setExpanded] = useState(false);
+  const earlier = file.versions.slice(1);
+
   return (
-    <section className="overflow-hidden rounded-md border border-line bg-panel-alt">
-      <header className="flex items-baseline justify-between border-b border-line px-4 py-2.5">
-        <div className="flex items-baseline gap-2">
-          <h3 className="text-sm font-medium text-fg">{group.label}</h3>
-          {group.retry > 0 && (
-            <span className="rounded bg-overlay px-1.5 py-0.5 text-[11px] font-medium text-fg-3">
-              retry {group.retry}
-            </span>
-          )}
-        </div>
-        <span className="text-xs tabular-nums text-fg-muted">
-          {group.entries.length} {group.entries.length === 1 ? "file" : "files"}
-          {" · "}
-          {formatBytes(group.totalBytes)}
+    <div className="border-t border-line first:border-t-0">
+      <div className="flex items-center gap-4 px-4 py-2.5">
+        {earlier.length > 0 ? (
+          <button
+            type="button"
+            aria-expanded={expanded}
+            onClick={() => setExpanded((prev) => !prev)}
+            className="shrink-0 rounded-md p-1 text-fg-3 transition-colors hover:bg-overlay hover:text-fg-2 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500"
+          >
+            <span className="sr-only">Show earlier versions of {file.name}</span>
+            <ChevronRightIcon
+              className={`size-3.5 transition-transform ${expanded ? "rotate-90" : ""}`}
+              aria-hidden="true"
+            />
+          </button>
+        ) : (
+          <span className="size-5 shrink-0" aria-hidden="true" />
+        )}
+
+        <span className="flex min-w-0 flex-1 font-mono text-xs" title={file.path}>
+          <span className="shrink-0 text-fg-muted">{file.dir}</span>
+          <span className="truncate text-fg-2">{file.name}</span>
         </span>
-      </header>
-      <ul className="divide-y divide-line">
-        {group.entries.map((entry) => (
-          <ArtifactRow
-            key={`${group.key}#${entry.relative_path}`}
-            runId={runId}
-            entry={entry}
-          />
-        ))}
-      </ul>
-    </section>
+
+        {earlier.length > 0 && (
+          <span className="shrink-0 rounded-full bg-overlay-strong px-2 py-0.5 text-[11px] text-fg-3">
+            {file.versions.length} versions
+          </span>
+        )}
+
+        <span className="shrink-0 text-xs text-fg-3">{file.latest.stageLabel}</span>
+        <span className="shrink-0 text-xs tabular-nums text-fg-muted">
+          {formatBytes(file.latest.size)}
+        </span>
+        <DownloadLink runId={runId} path={file.path} version={file.latest} />
+      </div>
+
+      {expanded && earlier.length > 0 && (
+        <ul className="border-t border-line bg-black/15 py-1">
+          {earlier.map((version) => (
+            <li
+              key={`${version.stageId}#${version.retry}`}
+              className="flex items-center gap-4 py-1.5 pl-14 pr-4 hover:bg-overlay"
+            >
+              <span className="min-w-0 flex-1 truncate text-xs text-fg-3">
+                {version.stageLabel}
+                {version.retry > 1 && (
+                  <span className="ml-2 text-fg-muted">attempt {version.retry}</span>
+                )}
+              </span>
+              <span className="shrink-0 text-xs tabular-nums text-fg-muted">
+                {formatBytes(version.size)}
+              </span>
+              <SizeDelta delta={version.delta} />
+              <DownloadLink runId={runId} path={file.path} version={version} />
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
   );
 }
 
-function ArtifactRow({ runId, entry }: { runId: string; entry: RunArtifactEntry }) {
-  const href = stageArtifactDownloadUrl(
-    runId,
-    entry.stage_id,
-    entry.relative_path,
-    entry.retry,
-  );
-
+function SizeDelta({ delta }: { delta: number | null }) {
+  if (delta === null) {
+    return <span className="shrink-0 text-[11px] tabular-nums text-fg-muted">first</span>;
+  }
+  const tone = delta < 0 ? "text-amber" : "text-mint";
+  const sign = delta < 0 ? "−" : "+";
   return (
-    <li className="flex items-center gap-4 px-4 py-2">
-      <span
-        className="flex-1 truncate font-mono text-xs text-fg-2"
-        title={entry.relative_path}
-      >
-        {entry.relative_path}
-      </span>
-      <span className="shrink-0 tabular-nums text-xs text-fg-muted">
-        {formatBytes(entry.size)}
-      </span>
-      <a
-        href={href}
-        download={basename(entry.relative_path)}
-        className="inline-flex shrink-0 items-center gap-1 rounded-md px-2 py-1 text-xs text-fg-3 transition-colors hover:bg-overlay hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500"
-      >
-        <ArrowDownTrayIcon className="size-3.5" aria-hidden="true" />
-        Download
-      </a>
-    </li>
+    <span className={`shrink-0 text-[11px] tabular-nums ${tone}`}>
+      {sign}
+      {formatBytes(Math.abs(delta))}
+    </span>
+  );
+}
+
+function DownloadLink({
+  runId,
+  path,
+  version,
+}: {
+  runId: string;
+  path: string;
+  version: ArtifactVersion;
+}) {
+  const href = stageArtifactDownloadUrl(runId, version.stageId, path, version.retry);
+  return (
+    <a
+      href={href}
+      download={basename(path)}
+      className="inline-flex shrink-0 items-center gap-1 rounded-md px-2 py-1 text-xs text-fg-3 transition-colors hover:bg-overlay hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500"
+    >
+      <ArrowDownTrayIcon className="size-3.5" aria-hidden="true" />
+      Download
+    </a>
   );
 }
 
diff --git a/apps/fabro-web/app/routes/run-artifacts/group.test.ts b/apps/fabro-web/app/routes/run-artifacts/group.test.ts
new file mode 100644
index 000000000..a4cfa2ff9
--- /dev/null
+++ b/apps/fabro-web/app/routes/run-artifacts/group.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+import { StageHandler, StageState } from "@qltysh/fabro-api-client";
+import type { RunArtifactEntry } from "@qltysh/fabro-api-client";
+
+import type { Stage } from "../../lib/stage-sidebar";
+import { groupArtifactsByFile, splitArtifactPath } from "./group";
+
+function stage(nodeId: string, startedAt: string | null, visit = 1): Stage {
+  return {
+    id: `${nodeId}@${visit}`,
+    name: nodeId,
+    handler: StageHandler.AGENT,
+    nodeId,
+    visit,
+    graphVisit: null,
+    resumedFromStageId: null,
+    status: StageState.SUCCEEDED,
+    duration: "1s",
+    startedAt,
+    providerUsed: null,
+  };
+}
+
+function artifact(
+  nodeSlug: string,
+  path: string,
+  size: number,
+  retry = 1,
+  visit = 1,
+): RunArtifactEntry {
+  return {
+    stage_id: `${nodeSlug}@${visit}`,
+    node_slug: nodeSlug,
+    retry,
+    relative_path: path,
+    size,
+  };
+}
+
+/** Mirrors run 01KYJ8ZR0N: one report rewritten by four stages. */
+const REPORT = ".ai/reports/2026-07-27-wrk-002-instance-lifecycle.md";
+
+const STAGES: Stage[] = [
+  stage("start", "2026-07-27T17:12:08Z"),
+  stage("plan", "2026-07-27T17:21:44Z"),
+  stage("implement_plan", "2026-07-27T17:44:18Z"),
+  stage("simplify", "2026-07-27T18:43:11Z"),
+  stage("consolidate_reviews", "2026-07-27T19:44:26Z"),
+  stage("fix_review_findings", "2026-07-27T19:49:22Z"),
+];
+
+describe("splitArtifactPath", () => {
+  test("splits a nested path into directory prefix and filename", () => {
+    expect(splitArtifactPath(".ai/reports/run.md")).toEqual({
+      dir: ".ai/reports/",
+      name: "run.md",
+    });
+  });
+
+  test("leaves a root-level path without a directory", () => {
+    expect(splitArtifactPath("README.md")).toEqual({ dir: "", name: "README.md" });
+  });
+});
+
+describe("groupArtifactsByFile", () => {
+  test("collapses repeated captures of one path into a single file", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("consolidate_reviews", REPORT, 14323),
+        artifact("fix_review_findings", REPORT, 17483),
+        artifact("implement_plan", REPORT, 8422),
+        artifact("simplify", REPORT, 13162),
+      ],
+      STAGES,
+    );
+
+    expect(files).toHaveLength(1);
+    expect(files[0].path).toBe(REPORT);
+    expect(files[0].dir).toBe(".ai/reports/");
+    expect(files[0].name).toBe("2026-07-27-wrk-002-instance-lifecycle.md");
+    expect(files[0].versions).toHaveLength(4);
+  });
+
+  test("orders versions newest first using stage start time, not stage name", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("consolidate_reviews", REPORT, 14323),
+        artifact("fix_review_findings", REPORT, 17483),
+        artifact("implement_plan", REPORT, 8422),
+        artifact("simplify", REPORT, 13162),
+      ],
+      STAGES,
+    );
+
+    expect(files[0].versions.map((v) => v.stageLabel)).toEqual([
+      "fix_review_findings",
+      "consolidate_reviews",
+      "simplify",
+      "implement_plan",
+    ]);
+    expect(files[0].latest.size).toBe(17483);
+  });
+
+  test("reports the byte change each capture introduced, oldest capture first", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("implement_plan", REPORT, 8422),
+        artifact("simplify", REPORT, 13162),
+        artifact("consolidate_reviews", REPORT, 14323),
+        artifact("fix_review_findings", REPORT, 17483),
+      ],
+      STAGES,
+    );
+
+    // versions are newest-first, so deltas read 17483-14323, 14323-13162, ...
+    expect(files[0].versions.map((v) => v.delta)).toEqual([3160, 1161, 4740, null]);
+  });
+
+  test("drops captures from graph control nodes", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("start", ".ai/reports/pre-existing.md", 12402),
+        artifact("plan", ".ai/plans/plan.md", 21749),
+      ],
+      STAGES,
+    );
+
+    expect(files.map((file) => file.path)).toEqual([".ai/plans/plan.md"]);
+  });
+
+  test("sorts files by their most recent capture", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("plan", ".ai/plans/plan.md", 21749),
+        artifact("fix_review_findings", REPORT, 17483),
+        artifact("simplify", ".ai/reviews/bugs.xml", 5231),
+      ],
+      STAGES,
+    );
+
+    expect(files.map((file) => file.path)).toEqual([
+      REPORT,
+      ".ai/reviews/bugs.xml",
+      ".ai/plans/plan.md",
+    ]);
+  });
+
+  test("keeps retries of one stage as separate ordered versions", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("simplify", REPORT, 13162, 2),
+        artifact("simplify", REPORT, 9000, 1),
+      ],
+      STAGES,
+    );
+
+    expect(files[0].versions.map((v) => v.retry)).toEqual([2, 1]);
+    expect(files[0].latest.size).toBe(13162);
+    expect(files[0].versions.map((v) => v.delta)).toEqual([4162, null]);
+  });
+
+  test("falls back to a stable order when stages have not loaded yet", () => {
+    const files = groupArtifactsByFile(
+      [
+        artifact("simplify", REPORT, 13162),
+        artifact("implement_plan", REPORT, 8422),
+      ],
+      [],
+    );
+
+    expect(files[0].versions.map((v) => v.stageLabel)).toEqual([
+      "simplify",
+      "implement_plan",
+    ]);
+  });
+
+  test("returns no files when every capture came from a control node", () => {
+    const files = groupArtifactsByFile(
+      [artifact("start", ".ai/reports/pre-existing.md", 12402)],
+      STAGES,
+    );
+
+    expect(files).toEqual([]);
+  });
+});
diff --git a/apps/fabro-web/app/routes/run-artifacts/group.ts b/apps/fabro-web/app/routes/run-artifacts/group.ts
new file mode 100644
index 000000000..99ee84f83
--- /dev/null
+++ b/apps/fabro-web/app/routes/run-artifacts/group.ts
@@ -0,0 +1,124 @@
+import type { RunArtifactEntry } from "@qltysh/fabro-api-client";
+
+import { isVisibleStage } from "../../data/runs";
+import type { Stage } from "../../lib/stage-sidebar";
+import { formatStageLabel } from "../../lib/stage-sidebar";
+
+/** One capture of a file, written by a single stage attempt. */
+export interface ArtifactVersion {
+  stageId: string;
+  stageLabel: string;
+  retry: number;
+  size: number;
+  /** Byte change this capture introduced; null for the first capture. */
+  delta: number | null;
+}
+
+/** One artifact path together with its capture history, newest first. */
+export interface ArtifactFile {
+  path: string;
+  /** Directory prefix including the trailing slash, or "" at the root. */
+  dir: string;
+  name: string;
+  versions: ArtifactVersion[];
+  latest: ArtifactVersion;
+}
+
+export function splitArtifactPath(path: string): { dir: string; name: string } {
+  const idx = path.lastIndexOf("/");
+  return idx >= 0
+    ? { dir: path.slice(0, idx + 1), name: path.slice(idx + 1) }
+    : { dir: "", name: path };
+}
+
+interface StageInfo {
+  label: string;
+  order: number;
+}
+
+/**
+ * Chronological position of each stage, keyed by stage ID.
+ *
+ * Stage IDs are `node@visit`, where `visit` counts visits to that one node — it
+ * is not a run-wide ordinal, so it cannot order stages against each other.
+ * `startedAt` is the only run-wide clock available here.
+ */
+function stageInfoById(stages: readonly Stage[]): Map<string, StageInfo> {
+  const chronological = stages
+    .map((stage, index) => ({ stage, index }))
+    .sort((a, b) => {
+      const at = a.stage.startedAt;
+      const bt = b.stage.startedAt;
+      // Stages that have not started yet sort last but keep a stable order.
+      if (at === null && bt === null) return a.index - b.index;
+      if (at === null) return 1;
+      if (bt === null) return -1;
+      const cmp = at.localeCompare(bt);
+      return cmp !== 0 ? cmp : a.index - b.index;
+    });
+
+  const info = new Map<string, StageInfo>();
+  chronological.forEach(({ stage }, order) => {
+    info.set(stage.id, { label: formatStageLabel(stage), order });
+  });
+  return info;
+}
+
+/**
+ * Collapse raw `(stage, retry, path)` capture keys into one entry per file,
+ * carrying the ordered history of every capture of that path.
+ *
+ * Captures from graph control nodes (`start`, `exit`) are dropped: those nodes
+ * run no work, so anything they match is a pre-existing workspace file rather
+ * than something the run produced.
+ */
+export function groupArtifactsByFile(
+  entries: readonly RunArtifactEntry[],
+  stages: readonly Stage[],
+): ArtifactFile[] {
+  const stageInfo = stageInfoById(stages);
+  const byPath = new Map<string, Array<ArtifactVersion & { order: number }>>();
+
+  for (const entry of entries) {
+    if (!isVisibleStage(entry.node_slug)) continue;
+
+    // Until the stages request resolves there is no clock to order by, so
+    // unresolved stages fall back to a stable sort on stage ID.
+    const info = stageInfo.get(entry.stage_id);
+    const version: ArtifactVersion & { order: number } = {
+      stageId: entry.stage_id,
+      stageLabel: info?.label ?? entry.node_slug,
+      retry: entry.retry,
+      size: entry.size,
+      delta: null,
+      order: info?.order ?? Number.MAX_SAFE_INTEGER,
+    };
+    const bucket = byPath.get(entry.relative_path);
+    if (bucket) bucket.push(version);
+    else byPath.set(entry.relative_path, [version]);
+  }
+
+  const files: Array<{ file: ArtifactFile; order: number }> = [];
+  for (const [path, versions] of byPath) {
+    // Oldest first, so each version's delta is the change that capture introduced.
+    versions.sort(
+      (a, b) =>
+        a.order - b.order || a.retry - b.retry || a.stageId.localeCompare(b.stageId),
+    );
+    versions.forEach((version, index) => {
+      version.delta = index === 0 ? null : version.size - versions[index - 1].size;
+    });
+
+    const newestFirst = versions.slice().reverse();
+    const latest = newestFirst[0];
+    const { dir, name } = splitArtifactPath(path);
+    files.push({
+      file: { path, dir, name, versions: newestFirst, latest },
+      order: latest.order,
+    });
+  }
+
+  // Most recently written file first — the page answers "what just happened?".
+  files.sort((a, b) => b.order - a.order || a.file.path.localeCompare(b.file.path));
+  return files.map((entry) => entry.file);
+}

From 9e744f8072db1b81abd853cfcdd2bd029081a122 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 18:39:25 -0400
Subject: [PATCH 11/36] Keep server tests off the developer's real
 ~/.fabro/storage

Test settings usually omit `[server.storage] root`, so it resolved to the
production default. Handlers that walk that tree read whatever the machine
happened to have.

That is why all_spec_routes_are_routable was slow. Timing every request in
it showed 91% of the runtime in two routes:

  6304ms  GET /api/v1/system/resources
  4574ms  GET /api/v1/system/df
   583ms  POST /api/v1/system/prune/runs
  ...
  the remaining 134 operations: 8ms combined

Both size Fabro-managed storage. On this machine that meant 193MB and 90,795
entries under scratch/, so the test's duration tracked how long the developer
had been running Fabro locally. Run-creating tests were writing there too.

Redirect settings that still carry the production default to a `storage`
directory beside the test vault, alongside the existing `server.env` and
`settings.toml` siblings. A test that chose its own root keeps it.

all_spec_routes_are_routable drops from ~15s to 0.6s, and the full workspace
run from ~33s to ~21s. All 7402 tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/apps/fabro-server/src/test_support.rs | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/lib/apps/fabro-server/src/test_support.rs b/lib/apps/fabro-server/src/test_support.rs
index 8fe368fff..178641298 100644
--- a/lib/apps/fabro-server/src/test_support.rs
+++ b/lib/apps/fabro-server/src/test_support.rs
@@ -13,6 +13,7 @@ use axum::middleware::Next;
 use axum::response::Response;
 use axum::{Router, middleware};
 use chrono::Duration as ChronoDuration;
+use fabro_config::user::default_storage_dir;
 use fabro_config::{RunLayer, ServerSettingsBuilder, Storage, envfile};
 use fabro_db::DbPool;
 use fabro_interview::Interviewer;
@@ -253,9 +254,10 @@ impl TestAppStateBuilder {
         self.try_build().expect("test app state should build")
     }
 
-    pub fn try_build(self) -> anyhow::Result<Arc<AppState>> {
+    pub fn try_build(mut self) -> anyhow::Result<Arc<AppState>> {
         let (store, artifact_store) = self.store_bundle.unwrap_or_else(test_store_bundle);
         let vault_path = self.vault_path.unwrap_or_else(test_secret_store_path);
+        redirect_default_storage_root(&mut self.server_settings, &vault_path);
         if !self.vault_entries.is_empty() {
             let mut vault = Vault::load(vault_path.clone()).expect("test vault should load");
             for (name, value) in &self.vault_entries {
@@ -672,6 +674,25 @@ pub fn test_secret_store_path() -> PathBuf {
     dir.join("secrets.json")
 }
 
+/// Keeps tests off the developer's real `~/.fabro/storage`.
+///
+/// Settings built for tests usually omit `[server.storage] root`, which
+/// resolves to the production default. Handlers that walk that tree — `df`,
+/// `system/resources`, `prune` — then read whatever runs and scratch
+/// directories the machine happens to have, making tests slow and
+/// machine-dependent, and letting run-creating tests write there.
+///
+/// Only settings still carrying the production default are redirected; a test
+/// that chose its own root keeps it.
+fn redirect_default_storage_root(settings: &mut ServerSettings, vault_path: &Path) {
+    if Path::new(&settings.server.storage.root) != default_storage_dir() {
+        return;
+    }
+    let root = vault_path.with_file_name("storage");
+    std::fs::create_dir_all(&root).expect("test storage root should be creatable");
+    settings.server.storage.root = root.display().to_string();
+}
+
 #[must_use]
 pub fn test_auth_mode() -> AuthMode {
     AuthMode::Enabled(ConfiguredAuth {

From b97b253deed93f312360793f03ea742b82f03748 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Mon, 27 Jul 2026 18:53:49 -0400
Subject: [PATCH 12/36] Drop the special-case timeout for
 all_spec_routes_are_routable

The test needed room only because it was walking the developer's real
~/.fabro/storage. Now that it runs in about a second, the package-wide
fabro-server timeout covers it with plenty of margin.

The override was not doing anything anyway: nextest resolves each setting
from the first matching override, and `package(fabro-server)` was defined
above it, so the narrower filter never applied. Removing it makes the
config say what was already true.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .config/nextest.toml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/.config/nextest.toml b/.config/nextest.toml
index fe7f4f778..3af76c17c 100644
--- a/.config/nextest.toml
+++ b/.config/nextest.toml
@@ -11,10 +11,6 @@ leak-timeout = "500ms"
     filter = "package(fabro-server)"
     slow-timeout = { period = "5s", terminate-after = 4 }
 
-    [[profile.default.overrides]]
-    filter = "package(fabro-server) & test(all_spec_routes_are_routable)"
-    slow-timeout = { period = "15s", terminate-after = 4 }
-
     [[profile.default.overrides]]
     filter = "package(fabro-workflow)"
     slow-timeout = { period = "2s", terminate-after = 3 }

From 8cc711463b4821a193595603bc70fa4abed33142 Mon Sep 17 00:00:00 2001
From: "fabro-releases[bot]" <fabro-releases[bot]@users.noreply.github.com>
Date: Tue, 28 Jul 2026 10:11:13 +0000
Subject: [PATCH 13/36] Bump version to 0.308.0-nightly.0

---
 Cargo.lock | 102 ++++++++++++++++++++++++++---------------------------
 Cargo.toml |   2 +-
 2 files changed, 52 insertions(+), 52 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index e71612fb2..a9b6f681e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2239,7 +2239,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-acp"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "agent-client-protocol",
  "agent-client-protocol-tokio",
@@ -2258,7 +2258,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-agent"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -2304,7 +2304,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-api"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "chrono",
  "fabro-automation",
@@ -2327,7 +2327,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-auth"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -2352,7 +2352,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-automation"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -2371,11 +2371,11 @@ dependencies = [
 
 [[package]]
 name = "fabro-build-support"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 
 [[package]]
 name = "fabro-checkpoint"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "chrono",
  "fabro-config",
@@ -2391,7 +2391,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-cli"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -2493,7 +2493,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-client"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "bytes",
@@ -2522,7 +2522,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-config"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -2552,7 +2552,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-core"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "async-trait",
  "fabro-types",
@@ -2567,7 +2567,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-db"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -2579,7 +2579,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-dev"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -2598,7 +2598,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-dump"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "bytes",
@@ -2612,7 +2612,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-environment"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -2634,7 +2634,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-github"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "base64",
@@ -2656,7 +2656,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-graphviz"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "fabro-types",
@@ -2671,7 +2671,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-hooks"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "async-trait",
  "fabro-agent",
@@ -2694,7 +2694,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-http"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "fabro-static",
  "http 1.4.0",
@@ -2704,7 +2704,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-install"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "base64",
@@ -2723,7 +2723,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-interview"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "async-trait",
  "dialoguer",
@@ -2738,7 +2738,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-llm"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -2779,7 +2779,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-macros"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "clap",
  "fabro-options-metadata",
@@ -2790,7 +2790,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-manifest"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "fabro-api",
@@ -2808,7 +2808,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-mcp"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "axum",
@@ -2828,7 +2828,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-mcp-server"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -2855,7 +2855,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-mcp-store"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "chrono",
  "fabro-db",
@@ -2873,7 +2873,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-model"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "fabro-static",
  "http 1.4.0",
@@ -2889,7 +2889,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-oauth"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "axum",
@@ -2911,7 +2911,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-options-metadata"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "serde",
  "serde_json",
@@ -2919,7 +2919,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-proc"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "cc",
  "libc",
@@ -2928,7 +2928,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-redact"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "aho-corasick",
  "ref-cast",
@@ -2944,7 +2944,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-sandbox"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -2988,7 +2988,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-server"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -3080,7 +3080,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-slack"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "fabro-http",
  "fabro-interview",
@@ -3102,18 +3102,18 @@ dependencies = [
 
 [[package]]
 name = "fabro-spa"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "rust-embed",
 ]
 
 [[package]]
 name = "fabro-static"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 
 [[package]]
 name = "fabro-store"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "async-trait",
  "bytes",
@@ -3143,7 +3143,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-telemetry"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "base64",
@@ -3169,7 +3169,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-template"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "fabro-types",
@@ -3183,7 +3183,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-test"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -3208,7 +3208,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-tool"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -3229,7 +3229,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-tracker"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -3243,7 +3243,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-types"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "chrono",
  "clap",
@@ -3265,7 +3265,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-util"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "console 0.15.11",
@@ -3288,7 +3288,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-validate"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "fabro-acp",
  "fabro-graphviz",
@@ -3301,7 +3301,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-variable"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -3318,7 +3318,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-vault"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -3337,7 +3337,7 @@ dependencies = [
 
 [[package]]
 name = "fabro-workflow"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "assert_cmd",
@@ -8501,7 +8501,7 @@ dependencies = [
 
 [[package]]
 name = "twin-github"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "axum",
  "base64",
@@ -8520,7 +8520,7 @@ dependencies = [
 
 [[package]]
 name = "twin-openai"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 dependencies = [
  "anyhow",
  "async-stream",
diff --git a/Cargo.toml b/Cargo.toml
index 077adbc7d..12726868f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -11,7 +11,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.305.0-nightly.3"
+version = "0.308.0-nightly.0"
 license = "MIT"
 
 [workspace.dependencies]

From 813e73a0bb720b62fde767e5b48d213edca7534d Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 07:50:31 -0400
Subject: [PATCH 14/36] fix(workflow): validate outermost custom output object

---
 .../src/handler/structured_output.rs          | 67 ++++++++++++++++++-
 1 file changed, 66 insertions(+), 1 deletion(-)

diff --git a/lib/components/fabro-workflow/src/handler/structured_output.rs b/lib/components/fabro-workflow/src/handler/structured_output.rs
index d36435bf3..888256b21 100644
--- a/lib/components/fabro-workflow/src/handler/structured_output.rs
+++ b/lib/components/fabro-workflow/src/handler/structured_output.rs
@@ -226,6 +226,16 @@ pub(crate) fn apply_validated_output(
 
 /// Find all balanced `{...}` JSON object substrings in the text.
 fn find_json_objects(text: &str) -> Vec<&str> {
+    find_json_objects_with_nested(text, true)
+}
+
+/// Find balanced `{...}` JSON object substrings in the text, skipping objects
+/// nested within a previous match.
+fn find_outermost_json_objects(text: &str) -> Vec<&str> {
+    find_json_objects_with_nested(text, false)
+}
+
+fn find_json_objects_with_nested(text: &str, include_nested: bool) -> Vec<&str> {
     let mut results = Vec::new();
     let bytes = text.as_bytes();
     let mut i = 0;
@@ -251,6 +261,9 @@ fn find_json_objects(text: &str) -> Vec<&str> {
                         depth -= 1;
                         if depth == 0 {
                             results.push(&text[start..=j]);
+                            if !include_nested {
+                                i = j;
+                            }
                             break;
                         }
                     }
@@ -334,7 +347,7 @@ fn validate_custom_response_text(
     validator: &Validator,
     text: &str,
 ) -> Result<ValidatedStructuredOutput, StructuredOutputError> {
-    let candidates = find_json_objects(text);
+    let candidates = find_outermost_json_objects(text);
     let Some(candidate) = candidates.last() else {
         return Err(StructuredOutputError::new(
             StructuredOutputErrorKind::NoJsonObject,
@@ -558,6 +571,58 @@ mod tests {
         assert_eq!(validated.value, serde_json::json!({"passed": true}));
     }
 
+    #[test]
+    fn validates_custom_schema_against_outermost_object() {
+        let schema = schema(serde_json::json!({
+            "type": "object",
+            "required": ["issue"],
+            "properties": {
+                "issue": {
+                    "type": "object",
+                    "required": ["number"],
+                    "properties": {
+                        "number": { "type": "integer" }
+                    }
+                }
+            }
+        }));
+
+        let validated = validate_response_text(&schema, r#"{"issue":{"number":19}}"#).unwrap();
+
+        assert_eq!(
+            validated.value,
+            serde_json::json!({"issue": {"number": 19}})
+        );
+    }
+
+    #[test]
+    fn validates_last_outermost_object_when_response_has_trailing_prose() {
+        let schema = schema(serde_json::json!({
+            "type": "object",
+            "required": ["issue"],
+            "properties": {
+                "issue": {
+                    "type": "object",
+                    "required": ["number"],
+                    "properties": {
+                        "number": { "type": "integer" }
+                    }
+                }
+            }
+        }));
+
+        let validated = validate_response_text(
+            &schema,
+            r#"ignore {"issue":{"number":1}} final {"issue":{"number":19}} trailing"#,
+        )
+        .unwrap();
+
+        assert_eq!(
+            validated.value,
+            serde_json::json!({"issue": {"number": 19}})
+        );
+    }
+
     #[test]
     fn custom_schema_validation_errors_are_reported() {
         let schema = schema(serde_json::json!({

From d2510447fe69e89cb84a1c19377f17292b58f139 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 09:03:47 -0400
Subject: [PATCH 15/36] Retry the sandbox clone when GitHub token replication
 lags

A Daytona-backed run could fail five seconds after start when the sandbox
git clone hit a transient GitHub "Repository not found" error. Clone-based
providers mint an installation access token and clone with it in the same
breath, but GitHub replicates a new token to its edge cache sites
asynchronously. A clone that starts within a second of the mint can be
rejected before the token is visible to the site serving it, and on a
private repo that rejection arrives as "Repository not found" because
GitHub answers unauthorized reads with 404.

Nothing retried the clone, and the failure classified as `deterministic`,
which is the one category `loop_restart` refuses to restart. An identical
run relaunched 46 seconds later succeeded with no changes.

A successful mint is what makes the message safe to retry.
`resolve_clone_credentials` already fails loudly on every deterministic
explanation for a clone 404: the installation lookup 404s when the App is
not installed for the owner, and token creation 422s when the installation
does not cover the repo. Once credentials are in hand, "not found" from the
clone itself cannot mean "no access".

Add `clone_retry` and use it from both clone-based providers: 3 attempts
with 3s then 9s backoff, reusing the same token so replication keeps making
progress instead of restarting the clock. Token-replication signatures
retry only when credentials are present, so a public clone of a wrong URL
still fails fast. Infrastructure failures retry either way.

The Docker provider had the identical single-shot clone and is the default
runtime provider, so it is covered too.

Also fix two nearby issues found while reading the area:

- The GitHub-URL-parse path in the Daytona clone skipped `fail_init`,
  unlike every sibling path, so `InitializeFailed` was never emitted.
- The `classify_exec_failure` hint for "repository not found" asserted the
  App installation may not cover the repo. After a successful scoped mint
  that diagnosis is impossible, and it sent operators hunting a
  configuration problem that did not exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../fabro-sandbox/src/clone_retry.rs          | 333 ++++++++++++++++++
 .../fabro-sandbox/src/daytona/mod.rs          | 107 +++++-
 lib/components/fabro-sandbox/src/docker.rs    |  77 +++-
 lib/components/fabro-sandbox/src/error.rs     |   6 +-
 lib/components/fabro-sandbox/src/lib.rs       |   3 +
 5 files changed, 500 insertions(+), 26 deletions(-)
 create mode 100644 lib/components/fabro-sandbox/src/clone_retry.rs

diff --git a/lib/components/fabro-sandbox/src/clone_retry.rs b/lib/components/fabro-sandbox/src/clone_retry.rs
new file mode 100644
index 000000000..d94a52485
--- /dev/null
+++ b/lib/components/fabro-sandbox/src/clone_retry.rs
@@ -0,0 +1,333 @@
+//! Retry for the first repository clone in a clone-based sandbox.
+//!
+//! Clone-based providers mint a GitHub installation access token and clone with
+//! it in the same breath. GitHub replicates a new token to its edge cache sites
+//! asynchronously, so a clone that starts within a second of the mint can be
+//! rejected before the token is visible to the site serving it. On a private
+//! repository that rejection arrives as `Repository not found.`, because GitHub
+//! answers unauthorized reads with 404 rather than 403.
+//!
+//! A successful mint is what makes that message safe to retry.
+//! `resolve_clone_credentials` already fails loudly on every deterministic
+//! explanation for a clone 404: the installation lookup 404s when the App is
+//! not installed for the owner, and token creation 422s when the installation
+//! does not cover the repository. So once credentials are in hand, `not found`
+//! from the clone itself cannot mean "no access" — the repository exists and
+//! the token covers it.
+//!
+//! Retries reuse the same token on purpose. Replication of a given token only
+//! makes progress, so each attempt strictly improves the odds, while re-minting
+//! would restart the replication clock.
+
+use std::future::Future;
+use std::time::Duration;
+
+use fabro_util::backoff::BackoffPolicy;
+use tokio::time;
+
+/// Total clone attempts, including the first.
+const MAX_ATTEMPTS: u32 = 3;
+
+/// Why a failed clone attempt is worth repeating.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
+#[strum(serialize_all = "snake_case")]
+pub(crate) enum CloneRetryReason {
+    /// A freshly minted installation token has not reached the GitHub edge
+    /// cache site serving this clone yet.
+    TokenReplication,
+    /// The clone failed on infrastructure, unrelated to credentials.
+    TransientInfra,
+}
+
+/// Message fragments that mean the clone failed on infrastructure.
+///
+/// These are safe to retry whether or not the clone was authenticated.
+const TRANSIENT_HINTS: &[&str] = &[
+    "could not resolve host",
+    "temporary failure in name resolution",
+    "connection refused",
+    "connection reset",
+    "connection timed out",
+    "timed out",
+    "network is unreachable",
+    "no route to host",
+    "tls handshake",
+    "early eof",
+    "rpc failed",
+    "unexpected disconnect",
+    "the remote end hung up unexpectedly",
+    "index-pack failed",
+    "service unavailable",
+    "gateway timeout",
+    "too many requests",
+    "rate limit",
+];
+
+/// Message fragments GitHub uses when a token is not yet visible.
+///
+/// Only meaningful when the clone carried credentials. The same lag surfaces as
+/// 404 or as an auth failure depending on which endpoint answers first.
+const TOKEN_REPLICATION_HINTS: &[&str] = &[
+    "repository not found",
+    "authentication failed",
+    "invalid username or password",
+    "bad credentials",
+];
+
+/// Classify a failed clone by its rendered message.
+///
+/// `has_credentials` gates the token-replication reading. Without credentials
+/// there is no token to replicate, so `not found` on a public clone means the
+/// URL names a repository that is not there — that should fail immediately
+/// rather than burn 12 seconds of backoff.
+pub(crate) fn classify_message(message: &str, has_credentials: bool) -> Option<CloneRetryReason> {
+    let lower = message.to_ascii_lowercase();
+
+    if TRANSIENT_HINTS.iter().any(|hint| lower.contains(hint)) {
+        return Some(CloneRetryReason::TransientInfra);
+    }
+    if has_credentials
+        && TOKEN_REPLICATION_HINTS
+            .iter()
+            .any(|hint| lower.contains(hint))
+    {
+        return Some(CloneRetryReason::TokenReplication);
+    }
+    None
+}
+
+/// Backoff between clone attempts: 3s, then 9s.
+///
+/// GitHub's guidance for token replication is to wait a few seconds and retry
+/// with the same token. Sub-second delays land inside the same replication
+/// window and spend an attempt for nothing.
+fn backoff() -> BackoffPolicy {
+    BackoffPolicy {
+        initial_delay: Duration::from_secs(3),
+        factor:        3.0,
+        max_delay:     Duration::from_secs(10),
+        jitter:        false,
+    }
+}
+
+/// Run a clone, repeating it while the failure looks transient.
+///
+/// `attempt` receives the 1-based attempt number so the caller can clear
+/// leftovers from the previous try before cloning again. `classify` decides
+/// whether an error is worth repeating; `None` returns it to the caller
+/// untouched. The error from the final attempt is returned as-is, so callers
+/// keep the cause chain they would have had without retries.
+pub(crate) async fn retry_clone<T, E, Attempt, Fut, Classify>(
+    provider: &'static str,
+    mut attempt: Attempt,
+    classify: Classify,
+) -> Result<T, E>
+where
+    Attempt: FnMut(u32) -> Fut,
+    Fut: Future<Output = Result<T, E>>,
+    Classify: Fn(&E) -> Option<CloneRetryReason>,
+{
+    let backoff = backoff();
+
+    for attempt_number in 1..MAX_ATTEMPTS {
+        match attempt(attempt_number).await {
+            Ok(value) => return Ok(value),
+            Err(err) => {
+                let Some(reason) = classify(&err) else {
+                    return Err(err);
+                };
+                let delay = backoff.delay_for_attempt(attempt_number);
+                // The failure text can carry git stderr, so log the category
+                // rather than the message. The caller still reports the full
+                // error if the attempts run out.
+                tracing::warn!(
+                    provider,
+                    attempt = attempt_number,
+                    max_attempts = MAX_ATTEMPTS,
+                    reason = %reason,
+                    delay_ms = u64::try_from(delay.as_millis()).unwrap_or(u64::MAX),
+                    "Git clone failed, retrying"
+                );
+                time::sleep(delay).await;
+            }
+        }
+    }
+
+    attempt(MAX_ATTEMPTS).await
+}
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Mutex;
+
+    use super::*;
+
+    /// Records the attempt numbers a closure was called with.
+    #[derive(Default)]
+    struct Attempts(Mutex<Vec<u32>>);
+
+    impl Attempts {
+        fn record(&self, attempt: u32) {
+            self.0.lock().expect("attempt log mutex").push(attempt);
+        }
+
+        fn recorded(&self) -> Vec<u32> {
+            self.0.lock().expect("attempt log mutex").clone()
+        }
+    }
+
+    /// A classifier that treats every failure as worth repeating.
+    const ALWAYS_RETRY: fn(&String) -> Option<CloneRetryReason> =
+        |_| Some(CloneRetryReason::TokenReplication);
+
+    #[test]
+    fn private_repo_not_found_after_a_successful_mint_is_a_replication_lag() {
+        assert_eq!(
+            classify_message("repository not found: Repository not found.", true),
+            Some(CloneRetryReason::TokenReplication)
+        );
+    }
+
+    #[test]
+    fn not_found_without_credentials_is_a_wrong_url() {
+        assert_eq!(
+            classify_message("repository not found: Repository not found.", false),
+            None
+        );
+    }
+
+    #[test]
+    fn auth_failure_with_credentials_is_a_replication_lag() {
+        assert_eq!(
+            classify_message(
+                "fatal: Authentication failed for 'https://github.com/owner/repo'",
+                true
+            ),
+            Some(CloneRetryReason::TokenReplication)
+        );
+    }
+
+    #[test]
+    fn infra_failures_retry_without_credentials() {
+        for message in [
+            "fatal: unable to access: Could not resolve host: github.com",
+            "error: RPC failed; curl 56 recv failure",
+            "fatal: early EOF",
+            "Operation timed out",
+        ] {
+            assert_eq!(
+                classify_message(message, false),
+                Some(CloneRetryReason::TransientInfra),
+                "expected {message:?} to be transient"
+            );
+        }
+    }
+
+    #[test]
+    fn genuine_failures_are_not_retried() {
+        for message in [
+            "fatal: could not read Username for 'https://github.com'",
+            "remote: Permission to owner/repo.git denied",
+            "fatal: destination path 'repo' already exists",
+        ] {
+            assert_eq!(
+                classify_message(message, true),
+                None,
+                "expected {message:?} to fail fast"
+            );
+        }
+    }
+
+    #[test]
+    fn backoff_waits_seconds_not_milliseconds() {
+        let backoff = backoff();
+        assert_eq!(backoff.delay_for_attempt(1), Duration::from_secs(3));
+        assert_eq!(backoff.delay_for_attempt(2), Duration::from_secs(9));
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn first_success_runs_one_attempt() {
+        let attempts = Attempts::default();
+
+        let result = retry_clone(
+            "test",
+            |attempt| {
+                attempts.record(attempt);
+                async move { Ok::<_, String>(attempt) }
+            },
+            ALWAYS_RETRY,
+        )
+        .await;
+
+        assert_eq!(result, Ok(1));
+        assert_eq!(attempts.recorded(), vec![1]);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn retries_until_a_later_attempt_succeeds() {
+        let attempts = Attempts::default();
+
+        let result = retry_clone(
+            "test",
+            |attempt| {
+                attempts.record(attempt);
+                async move {
+                    if attempt < 3 {
+                        Err("Repository not found.".to_string())
+                    } else {
+                        Ok(attempt)
+                    }
+                }
+            },
+            ALWAYS_RETRY,
+        )
+        .await;
+
+        assert_eq!(result, Ok(3));
+        assert_eq!(attempts.recorded(), vec![1, 2, 3]);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn exhausted_attempts_return_the_final_error() {
+        let attempts = Attempts::default();
+
+        let result = retry_clone(
+            "test",
+            |attempt| {
+                attempts.record(attempt);
+                async move { Err::<(), _>(format!("Repository not found. (attempt {attempt})")) }
+            },
+            ALWAYS_RETRY,
+        )
+        .await;
+
+        assert_eq!(
+            result,
+            Err("Repository not found. (attempt 3)".to_string()),
+            "the caller should see the last failure, not the first"
+        );
+        assert_eq!(attempts.recorded(), vec![1, 2, 3]);
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn unretryable_failure_stops_immediately() {
+        let attempts = Attempts::default();
+
+        let result = retry_clone(
+            "test",
+            |attempt| {
+                attempts.record(attempt);
+                async move { Err::<(), _>("permission denied".to_string()) }
+            },
+            |_: &String| None,
+        )
+        .await;
+
+        assert_eq!(result, Err("permission denied".to_string()));
+        assert_eq!(
+            attempts.recorded(),
+            vec![1],
+            "a deterministic failure should not wait out the backoff"
+        );
+    }
+}
diff --git a/lib/components/fabro-sandbox/src/daytona/mod.rs b/lib/components/fabro-sandbox/src/daytona/mod.rs
index 292cc3ebe..39798e54a 100644
--- a/lib/components/fabro-sandbox/src/daytona/mod.rs
+++ b/lib/components/fabro-sandbox/src/daytona/mod.rs
@@ -24,6 +24,7 @@ use tokio::task::JoinHandle;
 use tokio::{fs, time};
 use tokio_util::sync::CancellationToken;
 
+use crate::clone_retry::{self, CloneRetryReason};
 use crate::clone_source::{self, CloneDecision, EmptyWorkspaceReason};
 use crate::redact::redact_auth_url;
 use crate::sandbox::{
@@ -1066,7 +1067,7 @@ impl Sandbox for DaytonaSandbox {
                                     error:  err.to_string(),
                                     causes: err.causes(),
                                 });
-                                err
+                                self.fail_init(init_start, err)
                             })?;
                         fabro_github::resolve_clone_credentials(
                             &fabro_github::GitHubContext::new(
@@ -1154,18 +1155,34 @@ impl Sandbox for DaytonaSandbox {
                 })?;
 
                 let clone_token = password.clone();
-                let clone_result = git_svc
-                    .clone(
-                        &origin_url,
-                        &layout.primary_repo_path,
-                        daytona_sdk::GitCloneOptions {
-                            branch,
-                            username,
-                            password,
+                let has_credentials = password.is_some();
+                let clone_result = clone_retry::retry_clone(
+                    "daytona",
+                    |attempt| {
+                        let git_svc = &git_svc;
+                        let fs_svc = &fs_svc;
+                        let origin = origin_url.as_str();
+                        let target = layout.primary_repo_path.as_str();
+                        let options = daytona_sdk::GitCloneOptions {
+                            branch: branch.clone(),
+                            username: username.clone(),
+                            password: password.clone(),
                             ..Default::default()
-                        },
-                    )
-                    .await;
+                        };
+                        async move {
+                            if attempt > 1 {
+                                // git removes the directory it created when it
+                                // exits on its own, but a clone killed part-way
+                                // leaves a partial checkout that the next
+                                // `git clone` would refuse to write into.
+                                let _ = fs_svc.delete_file(target, true).await;
+                            }
+                            git_svc.clone(origin, target, options).await
+                        }
+                    },
+                    |err: &DaytonaError| classify_clone_failure(err, has_credentials),
+                )
+                .await;
 
                 match clone_result {
                     Ok(()) => {
@@ -2469,6 +2486,24 @@ fn daytona_bash_session_probe_outcome(execution: crate::Result<ExecResult>) -> c
     ))
 }
 
+/// Classify a failed Daytona clone for retry.
+///
+/// The GitHub 404 does not arrive as an HTTP 404 on the Daytona call. git runs
+/// inside the sandbox, so its stderr comes back through the toolbox as the
+/// error message — the credential race has to be matched on text. Daytona's own
+/// transport failures are visible structurally.
+fn classify_clone_failure(err: &DaytonaError, has_credentials: bool) -> Option<CloneRetryReason> {
+    let transient_transport = match err {
+        DaytonaError::Timeout { .. } | DaytonaError::RateLimit { .. } => true,
+        DaytonaError::Api { status_code, .. } => (500..600).contains(status_code),
+        DaytonaError::NotFound { .. } | DaytonaError::General(_) => false,
+    };
+    if transient_transport {
+        return Some(CloneRetryReason::TransientInfra);
+    }
+    clone_retry::classify_message(err.message(), has_credentials)
+}
+
 fn daytona_symlink_command(layout: &clone_source::GitHubRepoLayout) -> String {
     format!(
         "ln -s {} {}",
@@ -2859,6 +2894,54 @@ mod tests {
         );
     }
 
+    #[test]
+    fn clone_not_found_after_a_successful_mint_is_retried() {
+        // The exact error from run 01KYM99DF27JRRW4XSYZBP27K7: git's stderr,
+        // relayed through the toolbox, five seconds after a token was minted.
+        let err = DaytonaError::general("repository not found: Repository not found.");
+
+        assert_eq!(
+            classify_clone_failure(&err, true),
+            Some(CloneRetryReason::TokenReplication)
+        );
+        assert_eq!(
+            classify_clone_failure(&err, false),
+            None,
+            "without credentials there is no token to replicate"
+        );
+    }
+
+    #[test]
+    fn clone_transient_transport_failures_are_retried() {
+        for err in [
+            DaytonaError::timeout("request timed out"),
+            DaytonaError::rate_limit("too many requests"),
+            DaytonaError::api(503, ""),
+        ] {
+            assert_eq!(
+                classify_clone_failure(&err, false),
+                Some(CloneRetryReason::TransientInfra),
+                "expected {err:?} to be transient"
+            );
+        }
+    }
+
+    #[test]
+    fn clone_client_errors_are_not_retried() {
+        for err in [
+            DaytonaError::api(400, "bad request"),
+            DaytonaError::api(403, "forbidden"),
+            DaytonaError::not_found("Sandbox not found"),
+            DaytonaError::general("fatal: could not read Username for 'https://github.com'"),
+        ] {
+            assert_eq!(
+                classify_clone_failure(&err, true),
+                None,
+                "expected {err:?} to fail fast"
+            );
+        }
+    }
+
     #[test]
     fn wrap_fs_error_classifies_http_400_and_403() {
         let err_400 = wrap_fs_error(
diff --git a/lib/components/fabro-sandbox/src/docker.rs b/lib/components/fabro-sandbox/src/docker.rs
index fb9b7df9c..c9fd3ce4c 100644
--- a/lib/components/fabro-sandbox/src/docker.rs
+++ b/lib/components/fabro-sandbox/src/docker.rs
@@ -37,7 +37,7 @@ use crate::{
     CommandOutputCallback, DEFAULT_EXEC_OUTPUT_TAIL_BYTES, DirEntry, ExecResult,
     ExecStreamingResult, GrepOptions, Sandbox, SandboxEvent, SandboxEventCallback, SandboxFile,
     StderrCollector, StdioProcess, StdioProcessHandle, StdioProcessTermination, WalkOptions,
-    format_lines_numbered, shell_quote,
+    clone_retry, format_lines_numbered, shell_quote,
 };
 
 const DOCKER_BASH_REQUIREMENT: &str = "Docker sandboxes require /bin/bash for every command, with no `sh` fallback; use an \
@@ -656,6 +656,42 @@ impl DockerSandbox {
         Ok(())
     }
 
+    /// Render a failed `git clone` exit into an error, with the auth URL
+    /// masked.
+    fn clone_failure_error(
+        &self,
+        stderr: &str,
+        auth_url: Option<&fabro_redact::DisplaySafeUrl>,
+    ) -> crate::Error {
+        let stderr = redact_auth_url(stderr, auth_url);
+        crate::Error::message(if self.github_app.is_none() {
+            format!(
+                "Git clone failed: {stderr}. If this is a private repository, configure a GitHub App with `fabro install` and install it for your organization."
+            )
+        } else {
+            format!("Failed to clone repo into Docker sandbox: {stderr}")
+        })
+    }
+
+    /// Clear a checkout left behind by a failed clone, before cloning again.
+    ///
+    /// git removes the directory it created when it exits on its own, but a
+    /// clone killed by the exec timeout leaves a partial checkout that the next
+    /// `git clone` would refuse to write into. Best-effort: if the removal
+    /// fails, the retry surfaces the real error.
+    async fn clear_partial_clone(&self, repo_path: &str) {
+        let command = format!("rm -rf {}", shell_quote(repo_path));
+        if let Err(err) = self
+            .docker_exec_shell(&command, 30_000, Some("/"), None, None)
+            .await
+        {
+            tracing::debug!(
+                error = %crate::display_for_log(&err),
+                "Failed to clear partial clone before retry"
+            );
+        }
+    }
+
     async fn clone_github_repo(
         &self,
         origin_url: String,
@@ -690,19 +726,34 @@ impl DockerSandbox {
             .map_or(origin_url.as_str(), |url| url.as_raw_url().as_str());
 
         let command = git_clone_and_link_command(clone_url, branch.as_deref(), &layout);
+        let has_credentials = auth_url.is_some();
 
-        let result = self
-            .docker_exec_shell(&command, 300_000, Some("/"), None, None)
-            .await?;
-        if !result.is_success() {
-            let stderr = redact_auth_url(&result.stderr, auth_url.as_ref());
-            let err = crate::Error::message(if self.github_app.is_none() {
-                format!(
-                    "Git clone failed: {stderr}. If this is a private repository, configure a GitHub App with `fabro install` and install it for your organization."
-                )
-            } else {
-                format!("Failed to clone repo into Docker sandbox: {stderr}")
-            });
+        let clone_result = clone_retry::retry_clone(
+            "docker",
+            |attempt| {
+                let command = command.as_str();
+                let auth_url = auth_url.as_ref();
+                let repo_path = layout.primary_repo_path.as_str();
+                async move {
+                    if attempt > 1 {
+                        self.clear_partial_clone(repo_path).await;
+                    }
+                    let result = self
+                        .docker_exec_shell(command, 300_000, Some("/"), None, None)
+                        .await?;
+                    if result.is_success() {
+                        return Ok(());
+                    }
+                    Err(self.clone_failure_error(&result.stderr, auth_url))
+                }
+            },
+            |err: &crate::Error| {
+                clone_retry::classify_message(&err.display_with_causes(), has_credentials)
+            },
+        )
+        .await;
+
+        if let Err(err) = clone_result {
             self.emit(SandboxEvent::GitCloneFailed {
                 url:    origin_url,
                 error:  err.to_string(),
diff --git a/lib/components/fabro-sandbox/src/error.rs b/lib/components/fabro-sandbox/src/error.rs
index 7b2377660..d872f9ac3 100644
--- a/lib/components/fabro-sandbox/src/error.rs
+++ b/lib/components/fabro-sandbox/src/error.rs
@@ -143,7 +143,11 @@ pub(crate) fn classify_exec_failure(stderr: &str) -> Option<&'static str> {
     } else if lower.contains("could not resolve host") || lower.contains("network is unreachable") {
         Some("network failure inside sandbox - check DNS / egress from the run container")
     } else if lower.contains("repository not found") {
-        Some("github 404 - the App installation may not include this repo")
+        Some(
+            "github 404 - the repo does not exist, the App installation does not \
+             include it, or a freshly minted installation token has not replicated \
+             to GitHub's edge cache yet (github answers unauthorized reads with 404)",
+        )
     } else if lower.contains("no such remote") && lower.contains("origin") {
         Some("origin remote missing - push credentials could not be installed")
     } else if lower.contains("not a git repository")
diff --git a/lib/components/fabro-sandbox/src/lib.rs b/lib/components/fabro-sandbox/src/lib.rs
index edf567ada..06285ae37 100644
--- a/lib/components/fabro-sandbox/src/lib.rs
+++ b/lib/components/fabro-sandbox/src/lib.rs
@@ -9,6 +9,9 @@ pub mod sandbox_spec;
 #[cfg(any(feature = "docker", feature = "daytona"))]
 mod clone_source;
 
+#[cfg(any(feature = "docker", feature = "daytona", test))]
+mod clone_retry;
+
 #[cfg(any(feature = "docker", feature = "daytona", test))]
 mod managed_labels;
 

From 46e8d921952f57baa483da791612b5b924282d9f Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 12:11:04 -0400
Subject: [PATCH 16/36] Give the run docks a shared collapsible shell

The interview question panel could take half the viewport, and the page
reserved a fixed 18rem beneath it regardless of how tall it actually was,
so a long question covered the stage rows it was asking about.

Add a shared `RunDockShell` for the two controls docked at the bottom of
the run detail route. It is three zones: a header that is always visible
and doubles as the collapsed bar, a body that scrolls, and actions that
stay pinned so the controls needed to answer or send never scroll out of
reach.

The interview dock drops the question-type subtitle the answer buttons
already state, turns the 160px context box into a closed disclosure with
a first-line preview, drops the "or" divider row, and reveals the
keyboard hint on focus inside the composer row instead of standing below
it. Options stack into a list once a label is too long to sit in a pill.
For the sample question this is 506px down to 325px, or 43px collapsed.

The steering dock gains the same header. `Interrupt` moves into it,
because it acts on the run rather than on the message being composed, and
the waiting notice folds into the header status instead of adding a row.
Both docks now share one composer.

Clearance is measured from the rendered dock rather than assumed. The
former constants remain as the pre-measurement first frame.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../app/components/interview-dock.test.tsx    | 112 +++++-
 .../app/components/interview-dock.tsx         | 342 +++++++-----------
 apps/fabro-web/app/components/run-dock.tsx    | 300 +++++++++++++++
 .../app/components/steer-bar.test.tsx         |  24 +-
 apps/fabro-web/app/components/steer-bar.tsx   | 123 +++----
 apps/fabro-web/app/routes/run-detail.test.ts  |   2 +-
 apps/fabro-web/app/routes/run-detail.tsx      |  13 +-
 .../app/routes/run-detail/docked-controls.tsx |  23 +-
 8 files changed, 654 insertions(+), 285 deletions(-)
 create mode 100644 apps/fabro-web/app/components/run-dock.tsx

diff --git a/apps/fabro-web/app/components/interview-dock.test.tsx b/apps/fabro-web/app/components/interview-dock.test.tsx
index 290581690..be6330be2 100644
--- a/apps/fabro-web/app/components/interview-dock.test.tsx
+++ b/apps/fabro-web/app/components/interview-dock.test.tsx
@@ -6,7 +6,11 @@ import {
   QuestionType,
 } from "@qltysh/fabro-api-client";
 
-import { InterviewDock } from "./interview-dock";
+import {
+  contextPreview,
+  InterviewDock,
+  shouldStackOptions,
+} from "./interview-dock";
 import { displayLabel } from "./interview-label";
 import { generatedAxios } from "../lib/api-client";
 
@@ -236,6 +240,112 @@ describe("InterviewDock", () => {
     expect(text).toContain("Context from preceding stage");
     expect(text).toContain("1. Deploy");
   });
+
+  test("context starts closed so it costs one line, not a standing panel", () => {
+    const question = makeQuestion({
+      context_display: "Plan:\n1. Deploy\n2. Verify",
+    });
+    const tree = render(
+      <InterviewDock runId="run-1" questions={[question]} />,
+    );
+    const details = tree.root.findAllByType("details");
+    expect(details).toHaveLength(1);
+    expect(details[0]!.props.open).toBeFalsy();
+  });
+
+  test("omits the question type subtitle that the answer buttons already state", () => {
+    const question = makeQuestion({
+      question_type: QuestionType.MULTIPLE_CHOICE,
+      options: [{ key: "A", label: "[A] Approve" }],
+    });
+    const tree = render(
+      <InterviewDock runId="run-1" questions={[question]} />,
+    );
+    expect(textContent(tree.toJSON())).not.toContain("Pick one");
+  });
+
+  test("collapsing hides the answer controls but keeps the header", () => {
+    const tree = render(
+      <InterviewDock runId="run-1" questions={[makeQuestion()]} />,
+    );
+    const toggle = tree.root.findByProps({ "aria-label": "Collapse Interview question" });
+
+    act(() => {
+      toggle.props.onClick();
+    });
+
+    const expanded = tree.root.findByProps({
+      "aria-label": "Expand Interview question",
+    });
+    expect(expanded.props["aria-expanded"]).toBe(false);
+    expect(textContent(tree.toJSON())).toContain("Awaiting input");
+  });
+
+  test("a queued question arrives expanded even after the panel was collapsed", () => {
+    const questions = [
+      makeQuestion({ id: "q-1", stage: "stage-a" }),
+      makeQuestion({ id: "q-2", stage: "stage-b" }),
+    ];
+    const tree = render(<InterviewDock runId="run-1" questions={questions} />);
+
+    act(() => {
+      tree.root
+        .findByProps({ "aria-label": "Collapse Interview question" })
+        .props.onClick();
+    });
+    act(() => {
+      buttonsByText(tree)["1 more pending"]!.props.onClick();
+    });
+
+    const toggle = tree.root.findByProps({
+      "aria-label": "Collapse Interview question",
+    });
+    expect(toggle.props["aria-expanded"]).toBe(true);
+  });
+});
+
+describe("shouldStackOptions", () => {
+  test("keeps short labels as a wrapping row", () => {
+    expect(
+      shouldStackOptions([
+        { key: "a", label: "Approve" },
+        { key: "b", label: "Revise" },
+      ]),
+    ).toBe(false);
+  });
+
+  test("stacks once a label is too long to sit in a pill", () => {
+    expect(
+      shouldStackOptions([
+        { key: "a", label: "Approve" },
+        { key: "b", label: "Review complete; sync the current Markdown document" },
+      ]),
+    ).toBe(true);
+  });
+
+  test("stacks when any option carries a description", () => {
+    expect(
+      shouldStackOptions([
+        { key: "a", label: "Approve", description: "Deploy the current patch" },
+      ]),
+    ).toBe(true);
+  });
+});
+
+describe("contextPreview", () => {
+  test("uses the first non-empty line", () => {
+    expect(contextPreview("\n\nPlan is ready\nSecond line")).toBe("Plan is ready");
+  });
+
+  test("truncates a long first line", () => {
+    const preview = contextPreview("x".repeat(200));
+    expect(preview).toHaveLength(61);
+    expect(preview.endsWith("…")).toBe(true);
+  });
+
+  test("returns an empty string for blank context", () => {
+    expect(contextPreview("   \n  ")).toBe("");
+  });
 });
 
 describe("displayLabel", () => {
diff --git a/apps/fabro-web/app/components/interview-dock.tsx b/apps/fabro-web/app/components/interview-dock.tsx
index a2164715a..e53804772 100644
--- a/apps/fabro-web/app/components/interview-dock.tsx
+++ b/apps/fabro-web/app/components/interview-dock.tsx
@@ -1,14 +1,8 @@
+import { useCallback, useState } from "react";
 import {
-  useCallback,
-  useState,
-  type FormEvent,
-  type KeyboardEvent,
-} from "react";
-import {
-  ArrowPathIcon,
   ArrowRightIcon,
-  ArrowUturnLeftIcon,
   CheckIcon,
+  ChevronRightIcon,
 } from "@heroicons/react/20/solid";
 import { QuestionType } from "@qltysh/fabro-api-client";
 import type {
@@ -22,16 +16,22 @@ import {
 } from "../lib/mutations";
 import { ApiError } from "../lib/api-client";
 import { displayLabel } from "./interview-label";
+import {
+  DockComposer,
+  DockSpinner,
+  RunDockShell,
+  DOCK_CHOICE_BUTTON,
+  DOCK_CHOICE_BUTTON_SELECTED,
+  DOCK_HEADER_BUTTON,
+  DOCK_PRIMARY_BUTTON,
+} from "./run-dock";
 import { ErrorMessage } from "./ui";
 
-const PRIMARY_BUTTON =
-  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-teal-500 px-3.5 py-2 text-sm font-medium text-on-primary transition-colors hover:bg-teal-300 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-teal-500";
-
-const CHOICE_BUTTON =
-  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-overlay px-3.5 py-2 text-sm font-medium text-fg-2 outline-1 -outline-offset-1 outline-line-strong transition-colors hover:bg-overlay-strong hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60";
-
-const CHOICE_BUTTON_SELECTED =
-  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-teal-500/15 px-3.5 py-2 text-sm font-medium text-fg outline-1 -outline-offset-1 outline-teal-500/60 transition-colors hover:bg-teal-500/20 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500";
+/**
+ * Options stack into a list once a label is long enough that a row of pills
+ * would wrap mid-sentence.
+ */
+const STACK_LABEL_LENGTH = 40;
 
 type SubmitInterviewAnswer = SubmitInterviewAnswerArg["answer"];
 
@@ -51,6 +51,8 @@ export function InterviewDock({ runId, questions }: InterviewDockProps) {
   const moreCount = questions.length - 1;
 
   return (
+    // Keyed by question id, so a new question always arrives expanded with an
+    // empty composer. A collapsed panel can never silently block a run.
     <InterviewQuestionDock
       key={question.id}
       runId={runId}
@@ -76,6 +78,7 @@ function InterviewQuestionDock({
 }) {
   const submitMutation = useSubmitInterviewAnswer(runId);
   const [error, setError] = useState<string | null>(null);
+  const [collapsed, setCollapsed] = useState(false);
   const submitting = submitMutation.isMutating;
 
   const submit = useCallback(
@@ -83,105 +86,92 @@ function InterviewQuestionDock({
       setError(null);
       try {
         await submitMutation.trigger({ questionId: question.id, answer });
+        return true;
       } catch (caught) {
         setError(interviewSubmitErrorMessage(caught));
+        return false;
       }
     },
     [question.id, submitMutation],
   );
 
   return (
-    <section aria-label="Interview question">
-      <DockHeader
-        stage={question.stage}
-        moreCount={moreCount}
-        onCycle={onCycle}
-      />
-      <div className="space-y-5 px-5 py-4 sm:px-6">
-        <div>
-          <p className="text-pretty text-base/6 font-medium text-fg">
+    <RunDockShell
+      label="Interview question"
+      tone="waiting"
+      status="Awaiting input"
+      stage={question.stage}
+      peek={question.text}
+      collapsed={collapsed}
+      onCollapsedChange={setCollapsed}
+      headerActions={
+        moreCount > 0 && (
+          <button
+            type="button"
+            onClick={onCycle}
+            className={DOCK_HEADER_BUTTON}
+          >
+            <span className="tabular-nums">{moreCount}</span> more pending
+            <ArrowRightIcon className="size-3" aria-hidden="true" />
+          </button>
+        )
+      }
+      body={
+        <>
+          <p className="max-w-[78ch] text-pretty text-base/6 font-medium text-fg">
             {question.text}
           </p>
-          <p className="mt-1 text-xs/5 text-fg-muted">
-            {questionTypeLabel(question.question_type)}
-          </p>
-        </div>
-
-        {question.context_display && (
-          <ContextPanel text={question.context_display} />
-        )}
-
-        <QuestionBody
-          question={question}
-          submitting={submitting}
-          onSubmit={submit}
-        />
-
-        {error && <ErrorMessage message={error} />}
-      </div>
-    </section>
-  );
-}
-
-function DockHeader({
-  stage,
-  moreCount,
-  onCycle,
-}: {
-  stage: string;
-  moreCount: number;
-  onCycle: () => void;
-}) {
-  return (
-    <div className="flex items-center justify-between gap-3 border-b border-line px-5 py-2.5">
-      <div className="flex min-w-0 items-center gap-2 text-sm">
-        <PulseDot />
-        <span className="font-medium text-fg-2">Awaiting input</span>
-        {stage && (
-          <>
-            <span className="text-fg-muted" aria-hidden="true">
-              ·
-            </span>
-            <span className="truncate font-mono text-xs text-fg-3">{stage}</span>
-          </>
-        )}
-      </div>
-      {moreCount > 0 && (
-        <button
-          type="button"
-          onClick={onCycle}
-          className="inline-flex shrink-0 items-center gap-1 rounded-md bg-overlay px-2 py-1 text-xs font-medium text-fg-2 outline-1 -outline-offset-1 outline-line-strong hover:bg-overlay-strong hover:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
-        >
-          <span className="tabular-nums">{moreCount}</span> more pending
-          <ArrowRightIcon className="size-3" aria-hidden="true" />
-        </button>
-      )}
-    </div>
-  );
-}
-
-function PulseDot() {
-  return (
-    <span className="relative flex size-2 items-center justify-center" aria-hidden="true">
-      <span className="absolute inline-flex size-full animate-ping rounded-full bg-amber/60" />
-      <span className="relative inline-flex size-2 rounded-full bg-amber" />
-    </span>
+          {question.context_display && (
+            <ContextPanel text={question.context_display} />
+          )}
+        </>
+      }
+      actions={
+        <>
+          <QuestionBody
+            question={question}
+            submitting={submitting}
+            onSubmit={submit}
+          />
+          {error && <ErrorMessage message={error} />}
+        </>
+      }
+    />
   );
 }
 
+/**
+ * Context arrives collapsed. It repeats material the operator has usually
+ * already read in the stage stream above, so it earns a line rather than a
+ * standing panel.
+ */
 function ContextPanel({ text }: { text: string }) {
   return (
-    <div className="rounded-lg bg-panel-alt p-4 outline-1 -outline-offset-1 outline-line">
-      <p className="mb-1.5 font-mono text-[0.6875rem] tracking-wide text-fg-muted uppercase">
+    <details className="group rounded-lg bg-panel-alt outline-1 -outline-offset-1 outline-line">
+      <summary className="flex cursor-pointer list-none items-center gap-1.5 rounded-lg px-3 py-1.5 font-mono text-[0.6875rem] tracking-wide text-fg-muted uppercase transition-colors hover:text-fg-3 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500 [&::-webkit-details-marker]:hidden">
+        <ChevronRightIcon
+          className="size-3 shrink-0 transition-transform group-open:rotate-90"
+          aria-hidden="true"
+        />
         Context from preceding stage
-      </p>
-      <div className="max-h-40 overflow-y-auto text-sm/6 text-fg-2">
+        <span className="ml-auto truncate pl-3 font-sans text-xs normal-case tracking-normal group-open:hidden">
+          {contextPreview(text)}
+        </span>
+      </summary>
+      <div className="px-3 pb-2.5 text-sm/6 text-fg-2">
         <pre className="font-sans whitespace-pre-wrap">{text}</pre>
       </div>
-    </div>
+    </details>
   );
 }
 
+/** First line of the context, for the collapsed summary. */
+export function contextPreview(text: string): string {
+  const line = text.split("\n").find((candidate) => candidate.trim()) ?? "";
+  const trimmed = line.trim();
+  return trimmed.length > 60 ? `${trimmed.slice(0, 60).trimEnd()}…` : trimmed;
+}
+
 function QuestionBody({
   question,
   submitting,
@@ -189,7 +179,7 @@ function QuestionBody({
 }: {
   question: ApiQuestion;
   submitting: boolean;
-  onSubmit: (answer: SubmitInterviewAnswer) => Promise<void>;
+  onSubmit: (answer: SubmitInterviewAnswer) => Promise<boolean>;
 }) {
   switch (question.question_type) {
     case QuestionType.YES_NO:
@@ -215,11 +205,10 @@ function QuestionBody({
       );
     case QuestionType.FREEFORM:
       return (
-        <FreeformBody
+        <FreeformAnswer
           submitting={submitting}
           onSubmit={onSubmit}
           placeholder="Write your response…"
-          submitLabel="Send"
         />
       );
     default:
@@ -232,7 +221,7 @@ function YesNoBody({
   onSubmit,
 }: {
   submitting: boolean;
-  onSubmit: (answer: SubmitInterviewAnswer) => Promise<void>;
+  onSubmit: (answer: SubmitInterviewAnswer) => Promise<boolean>;
 }) {
   return (
     <div className="flex flex-wrap items-center gap-2">
@@ -242,7 +231,7 @@ function YesNoBody({
         aria-label="Answer no"
         disabled={submitting}
         onClick={() => void onSubmit({ kind: "no" })}
-        className={CHOICE_BUTTON}
+        className={DOCK_CHOICE_BUTTON}
       >
         No
       </button>
@@ -251,9 +240,9 @@ function YesNoBody({
         aria-label="Answer yes"
         disabled={submitting}
         onClick={() => void onSubmit({ kind: "yes" })}
-        className={PRIMARY_BUTTON}
+        className={DOCK_PRIMARY_BUTTON}
       >
-        {submitting ? <Spinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
+        {submitting ? <DockSpinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
         Yes
       </button>
     </div>
@@ -265,7 +254,7 @@ function ConfirmationBody({
   onSubmit,
 }: {
   submitting: boolean;
-  onSubmit: (answer: SubmitInterviewAnswer) => Promise<void>;
+  onSubmit: (answer: SubmitInterviewAnswer) => Promise<boolean>;
 }) {
   return (
     <div className="flex flex-wrap items-center gap-2">
@@ -273,15 +262,31 @@ function ConfirmationBody({
         type="button"
         disabled={submitting}
         onClick={() => void onSubmit({ kind: "yes" })}
-        className={PRIMARY_BUTTON}
+        className={DOCK_PRIMARY_BUTTON}
       >
-        {submitting ? <Spinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
+        {submitting ? <DockSpinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
         Confirm
       </button>
     </div>
   );
 }
 
+/**
+ * Long labels wrap badly as pills, so they become a stacked list instead.
+ */
+export function shouldStackOptions(options: InterviewOption[]): boolean {
+  return options.some(
+    (option) =>
+      option.label.length > STACK_LABEL_LENGTH || Boolean(option.description),
+  );
+}
+
+function optionListClass(stacked: boolean): string {
+  return stacked
+    ? "flex flex-col items-stretch gap-2"
+    : "flex flex-wrap items-center gap-2";
+}
+
 function ChoiceBody({
   options,
   allowFreeform,
@@ -291,19 +296,23 @@ function ChoiceBody({
   options: InterviewOption[];
   allowFreeform: boolean;
   submitting: boolean;
-  onSubmit: (answer: SubmitInterviewAnswer) => Promise<void>;
+  onSubmit: (answer: SubmitInterviewAnswer) => Promise<boolean>;
 }) {
+  const stacked = shouldStackOptions(options);
+
   return (
-    <div className="space-y-4">
+    <div className="space-y-2.5">
       {options.length > 0 && (
-        <div className="flex flex-wrap items-center gap-2">
+        <div className={optionListClass(stacked)}>
           {options.map((option) => (
             <button
               key={option.key}
               type="button"
               disabled={submitting}
               onClick={() => void onSubmit({ kind: "selected", option_key: option.key })}
-              className={CHOICE_BUTTON}
+              className={
+                stacked ? `${DOCK_CHOICE_BUTTON} justify-start` : DOCK_CHOICE_BUTTON
+              }
             >
               <OptionLabel option={option} />
             </button>
@@ -311,7 +320,7 @@ function ChoiceBody({
         </div>
       )}
       {allowFreeform && (
-        <FreeformBody
+        <FreeformAnswer
           submitting={submitting}
           onSubmit={onSubmit}
           placeholder={
@@ -319,8 +328,6 @@ function ChoiceBody({
               ? "Or write a custom response…"
               : "Write your response…"
           }
-          submitLabel="Send"
-          divider={options.length > 0}
         />
       )}
     </div>
@@ -334,7 +341,7 @@ function MultiSelectBody({
 }: {
   options: InterviewOption[];
   submitting: boolean;
-  onSubmit: (answer: SubmitInterviewAnswer) => Promise<void>;
+  onSubmit: (answer: SubmitInterviewAnswer) => Promise<boolean>;
 }) {
   const [selected, setSelected] = useState<Set<string>>(new Set());
 
@@ -352,11 +359,14 @@ function MultiSelectBody({
     if (selected.has(option.key)) selectedKeys.push(option.key);
   }
 
+  const stacked = shouldStackOptions(options);
+
   return (
-    <div className="space-y-3">
-      <div className="flex flex-wrap items-center gap-2">
+    <div className="space-y-2.5">
+      <div className={optionListClass(stacked)}>
         {options.map((option) => {
           const isSelected = selected.has(option.key);
+          const base = isSelected ? DOCK_CHOICE_BUTTON_SELECTED : DOCK_CHOICE_BUTTON;
           return (
             <button
               key={option.key}
@@ -364,7 +374,7 @@ function MultiSelectBody({
               disabled={submitting}
               aria-pressed={isSelected}
               onClick={() => toggle(option.key)}
-              className={isSelected ? CHOICE_BUTTON_SELECTED : CHOICE_BUTTON}
+              className={stacked ? `${base} justify-start` : base}
             >
               {isSelected && <CheckIcon className="size-3.5" aria-hidden="true" />}
               <OptionLabel option={option} />
@@ -380,9 +390,9 @@ function MultiSelectBody({
           type="button"
           disabled={submitting || selectedKeys.length === 0}
           onClick={() => void onSubmit({ kind: "multi_selected", option_keys: selectedKeys })}
-          className={PRIMARY_BUTTON}
+          className={DOCK_PRIMARY_BUTTON}
         >
-          {submitting ? <Spinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
+          {submitting ? <DockSpinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
           Submit selection
         </button>
       </div>
@@ -390,82 +400,23 @@ function MultiSelectBody({
   );
 }
 
-function FreeformBody({
+function FreeformAnswer({
   submitting,
   onSubmit,
   placeholder,
-  submitLabel,
-  divider = false,
 }: {
   submitting: boolean;
-  onSubmit: (answer: SubmitInterviewAnswer) => Promise<void>;
+  onSubmit: (answer: SubmitInterviewAnswer) => Promise<boolean>;
   placeholder: string;
-  submitLabel: string;
-  divider?: boolean;
 }) {
-  const [value, setValue] = useState("");
-
-  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
-    event.preventDefault();
-    const trimmed = value.trim();
-    if (!trimmed || submitting) return;
-    await onSubmit({ kind: "text", text: trimmed });
-    setValue("");
-  }
-
-  function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>) {
-    if (event.key === "Enter" && !event.shiftKey) {
-      event.preventDefault();
-      const form = event.currentTarget.form;
-      if (form) form.requestSubmit();
-    }
-  }
-
-  const disabled = submitting || value.trim().length === 0;
-
   return (
-    <form onSubmit={handleSubmit} className="space-y-2">
-      {divider && (
-        <div className="flex items-center gap-3" aria-hidden="true">
-          <span className="h-px flex-1 bg-line" />
-          <span className="text-xs text-fg-muted">or</span>
-          <span className="h-px flex-1 bg-line" />
-        </div>
-      )}
-      <div className="flex items-end gap-2">
-        <label className="sr-only" htmlFor="interview-freeform-answer">
-          Your response
-        </label>
-        <textarea
-          id="interview-freeform-answer"
-          name="answer"
-          aria-label="Interview answer"
-          rows={1}
-          value={value}
-          onChange={(event) => setValue(event.target.value)}
-          onKeyDown={handleKeyDown}
-          placeholder={placeholder}
-          disabled={submitting}
-          className="block w-full resize-none rounded-lg bg-panel-alt px-3.5 py-2.5 text-base/6 text-fg outline-1 -outline-offset-1 outline-line-strong placeholder:text-fg-muted focus:outline-2 focus:-outline-offset-1 focus:outline-teal-500 disabled:opacity-60 sm:text-sm/5"
-        />
-        <button type="submit" disabled={disabled} className={PRIMARY_BUTTON}>
-          {submitting ? (
-            <Spinner />
-          ) : (
-            <ArrowUturnLeftIcon
-              className="size-3.5 -scale-x-100"
-              aria-hidden="true"
-            />
-          )}
-          {submitLabel}
-        </button>
-      </div>
-      <p className="text-xs text-fg-muted">
-        Press <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">Enter</kbd> to
-        send · <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">Shift</kbd>+
-        <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">Enter</kbd> for a new line
-      </p>
-    </form>
+    <DockComposer
+      onSubmit={(text) => onSubmit({ kind: "text", text })}
+      placeholder={placeholder}
+      submitLabel="Send"
+      pending={submitting}
+      ariaLabel="Interview answer"
+    />
   );
 }
 
@@ -482,27 +433,6 @@ function OptionLabel({ option }: { option: InterviewOption }) {
   );
 }
 
-function Spinner() {
-  return <ArrowPathIcon className="size-4 animate-spin" aria-hidden="true" />;
-}
-
-function questionTypeLabel(type: QuestionType): string {
-  switch (type) {
-    case QuestionType.YES_NO:
-      return "Yes or no";
-    case QuestionType.CONFIRMATION:
-      return "Confirmation required";
-    case QuestionType.MULTIPLE_CHOICE:
-      return "Pick one";
-    case QuestionType.MULTI_SELECT:
-      return "Pick one or more";
-    case QuestionType.FREEFORM:
-      return "Freeform response";
-    default:
-      return "";
-  }
-}
-
 function interviewSubmitErrorMessage(error: unknown): string {
   if (error instanceof ApiError) {
     return error.requestId
diff --git a/apps/fabro-web/app/components/run-dock.tsx b/apps/fabro-web/app/components/run-dock.tsx
new file mode 100644
index 000000000..ab684522b
--- /dev/null
+++ b/apps/fabro-web/app/components/run-dock.tsx
@@ -0,0 +1,300 @@
+import {
+  useId,
+  useState,
+  type FormEvent,
+  type KeyboardEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import {
+  ArrowPathIcon,
+  ArrowUturnLeftIcon,
+  ChevronUpIcon,
+} from "@heroicons/react/20/solid";
+
+/**
+ * Shared chrome for the two controls docked at the bottom of the run detail
+ * route: the interview question panel and the steering composer.
+ *
+ * The shell is three zones. The header is always visible and doubles as the
+ * collapsed bar. The body scrolls. The actions stay pinned, so the controls
+ * needed to answer or send never scroll out of reach.
+ *
+ * Collapsed state is owned by the caller. Each dock has its own rule for when
+ * a collapsed panel must reopen — a new question for the interview, a run
+ * waiting for steering for the composer — and those rules are clearer next to
+ * the state they depend on.
+ */
+
+/** Ceiling on the expanded dock, so a long body cannot take the page. */
+const DOCK_MAX_HEIGHT = "max-h-[60vh]";
+
+/** Pinned actions never take more than half the dock. */
+const ACTIONS_MAX_HEIGHT = "max-h-[50%]";
+
+export const DOCK_HEADER_BUTTON =
+  "inline-flex shrink-0 items-center gap-1.5 rounded-md bg-overlay px-2 py-1 text-xs font-medium text-fg-2 outline-1 -outline-offset-1 outline-line-strong transition-colors hover:bg-overlay-strong hover:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-overlay disabled:hover:text-fg-2";
+
+export const DOCK_PRIMARY_BUTTON =
+  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-teal-500 px-3.5 py-2 text-sm font-medium text-on-primary transition-colors hover:bg-teal-300 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-teal-500";
+
+export const DOCK_CHOICE_BUTTON =
+  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-overlay px-3.5 py-2 text-left text-sm font-medium text-fg-2 outline-1 -outline-offset-1 outline-line-strong transition-colors hover:bg-overlay-strong hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60";
+
+export const DOCK_CHOICE_BUTTON_SELECTED =
+  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-teal-500/15 px-3.5 py-2 text-left text-sm font-medium text-fg outline-1 -outline-offset-1 outline-teal-500/60 transition-colors hover:bg-teal-500/20 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500";
+
+/**
+ * How the dock signals its state.
+ *
+ * - `waiting` pulses amber: the run is blocked on the operator, as expected.
+ * - `alert` pulses amber and colors the label too, for a run that went off
+ *   its normal path and is stuck until someone acts.
+ * - `idle` is a resting control with no pending demand.
+ */
+export type DockTone = "waiting" | "alert" | "idle";
+
+export interface RunDockShellProps {
+  /** Accessible name for the docked region. */
+  label: string;
+  tone: DockTone;
+  /** Short state phrase, e.g. "Awaiting input". */
+  status: string;
+  /** Stage name shown in mono beside the status. */
+  stage?: string | null;
+  /** One-line summary shown only while collapsed. */
+  peek?: string | null;
+  /** Run-level controls, rendered beside the collapse toggle. */
+  headerActions?: ReactNode;
+  /** Scrolling zone. Omit when there is nothing to scroll. */
+  body?: ReactNode;
+  /** Pinned zone. */
+  actions: ReactNode;
+  collapsed: boolean;
+  onCollapsedChange: (collapsed: boolean) => void;
+}
+
+export function RunDockShell({
+  label,
+  tone,
+  status,
+  stage,
+  peek,
+  headerActions,
+  body,
+  actions,
+  collapsed,
+  onCollapsedChange,
+}: RunDockShellProps) {
+  const contentId = useId();
+
+  return (
+    <section
+      aria-label={label}
+      className={`flex flex-col ${collapsed ? "" : DOCK_MAX_HEIGHT}`}
+    >
+      <div className="flex shrink-0 items-center gap-2.5 px-5 py-2 sm:px-6">
+        <StatusDot tone={tone} />
+        {/* A live region: the dock changing to a state that needs the
+            operator has to reach assistive tech, not only the eye. */}
+        <span
+          role="status"
+          className={`shrink-0 text-sm font-medium ${
+            tone === "alert" ? "text-amber" : "text-fg-2"
+          }`}
+        >
+          {status}
+        </span>
+        {stage && (
+          <>
+            <span className="shrink-0 text-fg-muted" aria-hidden="true">
+              ·
+            </span>
+            <span className="min-w-0 truncate font-mono text-xs text-fg-3">
+              {stage}
+            </span>
+          </>
+        )}
+        {collapsed && peek ? (
+          <span className="min-w-0 flex-1 truncate text-sm text-fg-3">
+            · {peek}
+          </span>
+        ) : (
+          <span className="flex-1" />
+        )}
+        {headerActions}
+        <button
+          type="button"
+          onClick={() => onCollapsedChange(!collapsed)}
+          aria-expanded={!collapsed}
+          aria-controls={contentId}
+          aria-label={collapsed ? `Expand ${label}` : `Collapse ${label}`}
+          className="inline-flex size-6.5 shrink-0 items-center justify-center rounded-md text-fg-3 transition-colors hover:bg-overlay hover:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
+        >
+          <ChevronUpIcon
+            className={`size-4 transition-transform duration-200 ease-[cubic-bezier(0.16,1,0.3,1)] ${
+              collapsed ? "rotate-180" : ""
+            }`}
+            aria-hidden="true"
+          />
+        </button>
+      </div>
+
+      {/* Hidden rather than unmounted, so a half-written message survives a
+          collapse. The display utility is swapped rather than layered, so two
+          display classes cannot collide in the cascade. */}
+      <div
+        id={contentId}
+        className={
+          collapsed ? "hidden" : "flex min-h-0 flex-1 flex-col"
+        }
+      >
+        {body && (
+          <div className="min-h-0 flex-1 space-y-3 overflow-y-auto border-t border-line px-5 pt-3.5 pb-1 sm:px-6">
+            {body}
+          </div>
+        )}
+        <div
+          className={`flex shrink-0 flex-col gap-2.5 overflow-y-auto px-5 pt-2.5 pb-3.5 sm:px-6 ${ACTIONS_MAX_HEIGHT} ${
+            body ? "" : "border-t border-line"
+          }`}
+        >
+          {actions}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function StatusDot({ tone }: { tone: DockTone }) {
+  if (tone === "idle") {
+    return (
+      <span
+        className="size-2 shrink-0 rounded-full bg-fg-muted"
+        aria-hidden="true"
+      />
+    );
+  }
+  return (
+    <span
+      className="relative flex size-2 shrink-0 items-center justify-center"
+      aria-hidden="true"
+    >
+      <span className="absolute inline-flex size-full animate-ping rounded-full bg-amber/60" />
+      <span className="relative inline-flex size-2 rounded-full bg-amber" />
+    </span>
+  );
+}
+
+export function DockSpinner() {
+  return <ArrowPathIcon className="size-4 animate-spin" aria-hidden="true" />;
+}
+
+export interface DockComposerProps {
+  /**
+   * Sends the trimmed text. Resolve `true` to clear the box; resolve `false`
+   * to keep what the operator typed, so a failed send is not lost.
+   */
+  onSubmit: (text: string) => Promise<boolean>;
+  placeholder: string;
+  submitLabel: string;
+  pendingLabel?: string;
+  pending: boolean;
+  ariaLabel: string;
+  maxLength?: number;
+  textareaRef?: Ref<HTMLTextAreaElement>;
+}
+
+/**
+ * The single composer used by both docks: the interview's freeform answer and
+ * the steering message. Enter sends, Shift+Enter breaks the line, and the
+ * hint for that only appears on focus — inside the row, so revealing it does
+ * not shift the layout.
+ */
+export function DockComposer({
+  onSubmit,
+  placeholder,
+  submitLabel,
+  pendingLabel,
+  pending,
+  ariaLabel,
+  maxLength,
+  textareaRef,
+}: DockComposerProps) {
+  const [value, setValue] = useState("");
+  const fieldId = useId();
+  const trimmed = value.trim();
+  const canSend = trimmed.length > 0 && !pending;
+
+  async function send() {
+    if (!canSend) return;
+    const cleared = await onSubmit(trimmed);
+    if (cleared) setValue("");
+  }
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    void send();
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>) {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      void send();
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="group flex items-end gap-2">
+      <label className="sr-only" htmlFor={fieldId}>
+        {ariaLabel}
+      </label>
+      <textarea
+        id={fieldId}
+        ref={textareaRef}
+        name="answer"
+        aria-label={ariaLabel}
+        rows={1}
+        value={value}
+        maxLength={maxLength}
+        onChange={(event) => setValue(event.target.value)}
+        onKeyDown={handleKeyDown}
+        placeholder={placeholder}
+        disabled={pending}
+        className="block w-full resize-none rounded-lg bg-panel-alt px-3.5 py-2.5 text-base/6 text-fg outline-1 -outline-offset-1 outline-line-strong placeholder:text-fg-muted focus:outline-2 focus:-outline-offset-1 focus:outline-teal-500 disabled:opacity-60 sm:text-sm/5"
+      />
+      <p
+        aria-hidden="true"
+        className="pointer-events-none flex shrink-0 items-center gap-1 pb-2.5 text-xs whitespace-nowrap text-fg-muted opacity-0 transition-opacity group-focus-within:opacity-100"
+      >
+        <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">
+          Enter
+        </kbd>
+        send
+        <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">
+          Shift
+        </kbd>
+        +
+        <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">
+          Enter
+        </kbd>
+        newline
+      </p>
+      <button
+        type="submit"
+        disabled={!canSend}
+        className={DOCK_PRIMARY_BUTTON}
+      >
+        {pending ? (
+          <DockSpinner />
+        ) : (
+          <ArrowUturnLeftIcon
+            className="size-3.5 -scale-x-100"
+            aria-hidden="true"
+          />
+        )}
+        {pending && pendingLabel ? pendingLabel : submitLabel}
+      </button>
+    </form>
+  );
+}
diff --git a/apps/fabro-web/app/components/steer-bar.test.tsx b/apps/fabro-web/app/components/steer-bar.test.tsx
index 33fefa556..a9c74714c 100644
--- a/apps/fabro-web/app/components/steer-bar.test.tsx
+++ b/apps/fabro-web/app/components/steer-bar.test.tsx
@@ -1,22 +1,28 @@
 import { describe, expect, test } from "bun:test";
-import { createElement } from "react";
-import { renderToStaticMarkup } from "react-dom/server";
 
 import {
   isInterruptDisabled,
-  SteerWaitingStatus,
+  isSteerDockCollapsed,
+  steerStatusLabel,
 } from "./steer-bar";
 
 describe("SteerBar", () => {
-  test("shows durable waiting state and prevents a second interrupt", () => {
+  test("prevents a second interrupt while one is in flight or already settled", () => {
     expect(isInterruptDisabled(true, false)).toBe(true);
     expect(isInterruptDisabled(false, true)).toBe(true);
     expect(isInterruptDisabled(false, false)).toBe(false);
+  });
 
-    const html = renderToStaticMarkup(
-      createElement(SteerWaitingStatus, { waitingForSteer: true }),
-    );
-    expect(html).toContain('role="status"');
-    expect(html).toContain("Interrupted — waiting for steering");
+  test("names the durable waiting state in the dock header", () => {
+    expect(steerStatusLabel(true)).toBe("Interrupted — waiting for steering");
+    expect(steerStatusLabel(false)).toBe("Steering");
+  });
+
+  test("reopens the dock while the run waits for steering", () => {
+    expect(isSteerDockCollapsed(true, false)).toBe(true);
+    expect(isSteerDockCollapsed(false, false)).toBe(false);
+    // Collapsing cannot hide a run that is blocked on the operator.
+    expect(isSteerDockCollapsed(true, true)).toBe(false);
+    expect(isSteerDockCollapsed(false, true)).toBe(false);
   });
 });
diff --git a/apps/fabro-web/app/components/steer-bar.tsx b/apps/fabro-web/app/components/steer-bar.tsx
index b78a62f92..7c229d77f 100644
--- a/apps/fabro-web/app/components/steer-bar.tsx
+++ b/apps/fabro-web/app/components/steer-bar.tsx
@@ -2,15 +2,21 @@ import {
   useImperativeHandle,
   useRef,
   useState,
-  type FormEvent,
-  type KeyboardEvent,
   type Ref,
 } from "react";
+import { StopIcon } from "@heroicons/react/20/solid";
 
 import { ApiError } from "../lib/api-client";
 import { useInterruptRun, useSteerRun } from "../lib/mutations";
+import {
+  DockComposer,
+  RunDockShell,
+  DOCK_HEADER_BUTTON,
+} from "./run-dock";
 import { ErrorMessage } from "./ui";
 
+const STEER_MAX_LENGTH = 8192;
+
 export interface SteerBarProps {
   runId: string;
   waitingForSteer?: boolean;
@@ -28,17 +34,20 @@ export function isInterruptDisabled(
   return waitingForSteer || mutationPending;
 }
 
-export function SteerWaitingStatus({
-  waitingForSteer,
-}: {
-  waitingForSteer: boolean;
-}) {
-  if (!waitingForSteer) return null;
-  return (
-    <p role="status" className="mt-2 text-xs text-amber">
-      Interrupted — waiting for steering
-    </p>
-  );
+/**
+ * A run that is waiting for steering needs the operator, so the dock reopens
+ * itself and stays open until the wait clears. Derived rather than stored, so
+ * collapsing during the wait cannot hide the prompt.
+ */
+export function isSteerDockCollapsed(
+  collapsePreferred: boolean,
+  waitingForSteer: boolean,
+): boolean {
+  return collapsePreferred && !waitingForSteer;
+}
+
+export function steerStatusLabel(waitingForSteer: boolean): string {
+  return waitingForSteer ? "Interrupted — waiting for steering" : "Steering";
 }
 
 export function SteerBar({
@@ -46,13 +55,14 @@ export function SteerBar({
   waitingForSteer = false,
   ref,
 }: SteerBarProps) {
-  const [text, setText] = useState("");
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [collapsePreferred, setCollapsePreferred] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement | null>(null);
   const steer = useSteerRun(runId);
   const interrupt = useInterruptRun(runId);
   const pending = steer.isMutating || interrupt.isMutating;
   const interruptDisabled = isInterruptDisabled(waitingForSteer, pending);
+  const collapsed = isSteerDockCollapsed(collapsePreferred, waitingForSteer);
 
   useImperativeHandle(ref, () => ({
     focus() {
@@ -60,17 +70,14 @@ export function SteerBar({
     },
   }));
 
-  const trimmed = text.trim();
-  const canSend = trimmed.length > 0 && !pending;
-
-  async function sendSteering() {
-    if (!canSend) return;
+  async function sendSteering(text: string) {
     setErrorMessage(null);
     try {
-      await steer.trigger({ text: trimmed, interrupt: false });
-      setText("");
+      await steer.trigger({ text, interrupt: false });
+      return true;
     } catch (err) {
       setErrorMessage(formatSteerError(err));
+      return false;
     }
   }
 
@@ -84,59 +91,43 @@ export function SteerBar({
     }
   }
 
-  function handleSubmit(e: FormEvent) {
-    e.preventDefault();
-    void sendSteering();
-  }
-
-  function handleKeyDown(e: KeyboardEvent<HTMLTextAreaElement>) {
-    if (e.key === "Enter" && !e.shiftKey) {
-      e.preventDefault();
-      void sendSteering();
-    }
-  }
-
   return (
-    <form
-      onSubmit={handleSubmit}
-      aria-label="Steer running agent"
-      className="mx-auto max-w-4xl px-4 py-3 sm:px-6 lg:px-8"
-    >
-      <div className="flex items-end gap-2">
-        <textarea
-          ref={textareaRef}
-          value={text}
-          onChange={(e) => setText(e.target.value)}
-          onKeyDown={handleKeyDown}
-          placeholder="Steer the agent…"
-          rows={1}
-          maxLength={8192}
-          aria-label="Steering message"
-          className="flex-1 resize-none rounded-md bg-overlay px-3 py-2 text-sm text-fg outline-1 -outline-offset-1 outline-line-strong placeholder:text-fg-muted focus:outline-2 focus:-outline-offset-1 focus:outline-teal-500"
-        />
+    <RunDockShell
+      label="Steer running agent"
+      tone={waitingForSteer ? "alert" : "idle"}
+      status={steerStatusLabel(waitingForSteer)}
+      peek="Send a message to the running agent"
+      collapsed={collapsed}
+      onCollapsedChange={setCollapsePreferred}
+      headerActions={
+        // Interrupt acts on the run, not on the message being composed, so it
+        // sits with the other run-level controls instead of in the composer.
         <button
           type="button"
           onClick={() => void fireInterrupt()}
           disabled={interruptDisabled}
-          className="inline-flex shrink-0 items-center gap-2 rounded-md bg-overlay px-3 py-2 text-sm font-medium text-amber outline-1 -outline-offset-1 outline-amber/40 transition-colors hover:bg-amber/15 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-amber disabled:cursor-not-allowed disabled:opacity-60"
+          className={`${DOCK_HEADER_BUTTON} text-amber outline-amber/40 hover:bg-amber/15 hover:text-amber focus-visible:outline-amber disabled:hover:bg-overlay disabled:hover:text-amber`}
         >
+          <StopIcon className="size-3" aria-hidden="true" />
           {interrupt.isMutating ? "Interrupting…" : "Interrupt"}
         </button>
-        <button
-          type="submit"
-          disabled={!canSend}
-          className="inline-flex shrink-0 items-center justify-center rounded-md bg-teal-500 px-4 py-2 text-sm font-medium text-on-primary transition-colors hover:bg-teal-300 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-teal-500"
-        >
-          {steer.isMutating ? "Sending…" : "Send"}
-        </button>
-      </div>
-      {errorMessage && (
-        <div className="mt-2">
-          <ErrorMessage message={errorMessage} />
-        </div>
-      )}
-      <SteerWaitingStatus waitingForSteer={waitingForSteer} />
-    </form>
+      }
+      actions={
+        <>
+          <DockComposer
+            onSubmit={sendSteering}
+            placeholder="Steer the agent…"
+            submitLabel="Send"
+            pendingLabel="Sending…"
+            pending={pending}
+            ariaLabel="Steering message"
+            maxLength={STEER_MAX_LENGTH}
+            textareaRef={textareaRef}
+          />
+          {errorMessage && <ErrorMessage message={errorMessage} />}
+        </>
+      }
+    />
   );
 }
 
diff --git a/apps/fabro-web/app/routes/run-detail.test.ts b/apps/fabro-web/app/routes/run-detail.test.ts
index 997f8457b..6abd07b4f 100644
--- a/apps/fabro-web/app/routes/run-detail.test.ts
+++ b/apps/fabro-web/app/routes/run-detail.test.ts
@@ -841,7 +841,7 @@ describe("RunDetail full-height child routes", () => {
     });
 
     const statuses = renderer.root.findAll(
-      (node) => node.type === "p" && node.props.role === "status",
+      (node) => node.props.role === "status",
     );
     expect(statuses.map(textFromTestNode)).toContain(
       "Interrupted — waiting for steering",
diff --git a/apps/fabro-web/app/routes/run-detail.tsx b/apps/fabro-web/app/routes/run-detail.tsx
index 97ce00702..02e55ff3c 100644
--- a/apps/fabro-web/app/routes/run-detail.tsx
+++ b/apps/fabro-web/app/routes/run-detail.tsx
@@ -102,6 +102,7 @@ export default function RunDetail({ params }: { params: { id: string } }) {
   const { mutate } = useSWRConfig();
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
   const [deletePending, setDeletePending] = useState(false);
+  const [dockHeight, setDockHeight] = useState<number | null>(null);
   const { push, dismiss } = useToast();
   const lifecycleToastStateRef = useRef(createLifecycleToastState());
   const filesCount = runQuery.data?.diff?.files_changed ?? null;
@@ -305,7 +306,16 @@ export default function RunDetail({ params }: { params: { id: string } }) {
         : []),
     ],
   };
-  const dockClearance = hasPendingQuestions ? "18rem" : "5rem";
+  // Reserve exactly the dock's rendered height. The constants are only the
+  // first frame, before the dock has been measured; a fixed reservation lets
+  // a tall question panel cover the content it is asking about.
+  const dockVisible = hasPendingQuestions || !hideSteerBar;
+  const dockClearance =
+    dockVisible && dockHeight !== null
+      ? `${dockHeight}px`
+      : hasPendingQuestions
+        ? "18rem"
+        : "5rem";
   const rootStyle = {
     "--fabro-interview-dock-clearance": dockClearance,
   } as CSSProperties;
@@ -372,6 +382,7 @@ export default function RunDetail({ params }: { params: { id: string } }) {
             isResizing={isResizing}
             steerBarRef={steerBarRef}
             waitingForSteer={waitingForSteer}
+            onHeightChange={setDockHeight}
           />
         </div>
       )}
diff --git a/apps/fabro-web/app/routes/run-detail/docked-controls.tsx b/apps/fabro-web/app/routes/run-detail/docked-controls.tsx
index 02ee9a2cb..2b99fab39 100644
--- a/apps/fabro-web/app/routes/run-detail/docked-controls.tsx
+++ b/apps/fabro-web/app/routes/run-detail/docked-controls.tsx
@@ -1,10 +1,13 @@
 import {
+  useRef,
   useState,
   type ReactNode,
   type RefObject,
 } from "react";
 import { SparklesIcon } from "@heroicons/react/20/solid";
 
+import { useResizeObserver } from "../../hooks/effects";
+
 import AskFabroSidebar, {
   SIDEBAR_WIDTH,
 } from "../../components/chats/ask-fabro-sidebar";
@@ -134,6 +137,7 @@ export function RunDetailDockedControls({
   isResizing,
   steerBarRef,
   waitingForSteer,
+  onHeightChange,
 }: {
   runId: string;
   hideSteerBar: boolean;
@@ -143,11 +147,28 @@ export function RunDetailDockedControls({
   isResizing: boolean;
   steerBarRef: RefObject<SteerBarHandle | null>;
   waitingForSteer: boolean;
+  /**
+   * Reports the dock's rendered height so the page can reserve exactly that
+   * much room beneath the scrolling content.
+   */
+  onHeightChange: (height: number | null) => void;
 }) {
-  if (hideSteerBar && !hasPendingQuestions) return null;
+  const dockRef = useRef<HTMLDivElement | null>(null);
+  const visible = hasPendingQuestions || !hideSteerBar;
+
+  // `offsetHeight` rather than the entry's content box: the dock carries a
+  // top border, and the page has to clear the border too.
+  useResizeObserver(
+    dockRef,
+    () => onHeightChange(dockRef.current?.offsetHeight ?? null),
+    visible,
+  );
+
+  if (!visible) return null;
 
   return (
     <div
+      ref={dockRef}
       className={`fixed bottom-0 left-0 z-30 border-t border-line bg-page ${
         isResizing
           ? ""

From 7906af3f3fcafae5f9523adfdcf0b86ffbaa16b5 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 12:50:20 -0400
Subject: [PATCH 17/36] fix(sandbox): reactivate stopped run sandboxes

---
 lib/apps/fabro-server/src/run_files.rs        |  2 +-
 .../src/server/handler/sandbox.rs             |  4 +-
 .../fabro-sandbox/src/daytona/mod.rs          | 63 +++++++++++++++++++
 lib/components/fabro-sandbox/src/docker.rs    | 29 +++++++++
 lib/components/fabro-sandbox/src/local.rs     |  4 ++
 lib/components/fabro-sandbox/src/sandbox.rs   | 12 ++++
 lib/components/fabro-sandbox/src/terminal.rs  |  4 +-
 .../fabro-sandbox/src/test_support.rs         | 17 +++++
 .../fabro-workflow/src/lifecycle/mod.rs       | 21 ++++++-
 .../src/pipeline/execute/tests.rs             | 58 +++++++++++++++++
 10 files changed, 208 insertions(+), 6 deletions(-)

diff --git a/lib/apps/fabro-server/src/run_files.rs b/lib/apps/fabro-server/src/run_files.rs
index 126408e43..920460f79 100644
--- a/lib/apps/fabro-server/src/run_files.rs
+++ b/lib/apps/fabro-server/src/run_files.rs
@@ -1217,7 +1217,7 @@ async fn reconnect_run_sandbox(
         .await
         .map_err(|err| ApiError::new(StatusCode::CONFLICT, err.to_string()))?;
     sandbox
-        .start()
+        .activate()
         .await
         .map_err(|err| ApiError::new(StatusCode::CONFLICT, err.display_with_causes()))?;
     Ok(sandbox)
diff --git a/lib/apps/fabro-server/src/server/handler/sandbox.rs b/lib/apps/fabro-server/src/server/handler/sandbox.rs
index c2027571e..53877c5c9 100644
--- a/lib/apps/fabro-server/src/server/handler/sandbox.rs
+++ b/lib/apps/fabro-server/src/server/handler/sandbox.rs
@@ -881,7 +881,7 @@ async fn reconnect_run_sandbox_instance(
             let detail = render_with_causes(&err.to_string(), &collect_causes(err.as_ref()));
             ApiError::new(StatusCode::CONFLICT, detail).into_response()
         })?;
-    sandbox.start().await.map_err(|err| {
+    sandbox.activate().await.map_err(|err| {
         ApiError::new(StatusCode::CONFLICT, err.display_with_causes()).into_response()
     })?;
     Ok(sandbox)
@@ -927,7 +927,7 @@ async fn reconnect_daytona_sandbox_instance(
     .map_err(|err| {
         ApiError::new(StatusCode::CONFLICT, err.display_with_causes()).into_response()
     })?;
-    sandbox.start().await.map_err(|err| {
+    sandbox.activate().await.map_err(|err| {
         ApiError::new(StatusCode::CONFLICT, err.display_with_causes()).into_response()
     })?;
     Ok(sandbox)
diff --git a/lib/components/fabro-sandbox/src/daytona/mod.rs b/lib/components/fabro-sandbox/src/daytona/mod.rs
index 292cc3ebe..c4e01e6ff 100644
--- a/lib/components/fabro-sandbox/src/daytona/mod.rs
+++ b/lib/components/fabro-sandbox/src/daytona/mod.rs
@@ -9,6 +9,7 @@ use anyhow::Context as _;
 use async_trait::async_trait;
 use daytona_api_client::apis::api_keys_api;
 use daytona_api_client::apis::configuration::Configuration;
+use daytona_api_client::models::SandboxState;
 use daytona_api_client::models::api_key_list::Permissions;
 use daytona_sdk::api_types::SignedPortPreviewUrl;
 use daytona_sdk::toolbox_types::Command as SessionCommandResult;
@@ -1367,6 +1368,17 @@ impl Sandbox for DaytonaSandbox {
         Ok(())
     }
 
+    async fn activate(&self) -> crate::Result<()> {
+        let sandbox = self.sandbox()?;
+        let current = self.client.get(&sandbox.name).await.map_err(|e| {
+            crate::Error::context("Failed to inspect Daytona sandbox before activation", e)
+        })?;
+        if current.state == Some(SandboxState::Started) {
+            return Ok(());
+        }
+        self.start().await
+    }
+
     async fn stop(&self) -> crate::Result<()> {
         self.emit(SandboxEvent::StopStarted {
             provider: "daytona".into(),
@@ -2628,6 +2640,25 @@ mod tests {
         })
     }
 
+    fn sandbox_body(name: &str, state: &str) -> serde_json::Value {
+        serde_json::json!({
+            "id": name,
+            "organizationId": "org-1",
+            "name": name,
+            "user": "daytona",
+            "env": {},
+            "labels": {},
+            "public": false,
+            "networkBlockAll": false,
+            "target": "us",
+            "cpu": 2.0,
+            "gpu": 0.0,
+            "memory": 4.0,
+            "disk": 20.0,
+            "state": state
+        })
+    }
+
     #[test]
     fn daytona_config_defaults() {
         let config = DaytonaConfig::default();
@@ -2783,6 +2814,38 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn activate_skips_start_when_daytona_reports_started() {
+        let server = MockServer::start_async().await;
+        let get_sandbox = server
+            .mock_async(|when, then| {
+                when.method(GET)
+                    .path("/sandbox/test-sandbox")
+                    .header("authorization", "Bearer dtn_test");
+                then.status(200)
+                    .header("content-type", "application/json")
+                    .json_body(sandbox_body("test-sandbox", "started"));
+            })
+            .await;
+        let sandbox = mock_daytona_sandbox(&server, "dtn_test", DaytonaConfig::default()).await;
+        let sdk_sandbox = sandbox
+            .client
+            .get("test-sandbox")
+            .await
+            .expect("test sandbox should load");
+        sandbox
+            .sandbox
+            .set(sdk_sandbox)
+            .expect("test sandbox should initialize once");
+
+        sandbox
+            .activate()
+            .await
+            .expect("an active sandbox should require no restart");
+
+        get_sandbox.assert_calls_async(2).await;
+    }
+
     #[tokio::test]
     async fn base_params_merges_managed_daytona_labels() {
         let run_id: RunId = "01HY0000000000000000000000".parse().unwrap();
diff --git a/lib/components/fabro-sandbox/src/docker.rs b/lib/components/fabro-sandbox/src/docker.rs
index fb9b7df9c..9a9bdaa08 100644
--- a/lib/components/fabro-sandbox/src/docker.rs
+++ b/lib/components/fabro-sandbox/src/docker.rs
@@ -1461,6 +1461,35 @@ impl Sandbox for DockerSandbox {
         Ok(())
     }
 
+    async fn activate(&self) -> crate::Result<()> {
+        let container_id = self.container_id()?.to_string();
+        let inspect = self
+            .docker
+            .inspect_container(&container_id, None::<InspectContainerOptions>)
+            .await
+            .map_err(|e| {
+                if docker_not_found(&e) {
+                    crate::Error::message(format!("Docker container '{container_id}' is gone"))
+                } else {
+                    crate::Error::message(format!(
+                        "Failed to inspect Docker container '{container_id}': {e}"
+                    ))
+                }
+            })?;
+        let labels = inspect
+            .config
+            .and_then(|config| config.labels)
+            .unwrap_or_default();
+        verify_managed_labels(&container_id, &labels, self.run_id.as_ref())?;
+        let active = inspect
+            .state
+            .is_some_and(|state| state.running == Some(true) && state.paused != Some(true));
+        if active {
+            return Ok(());
+        }
+        self.start().await
+    }
+
     async fn stop(&self) -> crate::Result<()> {
         self.emit(SandboxEvent::StopStarted {
             provider: "docker".into(),
diff --git a/lib/components/fabro-sandbox/src/local.rs b/lib/components/fabro-sandbox/src/local.rs
index 2da5a788e..6af6c4e8d 100644
--- a/lib/components/fabro-sandbox/src/local.rs
+++ b/lib/components/fabro-sandbox/src/local.rs
@@ -835,6 +835,10 @@ impl Sandbox for LocalSandbox {
         result
     }
 
+    async fn activate(&self) -> crate::Result<()> {
+        Ok(())
+    }
+
     async fn git_push_ref(&self, refspec: &str) -> crate::Result<()> {
         let has_origin = match self
             .exec_command("git remote get-url origin", 10_000, None, None, None)
diff --git a/lib/components/fabro-sandbox/src/sandbox.rs b/lib/components/fabro-sandbox/src/sandbox.rs
index fee0c6c02..90fdd9bcb 100644
--- a/lib/components/fabro-sandbox/src/sandbox.rs
+++ b/lib/components/fabro-sandbox/src/sandbox.rs
@@ -250,6 +250,10 @@ macro_rules! delegate_sandbox {
                 self.$field.initialize().await
             }
 
+            async fn activate(&self) -> $crate::Result<()> {
+                self.$field.activate().await
+            }
+
             async fn start(&self) -> $crate::Result<()> {
                 self.$field.start().await
             }
@@ -1130,6 +1134,14 @@ pub trait Sandbox: Send + Sync {
         remote_path: &str,
     ) -> crate::Result<()>;
     async fn initialize(&self) -> crate::Result<()>;
+    /// Ensure the sandbox is active and ready for ordinary operations.
+    ///
+    /// This access-time operation must be idempotent. Providers that can stop
+    /// independently should avoid restarting an already-active sandbox. This
+    /// method does not keep a sandbox active between calls.
+    async fn activate(&self) -> crate::Result<()> {
+        self.start().await
+    }
     async fn start(&self) -> crate::Result<()> {
         Ok(())
     }
diff --git a/lib/components/fabro-sandbox/src/terminal.rs b/lib/components/fabro-sandbox/src/terminal.rs
index 44081f9bb..f8df8aa2a 100644
--- a/lib/components/fabro-sandbox/src/terminal.rs
+++ b/lib/components/fabro-sandbox/src/terminal.rs
@@ -64,7 +64,7 @@ pub async fn open_terminal_for_run(
                 runtime.clone_branch.clone(),
             )
             .await?;
-            sandbox.start().await?;
+            sandbox.activate().await?;
             let api_key = resolve_daytona_api_key(daytona_api_key)?;
             let organization_id = resolve_daytona_organization_id(daytona_organization_id);
             let session = DaytonaTerminalSession::open(
@@ -95,7 +95,7 @@ pub async fn open_terminal_for_run(
                 run_id,
             )
             .await?;
-            sandbox.start().await?;
+            sandbox.activate().await?;
             let session = DockerTerminalSession::open(&sandbox, size).await?;
             Ok(Box::new(session))
         }
diff --git a/lib/components/fabro-sandbox/src/test_support.rs b/lib/components/fabro-sandbox/src/test_support.rs
index 4b62ac20a..a1f9e102b 100644
--- a/lib/components/fabro-sandbox/src/test_support.rs
+++ b/lib/components/fabro-sandbox/src/test_support.rs
@@ -38,6 +38,7 @@ pub struct MockSandbox {
     pub captured_working_dirs: Mutex<Vec<Option<String>>>,
     /// Captures the `env_vars` argument from `exec_command` calls.
     pub captured_env_vars:     Mutex<Option<HashMap<String, String>>>,
+    pub activate_calls:        Mutex<u32>,
     pub start_calls:           Mutex<u32>,
     pub stop_calls:            Mutex<u32>,
     pub delete_calls:          Mutex<u32>,
@@ -70,6 +71,13 @@ impl MockSandbox {
         *self.start_calls.lock().expect("start_calls lock poisoned")
     }
 
+    pub fn activate_count(&self) -> u32 {
+        *self
+            .activate_calls
+            .lock()
+            .expect("activate_calls lock poisoned")
+    }
+
     pub fn stop_count(&self) -> u32 {
         *self.stop_calls.lock().expect("stop_calls lock poisoned")
     }
@@ -132,6 +140,7 @@ impl Default for MockSandbox {
             captured_commands:     Mutex::new(Vec::new()),
             captured_working_dirs: Mutex::new(Vec::new()),
             captured_env_vars:     Mutex::new(None),
+            activate_calls:        Mutex::new(0),
             start_calls:           Mutex::new(0),
             stop_calls:            Mutex::new(0),
             delete_calls:          Mutex::new(0),
@@ -444,6 +453,14 @@ impl Sandbox for MockSandbox {
         Ok(())
     }
 
+    async fn activate(&self) -> crate::Result<()> {
+        *self
+            .activate_calls
+            .lock()
+            .expect("activate_calls lock poisoned") += 1;
+        self.start().await
+    }
+
     async fn start(&self) -> crate::Result<()> {
         *self.start_calls.lock().expect("start_calls lock poisoned") += 1;
         Ok(())
diff --git a/lib/components/fabro-workflow/src/lifecycle/mod.rs b/lib/components/fabro-workflow/src/lifecycle/mod.rs
index 751c20842..cf442f497 100644
--- a/lib/components/fabro-workflow/src/lifecycle/mod.rs
+++ b/lib/components/fabro-workflow/src/lifecycle/mod.rs
@@ -13,7 +13,7 @@ use std::sync::{Arc, Mutex};
 use std::time::Instant;
 
 use async_trait::async_trait;
-use fabro_core::error::Result as CoreResult;
+use fabro_core::error::{Error as CoreError, Result as CoreResult};
 use fabro_core::graph::NodeSpec;
 use fabro_core::lifecycle::{
     AttemptContext, AttemptResultContext, EdgeContext, EdgeDecision, NodeDecision, RunLifecycle,
@@ -60,6 +60,7 @@ pub(crate) struct WorkflowLifecycle {
     circuit_breaker:       Arc<CircuitBreakerLifecycle>,
     git:                   GitLifecycle,
     artifact:              ArtifactLifecycle,
+    sandbox:               Arc<dyn Sandbox>,
     on_node:               crate::OnNodeCallback,
     emitter:               Arc<Emitter>,
     run_control:           Option<Arc<RunControlState>>,
@@ -190,6 +191,7 @@ impl WorkflowLifecycle {
             circuit_breaker,
             git,
             artifact,
+            sandbox: Arc::clone(sandbox),
             on_node,
             emitter: Arc::clone(emitter),
             run_control,
@@ -280,6 +282,14 @@ impl RunLifecycle<WorkflowGraph> for WorkflowLifecycle {
         if let Some(run_control) = &self.run_control {
             run_control.wait_if_paused(self.emitter.as_ref()).await;
         }
+        // A provider may auto-stop while the run is paused between nodes.
+        self.sandbox.activate().await.map_err(|err| {
+            CoreError::Other(format!(
+                "failed to activate sandbox before node {:?}: {}",
+                node.id(),
+                err.display_with_causes()
+            ))
+        })?;
         if let Some(on_node) = &self.on_node {
             on_node(node.id());
         }
@@ -330,6 +340,15 @@ impl RunLifecycle<WorkflowGraph> for WorkflowLifecycle {
         if let Some(run_control) = &self.run_control {
             run_control.wait_if_paused(self.emitter.as_ref()).await;
         }
+        // Human, wait, and paused stages can return after a long period with
+        // no sandbox traffic. Reactivate before artifact and checkpoint work.
+        self.sandbox.activate().await.map_err(|err| {
+            CoreError::Other(format!(
+                "failed to activate sandbox after node attempt {:?}: {}",
+                ctx.node.id(),
+                err.display_with_causes()
+            ))
+        })?;
         self.artifact.after_attempt(ctx, state).await?;
         self.event.after_attempt(ctx, state).await?;
         Ok(())
diff --git a/lib/components/fabro-workflow/src/pipeline/execute/tests.rs b/lib/components/fabro-workflow/src/pipeline/execute/tests.rs
index 2322e6b71..6807277e8 100644
--- a/lib/components/fabro-workflow/src/pipeline/execute/tests.rs
+++ b/lib/components/fabro-workflow/src/pipeline/execute/tests.rs
@@ -16,6 +16,7 @@ use fabro_graphviz::graph::{AttrValue, Edge, Graph, Node};
 use fabro_hooks::HookSettings;
 use fabro_interview::AutoApproveInterviewer;
 use fabro_sandbox::SandboxSpec;
+use fabro_sandbox::test_support::MockSandbox;
 use fabro_store::Database;
 use fabro_types::settings::run::RunModelControls;
 use fabro_types::{
@@ -647,6 +648,31 @@ impl HandlerTrait for SlowHandler {
     }
 }
 
+struct StopsSandboxHandler {
+    sandbox:                   Arc<MockSandbox>,
+    observed_activation_count: Arc<AtomicU32>,
+}
+
+#[async_trait]
+impl HandlerTrait for StopsSandboxHandler {
+    async fn execute(
+        &self,
+        _node: &Node,
+        _context: &Context,
+        _graph: &Graph,
+        _run_dir: &Path,
+        _services: &crate::handler::EngineServices,
+    ) -> std::result::Result<Outcome, Error> {
+        self.observed_activation_count
+            .store(self.sandbox.activate_count(), Ordering::Relaxed);
+        self.sandbox
+            .stop()
+            .await
+            .map_err(|err| Error::handler_with_source("failed to stop test sandbox", err))?;
+        Ok(Outcome::success())
+    }
+}
+
 struct PanickingHandler;
 
 #[async_trait]
@@ -802,6 +828,38 @@ async fn execute_runs_simple_workflow() {
     assert_eq!(outcome.status, StageOutcome::Succeeded);
 }
 
+#[tokio::test]
+async fn execute_reactivates_sandbox_after_a_stage_can_leave_it_stopped() {
+    let dir = tempfile::tempdir().unwrap();
+    let sandbox = Arc::new(MockSandbox::linux());
+    let observed_activation_count = Arc::new(AtomicU32::new(0));
+    let mut registry = make_registry();
+    registry.register(
+        "start",
+        Box::new(StopsSandboxHandler {
+            sandbox:                   Arc::clone(&sandbox),
+            observed_activation_count: Arc::clone(&observed_activation_count),
+        }),
+    );
+    let sandbox_for_run: Arc<dyn Sandbox> = sandbox.clone();
+
+    let outcome = run_graph(
+        registry,
+        test_emitter_arc("test-run"),
+        sandbox_for_run,
+        &simple_graph(),
+        &test_run_options(dir.path(), "test-run"),
+    )
+    .await
+    .unwrap();
+
+    assert_eq!(outcome.status, StageOutcome::Succeeded);
+    assert_eq!(observed_activation_count.load(Ordering::Relaxed), 1);
+    assert_eq!(sandbox.stop_count(), 1);
+    assert_eq!(sandbox.activate_count(), 2);
+    assert_eq!(sandbox.start_count(), 2);
+}
+
 #[tokio::test]
 async fn execute_saves_checkpoint() {
     let dir = tempfile::tempdir().unwrap();

From 010c8d50c1fefdcc6578d0c3c96bf4b7a1d84dff Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 13:24:12 -0400
Subject: [PATCH 18/36] Add structured review targets to human gates

---
 Cargo.lock                                    |   1 +
 .../app/components/interview-dock.test.tsx    |  53 +++++
 .../app/components/interview-dock.tsx         |   9 +-
 .../app/components/review-target-question.tsx |  76 +++++++
 .../stage-renderers/helpers.test.ts           |  27 +++
 .../app/components/stage-renderers/helpers.ts |  17 +-
 .../components/stage-renderers/human-qa.tsx   |  11 +-
 docs/public/api-reference/fabro-api.yaml      |  39 ++++
 docs/public/execution/context.mdx             |   5 +
 docs/public/reference/dot-language.mdx        |   1 +
 docs/public/workflows/human-in-the-loop.mdx   |  59 +++++
 lib/apps/fabro-cli/src/commands/run/attach.rs |   9 +
 lib/apps/fabro-cli/src/commands/run/runner.rs |   1 +
 lib/apps/fabro-server/src/demo/mod.rs         |   2 +
 lib/apps/fabro-server/src/server.rs           |   3 +
 lib/apps/fabro-server/src/server/tests.rs     |  26 +++
 lib/components/fabro-interview/src/console.rs |  38 ++++
 lib/components/fabro-interview/src/lib.rs     |   6 +-
 lib/components/fabro-slack/src/blocks.rs      |  40 +++-
 lib/components/fabro-store/src/run_state.rs   |  17 ++
 .../tests/serializable_projection.rs          |   1 +
 .../src/rules/inert_attribute.rs              |  20 ++
 lib/components/fabro-workflow/src/context.rs  |   2 +
 .../fabro-workflow/src/event/convert.rs       |   2 +
 .../fabro-workflow/src/event/events.rs        |   9 +-
 .../fabro-workflow/src/handler/human.rs       | 183 ++++++++++++++-
 .../fabro-workflow/src/interview_runtime.rs   |   1 +
 lib/foundation/fabro-api/build.rs             |   2 +
 lib/foundation/fabro-api/src/lib.rs           |  12 +-
 .../interview_question_record_round_trip.rs   |  16 +-
 .../pending_interview_record_round_trip.rs    |   7 +-
 lib/foundation/fabro-types/Cargo.toml         |   1 +
 lib/foundation/fabro-types/src/graph.rs       |   9 +
 lib/foundation/fabro-types/src/interview.rs   | 215 ++++++++++++++++++
 lib/foundation/fabro-types/src/lib.rs         |   4 +-
 .../fabro-types/src/run_event/misc.rs         |   2 +
 .../src/.openapi-generator/FILES              |   2 +
 .../src/models/api-question.ts                |   4 +
 .../fabro-api-client/src/models/index.ts      |   2 +
 .../src/models/interview-question-record.ts   |   4 +
 .../src/models/review-target-kind.ts          |  25 ++
 .../src/models/review-target.ts               |  33 +++
 42 files changed, 974 insertions(+), 22 deletions(-)
 create mode 100644 apps/fabro-web/app/components/review-target-question.tsx
 create mode 100644 lib/packages/fabro-api-client/src/models/review-target-kind.ts
 create mode 100644 lib/packages/fabro-api-client/src/models/review-target.ts

diff --git a/Cargo.lock b/Cargo.lock
index a9b6f681e..d273f55cb 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3258,6 +3258,7 @@ dependencies = [
  "shlex",
  "strum 0.28.0",
  "tempfile",
+ "thiserror 2.0.18",
  "toml 0.8.23",
  "ulid",
  "url",
diff --git a/apps/fabro-web/app/components/interview-dock.test.tsx b/apps/fabro-web/app/components/interview-dock.test.tsx
index 290581690..7120a15f1 100644
--- a/apps/fabro-web/app/components/interview-dock.test.tsx
+++ b/apps/fabro-web/app/components/interview-dock.test.tsx
@@ -4,6 +4,7 @@ import { SWRConfig } from "swr";
 import {
   type ApiQuestion,
   QuestionType,
+  ReviewTargetKind,
 } from "@qltysh/fabro-api-client";
 
 import { InterviewDock } from "./interview-dock";
@@ -74,6 +75,58 @@ describe("InterviewDock", () => {
     expect(text).toContain("Awaiting input");
   });
 
+  test("renders the review target as the link in the question", () => {
+    const url =
+      "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef";
+    const tree = render(
+      <InterviewDock
+        runId="run-1"
+        questions={[
+          makeQuestion({
+            text: "Review the Quarry review exercise document, then choose the next action.",
+            review_target: {
+              label: "Quarry review exercise",
+              url,
+              kind: ReviewTargetKind.DOCUMENT,
+            },
+          }),
+        ]}
+      />,
+    );
+
+    expect(textContent(tree.toJSON())).toContain(
+      "Review the Quarry review exercise document, then choose the next action.",
+    );
+    const links = tree.root.findAllByType("a");
+    expect(links).toHaveLength(1);
+    expect(links[0].props.href).toBe(url);
+    expect(links[0].props.target).toBe("_blank");
+    expect(links[0].props.rel).toBe("noopener noreferrer");
+    expect(links[0].props.referrerPolicy).toBe("no-referrer");
+  });
+
+  test("does not link an unsafe review target received from the API", () => {
+    const fallback = "Review the document, then choose the next action.";
+    const tree = render(
+      <InterviewDock
+        runId="run-1"
+        questions={[
+          makeQuestion({
+            text: fallback,
+            review_target: {
+              label: "Unsafe target",
+              url: "javascript:alert(1)",
+              kind: ReviewTargetKind.DOCUMENT,
+            },
+          }),
+        ]}
+      />,
+    );
+
+    expect(textContent(tree.toJSON())).toContain(fallback);
+    expect(tree.root.findAllByType("a")).toHaveLength(0);
+  });
+
   test("yes/no question shows two buttons", () => {
     const tree = render(
       <InterviewDock runId="run-1" questions={[makeQuestion()]} />,
diff --git a/apps/fabro-web/app/components/interview-dock.tsx b/apps/fabro-web/app/components/interview-dock.tsx
index a2164715a..5012f53c1 100644
--- a/apps/fabro-web/app/components/interview-dock.tsx
+++ b/apps/fabro-web/app/components/interview-dock.tsx
@@ -22,6 +22,7 @@ import {
 } from "../lib/mutations";
 import { ApiError } from "../lib/api-client";
 import { displayLabel } from "./interview-label";
+import { ReviewTargetQuestion } from "./review-target-question";
 import { ErrorMessage } from "./ui";
 
 const PRIMARY_BUTTON =
@@ -99,9 +100,11 @@ function InterviewQuestionDock({
       />
       <div className="space-y-5 px-5 py-4 sm:px-6">
         <div>
-          <p className="text-pretty text-base/6 font-medium text-fg">
-            {question.text}
-          </p>
+          <ReviewTargetQuestion
+            reviewTarget={question.review_target}
+            fallbackText={question.text}
+            className="text-pretty text-base/6 font-medium text-fg"
+          />
           <p className="mt-1 text-xs/5 text-fg-muted">
             {questionTypeLabel(question.question_type)}
           </p>
diff --git a/apps/fabro-web/app/components/review-target-question.tsx b/apps/fabro-web/app/components/review-target-question.tsx
new file mode 100644
index 000000000..99c041923
--- /dev/null
+++ b/apps/fabro-web/app/components/review-target-question.tsx
@@ -0,0 +1,76 @@
+import { ArrowTopRightOnSquareIcon } from "@heroicons/react/20/solid";
+import {
+  ReviewTargetKind,
+  type ReviewTarget,
+} from "@qltysh/fabro-api-client";
+
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/u;
+const UNSAFE_LINK_DELIMITER = /[<>|]/u;
+
+function unicodeScalarCount(value: string): number {
+  return Array.from(value).length;
+}
+
+function hasSafeReviewTarget(target: ReviewTarget | null | undefined): target is ReviewTarget {
+  if (
+    !target ||
+    target.kind !== ReviewTargetKind.DOCUMENT ||
+    !target.label.trim() ||
+    target.label !== target.label.trim() ||
+    unicodeScalarCount(target.label) > 200 ||
+    CONTROL_CHARACTER.test(target.label) ||
+    !target.url ||
+    target.url !== target.url.trim() ||
+    unicodeScalarCount(target.url) > 2048 ||
+    CONTROL_CHARACTER.test(target.url) ||
+    UNSAFE_LINK_DELIMITER.test(target.url)
+  ) {
+    return false;
+  }
+
+  try {
+    const parsed = new URL(target.url);
+    return (
+      (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+      Boolean(parsed.host) &&
+      !parsed.username &&
+      !parsed.password
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function ReviewTargetQuestion({
+  reviewTarget,
+  fallbackText,
+  className,
+}: {
+  reviewTarget: ReviewTarget | null | undefined;
+  fallbackText: string;
+  className?: string;
+}) {
+  if (!hasSafeReviewTarget(reviewTarget)) {
+    return <p className={className}>{fallbackText}</p>;
+  }
+
+  return (
+    <p className={className}>
+      Review the{" "}
+      <a
+        href={reviewTarget.url}
+        target="_blank"
+        rel="noopener noreferrer"
+        referrerPolicy="no-referrer"
+        className="inline-flex items-baseline gap-1 font-semibold text-teal-300 underline decoration-teal-500/50 underline-offset-2 transition-colors hover:text-fg focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
+      >
+        <span>{reviewTarget.label}</span>
+        <ArrowTopRightOnSquareIcon
+          className="size-3 shrink-0 self-center"
+          aria-hidden="true"
+        />
+      </a>{" "}
+      document, then choose the next action.
+    </p>
+  );
+}
diff --git a/apps/fabro-web/app/components/stage-renderers/helpers.test.ts b/apps/fabro-web/app/components/stage-renderers/helpers.test.ts
index 0982cdc99..bec7a4a46 100644
--- a/apps/fabro-web/app/components/stage-renderers/helpers.test.ts
+++ b/apps/fabro-web/app/components/stage-renderers/helpers.test.ts
@@ -98,6 +98,33 @@ describe("parseHumanInterviewPairs", () => {
     });
   });
 
+  test("preserves a typed review target from started events", () => {
+    const events: EventEnvelope[] = [
+      makeEventEnvelope(1, {
+        event: "interview.started",
+        properties: {
+          question_id: "q-1",
+          question:
+            "Review the Quarry review exercise document, then choose the next action.",
+          question_type: "multiple_choice",
+          review_target: {
+            label: "Quarry review exercise",
+            url: "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+            kind: "document",
+          },
+        },
+      }),
+    ];
+
+    const pairs = parseHumanInterviewPairs(events);
+
+    expect(pairs[0].question.reviewTarget).toEqual({
+      label: "Quarry review exercise",
+      url: "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+      kind: "document",
+    });
+  });
+
   test("captures timeout and interrupted resolutions", () => {
     const events: EventEnvelope[] = [
       makeEventEnvelope(1, {
diff --git a/apps/fabro-web/app/components/stage-renderers/helpers.ts b/apps/fabro-web/app/components/stage-renderers/helpers.ts
index 2ea42b1f4..6ddcba7a0 100644
--- a/apps/fabro-web/app/components/stage-renderers/helpers.ts
+++ b/apps/fabro-web/app/components/stage-renderers/helpers.ts
@@ -1,5 +1,8 @@
 import { StageOutcome } from "@qltysh/fabro-api-client";
-import type { EventEnvelope } from "@qltysh/fabro-api-client";
+import type {
+  EventEnvelope,
+  ReviewTarget,
+} from "@qltysh/fabro-api-client";
 
 import { getArray, getNumber, getObject, getString, type UnknownRecord } from "../../lib/unknown";
 
@@ -25,6 +28,7 @@ export interface HumanQuestion {
   allowFreeform: boolean;
   timeoutSeconds: number | null;
   contextDisplay: string | null;
+  reviewTarget: ReviewTarget | null;
 }
 
 export type HumanResolution =
@@ -75,6 +79,16 @@ function parseInterviewOptions(value: unknown): InterviewOption[] {
   return out;
 }
 
+function parseReviewTarget(value: unknown): ReviewTarget | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as UnknownRecord;
+  const label = getString(record, "label");
+  const url = getString(record, "url");
+  const kind = getString(record, "kind");
+  if (!label || !url || kind !== "document") return null;
+  return { label, url, kind };
+}
+
 /**
  * Pair `interview.started` events with the matching `interview.completed`,
  * `.timeout`, or `.interrupted` resolution by `question_id`. Unanswered
@@ -98,6 +112,7 @@ export function parseHumanInterviewPairs(events: EventEnvelope[]): HumanIntervie
           allowFreeform: props.allow_freeform === true,
           timeoutSeconds: getNumber(props, "timeout_seconds") ?? null,
           contextDisplay: getString(props, "context_display") ?? null,
+          reviewTarget: parseReviewTarget(props.review_target),
         },
         resolution: null,
       });
diff --git a/apps/fabro-web/app/components/stage-renderers/human-qa.tsx b/apps/fabro-web/app/components/stage-renderers/human-qa.tsx
index 12ebd6d6e..c2180c0ef 100644
--- a/apps/fabro-web/app/components/stage-renderers/human-qa.tsx
+++ b/apps/fabro-web/app/components/stage-renderers/human-qa.tsx
@@ -10,6 +10,7 @@ import {
 import type { EventEnvelope } from "@qltysh/fabro-api-client";
 
 import type { Stage } from "../stage-sidebar";
+import { ReviewTargetQuestion } from "../review-target-question";
 import { Tooltip } from "../ui";
 import { formatAbsoluteTs, formatDurationMs } from "../../lib/format";
 import { ACTIVE_STAGE_STATES } from "../../lib/stage-sidebar";
@@ -168,7 +169,15 @@ function QuestionBlock({
       </header>
 
       <div className="rounded-lg bg-panel p-4 outline-1 -outline-offset-1 outline-line">
-        <Markdown content={question.question} />
+        {question.reviewTarget ? (
+          <ReviewTargetQuestion
+            reviewTarget={question.reviewTarget}
+            fallbackText={question.question}
+            className="text-sm/6 text-fg-2"
+          />
+        ) : (
+          <Markdown content={question.question} />
+        )}
         {question.contextDisplay && (
           <div className="mt-3 border-t border-line pt-3 text-xs text-fg-muted">
             <Markdown content={question.contextDisplay} />
diff --git a/docs/public/api-reference/fabro-api.yaml b/docs/public/api-reference/fabro-api.yaml
index b028d89c0..8bbeb16d6 100644
--- a/docs/public/api-reference/fabro-api.yaml
+++ b/docs/public/api-reference/fabro-api.yaml
@@ -9597,6 +9597,11 @@ components:
           type: ["string", "null"]
           description: Optional contextual text shown alongside the question.
           example: Latest draft
+        review_target:
+          description: Optional validated external resource that is the primary subject of this review question.
+          oneOf:
+            - $ref: "#/components/schemas/ReviewTarget"
+            - type: "null"
 
     QuestionType:
       description: The interaction type of a human-in-the-loop question.
@@ -11102,6 +11107,36 @@ components:
           type: ["string", "null"]
           description: Optional untrusted model-authored option preview captured for clients.
 
+    ReviewTargetKind:
+      description: The type of resource presented for human review.
+      type: string
+      enum:
+        - document
+
+    ReviewTarget:
+      description: A validated external resource presented as the primary subject of a human review question.
+      type: object
+      required:
+        - label
+        - url
+        - kind
+      properties:
+        label:
+          type: string
+          minLength: 1
+          maxLength: 200
+          description: Human-readable link label.
+          example: Quarry review exercise
+        url:
+          type: string
+          format: uri
+          minLength: 1
+          maxLength: 2048
+          description: Absolute HTTP or HTTPS URL opened by the reviewer.
+          example: https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef
+        kind:
+          $ref: "#/components/schemas/ReviewTargetKind"
+
     InterviewQuestionRecord:
       description: Storage shape of an interview question recorded in the event log.
       type: object
@@ -11131,6 +11166,10 @@ components:
           format: double
         context_display:
           type: ["string", "null"]
+        review_target:
+          oneOf:
+            - $ref: "#/components/schemas/ReviewTarget"
+            - type: "null"
 
     PendingInterviewRecord:
       description: Pending interview question plus the time it entered the unresolved set.
diff --git a/docs/public/execution/context.mdx b/docs/public/execution/context.mdx
index 6f25c39c4..c0d7d2cda 100644
--- a/docs/public/execution/context.mdx
+++ b/docs/public/execution/context.mdx
@@ -40,6 +40,11 @@ Each handler type writes specific keys into the context after execution:
 
 Agents can also emit arbitrary context updates by including a JSON object with a `context_updates` field in their response. See [Transitions](/workflows/transitions#agent-transitions).
 
+The `review_target` key has an optional typed convention for human review
+workflows. A human gate with `review_target=true` reads this exact flat key and
+presents its document URL as the primary question link. See
+[Review targets](/workflows/human-in-the-loop#review-targets).
+
 ### Command nodes
 
 | Key | Value |
diff --git a/docs/public/reference/dot-language.mdx b/docs/public/reference/dot-language.mdx
index 8c350d1ba..a341f1145 100644
--- a/docs/public/reference/dot-language.mdx
+++ b/docs/public/reference/dot-language.mdx
@@ -267,6 +267,7 @@ For the first node in each branch, `fidelity` resolves from the fork-to-branch e
 | Attribute | Type | Description |
 |---|---|---|
 | `question_type` | String | Optional interview question type override: `yes_no`, `confirmation`, `multiple_choice`, `multi_select`, or `freeform`. Defaults to `freeform` when the gate only has a freeform edge; otherwise defaults to `multiple_choice`. |
+| `review_target` | Boolean | When `true`, read and validate the typed `review_target` context value, then present it as the primary link in the question. See [Review targets](/workflows/human-in-the-loop#review-targets). |
 | `human.default_choice` | String | Target node to use when the question times out. |
 
 ### Manager loop (sub-workflow) nodes
diff --git a/docs/public/workflows/human-in-the-loop.mdx b/docs/public/workflows/human-in-the-loop.mdx
index 01efcb3e3..bf95362eb 100644
--- a/docs/public/workflows/human-in-the-loop.mdx
+++ b/docs/public/workflows/human-in-the-loop.mdx
@@ -60,6 +60,65 @@ confirm -> exit [label="[N] No"]
 
 Supported values are `yes_no`, `confirmation`, `multiple_choice`, `multi_select`, and `freeform`.
 
+### Review targets
+
+A human gate can present one external document as the primary review link. Set
+`review_target=true` on the gate:
+
+```dot
+review [
+  shape=hexagon,
+  review_target=true
+]
+
+review -> sync     [label="[S] Review complete; sync the current Markdown"]
+review -> address  [label="[A] Ask the agent to address human feedback"]
+review -> review   [label="[C] Continue reviewing"]
+```
+
+Before the workflow reaches the gate, an agent, prompt, or command node must set
+the flat `review_target` context key. A routing response can do this directly:
+
+```json
+{
+  "outcome": "succeeded",
+  "context_updates": {
+    "review_target": {
+      "label": "Quarry review exercise",
+      "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+      "kind": "document"
+    }
+  }
+}
+```
+
+Fabro then presents this question:
+
+> Review the [Quarry review exercise](https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef) document, then choose the next action.
+
+The link uses the target URL from context. The example uses a placeholder
+secret, not a live Quarry document.
+
+The target object has three required fields:
+
+| Field | Meaning |
+|---|---|
+| `label` | The link text. It must contain 1 to 200 characters and no control characters. |
+| `url` | An absolute HTTP or HTTPS URL. It must contain a host, must not contain URL credentials, and must be at most 2048 characters. |
+| `kind` | The resource type. The supported value is `document`. |
+
+Fabro validates the target before it starts the interview. A missing or invalid
+target fails the gate deterministically. A gate without `review_target=true`
+ignores this context key and keeps its normal label.
+
+The context value remains available after the human answers. A feedback loop
+can return to the same gate without recreating the target. A later stage can
+replace the target by writing a new value to the same context key.
+
+Fabro does not fetch the URL. Web and Slack clients open it as an external link.
+Treat bearer-capability links as secrets and only provide them to people who
+can access the run.
+
 ### Default choice on timeout
 
 If a human gate has a timeout configured, you can specify a default choice using the `human.default_choice` attribute:
diff --git a/lib/apps/fabro-cli/src/commands/run/attach.rs b/lib/apps/fabro-cli/src/commands/run/attach.rs
index faab25163..122ae8b1f 100644
--- a/lib/apps/fabro-cli/src/commands/run/attach.rs
+++ b/lib/apps/fabro-cli/src/commands/run/attach.rs
@@ -438,6 +438,7 @@ fn api_question_to_question(question: &types::ApiQuestion) -> Question {
     converted
         .context_display
         .clone_from(&question.context_display);
+    converted.review_target.clone_from(&question.review_target);
     converted
 }
 
@@ -451,6 +452,14 @@ async fn ask_attach_question(question: Question, styles: &'static Styles) -> Ans
         let rendered = styles.render_markdown(context_text);
         eprint!("{rendered}");
     }
+    if let Some(target) = &question.review_target {
+        eprintln!(
+            "Review {}: {} — {}",
+            target.kind().noun(),
+            target.label(),
+            target.url()
+        );
+    }
     eprintln!("{} {}", styles.bold_cyan.apply_to("?"), question.text);
 
     match question.question_type {
diff --git a/lib/apps/fabro-cli/src/commands/run/runner.rs b/lib/apps/fabro-cli/src/commands/run/runner.rs
index 4e6b72b8b..a8fa36f23 100644
--- a/lib/apps/fabro-cli/src/commands/run/runner.rs
+++ b/lib/apps/fabro-cli/src/commands/run/runner.rs
@@ -1361,6 +1361,7 @@ mod tests {
                 allow_freeform:  false,
                 timeout_seconds: None,
                 context_display: None,
+                review_target:   None,
             })),
             Some(WorkerTitlePhase::Waiting)
         );
diff --git a/lib/apps/fabro-server/src/demo/mod.rs b/lib/apps/fabro-server/src/demo/mod.rs
index b9d51dcef..f2f45566a 100644
--- a/lib/apps/fabro-server/src/demo/mod.rs
+++ b/lib/apps/fabro-server/src/demo/mod.rs
@@ -1752,6 +1752,7 @@ mod runs {
                 allow_freeform:  false,
                 timeout_seconds: None,
                 context_display: None,
+                review_target:   None,
             },
             ApiQuestion {
                 id:              "q-002".into(),
@@ -1775,6 +1776,7 @@ mod runs {
                 allow_freeform:  true,
                 timeout_seconds: None,
                 context_display: None,
+                review_target:   None,
             },
         ]
     }
diff --git a/lib/apps/fabro-server/src/server.rs b/lib/apps/fabro-server/src/server.rs
index 11a9a0948..35cb7249d 100644
--- a/lib/apps/fabro-server/src/server.rs
+++ b/lib/apps/fabro-server/src/server.rs
@@ -719,6 +719,7 @@ impl SlackService {
                     allow_freeform:  props.allow_freeform,
                     timeout_seconds: props.timeout_seconds,
                     context_display: props.context_display.clone(),
+                    review_target:   props.review_target.clone(),
                 });
                 let blocks = slack_blocks::question_to_blocks(
                     &event.run_id.to_string(),
@@ -3708,6 +3709,7 @@ fn runtime_question_from_interview_record(question: &InterviewQuestionRecord) ->
         stage:           question.stage.clone(),
         metadata:        HashMap::new(),
         context_display: question.context_display.clone(),
+        review_target:   question.review_target.clone(),
     }
 }
 
@@ -3721,6 +3723,7 @@ fn api_question_from_interview_record(question: &InterviewQuestionRecord) -> Api
         allow_freeform:  question.allow_freeform,
         timeout_seconds: question.timeout_seconds,
         context_display: question.context_display.clone(),
+        review_target:   question.review_target.clone(),
     }
 }
 
diff --git a/lib/apps/fabro-server/src/server/tests.rs b/lib/apps/fabro-server/src/server/tests.rs
index 71b4dfebf..3f88c9a36 100644
--- a/lib/apps/fabro-server/src/server/tests.rs
+++ b/lib/apps/fabro-server/src/server/tests.rs
@@ -4765,6 +4765,7 @@ channel = "#deploys"
             allow_freeform:  true,
             timeout_seconds: None,
             context_display: None,
+            review_target:   None,
         },
     )
     .await;
@@ -8031,6 +8032,7 @@ async fn submit_pending_interview_answer_rejects_invalid_answer_shape() {
             allow_freeform:  false,
             timeout_seconds: None,
             context_display: None,
+            review_target:   None,
         },
     };
 
@@ -8059,6 +8061,7 @@ fn validate_answer_for_question_accepts_no_for_confirmation() {
         allow_freeform:  false,
         timeout_seconds: None,
         context_display: None,
+        review_target:   None,
     };
 
     let result = validate_answer_for_question(&question, &Answer::no());
@@ -8077,6 +8080,7 @@ fn answer_from_typed_yes_request_maps_to_yes_answer() {
         allow_freeform:  false,
         timeout_seconds: None,
         context_display: None,
+        review_target:   None,
     };
     let req: SubmitAnswerRequest = serde_json::from_value(json!({ "kind": "yes" })).unwrap();
 
@@ -8096,6 +8100,7 @@ fn answer_from_typed_no_request_maps_to_no_answer() {
         allow_freeform:  false,
         timeout_seconds: None,
         context_display: None,
+        review_target:   None,
     };
     let req: SubmitAnswerRequest = serde_json::from_value(json!({ "kind": "no" })).unwrap();
 
@@ -8120,6 +8125,7 @@ fn answer_from_typed_selected_request_validates_and_attaches_option() {
         allow_freeform:  false,
         timeout_seconds: None,
         context_display: None,
+        review_target:   None,
     };
     let req: SubmitAnswerRequest =
         serde_json::from_value(json!({ "kind": "selected", "option_key": "approve" })).unwrap();
@@ -8160,6 +8166,7 @@ fn answer_from_typed_multi_selected_request_validates_option_keys() {
         allow_freeform:  false,
         timeout_seconds: None,
         context_display: None,
+        review_target:   None,
     };
     let req: SubmitAnswerRequest = serde_json::from_value(json!({
         "kind": "multi_selected",
@@ -9577,6 +9584,11 @@ async fn get_run_state_exposes_pending_interviews() {
             "allow_freeform": false,
             "context_display": null,
             "timeout_seconds": null,
+            "review_target": {
+                "label": "Quarry review exercise",
+                "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                "kind": "document"
+            },
         }),
         Some("gate"),
     )
@@ -9656,6 +9668,11 @@ async fn cache_backed_run_endpoints_reflect_events_appended_after_warmup() {
             "allow_freeform": false,
             "context_display": null,
             "timeout_seconds": null,
+            "review_target": {
+                "label": "Quarry review exercise",
+                "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                "kind": "document"
+            },
         }),
         Some("review"),
     )
@@ -9713,6 +9730,10 @@ async fn cache_backed_run_endpoints_reflect_events_appended_after_warmup() {
         state_body["pending_interviews"]["q-cache"]["question"]["text"].as_str(),
         Some("Approve cached deploy?")
     );
+    assert_eq!(
+        state_body["pending_interviews"]["q-cache"]["question"]["review_target"]["url"].as_str(),
+        Some("https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef")
+    );
 
     let stages = app
         .clone()
@@ -9744,6 +9765,10 @@ async fn cache_backed_run_endpoints_reflect_events_appended_after_warmup() {
         questions["data"][0]["text"].as_str(),
         Some("Approve cached deploy?")
     );
+    assert_eq!(
+        questions["data"][0]["review_target"]["label"].as_str(),
+        Some("Quarry review exercise")
+    );
 
     let settings = app
         .clone()
@@ -16489,6 +16514,7 @@ async fn list_runs_includes_live_metadata_from_run_state() {
             allow_freeform:  false,
             timeout_seconds: None,
             context_display: None,
+            review_target:   None,
         },
     ] {
         workflow_event::append_event(&run_store, &run_id, &event)
diff --git a/lib/components/fabro-interview/src/console.rs b/lib/components/fabro-interview/src/console.rs
index 0005b1aca..bc4de4c15 100644
--- a/lib/components/fabro-interview/src/console.rs
+++ b/lib/components/fabro-interview/src/console.rs
@@ -111,6 +111,17 @@ fn parse_non_tty_freeform_response(prompt_read: PromptRead) -> Answer {
     }
 }
 
+fn review_target_line(question: &Question) -> Option<String> {
+    question.review_target.as_ref().map(|target| {
+        format!(
+            "Review {}: {} — {}",
+            target.kind().noun(),
+            target.label(),
+            target.url()
+        )
+    })
+}
+
 /// Ask a multiple-choice question using dialoguer's `Select` widget on a TTY.
 fn ask_select_interactive(question: &Question) -> Answer {
     let items: Vec<String> = question
@@ -237,6 +248,9 @@ impl Interviewer for ConsoleInterviewer {
                 let rendered = self.styles.render_markdown(context_text);
                 eprint!("{rendered}");
             }
+            if let Some(line) = review_target_line(&question) {
+                eprintln!("{line}");
+            }
             let q = question;
             let answer = task::spawn_blocking(move || match q.question_type {
                 QuestionType::MultipleChoice => ask_select_interactive(&q),
@@ -251,6 +265,9 @@ impl Interviewer for ConsoleInterviewer {
 
         // Non-TTY fallback: line-based stdin reading
         let s = self.styles;
+        if let Some(line) = review_target_line(&question) {
+            eprintln!("{line}");
+        }
         eprintln!("{} {}", s.bold_cyan.apply_to("?"), question.text);
 
         let answer = match question.question_type {
@@ -314,6 +331,27 @@ mod tests {
         assert_eq!(answer.value, AnswerValue::Selected("A".to_string()));
     }
 
+    #[test]
+    fn review_target_line_includes_label_and_url() {
+        let mut question = Question::new("Review", QuestionType::MultipleChoice);
+        question.review_target = Some(
+            fabro_types::ReviewTarget::new(
+                "Quarry review exercise",
+                "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                fabro_types::ReviewTargetKind::Document,
+            )
+            .unwrap(),
+        );
+
+        assert_eq!(
+            review_target_line(&question).as_deref(),
+            Some(
+                "Review document: Quarry review exercise — \
+                 https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef"
+            )
+        );
+    }
+
     #[test]
     fn find_matching_option_by_key_case_insensitive() {
         let options = vec![InterviewOption {
diff --git a/lib/components/fabro-interview/src/lib.rs b/lib/components/fabro-interview/src/lib.rs
index 6d8c414a1..e32f4bd30 100644
--- a/lib/components/fabro-interview/src/lib.rs
+++ b/lib/components/fabro-interview/src/lib.rs
@@ -10,7 +10,7 @@ mod replay;
 use std::collections::HashMap;
 
 use async_trait::async_trait;
-use fabro_types::{InterviewOption, Principal, QuestionType, SystemActorKind};
+use fabro_types::{InterviewOption, Principal, QuestionType, ReviewTarget, SystemActorKind};
 use serde::{Deserialize, Serialize};
 use tokio::time;
 
@@ -29,6 +29,8 @@ pub struct Question {
     pub metadata:        HashMap<String, serde_json::Value>,
     #[serde(default)]
     pub context_display: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub review_target:   Option<ReviewTarget>,
 }
 
 impl Question {
@@ -44,6 +46,7 @@ impl Question {
             stage: String::new(),
             metadata: HashMap::new(),
             context_display: None,
+            review_target: None,
         }
     }
 }
@@ -260,6 +263,7 @@ mod tests {
         assert!(q.timeout_seconds.is_none());
         assert!(q.stage.is_empty());
         assert!(q.metadata.is_empty());
+        assert!(q.review_target.is_none());
     }
 
     #[test]
diff --git a/lib/components/fabro-slack/src/blocks.rs b/lib/components/fabro-slack/src/blocks.rs
index da2626167..51c60010b 100644
--- a/lib/components/fabro-slack/src/blocks.rs
+++ b/lib/components/fabro-slack/src/blocks.rs
@@ -99,7 +99,16 @@ fn truncate_to_limit(text: &str, limit: usize, suffix: &str) -> String {
 /// final text is bounded by Slack's section-text limit so even pathological
 /// inputs cannot produce `invalid_blocks`.
 fn header_section(question: &Question, run_web_url: Option<&str>) -> Value {
-    let mut text = format!("*{}*", escape_slack_controls(&question.text));
+    let mut text = question.review_target.as_ref().map_or_else(
+        || format!("*{}*", escape_slack_controls(&question.text)),
+        |target| {
+            format!(
+                "*Review the {} {}, then choose the next action.*",
+                slack_link(target.url(), target.label()),
+                target.kind().noun()
+            )
+        },
+    );
     if !question.stage.is_empty() {
         let _ = write!(
             text,
@@ -634,6 +643,35 @@ mod tests {
         assert!(header.contains("<http://127.0.0.1:32276/runs/run-1|Open in Fabro>"));
     }
 
+    #[test]
+    fn header_renders_review_target_as_the_question_link() {
+        let mut q = Question::new(
+            "Review the Quarry review exercise document, then choose the next action.",
+            QuestionType::MultipleChoice,
+        );
+        q.review_target = Some(
+            fabro_types::ReviewTarget::new(
+                "Quarry review exercise",
+                "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                fabro_types::ReviewTargetKind::Document,
+            )
+            .unwrap(),
+        );
+
+        let blocks = question_to_blocks("run-1", "q-1", &q, None);
+        let header = serde_json::to_value(&blocks).unwrap()[0]["text"]["text"]
+            .as_str()
+            .unwrap()
+            .to_string();
+
+        assert_eq!(
+            header,
+            "*Review the \
+             <https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef|Quarry review \
+             exercise> document, then choose the next action.*"
+        );
+    }
+
     #[test]
     fn header_omits_link_when_url_missing() {
         let q = Question::new("Approve Plan", QuestionType::YesNo);
diff --git a/lib/components/fabro-store/src/run_state.rs b/lib/components/fabro-store/src/run_state.rs
index 9ab1e2b2d..f9ff63631 100644
--- a/lib/components/fabro-store/src/run_state.rs
+++ b/lib/components/fabro-store/src/run_state.rs
@@ -334,6 +334,7 @@ impl RunProjectionReducer for RunProjection {
                             allow_freeform:  props.allow_freeform,
                             timeout_seconds: props.timeout_seconds,
                             context_display: props.context_display.clone(),
+                            review_target:   props.review_target.clone(),
                         },
                         started_at: ts,
                     });
@@ -2859,6 +2860,14 @@ mod tests {
                     allow_freeform:  true,
                     timeout_seconds: Some(30.0),
                     context_display: Some("Latest draft".to_string()),
+                    review_target:   Some(
+                        fabro_types::ReviewTarget::new(
+                            "Quarry review exercise",
+                            "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                            fabro_types::ReviewTargetKind::Document,
+                        )
+                        .unwrap(),
+                    ),
                 }),
                 Some("gate"),
             ))
@@ -2886,6 +2895,14 @@ mod tests {
             pending.question.context_display.as_deref(),
             Some("Latest draft")
         );
+        assert_eq!(
+            pending
+                .question
+                .review_target
+                .as_ref()
+                .map(fabro_types::ReviewTarget::url),
+            Some("https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef")
+        );
 
         state
             .apply_event(&test_event(
diff --git a/lib/components/fabro-store/tests/serializable_projection.rs b/lib/components/fabro-store/tests/serializable_projection.rs
index 66600c154..140542a70 100644
--- a/lib/components/fabro-store/tests/serializable_projection.rs
+++ b/lib/components/fabro-store/tests/serializable_projection.rs
@@ -235,6 +235,7 @@ fn projection_query_methods_expose_common_state() {
                 allow_freeform:  true,
                 timeout_seconds: None,
                 context_display: None,
+                review_target:   None,
             },
             started_at: Utc::now(),
         })]);
diff --git a/lib/components/fabro-validate/src/rules/inert_attribute.rs b/lib/components/fabro-validate/src/rules/inert_attribute.rs
index 2ae6d0e04..ac2629422 100644
--- a/lib/components/fabro-validate/src/rules/inert_attribute.rs
+++ b/lib/components/fabro-validate/src/rules/inert_attribute.rs
@@ -22,6 +22,7 @@ const HANDLER_SPECIFIC_ATTRS: &[(&str, &[&str])] = &[
     ("output_retries", &["agent", "prompt"]),
     ("output_schema", &["agent", "prompt", "command"]),
     ("prompt", &["agent", "prompt", "parallel.fan_in"]),
+    ("review_target", &["human"]),
 ];
 
 struct Rule;
@@ -197,9 +198,28 @@ mod tests {
             "prompt".to_string(),
             node_with_attr("prompt", "tab", "output_retries", "2"),
         );
+        g.nodes.insert(
+            "human".to_string(),
+            node_with_attr("human", "hexagon", "review_target", "true"),
+        );
         assert!(Rule.apply(&g).is_empty());
     }
 
+    #[test]
+    fn warns_on_review_target_on_non_human_node() {
+        let mut g = minimal_graph();
+        g.nodes.insert(
+            "work".to_string(),
+            node_with_attr("work", "box", "review_target", "true"),
+        );
+
+        let diagnostics = Rule.apply(&g);
+
+        assert_eq!(diagnostics.len(), 1);
+        assert!(diagnostics[0].message.contains("'review_target'"));
+        assert!(diagnostics[0].message.contains("human"));
+    }
+
     #[test]
     fn accepts_prompt_on_shapeless_node_defaulting_to_agent() {
         let mut g = minimal_graph();
diff --git a/lib/components/fabro-workflow/src/context.rs b/lib/components/fabro-workflow/src/context.rs
index 6e94368b2..46aefccda 100644
--- a/lib/components/fabro-workflow/src/context.rs
+++ b/lib/components/fabro-workflow/src/context.rs
@@ -12,6 +12,7 @@ pub mod keys {
     pub const PREFERRED_LABEL: &str = "preferred_label";
     pub const LAST_STAGE: &str = "last_stage";
     pub const LAST_RESPONSE: &str = "last_response";
+    pub const REVIEW_TARGET: &str = "review_target";
 
     // --- graph.* keys ---
     pub const GRAPH_GOAL: &str = "graph.goal";
@@ -142,6 +143,7 @@ pub mod keys {
             assert!(!is_engine_internal_key("outcome"));
             assert!(!is_engine_internal_key("last_stage"));
             assert!(!is_engine_internal_key("review.result"));
+            assert!(!is_engine_internal_key(REVIEW_TARGET));
             assert!(!is_engine_internal_key("user.name"));
         }
     }
diff --git a/lib/components/fabro-workflow/src/event/convert.rs b/lib/components/fabro-workflow/src/event/convert.rs
index 5cef4e581..e2d236533 100644
--- a/lib/components/fabro-workflow/src/event/convert.rs
+++ b/lib/components/fabro-workflow/src/event/convert.rs
@@ -423,6 +423,7 @@ fn event_body_from_event(event: &Event) -> EventBody {
             allow_freeform,
             timeout_seconds,
             context_display,
+            review_target,
         } => EventBody::InterviewStarted(fabro_types::InterviewStartedProps {
             question_id:     question_id.clone(),
             question:        question.clone(),
@@ -432,6 +433,7 @@ fn event_body_from_event(event: &Event) -> EventBody {
             allow_freeform:  *allow_freeform,
             timeout_seconds: *timeout_seconds,
             context_display: context_display.clone(),
+            review_target:   review_target.clone(),
         }),
         Event::InterviewCompleted {
             actor: _,
diff --git a/lib/components/fabro-workflow/src/event/events.rs b/lib/components/fabro-workflow/src/event/events.rs
index 20803b1fa..9870de6ae 100644
--- a/lib/components/fabro-workflow/src/event/events.rs
+++ b/lib/components/fabro-workflow/src/event/events.rs
@@ -4,9 +4,10 @@ use ::fabro_types::{
     AutomationRef, BilledTokenCounts, BlockedReason, CommandTermination, DiffSummary,
     FailureReason, ForkSourceRef, GitContext, PairId, PairMessageId, PairSystemMessageKind,
     PairTarget, ParallelBranchId, ParallelBranchResult, PendingReason, PermissionLevel, Principal,
-    PullRequestLink, RunBlobId, RunFailure, RunId, RunNoticeLevel, RunPairEndedReason,
-    RunPairFailedReason, RunProvenance, RunRunnableSource, RunTiming, SandboxProviderKind, StageId,
-    StageOutcome, StageTiming, SuccessReason, run_event as fabro_types,
+    PullRequestLink, ReviewTarget, RunBlobId, RunFailure, RunId, RunNoticeLevel,
+    RunPairEndedReason, RunPairFailedReason, RunProvenance, RunRunnableSource, RunTiming,
+    SandboxProviderKind, StageId, StageOutcome, StageTiming, SuccessReason,
+    run_event as fabro_types,
 };
 use fabro_agent::{AgentEvent, SandboxEvent};
 use fabro_model::{ReasoningEffort, Speed};
@@ -355,6 +356,8 @@ pub enum Event {
         timeout_seconds: Option<f64>,
         #[serde(default, skip_serializing_if = "Option::is_none")]
         context_display: Option<String>,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        review_target:   Option<ReviewTarget>,
     },
     InterviewCompleted {
         #[serde(default, skip_serializing_if = "Option::is_none")]
diff --git a/lib/components/fabro-workflow/src/handler/human.rs b/lib/components/fabro-workflow/src/handler/human.rs
index 77b83454a..a961ecb02 100644
--- a/lib/components/fabro-workflow/src/handler/human.rs
+++ b/lib/components/fabro-workflow/src/handler/human.rs
@@ -6,7 +6,7 @@ use std::time::Instant;
 use async_trait::async_trait;
 use fabro_graphviz::graph::{Graph, Node};
 use fabro_interview::{Answer, AnswerValue, Interviewer, Question, ask_with_timeout};
-use fabro_types::{InterviewOption, Principal, QuestionType, SystemActorKind};
+use fabro_types::{InterviewOption, Principal, QuestionType, ReviewTarget, SystemActorKind};
 use ulid::Ulid;
 
 use super::{EngineServices, Handler, NodeTimeoutPolicy};
@@ -121,6 +121,23 @@ fn build_human_gate_question(
     question.stage.clone_from(&node.id);
     question.timeout_seconds = node.timeout().map(|duration| duration.as_secs_f64());
 
+    if node.review_target() {
+        let value = context.get(keys::REVIEW_TARGET).ok_or_else(|| {
+            format!(
+                "Human gate \"{}\" has review_target=true but context.review_target is missing",
+                node.id
+            )
+        })?;
+        let review_target = serde_json::from_value::<ReviewTarget>(value).map_err(|error| {
+            format!(
+                "Human gate \"{}\" has invalid context.review_target: {error}",
+                node.id
+            )
+        })?;
+        question.text = review_target.question_text();
+        question.review_target = Some(review_target);
+    }
+
     if let Some(serde_json::Value::String(last_node)) = context.get(keys::LAST_STAGE) {
         if let Some(serde_json::Value::String(response)) =
             context.get(&keys::response_key(&last_node))
@@ -253,6 +270,7 @@ impl Handler for HumanHandler {
                 allow_freeform:  question.allow_freeform,
                 timeout_seconds: question.timeout_seconds,
                 context_display: question.context_display.clone(),
+                review_target:   question.review_target.clone(),
             },
             &stage_scope,
         );
@@ -639,6 +657,15 @@ mod tests {
         graph
     }
 
+    fn enable_review_target(graph: &mut Graph) {
+        graph
+            .nodes
+            .get_mut("gate")
+            .unwrap()
+            .attrs
+            .insert("review_target".to_string(), AttrValue::Boolean(true));
+    }
+
     #[test]
     fn parse_accelerator_key_bracket() {
         assert_eq!(parse_accelerator_key("[A] Approve"), "A");
@@ -665,6 +692,160 @@ mod tests {
         assert_eq!(parse_accelerator_key(""), "");
     }
 
+    #[tokio::test]
+    async fn review_target_gate_snapshots_validated_context_into_question_and_event() {
+        let inner = Box::new(AutoApproveInterviewer::engine());
+        let recorder = Arc::new(RecordingInterviewer::new(inner));
+        let handler = HumanHandler::new(recorder.clone());
+        let mut graph = build_graph_with_human_gate();
+        enable_review_target(&mut graph);
+        let node = graph.nodes.get("gate").unwrap();
+        let context = Context::new();
+        let target_value = serde_json::json!({
+            "label": "Quarry review exercise",
+            "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+            "kind": "document",
+        });
+        context.set(keys::REVIEW_TARGET, target_value.clone());
+        let events = Arc::new(Mutex::new(Vec::new()));
+
+        let outcome = handler
+            .execute(
+                node,
+                &context,
+                &graph,
+                Path::new("/tmp/test"),
+                &make_services_with_events(Arc::clone(&events)),
+            )
+            .await
+            .unwrap();
+
+        let recordings = recorder.recordings();
+        assert_eq!(recordings.len(), 1);
+        let question = &recordings[0].0;
+        assert_eq!(
+            question.text,
+            "Review the Quarry review exercise document, then choose the next action."
+        );
+        assert_eq!(
+            question.review_target.as_ref().map(ReviewTarget::url),
+            Some("https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef")
+        );
+
+        let event_target = events
+            .lock()
+            .expect("event log lock poisoned")
+            .iter()
+            .find_map(|event| match &event.body {
+                EventBody::InterviewStarted(props) => props.review_target.clone(),
+                _ => None,
+            })
+            .expect("interview.started should carry the review target");
+        assert_eq!(event_target.label(), "Quarry review exercise");
+
+        context.apply_updates(&outcome.context_updates);
+        assert_eq!(context.get(keys::REVIEW_TARGET), Some(target_value));
+    }
+
+    #[tokio::test]
+    async fn review_target_gate_fails_before_interview_when_context_is_missing() {
+        let inner = Box::new(AutoApproveInterviewer::engine());
+        let recorder = Arc::new(RecordingInterviewer::new(inner));
+        let handler = HumanHandler::new(recorder.clone());
+        let mut graph = build_graph_with_human_gate();
+        enable_review_target(&mut graph);
+        let node = graph.nodes.get("gate").unwrap();
+
+        let outcome = handler
+            .execute(
+                node,
+                &Context::new(),
+                &graph,
+                Path::new("/tmp/test"),
+                &make_services(),
+            )
+            .await
+            .unwrap();
+
+        assert!(outcome.status.is_failure());
+        assert_eq!(
+            outcome.failure_reason(),
+            Some("Human gate \"gate\" has review_target=true but context.review_target is missing")
+        );
+        assert!(recorder.recordings().is_empty());
+    }
+
+    #[tokio::test]
+    async fn review_target_gate_rejects_unsafe_url_without_echoing_it() {
+        let inner = Box::new(AutoApproveInterviewer::engine());
+        let recorder = Arc::new(RecordingInterviewer::new(inner));
+        let handler = HumanHandler::new(recorder.clone());
+        let mut graph = build_graph_with_human_gate();
+        enable_review_target(&mut graph);
+        let node = graph.nodes.get("gate").unwrap();
+        let context = Context::new();
+        context.set(
+            keys::REVIEW_TARGET,
+            serde_json::json!({
+                "label": "Unsafe review",
+                "url": "javascript:alert(1)",
+                "kind": "document",
+            }),
+        );
+
+        let outcome = handler
+            .execute(
+                node,
+                &context,
+                &graph,
+                Path::new("/tmp/test"),
+                &make_services(),
+            )
+            .await
+            .unwrap();
+
+        let failure = outcome
+            .failure_reason()
+            .expect("invalid review target should fail");
+        assert!(failure.contains("review target URL must use http or https"));
+        assert!(!failure.contains("javascript:alert"));
+        assert!(recorder.recordings().is_empty());
+    }
+
+    #[tokio::test]
+    async fn human_gate_ignores_review_target_context_without_opt_in() {
+        let inner = Box::new(AutoApproveInterviewer::engine());
+        let recorder = Arc::new(RecordingInterviewer::new(inner));
+        let handler = HumanHandler::new(recorder.clone());
+        let graph = build_graph_with_human_gate();
+        let node = graph.nodes.get("gate").unwrap();
+        let context = Context::new();
+        context.set(
+            keys::REVIEW_TARGET,
+            serde_json::json!({
+                "label": "Unsafe review",
+                "url": "javascript:alert(1)",
+                "kind": "document",
+            }),
+        );
+
+        let outcome = handler
+            .execute(
+                node,
+                &context,
+                &graph,
+                Path::new("/tmp/test"),
+                &make_services(),
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(outcome.status, crate::outcome::StageOutcome::Succeeded);
+        let recordings = recorder.recordings();
+        assert_eq!(recordings[0].0.text, "Review Changes");
+        assert!(recordings[0].0.review_target.is_none());
+    }
+
     #[tokio::test]
     async fn wait_human_auto_approve_selects_first() {
         let interviewer = Arc::new(AutoApproveInterviewer::engine());
diff --git a/lib/components/fabro-workflow/src/interview_runtime.rs b/lib/components/fabro-workflow/src/interview_runtime.rs
index f0370ae0e..8eb58d889 100644
--- a/lib/components/fabro-workflow/src/interview_runtime.rs
+++ b/lib/components/fabro-workflow/src/interview_runtime.rs
@@ -224,6 +224,7 @@ impl AgentQuestionRuntime for WorkflowAgentQuestionRuntime {
                     allow_freeform:  question.allow_freeform,
                     timeout_seconds: None,
                     context_display: question.context_display.clone(),
+                    review_target:   question.review_target.clone(),
                 },
                 &self.stage_scope,
             );
diff --git a/lib/foundation/fabro-api/build.rs b/lib/foundation/fabro-api/build.rs
index fc943e99d..10f38a8eb 100644
--- a/lib/foundation/fabro-api/build.rs
+++ b/lib/foundation/fabro-api/build.rs
@@ -463,6 +463,8 @@ fn main() {
             &[],
         ),
         ("InterviewOption", "fabro_types::InterviewOption", &[]),
+        ("ReviewTarget", "fabro_types::ReviewTarget", &[]),
+        ("ReviewTargetKind", "fabro_types::ReviewTargetKind", &[]),
         (
             "InterviewQuestionRecord",
             "fabro_types::InterviewQuestionRecord",
diff --git a/lib/foundation/fabro-api/src/lib.rs b/lib/foundation/fabro-api/src/lib.rs
index 4312acb91..19f1e3c4c 100644
--- a/lib/foundation/fabro-api/src/lib.rs
+++ b/lib/foundation/fabro-api/src/lib.rs
@@ -55,12 +55,12 @@ pub mod types {
         PairTranscriptResponse, ParallelBranchResult, PendingInterviewRecord, PermissionLevel,
         PreRunPushOutcome, Principal, PullRequest, PullRequestDetails, PullRequestDetailsStatus,
         PullRequestDetailsUnavailableReason, PullRequestLink, PullRequestMeta, PullRequestResponse,
-        QuestionType, ReasoningOutput, RepositoryRef, Role, Run, RunApproval, RunApprovalState,
-        RunClientProvenance, RunEvent, RunEventDetailContentKind, RunEventDetailResponse,
-        RunFailure, RunPairStatusResponse, RunProjection, RunProvenance, RunRunnableSource,
-        RunSandbox, RunSandboxFailure, RunSandboxInstance, RunSandboxKind, RunSandboxPlan,
-        RunSandboxRuntime, RunServerProvenance, RunSize, SandboxDetails, SandboxInfo,
-        SandboxListMeta, SandboxListResponse, SandboxNetwork, SandboxNetworkPolicy,
+        QuestionType, ReasoningOutput, RepositoryRef, ReviewTarget, ReviewTargetKind, Role, Run,
+        RunApproval, RunApprovalState, RunClientProvenance, RunEvent, RunEventDetailContentKind,
+        RunEventDetailResponse, RunFailure, RunPairStatusResponse, RunProjection, RunProvenance,
+        RunRunnableSource, RunSandbox, RunSandboxFailure, RunSandboxInstance, RunSandboxKind,
+        RunSandboxPlan, RunSandboxRuntime, RunServerProvenance, RunSize, SandboxDetails,
+        SandboxInfo, SandboxListMeta, SandboxListResponse, SandboxNetwork, SandboxNetworkPolicy,
         SandboxNetworkPolicyMode, SandboxProviderKind, SandboxProviderLookupError,
         SandboxResources, SandboxService, SandboxServiceListResponse, SandboxState,
         SandboxTimestamps, SecretMetadata, SecretType, ServerSettings, SessionDetail, SessionId,
diff --git a/lib/foundation/fabro-api/tests/interview_question_record_round_trip.rs b/lib/foundation/fabro-api/tests/interview_question_record_round_trip.rs
index 14338c4b4..e6c828077 100644
--- a/lib/foundation/fabro-api/tests/interview_question_record_round_trip.rs
+++ b/lib/foundation/fabro-api/tests/interview_question_record_round_trip.rs
@@ -1,12 +1,17 @@
 use std::any::{TypeId, type_name};
 
-use fabro_api::types::InterviewQuestionRecord as ApiInterviewQuestionRecord;
-use fabro_types::InterviewQuestionRecord;
+use fabro_api::types::{
+    InterviewQuestionRecord as ApiInterviewQuestionRecord, ReviewTarget as ApiReviewTarget,
+    ReviewTargetKind as ApiReviewTargetKind,
+};
+use fabro_types::{InterviewQuestionRecord, ReviewTarget, ReviewTargetKind};
 use serde_json::json;
 
 #[test]
 fn interview_question_record_reuses_canonical_type() {
     assert_same_type::<ApiInterviewQuestionRecord, InterviewQuestionRecord>();
+    assert_same_type::<ApiReviewTarget, ReviewTarget>();
+    assert_same_type::<ApiReviewTargetKind, ReviewTargetKind>();
 }
 
 #[test]
@@ -27,7 +32,12 @@ fn interview_question_record_round_trips_representative_json() {
         ],
         "allow_freeform": true,
         "timeout_seconds": 30.0,
-        "context_display": "Diff summary"
+        "context_display": "Diff summary",
+        "review_target": {
+            "label": "Quarry review exercise",
+            "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+            "kind": "document"
+        }
     });
 
     let question: InterviewQuestionRecord = serde_json::from_value(value.clone()).unwrap();
diff --git a/lib/foundation/fabro-api/tests/pending_interview_record_round_trip.rs b/lib/foundation/fabro-api/tests/pending_interview_record_round_trip.rs
index dae81fdc3..c1ac64a8a 100644
--- a/lib/foundation/fabro-api/tests/pending_interview_record_round_trip.rs
+++ b/lib/foundation/fabro-api/tests/pending_interview_record_round_trip.rs
@@ -28,7 +28,12 @@ fn pending_interview_record_round_trips_populated_question() {
             ],
             "allow_freeform": true,
             "timeout_seconds": 30.0,
-            "context_display": "Diff summary"
+            "context_display": "Diff summary",
+            "review_target": {
+                "label": "Quarry review exercise",
+                "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                "kind": "document"
+            }
         },
         "started_at": "2026-04-29T12:34:56Z"
     });
diff --git a/lib/foundation/fabro-types/Cargo.toml b/lib/foundation/fabro-types/Cargo.toml
index 483e7d697..273309c73 100644
--- a/lib/foundation/fabro-types/Cargo.toml
+++ b/lib/foundation/fabro-types/Cargo.toml
@@ -28,6 +28,7 @@ serde.workspace = true
 serde_json.workspace = true
 sha2.workspace = true
 strum.workspace = true
+thiserror.workspace = true
 toml.workspace = true
 ulid.workspace = true
 url.workspace = true
diff --git a/lib/foundation/fabro-types/src/graph.rs b/lib/foundation/fabro-types/src/graph.rs
index 7ef9bad99..e593d55e4 100644
--- a/lib/foundation/fabro-types/src/graph.rs
+++ b/lib/foundation/fabro-types/src/graph.rs
@@ -193,6 +193,11 @@ impl Node {
         self.bool_attr("goal_gate").unwrap_or(false)
     }
 
+    #[must_use]
+    pub fn review_target(&self) -> bool {
+        self.bool_attr("review_target").unwrap_or(false)
+    }
+
     #[must_use]
     pub fn retry_target(&self) -> Option<&str> {
         self.str_attr("retry_target")
@@ -590,6 +595,7 @@ mod tests {
         assert_eq!(node.output_retries(), 2);
         assert_eq!(node.max_retries(), None);
         assert!(!node.goal_gate());
+        assert!(!node.review_target());
         assert_eq!(node.retry_target(), None);
         assert_eq!(node.fallback_retry_target(), None);
         assert_eq!(node.fidelity(), None);
@@ -652,12 +658,15 @@ mod tests {
         );
         node.attrs
             .insert("goal_gate".to_string(), AttrValue::Boolean(true));
+        node.attrs
+            .insert("review_target".to_string(), AttrValue::Boolean(true));
         node.attrs
             .insert("max_retries".to_string(), AttrValue::Integer(3));
 
         assert_eq!(node.label(), "Plan step");
         assert_eq!(node.shape(), "diamond");
         assert!(node.goal_gate());
+        assert!(node.review_target());
         assert_eq!(node.max_retries(), Some(3));
     }
 
diff --git a/lib/foundation/fabro-types/src/interview.rs b/lib/foundation/fabro-types/src/interview.rs
index 4ad2dc295..157fc31c6 100644
--- a/lib/foundation/fabro-types/src/interview.rs
+++ b/lib/foundation/fabro-types/src/interview.rs
@@ -1,7 +1,172 @@
+use serde::de::Error as _;
 use serde::{Deserialize, Serialize};
+use thiserror::Error;
 
 use crate::run_event::InterviewOption;
 
+const REVIEW_TARGET_LABEL_MAX_CHARS: usize = 200;
+const REVIEW_TARGET_URL_MAX_CHARS: usize = 2048;
+
+/// The type of resource a human should review.
+#[derive(
+    Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, strum::Display, strum::EnumString,
+)]
+#[serde(rename_all = "snake_case")]
+#[strum(serialize_all = "snake_case")]
+pub enum ReviewTargetKind {
+    Document,
+}
+
+impl ReviewTargetKind {
+    #[must_use]
+    pub const fn noun(self) -> &'static str {
+        match self {
+            Self::Document => "document",
+        }
+    }
+}
+
+/// A validated external resource presented as the primary subject of a human
+/// review question.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+pub struct ReviewTarget {
+    label: String,
+    url:   String,
+    kind:  ReviewTargetKind,
+}
+
+impl ReviewTarget {
+    pub fn new(
+        label: impl Into<String>,
+        url: impl Into<String>,
+        kind: ReviewTargetKind,
+    ) -> Result<Self, ReviewTargetError> {
+        let label = label.into();
+        let url = url.into();
+        let label = label.trim();
+        let url = url.trim();
+
+        validate_review_target_label(label)?;
+        validate_review_target_url(url)?;
+
+        Ok(Self {
+            label: label.to_string(),
+            url: url.to_string(),
+            kind,
+        })
+    }
+
+    #[must_use]
+    pub fn label(&self) -> &str {
+        &self.label
+    }
+
+    #[must_use]
+    pub fn url(&self) -> &str {
+        &self.url
+    }
+
+    #[must_use]
+    pub const fn kind(&self) -> ReviewTargetKind {
+        self.kind
+    }
+
+    #[must_use]
+    pub fn question_text(&self) -> String {
+        format!(
+            "Review the {} {}, then choose the next action.",
+            self.label,
+            self.kind.noun()
+        )
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Error)]
+pub enum ReviewTargetError {
+    #[error("review target label must not be empty")]
+    EmptyLabel,
+    #[error("review target label must be at most {REVIEW_TARGET_LABEL_MAX_CHARS} characters")]
+    LabelTooLong,
+    #[error("review target label must not contain control characters")]
+    LabelContainsControl,
+    #[error("review target URL must not be empty")]
+    EmptyUrl,
+    #[error("review target URL must be at most {REVIEW_TARGET_URL_MAX_CHARS} characters")]
+    UrlTooLong,
+    #[error("review target URL must not contain control characters or Slack link delimiters")]
+    UrlContainsUnsafeCharacters,
+    #[error("review target URL must be a valid absolute URL")]
+    InvalidUrl,
+    #[error("review target URL must use http or https")]
+    UnsupportedUrlScheme,
+    #[error("review target URL must include a host")]
+    MissingUrlHost,
+    #[error("review target URL must not include username or password credentials")]
+    UrlContainsCredentials,
+}
+
+fn validate_review_target_label(label: &str) -> Result<(), ReviewTargetError> {
+    if label.is_empty() {
+        return Err(ReviewTargetError::EmptyLabel);
+    }
+    if label.chars().count() > REVIEW_TARGET_LABEL_MAX_CHARS {
+        return Err(ReviewTargetError::LabelTooLong);
+    }
+    if label.chars().any(char::is_control) {
+        return Err(ReviewTargetError::LabelContainsControl);
+    }
+    Ok(())
+}
+
+#[expect(
+    clippy::disallowed_types,
+    reason = "Review target validation parses an untrusted URL only to enforce safe display schemes and syntax; Fabro never fetches the URL."
+)]
+fn validate_review_target_url(url: &str) -> Result<(), ReviewTargetError> {
+    if url.is_empty() {
+        return Err(ReviewTargetError::EmptyUrl);
+    }
+    if url.chars().count() > REVIEW_TARGET_URL_MAX_CHARS {
+        return Err(ReviewTargetError::UrlTooLong);
+    }
+    if url
+        .chars()
+        .any(|character| character.is_control() || matches!(character, '<' | '>' | '|'))
+    {
+        return Err(ReviewTargetError::UrlContainsUnsafeCharacters);
+    }
+
+    let parsed = url::Url::parse(url).map_err(|_| ReviewTargetError::InvalidUrl)?;
+    if !matches!(parsed.scheme(), "http" | "https") {
+        return Err(ReviewTargetError::UnsupportedUrlScheme);
+    }
+    if parsed.host_str().is_none() {
+        return Err(ReviewTargetError::MissingUrlHost);
+    }
+    if !parsed.username().is_empty() || parsed.password().is_some() {
+        return Err(ReviewTargetError::UrlContainsCredentials);
+    }
+    Ok(())
+}
+
+impl<'de> Deserialize<'de> for ReviewTarget {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        #[derive(Deserialize)]
+        #[serde(deny_unknown_fields)]
+        struct WireReviewTarget {
+            label: String,
+            url:   String,
+            kind:  ReviewTargetKind,
+        }
+
+        let wire = WireReviewTarget::deserialize(deserializer)?;
+        Self::new(wire.label, wire.url, wire.kind).map_err(D::Error::custom)
+    }
+}
+
 #[derive(
     Debug,
     Clone,
@@ -43,6 +208,8 @@ pub struct InterviewQuestionRecord {
     pub timeout_seconds: Option<f64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub context_display: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub review_target:   Option<ReviewTarget>,
 }
 
 #[cfg(test)]
@@ -64,4 +231,52 @@ mod tests {
             assert_eq!(question_type.to_string(), wire);
         }
     }
+
+    #[test]
+    fn review_target_roundtrips_and_builds_question_text() {
+        let value = serde_json::json!({
+            "label": "Quarry review exercise",
+            "url": "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+            "kind": "document",
+        });
+
+        let target: ReviewTarget = serde_json::from_value(value.clone()).unwrap();
+
+        assert_eq!(target.label(), "Quarry review exercise");
+        assert_eq!(
+            target.question_text(),
+            "Review the Quarry review exercise document, then choose the next action."
+        );
+        assert_eq!(serde_json::to_value(target).unwrap(), value);
+    }
+
+    #[test]
+    fn review_target_rejects_non_http_urls_and_credentials() {
+        for url in [
+            "javascript:alert(1)",
+            "file:///tmp/review.md",
+            "https://user:secret@example.com/review",
+        ] {
+            assert!(
+                ReviewTarget::new("Review", url, ReviewTargetKind::Document).is_err(),
+                "URL should be rejected: {url}"
+            );
+        }
+    }
+
+    #[test]
+    fn review_target_rejects_blank_or_unsafe_display_values() {
+        assert_eq!(
+            ReviewTarget::new(" ", "https://example.com", ReviewTargetKind::Document),
+            Err(ReviewTargetError::EmptyLabel)
+        );
+        assert_eq!(
+            ReviewTarget::new(
+                "Review",
+                "https://example.com/a|b",
+                ReviewTargetKind::Document
+            ),
+            Err(ReviewTargetError::UrlContainsUnsafeCharacters)
+        );
+    }
 }
diff --git a/lib/foundation/fabro-types/src/lib.rs b/lib/foundation/fabro-types/src/lib.rs
index 68f5644a2..7ac7b5403 100644
--- a/lib/foundation/fabro-types/src/lib.rs
+++ b/lib/foundation/fabro-types/src/lib.rs
@@ -75,7 +75,9 @@ pub use graph::{
     AttrValue, Edge, Graph, KNOWN_HANDLER_TYPES, Node, is_known_handler_type, is_llm_handler_type,
     shape_to_handler_type,
 };
-pub use interview::{InterviewQuestionRecord, QuestionType};
+pub use interview::{
+    InterviewQuestionRecord, QuestionType, ReviewTarget, ReviewTargetError, ReviewTargetKind,
+};
 pub use llm_backend::AgentBackend;
 pub use manifest_path::{ManifestPath, ManifestPathParseError};
 pub use mcp_store::{
diff --git a/lib/foundation/fabro-types/src/run_event/misc.rs b/lib/foundation/fabro-types/src/run_event/misc.rs
index d3bf9c1c0..ad8b1b4a5 100644
--- a/lib/foundation/fabro-types/src/run_event/misc.rs
+++ b/lib/foundation/fabro-types/src/run_event/misc.rs
@@ -65,6 +65,8 @@ pub struct InterviewStartedProps {
     pub timeout_seconds: Option<f64>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub context_display: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub review_target:   Option<crate::ReviewTarget>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
diff --git a/lib/packages/fabro-api-client/src/.openapi-generator/FILES b/lib/packages/fabro-api-client/src/.openapi-generator/FILES
index e3a1a7c0e..c7a960e79 100644
--- a/lib/packages/fabro-api-client/src/.openapi-generator/FILES
+++ b/lib/packages/fabro-api-client/src/.openapi-generator/FILES
@@ -335,6 +335,8 @@ models/replace-mcp-server-request.ts
 models/repo-check-response-permissions.ts
 models/repo-check-response.ts
 models/repository-ref.ts
+models/review-target-kind.ts
+models/review-target.ts
 models/rewind-request.ts
 models/rewind-response.ts
 models/root-response-urls.ts
diff --git a/lib/packages/fabro-api-client/src/models/api-question.ts b/lib/packages/fabro-api-client/src/models/api-question.ts
index 74908ff63..8b0330475 100644
--- a/lib/packages/fabro-api-client/src/models/api-question.ts
+++ b/lib/packages/fabro-api-client/src/models/api-question.ts
@@ -19,6 +19,9 @@ import type { InterviewOption } from './interview-option';
 // May contain unused imports in some cases
 // @ts-ignore
 import type { QuestionType } from './question-type';
+// May contain unused imports in some cases
+// @ts-ignore
+import type { ReviewTarget } from './review-target';
 
 /**
  * A pending human-in-the-loop question generated by a workflow stage.
@@ -53,4 +56,5 @@ export interface ApiQuestion {
      * Optional contextual text shown alongside the question.
      */
     'context_display'?: string | null;
+    'review_target'?: ReviewTarget | null;
 }
diff --git a/lib/packages/fabro-api-client/src/models/index.ts b/lib/packages/fabro-api-client/src/models/index.ts
index 5cd29601d..9434d3980 100644
--- a/lib/packages/fabro-api-client/src/models/index.ts
+++ b/lib/packages/fabro-api-client/src/models/index.ts
@@ -305,6 +305,8 @@ export * from './replace-mcp-server-request';
 export * from './repo-check-response';
 export * from './repo-check-response-permissions';
 export * from './repository-ref';
+export * from './review-target';
+export * from './review-target-kind';
 export * from './rewind-request';
 export * from './rewind-response';
 export * from './root-response';
diff --git a/lib/packages/fabro-api-client/src/models/interview-question-record.ts b/lib/packages/fabro-api-client/src/models/interview-question-record.ts
index 6d940e919..2f2ecd2b8 100644
--- a/lib/packages/fabro-api-client/src/models/interview-question-record.ts
+++ b/lib/packages/fabro-api-client/src/models/interview-question-record.ts
@@ -19,6 +19,9 @@ import type { InterviewOption } from './interview-option';
 // May contain unused imports in some cases
 // @ts-ignore
 import type { QuestionType } from './question-type';
+// May contain unused imports in some cases
+// @ts-ignore
+import type { ReviewTarget } from './review-target';
 
 /**
  * Storage shape of an interview question recorded in the event log.
@@ -32,4 +35,5 @@ export interface InterviewQuestionRecord {
     'allow_freeform': boolean;
     'timeout_seconds'?: number | null;
     'context_display'?: string | null;
+    'review_target'?: ReviewTarget | null;
 }
diff --git a/lib/packages/fabro-api-client/src/models/review-target-kind.ts b/lib/packages/fabro-api-client/src/models/review-target-kind.ts
new file mode 100644
index 000000000..e50c78a38
--- /dev/null
+++ b/lib/packages/fabro-api-client/src/models/review-target-kind.ts
@@ -0,0 +1,25 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Fabro Run API
+ * HTTP API for managing Fabro workflow run executions.
+ *
+ * The version of the OpenAPI document: 0.1.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+
+/**
+ * The type of resource presented for human review.
+ */
+
+export const ReviewTargetKind = {
+    DOCUMENT: 'document'
+} as const;
+
+export type ReviewTargetKind = typeof ReviewTargetKind[keyof typeof ReviewTargetKind];
diff --git a/lib/packages/fabro-api-client/src/models/review-target.ts b/lib/packages/fabro-api-client/src/models/review-target.ts
new file mode 100644
index 000000000..61b476d21
--- /dev/null
+++ b/lib/packages/fabro-api-client/src/models/review-target.ts
@@ -0,0 +1,33 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Fabro Run API
+ * HTTP API for managing Fabro workflow run executions.
+ *
+ * The version of the OpenAPI document: 0.1.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+
+// May contain unused imports in some cases
+// @ts-ignore
+import type { ReviewTargetKind } from './review-target-kind';
+
+/**
+ * A validated external resource presented as the primary subject of a human review question.
+ */
+export interface ReviewTarget {
+    /**
+     * Human-readable link label.
+     */
+    'label': string;
+    /**
+     * Absolute HTTP or HTTPS URL opened by the reviewer.
+     */
+    'url': string;
+    'kind': ReviewTargetKind;
+}

From 80f321073f5688e60d8586bda716e25712f7acf6 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 13:38:47 -0400
Subject: [PATCH 19/36] fix(sandbox): unpause paused Docker containers

---
 lib/components/fabro-sandbox/src/docker.rs | 100 ++++++++++++++++++++-
 1 file changed, 97 insertions(+), 3 deletions(-)

diff --git a/lib/components/fabro-sandbox/src/docker.rs b/lib/components/fabro-sandbox/src/docker.rs
index 9a9bdaa08..50556550c 100644
--- a/lib/components/fabro-sandbox/src/docker.rs
+++ b/lib/components/fabro-sandbox/src/docker.rs
@@ -1481,10 +1481,27 @@ impl Sandbox for DockerSandbox {
             .and_then(|config| config.labels)
             .unwrap_or_default();
         verify_managed_labels(&container_id, &labels, self.run_id.as_ref())?;
-        let active = inspect
+        if inspect
             .state
-            .is_some_and(|state| state.running == Some(true) && state.paused != Some(true));
-        if active {
+            .as_ref()
+            .is_some_and(|state| state.running == Some(true))
+        {
+            if inspect
+                .state
+                .is_some_and(|state| state.paused != Some(true))
+            {
+                return Ok(());
+            }
+            if let Err(e) = self.docker.unpause_container(&container_id).await {
+                if !docker_not_modified(&e) {
+                    return Err(crate::Error::context(
+                        format!(
+                            "Failed to unpause Docker container '{container_id}' with labels {labels:?}"
+                        ),
+                        e,
+                    ));
+                }
+            }
             return Ok(());
         }
         self.start().await
@@ -2052,6 +2069,9 @@ mod tests {
     use std::process::Stdio;
     use std::time::Duration;
 
+    use bollard::API_DEFAULT_VERSION;
+    use httpmock::Method::{GET, POST};
+    use httpmock::MockServer;
     use tokio::io::AsyncWriteExt as _;
     use tokio::process::Command;
 
@@ -2164,6 +2184,56 @@ mod tests {
         ));
     }
 
+    #[tokio::test]
+    async fn activate_unpauses_paused_running_container() {
+        let server = MockServer::start_async().await;
+        let inspect = server
+            .mock_async(|when, then| {
+                when.method(GET)
+                    .path_suffix("/containers/test-container/json");
+                then.status(200)
+                    .header("content-type", "application/json")
+                    .json_body(serde_json::json!({
+                        "Config": {
+                            "Labels": {
+                                "sh.fabro.managed": "true"
+                            }
+                        },
+                        "State": {
+                            "Running": true,
+                            "Paused": true
+                        }
+                    }));
+            })
+            .await;
+        let unpause = server
+            .mock_async(|when, then| {
+                when.method(POST)
+                    .path_suffix("/containers/test-container/unpause");
+                then.status(204);
+            })
+            .await;
+        let start = server
+            .mock_async(|when, then| {
+                when.method(POST)
+                    .path_suffix("/containers/test-container/start");
+                then.status(204);
+            })
+            .await;
+        let docker = Docker::connect_with_http(&server.base_url(), 5, API_DEFAULT_VERSION)
+            .expect("mock Docker client should connect");
+        let sandbox = test_docker_sandbox(docker, "test-container");
+
+        sandbox
+            .activate()
+            .await
+            .expect("a paused running container should be unpaused");
+
+        inspect.assert_calls_async(1).await;
+        unpause.assert_calls_async(1).await;
+        start.assert_calls_async(0).await;
+    }
+
     #[test]
     fn default_options_are_clone_based() {
         let options = DockerSandboxOptions::default();
@@ -2476,4 +2546,28 @@ mod tests {
         entry.read_to_string(&mut content).unwrap();
         assert_eq!(content, "hello");
     }
+
+    fn test_docker_sandbox(docker: Docker, container_id: &str) -> DockerSandbox {
+        let sandbox = DockerSandbox {
+            docker,
+            config: DockerSandboxOptions::default(),
+            github_app: None,
+            run_id: None,
+            clone_origin_url: None,
+            clone_branch: None,
+            container_id: OnceCell::new(),
+            repo_cloned: OnceCell::new(),
+            working_directory: OnceCell::new(),
+            origin_url: OnceCell::new(),
+            cached_platform: std::sync::OnceLock::new(),
+            cached_os_version: std::sync::OnceLock::new(),
+            rg_available: OnceCell::new(),
+            event_callback: None,
+        };
+        sandbox
+            .container_id
+            .set(container_id.to_string())
+            .expect("test container should initialize once");
+        sandbox
+    }
 }

From 465bdd6c275535944569a593e31367ea94def450 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 13:50:16 -0400
Subject: [PATCH 20/36] Redirect test storage through with_storage_override

The test helper set server.storage.root directly, leaving the derived
local object-store roots (artifacts, slatedb) pointing at the real
~/.fabro/storage. Route the redirect through
ServerSettings::with_storage_override so every derived root moves to the
test directory together.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/apps/fabro-server/src/test_support.rs | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/lib/apps/fabro-server/src/test_support.rs b/lib/apps/fabro-server/src/test_support.rs
index 178641298..a37c2e195 100644
--- a/lib/apps/fabro-server/src/test_support.rs
+++ b/lib/apps/fabro-server/src/test_support.rs
@@ -257,7 +257,7 @@ impl TestAppStateBuilder {
     pub fn try_build(mut self) -> anyhow::Result<Arc<AppState>> {
         let (store, artifact_store) = self.store_bundle.unwrap_or_else(test_store_bundle);
         let vault_path = self.vault_path.unwrap_or_else(test_secret_store_path);
-        redirect_default_storage_root(&mut self.server_settings, &vault_path);
+        self.server_settings = redirect_default_storage_root(self.server_settings, &vault_path);
         if !self.vault_entries.is_empty() {
             let mut vault = Vault::load(vault_path.clone()).expect("test vault should load");
             for (name, value) in &self.vault_entries {
@@ -683,14 +683,16 @@ pub fn test_secret_store_path() -> PathBuf {
 /// machine-dependent, and letting run-creating tests write there.
 ///
 /// Only settings still carrying the production default are redirected; a test
-/// that chose its own root keeps it.
-fn redirect_default_storage_root(settings: &mut ServerSettings, vault_path: &Path) {
+/// that chose its own root keeps it. The redirect goes through
+/// [`ServerSettings::with_storage_override`] so the derived local object-store
+/// roots move with it instead of pointing back at the real storage tree.
+fn redirect_default_storage_root(settings: ServerSettings, vault_path: &Path) -> ServerSettings {
     if Path::new(&settings.server.storage.root) != default_storage_dir() {
-        return;
+        return settings;
     }
     let root = vault_path.with_file_name("storage");
     std::fs::create_dir_all(&root).expect("test storage root should be creatable");
-    settings.server.storage.root = root.display().to_string();
+    settings.with_storage_override(&root)
 }
 
 #[must_use]

From dc79da0dab900e24dbc1980c95ab65e2a8545196 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:04:58 -0400
Subject: [PATCH 21/36] Clean up size chip rendering and tests

---
 .../components/runs-list/run-table-row.tsx    |  6 ++--
 .../app/components/size-chip.test.tsx         | 36 ++++++++++++++-----
 apps/fabro-web/app/components/size-chip.tsx   |  5 +--
 apps/fabro-web/app/routes/runs.tsx            |  2 +-
 4 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/apps/fabro-web/app/components/runs-list/run-table-row.tsx b/apps/fabro-web/app/components/runs-list/run-table-row.tsx
index e7447bce5..5066bc9d8 100644
--- a/apps/fabro-web/app/components/runs-list/run-table-row.tsx
+++ b/apps/fabro-web/app/components/runs-list/run-table-row.tsx
@@ -115,11 +115,9 @@ export function RunTableRow({
         </td>
       )}
       {show("size") && (
-        <td className="whitespace-nowrap px-3 py-2.5 text-center">
+        <td className="relative z-10 px-3 py-2.5 text-center whitespace-nowrap">
           {run.size != null && (
-            <span className="relative z-10 inline-flex">
-              <SizeChip size={run.size} totalUsdMicros={run.totalUsdMicros} />
-            </span>
+            <SizeChip size={run.size} totalUsdMicros={run.totalUsdMicros} />
           )}
         </td>
       )}
diff --git a/apps/fabro-web/app/components/size-chip.test.tsx b/apps/fabro-web/app/components/size-chip.test.tsx
index b355f5db1..498c97f5e 100644
--- a/apps/fabro-web/app/components/size-chip.test.tsx
+++ b/apps/fabro-web/app/components/size-chip.test.tsx
@@ -1,25 +1,43 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import TestRenderer, { act } from "react-test-renderer";
 
+import { setupReactTestEnv } from "../lib/test-utils";
 import { SizeChip } from "./size-chip";
 import { Tooltip } from "./ui";
 
-function tooltipLabel(element: React.ReactElement): string {
+let teardownReactTestEnv: (() => void) | undefined;
+const mountedRenderers: TestRenderer.ReactTestRenderer[] = [];
+
+function render(element: React.ReactElement): TestRenderer.ReactTestRenderer {
   let renderer: TestRenderer.ReactTestRenderer | undefined;
   act(() => {
     renderer = TestRenderer.create(element);
   });
-  return renderer!.root.findByType(Tooltip).props.label as string;
+  mountedRenderers.push(renderer!);
+  return renderer!;
+}
+
+function tooltipLabel(element: React.ReactElement): string {
+  return render(element).root.findByType(Tooltip).props.label as string;
 }
 
 describe("SizeChip", () => {
-  test("renders the size letter", () => {
-    let renderer: TestRenderer.ReactTestRenderer | undefined;
-    act(() => {
-      renderer = TestRenderer.create(<SizeChip size="M" />);
-    });
+  beforeEach(() => {
+    teardownReactTestEnv = setupReactTestEnv();
+  });
 
-    expect(JSON.stringify(renderer!.toJSON())).toContain("M");
+  afterEach(() => {
+    act(() => {
+      for (const renderer of mountedRenderers.splice(0)) {
+        renderer.unmount();
+      }
+    });
+    teardownReactTestEnv?.();
+    teardownReactTestEnv = undefined;
+  });
+
+  test("renders the size letter", () => {
+    expect(JSON.stringify(render(<SizeChip size="M" />).toJSON())).toContain("M");
   });
 
   test("appends the cost to the tooltip", () => {
diff --git a/apps/fabro-web/app/components/size-chip.tsx b/apps/fabro-web/app/components/size-chip.tsx
index d23210955..7563b4c87 100644
--- a/apps/fabro-web/app/components/size-chip.tsx
+++ b/apps/fabro-web/app/components/size-chip.tsx
@@ -1,3 +1,4 @@
+import { memo } from "react";
 import type { RunSize } from "@qltysh/fabro-api-client";
 
 import { formatUsdMicros } from "../lib/format";
@@ -11,7 +12,7 @@ const SIZE_TONE: Record<RunSize, { className: string; note: string | null }> = {
   XL: { className: "bg-coral/15 text-coral",     note: "unhealthy" },
 };
 
-export function SizeChip({
+export const SizeChip = memo(function SizeChip({
   size,
   totalUsdMicros,
 }: {
@@ -30,4 +31,4 @@ export function SizeChip({
       </span>
     </Tooltip>
   );
-}
+});
diff --git a/apps/fabro-web/app/routes/runs.tsx b/apps/fabro-web/app/routes/runs.tsx
index fe21e36c8..b1e09bf67 100644
--- a/apps/fabro-web/app/routes/runs.tsx
+++ b/apps/fabro-web/app/routes/runs.tsx
@@ -418,7 +418,7 @@ function PrCardFooter({ pr, actions }: { pr: RunItem; actions?: string[] }) {
         </div>
       )}
       {pr.size != null && (
-        <span className={`inline-flex ${hasActions ? "" : "ml-auto"}`}>
+        <span className={hasActions ? "inline-flex" : "ml-auto inline-flex"}>
           <SizeChip size={pr.size} totalUsdMicros={pr.totalUsdMicros} />
         </span>
       )}

From 8592a34968b465fa2e408dfe22a1955574dee762 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:13:45 -0400
Subject: [PATCH 22/36] refactor: collapse the split validation paths

Follow-up cleanup on the catalog-free validation split. Same behavior,
fewer parallel code paths.

- Make the catalog an explicit `Option<&Catalog>` on `pipeline::validate`
  instead of a `validate` / `validate_with_catalog` pair, so each call
  site states whether catalog rules run.
- Collapse `preprocess_and_validate`, `preprocess_and_validate_structural`,
  and `preprocess` into one function that takes `TransformOptions`. Its
  `model_resolution` field is now the single source of truth for catalog
  awareness, which drops a 12-argument signature and the
  `too_many_arguments` allow.
- Replace the duplicated resolve-and-preprocess block in
  `operations::validate` with one `validate_in_scope` helper, and drop the
  HashSet -> Vec -> HashSet round trip on the catalog path.
- Extract `configured_default_provider`, previously duplicated between
  `operations::create` and `operations::validate`.
- Delete `validate_manifest_with_environment_defaults`, which had no
  callers outside its own module.
- Share the `server-model.fabro` fixture between the two CLI tests instead
  of inlining it twice. The validate test now asserts the rendered output
  through the usual snapshot helper, which also removes a hand-rolled
  `std::fs::write` and its clippy allow.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/apps/fabro-cli/tests/it/cmd/create.rs     |  14 +-
 lib/apps/fabro-cli/tests/it/cmd/validate.rs   |  43 ++--
 .../fabro-server/src/manifest_validation.rs   |  35 ++-
 .../fabro-workflow/src/operations/create.rs   | 221 +++++++-----------
 .../fabro-workflow/src/operations/validate.rs | 114 +++++----
 .../fabro-workflow/src/pipeline/mod.rs        |   2 +-
 .../fabro-workflow/src/pipeline/validate.rs   |  36 ++-
 .../fabro-workflow/tests/it/integration.rs    |   6 +-
 test/server-model.fabro                       |  10 +
 9 files changed, 191 insertions(+), 290 deletions(-)
 create mode 100644 test/server-model.fabro

diff --git a/lib/apps/fabro-cli/tests/it/cmd/create.rs b/lib/apps/fabro-cli/tests/it/cmd/create.rs
index 462a0996f..488f6a1f5 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/create.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/create.rs
@@ -114,25 +114,13 @@ fn create_defers_provider_validation_to_the_server() {
             .header("Content-Type", "application/json")
             .body(run_status_response(run_id.as_str(), "submitted").to_string());
     });
-    let workflow_path = context.temp_dir.join("server-model.fabro");
-    context.write_temp(
-        "server-model.fabro",
-        r#"digraph ServerModel {
-            graph [goal="Use a server-owned model"]
-            start [shape=Mdiamond]
-            work [prompt="Do work", model="private-model", provider="server-only"]
-            exit [shape=Msquare]
-            start -> work -> exit
-        }"#,
-    );
-
     let output = context
         .create_cmd()
         .args([
             "--server",
             &format!("{}/api/v1", server.base_url()),
             "--dry-run",
-            workflow_path.to_str().unwrap(),
+            fixture("server-model.fabro").to_str().unwrap(),
         ])
         .output()
         .expect("command should execute");
diff --git a/lib/apps/fabro-cli/tests/it/cmd/validate.rs b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
index 2bbec8c76..fcdaec83d 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/validate.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
@@ -69,37 +69,22 @@ fn simple_does_not_connect_to_configured_server() {
     );
 }
 
+/// Offline validation has no model catalog, so a model or provider the server
+/// owns must pass rather than be reported as unknown.
 #[test]
-#[expect(
-    clippy::disallowed_methods,
-    reason = "sync CLI test writes one workflow fixture before spawning the subprocess"
-)]
 fn server_owned_provider_is_not_rejected_by_offline_validation() {
-    let cli = LightweightCli::new();
-    let workflow = cli.home().join("server-model.fabro");
-    std::fs::write(
-        &workflow,
-        r#"digraph ServerModel {
-            graph [goal="Use a server-owned model"]
-            start [shape=Mdiamond]
-            work [prompt="Do work", model="private-model", provider="server-only"]
-            exit [shape=Msquare]
-            start -> work -> exit
-        }"#,
-    )
-    .expect("workflow fixture should be written");
-    let mut cmd = cli.command();
-    cmd.env("FABRO_SERVER", "http://127.0.0.1:9")
-        .arg("validate")
-        .arg(&workflow);
-
-    let output = cmd.output().expect("validate should execute");
-    assert!(
-        output.status.success(),
-        "offline validation should leave provider availability to the server\nstdout:\n{}\nstderr:\n{}",
-        String::from_utf8_lossy(&output.stdout),
-        String::from_utf8_lossy(&output.stderr),
-    );
+    let context = test_context!();
+    let mut cmd = context.validate();
+    cmd.arg(fixture("server-model.fabro"));
+    fabro_snapshot!(context.filters(), cmd, @"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+    ----- stderr -----
+    Workflow: ServerModel (3 nodes, 2 edges)
+    Graph: [FIXTURES]/server-model.fabro
+    Validation: OK
+    ");
 }
 
 #[test]
diff --git a/lib/apps/fabro-server/src/manifest_validation.rs b/lib/apps/fabro-server/src/manifest_validation.rs
index 3016fde65..3d872954f 100644
--- a/lib/apps/fabro-server/src/manifest_validation.rs
+++ b/lib/apps/fabro-server/src/manifest_validation.rs
@@ -3,53 +3,46 @@ use std::sync::Arc;
 
 use anyhow::Result;
 use fabro_api::types;
-use fabro_config::{EnvironmentLayer, MergeMap, RunLayer};
+use fabro_config::RunLayer;
 use fabro_model::Catalog;
 use fabro_workflow::pipeline::TEMPLATE_UNDEFINED_VARIABLE_RULE;
 
 use crate::run_manifest;
 
+/// Validate a manifest without a model catalog. Model and provider
+/// availability is deferred to the server, which owns the catalog.
 pub fn validate_manifest(
     manifest_run_defaults: &RunLayer,
     manifest: &types::RunManifest,
 ) -> Result<types::ValidateResponse> {
-    validate_manifest_with_environment_defaults(
-        manifest_run_defaults,
-        &fabro_environment::seeded_catalog_layer(),
-        manifest,
-    )
+    let prepared = prepare(manifest_run_defaults, manifest)?;
+    let validated = run_manifest::validate_prepared_manifest_structural(&prepared)
+        .map_err(anyhow::Error::new)?;
+    Ok(run_manifest::validate_response(&prepared, &validated))
 }
 
+/// Validate a manifest including the catalog-backed model and provider rules.
 pub fn validate_manifest_with_catalog(
     manifest_run_defaults: &RunLayer,
     manifest: &types::RunManifest,
     catalog: &Arc<Catalog>,
 ) -> Result<types::ValidateResponse> {
-    let prepared = run_manifest::prepare_manifest_with_environment_defaults(
-        manifest_run_defaults,
-        &fabro_environment::seeded_catalog_layer(),
-        &HashMap::new(),
-        manifest,
-    )?;
+    let prepared = prepare(manifest_run_defaults, manifest)?;
     let validated =
         run_manifest::validate_prepared_manifest(&prepared, catalog).map_err(anyhow::Error::new)?;
     Ok(run_manifest::validate_response(&prepared, &validated))
 }
 
-pub fn validate_manifest_with_environment_defaults(
+fn prepare(
     manifest_run_defaults: &RunLayer,
-    manifest_environment_defaults: &MergeMap<EnvironmentLayer>,
     manifest: &types::RunManifest,
-) -> Result<types::ValidateResponse> {
-    let prepared = run_manifest::prepare_manifest_with_environment_defaults(
+) -> Result<run_manifest::PreparedManifest> {
+    run_manifest::prepare_manifest_with_environment_defaults(
         manifest_run_defaults,
-        manifest_environment_defaults,
+        &fabro_environment::seeded_catalog_layer(),
         &HashMap::new(),
         manifest,
-    )?;
-    let validated = run_manifest::validate_prepared_manifest_structural(&prepared)
-        .map_err(anyhow::Error::new)?;
-    Ok(run_manifest::validate_response(&prepared, &validated))
+    )
 }
 
 pub fn promote_template_undefined_variables_to_errors(response: &mut types::ValidateResponse) {
diff --git a/lib/components/fabro-workflow/src/operations/create.rs b/lib/components/fabro-workflow/src/operations/create.rs
index 4fff69898..3e976e824 100644
--- a/lib/components/fabro-workflow/src/operations/create.rs
+++ b/lib/components/fabro-workflow/src/operations/create.rs
@@ -24,13 +24,11 @@ use crate::error::Error;
 use crate::event::{Event, append_event, to_run_event_at};
 use crate::file_resolver::FileResolver;
 use crate::pipeline::types::PersistOptions;
-use crate::pipeline::{
-    self, ModelResolutionOptions, Persisted, TransformOptions, Transformed, Validated,
-};
+use crate::pipeline::{self, ModelResolutionOptions, Persisted, TransformOptions, Validated};
 use crate::records::RunSpec;
 use crate::run_lookup::default_scratch_base;
 use crate::run_materialization::materialize_run;
-use crate::transforms::{RenderMode, Transform};
+use crate::transforms::RenderMode;
 use crate::workflow_bundle::{RunDefinition, WorkflowBundle};
 
 #[derive(Clone, Debug)]
@@ -295,28 +293,20 @@ fn create_from_source(
     file_resolver: Option<Arc<dyn FileResolver>>,
     goal_override: Option<&str>,
 ) -> Result<Persisted, Error> {
-    let template_context = template_context(Some(&options.settings), vars);
-    let mut validated = preprocess_and_validate(
-        dot_source,
-        options.source_name.clone(),
+    let mut validated = preprocess_and_validate(dot_source, goal_override, &TransformOptions {
         current_dir,
         file_resolver,
-        Vec::new(),
-        template_context,
-        goal_override,
-        RenderMode::Structural,
-        options
-            .settings
-            .run
-            .model
-            .provider
-            .as_deref()
-            .filter(|provider| !provider.is_empty())
-            .map(ProviderId::new),
-        &options.configured_providers,
-        false,
-        &options.catalog,
-    )?;
+        template_context: template_context(Some(&options.settings), vars),
+        source_name: options.source_name.clone(),
+        render_mode: RenderMode::Structural,
+        custom_transforms: Vec::new(),
+        model_resolution: Some(ModelResolutionOptions {
+            catalog:            Arc::clone(&options.catalog),
+            default_provider:   configured_default_provider(&options.settings),
+            eligible_providers: options.configured_providers.iter().cloned().collect(),
+            catalog_fallback:   false,
+        }),
+    })?;
 
     validated.promote_template_undefined_variables_to_errors();
     if validated.has_errors() {
@@ -328,96 +318,37 @@ fn create_from_source(
     persist_validated(validated, options)
 }
 
+/// Parse, transform, and validate `dot_source`.
+///
+/// `options.model_resolution` drives both halves of catalog awareness: it
+/// selects concrete models during TRANSFORM and enables the catalog-backed
+/// lint rules during VALIDATE. `None` leaves authored model and provider
+/// selectors untouched for offline structural validation.
 pub(super) fn preprocess_and_validate(
     dot_source: &str,
-    source_name: Option<String>,
-    current_dir: Option<PathBuf>,
-    file_resolver: Option<Arc<dyn FileResolver>>,
-    custom_transforms: Vec<Box<dyn Transform>>,
-    template_context: TemplateContext,
     goal_override: Option<&str>,
-    render_mode: RenderMode,
-    default_provider: Option<ProviderId>,
-    eligible_providers: &[ProviderId],
-    catalog_fallback: bool,
-    catalog: &Arc<Catalog>,
+    options: &TransformOptions,
 ) -> Result<Validated, Error> {
-    let model_resolution = ModelResolutionOptions {
-        catalog: Arc::clone(catalog),
-        default_provider,
-        eligible_providers: eligible_providers.iter().cloned().collect(),
-        catalog_fallback,
-    };
-    let transformed = preprocess(
-        dot_source,
-        source_name,
-        current_dir,
-        file_resolver,
-        custom_transforms,
-        template_context,
-        goal_override,
-        render_mode,
-        Some(model_resolution),
-    )?;
-    Ok(pipeline::validate_with_catalog(
-        transformed,
-        catalog.as_ref(),
-        &[],
-    ))
-}
-
-pub(super) fn preprocess_and_validate_structural(
-    dot_source: &str,
-    source_name: Option<String>,
-    current_dir: Option<PathBuf>,
-    file_resolver: Option<Arc<dyn FileResolver>>,
-    custom_transforms: Vec<Box<dyn Transform>>,
-    template_context: TemplateContext,
-    goal_override: Option<&str>,
-    render_mode: RenderMode,
-) -> Result<Validated, Error> {
-    let transformed = preprocess(
-        dot_source,
-        source_name,
-        current_dir,
-        file_resolver,
-        custom_transforms,
-        template_context,
-        goal_override,
-        render_mode,
-        None,
-    )?;
-    Ok(pipeline::validate(transformed, &[]))
-}
-
-#[expect(
-    clippy::too_many_arguments,
-    reason = "pipeline stages have distinct source, rendering, and model-resolution inputs"
-)]
-fn preprocess(
-    dot_source: &str,
-    source_name: Option<String>,
-    current_dir: Option<PathBuf>,
-    file_resolver: Option<Arc<dyn FileResolver>>,
-    custom_transforms: Vec<Box<dyn Transform>>,
-    template_context: TemplateContext,
-    goal_override: Option<&str>,
-    render_mode: RenderMode,
-    model_resolution: Option<ModelResolutionOptions>,
-) -> Result<Transformed, Error> {
     let mut parsed = pipeline::parse(dot_source)?;
     apply_goal_override(&mut parsed.graph, goal_override);
 
-    let transformed = pipeline::transform(parsed, &TransformOptions {
-        current_dir,
-        file_resolver,
-        template_context,
-        source_name,
-        render_mode,
-        custom_transforms,
-        model_resolution,
-    })?;
-    Ok(transformed)
+    let transformed = pipeline::transform(parsed, options)?;
+    let catalog = options
+        .model_resolution
+        .as_ref()
+        .map(|resolution| resolution.catalog.as_ref());
+    Ok(pipeline::validate(transformed, catalog, &[]))
+}
+
+/// The workflow-level default provider, treating an empty setting as unset.
+pub(super) fn configured_default_provider(settings: &WorkflowSettings) -> Option<ProviderId> {
+    settings
+        .run
+        .model
+        .provider
+        .as_deref()
+        .filter(|provider| !provider.is_empty())
+        .map(ProviderId::new)
 }
 
 pub(super) fn template_context(
@@ -526,6 +457,7 @@ mod tests {
     use super::*;
     use crate::operations::{ValidateInput, validate, validate_with_catalog};
     use crate::pipeline::types::{GOAL_SELF_REFERENCE_RULE, TEMPLATE_UNDEFINED_VARIABLE_RULE};
+    use crate::transforms::Transform;
     use crate::workflow_bundle::BundledWorkflow;
     fn memory_store() -> Arc<Database> {
         Arc::new(Database::new(
@@ -637,21 +569,40 @@ reasoning = false
     fn validate_dot_with_vars(dot_source: &str, vars: HashMap<String, String>) -> Validated {
         preprocess_and_validate(
             dot_source,
-            Some("workflow.fabro".to_string()),
-            Some(PathBuf::from(".")),
             None,
-            Vec::new(),
-            template_context(Some(&WorkflowSettings::default()), vars),
-            None,
-            RenderMode::Structural,
-            None,
-            &test_provider_ids(),
-            false,
-            &test_catalog(),
+            &test_transform_options(
+                PathBuf::from("."),
+                None,
+                RenderMode::Structural,
+                template_context(Some(&WorkflowSettings::default()), vars),
+            ),
         )
         .unwrap()
     }
 
+    /// Catalog-backed TRANSFORM options for the built-in test catalog.
+    fn test_transform_options(
+        current_dir: PathBuf,
+        file_resolver: Option<Arc<dyn FileResolver>>,
+        render_mode: RenderMode,
+        template_context: TemplateContext,
+    ) -> TransformOptions {
+        TransformOptions {
+            current_dir: Some(current_dir),
+            file_resolver,
+            template_context,
+            source_name: Some("workflow.fabro".to_string()),
+            render_mode,
+            custom_transforms: Vec::new(),
+            model_resolution: Some(ModelResolutionOptions {
+                catalog:            test_catalog(),
+                default_provider:   None,
+                eligible_providers: test_provider_ids().into_iter().collect(),
+                catalog_fallback:   false,
+            }),
+        }
+    }
+
     const MINIMAL_DOT: &str = r#"digraph Test {
         graph [goal="Build feature"]
         start [shape=Mdiamond]
@@ -808,17 +759,13 @@ reasoning = false
 
         let result = preprocess_and_validate(
             dot,
-            Some("workflow.fabro".to_string()),
-            Some(PathBuf::from(".")),
             None,
-            Vec::new(),
-            template_context(Some(&WorkflowSettings::default()), HashMap::new()),
-            None,
-            RenderMode::Strict,
-            None,
-            &test_provider_ids(),
-            false,
-            &test_catalog(),
+            &test_transform_options(
+                PathBuf::from("."),
+                None,
+                RenderMode::Strict,
+                template_context(Some(&WorkflowSettings::default()), HashMap::new()),
+            ),
         );
         let Err(err) = result else {
             panic!("expected strict mode to hard-fail on unbound inline prompt");
@@ -845,19 +792,15 @@ reasoning = false
 
         let result = preprocess_and_validate(
             dot,
-            Some("workflow.fabro".to_string()),
-            Some(dir.path().to_path_buf()),
-            Some(Arc::new(crate::file_resolver::FilesystemFileResolver::new(
-                None,
-            ))),
-            Vec::new(),
-            template_context(Some(&WorkflowSettings::default()), HashMap::new()),
             None,
-            RenderMode::Strict,
-            None,
-            &test_provider_ids(),
-            false,
-            &test_catalog(),
+            &test_transform_options(
+                dir.path().to_path_buf(),
+                Some(Arc::new(crate::file_resolver::FilesystemFileResolver::new(
+                    None,
+                ))),
+                RenderMode::Strict,
+                template_context(Some(&WorkflowSettings::default()), HashMap::new()),
+            ),
         );
         let Err(err) = result else {
             panic!("expected strict mode to hard-fail on unbound imported prompt");
diff --git a/lib/components/fabro-workflow/src/operations/validate.rs b/lib/components/fabro-workflow/src/operations/validate.rs
index 7ac5e4531..4000443e1 100644
--- a/lib/components/fabro-workflow/src/operations/validate.rs
+++ b/lib/components/fabro-workflow/src/operations/validate.rs
@@ -1,17 +1,15 @@
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use std::path::PathBuf;
 use std::sync::Arc;
 
 use fabro_model::{Catalog, ProviderId};
 use fabro_types::WorkflowSettings;
 
-use super::create::{
-    preprocess_and_validate, preprocess_and_validate_structural, template_context,
-};
+use super::create::{configured_default_provider, preprocess_and_validate, template_context};
 use super::source::{ResolveWorkflowInput, WorkflowInput, resolve_workflow};
 use crate::error::Error;
 use crate::operations::RenderMode;
-use crate::pipeline::Validated;
+use crate::pipeline::{ModelResolutionOptions, TransformOptions, Validated};
 use crate::transforms::Transform;
 
 pub struct ValidateInput {
@@ -24,39 +22,25 @@ pub struct ValidateInput {
     pub custom_transforms: Vec<Box<dyn Transform>>,
 }
 
+/// Which providers catalog-backed model resolution may select from. The
+/// workflow's own default provider is read from the resolved settings, so it
+/// is not part of the caller's request.
+struct CatalogScope<'a> {
+    catalog:            &'a Arc<Catalog>,
+    eligible_providers: HashSet<ProviderId>,
+    /// Fall back to the full catalog when the eligible providers cannot
+    /// supply a requested model, instead of erroring.
+    catalog_fallback:   bool,
+}
+
 /// Parse, transform, and structurally validate a DOT source string without a
-/// model catalog.
+/// model catalog. Model and provider availability is left to the caller that
+/// owns a catalog — typically the server.
 ///
 /// Returns `Validated` even when validation produced errors. Call
 /// `validated.raise_on_errors()` if the caller wants to fail fast.
 pub fn validate(input: ValidateInput) -> Result<Validated, Error> {
-    let ValidateInput {
-        workflow,
-        settings,
-        vars,
-        cwd,
-        custom_transforms,
-    } = input;
-    let resolved = resolve_workflow(ResolveWorkflowInput {
-        workflow,
-        settings,
-        cwd,
-    })
-    .map_err(|err| Error::Parse(err.to_string()))?;
-
-    preprocess_and_validate_structural(
-        &resolved.raw_source,
-        resolved
-            .dot_path
-            .as_ref()
-            .map(|path| path.display().to_string()),
-        resolved.current_dir,
-        resolved.file_resolver,
-        custom_transforms,
-        template_context(Some(&resolved.settings), vars),
-        resolved.goal_override.as_deref(),
-        RenderMode::Structural,
-    )
+    validate_in_scope(input, None)
 }
 
 /// Parse, transform, and validate a DOT source string against `catalog`.
@@ -64,8 +48,14 @@ pub fn validate_with_catalog(
     input: ValidateInput,
     catalog: &Arc<Catalog>,
 ) -> Result<Validated, Error> {
-    let eligible_providers = catalog.all_provider_ids().into_iter().collect::<Vec<_>>();
-    validate_with_eligible_providers(input, catalog, &eligible_providers, false)
+    validate_in_scope(
+        input,
+        Some(CatalogScope {
+            catalog,
+            eligible_providers: catalog.all_provider_ids(),
+            catalog_fallback: false,
+        }),
+    )
 }
 
 /// Parse, transform, and validate, resolving models against the ready
@@ -76,14 +66,19 @@ pub fn validate_with_ready_providers(
     catalog: &Arc<Catalog>,
     ready_providers: &[ProviderId],
 ) -> Result<Validated, Error> {
-    validate_with_eligible_providers(input, catalog, ready_providers, true)
+    validate_in_scope(
+        input,
+        Some(CatalogScope {
+            catalog,
+            eligible_providers: ready_providers.iter().cloned().collect(),
+            catalog_fallback: true,
+        }),
+    )
 }
 
-fn validate_with_eligible_providers(
+fn validate_in_scope(
     input: ValidateInput,
-    catalog: &Arc<Catalog>,
-    eligible_providers: &[ProviderId],
-    catalog_fallback: bool,
+    scope: Option<CatalogScope<'_>>,
 ) -> Result<Validated, Error> {
     let ValidateInput {
         workflow,
@@ -99,28 +94,27 @@ fn validate_with_eligible_providers(
     })
     .map_err(|err| Error::Parse(err.to_string()))?;
 
+    let model_resolution = scope.map(|scope| ModelResolutionOptions {
+        catalog:            Arc::clone(scope.catalog),
+        default_provider:   configured_default_provider(&resolved.settings),
+        eligible_providers: scope.eligible_providers,
+        catalog_fallback:   scope.catalog_fallback,
+    });
+
     preprocess_and_validate(
         &resolved.raw_source,
-        resolved
-            .dot_path
-            .as_ref()
-            .map(|path| path.display().to_string()),
-        resolved.current_dir,
-        resolved.file_resolver,
-        custom_transforms,
-        template_context(Some(&resolved.settings), vars),
         resolved.goal_override.as_deref(),
-        RenderMode::Structural,
-        resolved
-            .settings
-            .run
-            .model
-            .provider
-            .as_deref()
-            .filter(|provider| !provider.is_empty())
-            .map(fabro_model::ProviderId::new),
-        eligible_providers,
-        catalog_fallback,
-        catalog,
+        &TransformOptions {
+            current_dir: resolved.current_dir,
+            file_resolver: resolved.file_resolver,
+            template_context: template_context(Some(&resolved.settings), vars),
+            source_name: resolved
+                .dot_path
+                .as_ref()
+                .map(|path| path.display().to_string()),
+            render_mode: RenderMode::Structural,
+            custom_transforms,
+            model_resolution,
+        },
     )
 }
diff --git a/lib/components/fabro-workflow/src/pipeline/mod.rs b/lib/components/fabro-workflow/src/pipeline/mod.rs
index c1cc3b4f9..46c271907 100644
--- a/lib/components/fabro-workflow/src/pipeline/mod.rs
+++ b/lib/components/fabro-workflow/src/pipeline/mod.rs
@@ -26,4 +26,4 @@ pub use types::{
     ModelResolutionOptions, Parsed, Persisted, PullRequestOptions, ResumeState, SandboxEnvSpec,
     TEMPLATE_UNDEFINED_VARIABLE_RULE, TransformOptions, Transformed, Validated,
 };
-pub use validate::{validate, validate_with_catalog};
+pub use validate::validate;
diff --git a/lib/components/fabro-workflow/src/pipeline/validate.rs b/lib/components/fabro-workflow/src/pipeline/validate.rs
index 00601b4a4..32bfaf69c 100644
--- a/lib/components/fabro-workflow/src/pipeline/validate.rs
+++ b/lib/components/fabro-workflow/src/pipeline/validate.rs
@@ -1,28 +1,19 @@
+use fabro_model::Catalog;
 use fabro_validate::LintRule;
 
 use super::types::{Transformed, Validated};
 
-/// VALIDATE phase: run catalog-free lint rules against the transformed graph.
+/// VALIDATE phase: run lint rules against the transformed graph.
+///
+/// Catalog-backed rules (model and provider availability) run only when
+/// `catalog` is `Some`. Offline callers pass `None` so a workflow naming a
+/// server-owned model is left for the server to judge.
 ///
 /// **Infallible.** Always returns `Validated` with diagnostics. Caller decides
 /// whether to fail via `validated.raise_on_errors()`.
-pub fn validate(transformed: Transformed, extra_rules: &[&dyn LintRule]) -> Validated {
-    let Transformed {
-        graph,
-        source,
-        mut diagnostics,
-    } = transformed;
-    diagnostics.extend(fabro_validate::validate(&graph, extra_rules));
-    Validated::new(graph, source, diagnostics)
-}
-
-/// VALIDATE phase: run catalog-free and catalog-backed lint rules.
-///
-/// **Infallible.** Always returns `Validated` with diagnostics. Caller decides
-/// whether to fail via `validated.raise_on_errors()`.
-pub fn validate_with_catalog(
+pub fn validate(
     transformed: Transformed,
-    catalog: &fabro_model::Catalog,
+    catalog: Option<&Catalog>,
     extra_rules: &[&dyn LintRule],
 ) -> Validated {
     let Transformed {
@@ -30,11 +21,10 @@ pub fn validate_with_catalog(
         source,
         mut diagnostics,
     } = transformed;
-    diagnostics.extend(fabro_validate::validate_with_catalog(
-        &graph,
-        catalog,
-        extra_rules,
-    ));
+    diagnostics.extend(match catalog {
+        Some(catalog) => fabro_validate::validate_with_catalog(&graph, catalog, extra_rules),
+        None => fabro_validate::validate(&graph, extra_rules),
+    });
     Validated::new(graph, source, diagnostics)
 }
 
@@ -57,7 +47,7 @@ mod tests {
             model_resolution:  None,
         })
         .unwrap();
-        validate(transformed, &[])
+        validate(transformed, None, &[])
     }
 
     #[test]
diff --git a/lib/components/fabro-workflow/tests/it/integration.rs b/lib/components/fabro-workflow/tests/it/integration.rs
index b07f600fe..51030ec05 100644
--- a/lib/components/fabro-workflow/tests/it/integration.rs
+++ b/lib/components/fabro-workflow/tests/it/integration.rs
@@ -4853,9 +4853,7 @@ async fn manager_loop_child_workflow_e2e() {
 
 #[tokio::test]
 async fn import_e2e_through_engine() {
-    use fabro_workflow::pipeline::{
-        ModelResolutionOptions, TransformOptions, transform, validate_with_catalog,
-    };
+    use fabro_workflow::pipeline::{ModelResolutionOptions, TransformOptions, transform, validate};
 
     let dir = tempfile::tempdir().unwrap();
     let catalog = std::sync::Arc::new(
@@ -4910,7 +4908,7 @@ async fn import_e2e_through_engine() {
         model_resolution:  Some(ModelResolutionOptions::new(std::sync::Arc::clone(&catalog))),
     })
     .unwrap();
-    let validated = validate_with_catalog(transformed, catalog.as_ref(), &[]);
+    let validated = validate(transformed, Some(catalog.as_ref()), &[]);
     validated
         .raise_on_errors()
         .expect("validation should pass after imports expand");
diff --git a/test/server-model.fabro b/test/server-model.fabro
new file mode 100644
index 000000000..099f3c8d9
--- /dev/null
+++ b/test/server-model.fabro
@@ -0,0 +1,10 @@
+digraph ServerModel {
+    graph [goal="Use a server-owned model"]
+
+    start [shape=Mdiamond, label="Start"]
+    exit  [shape=Msquare, label="Exit"]
+
+    work [label="Work", prompt="Do work", model="private-model", provider="server-only"]
+
+    start -> work -> exit
+}

From 04c931e9d35e8b9ec1e36cc9743c4e8f168c8d44 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:14:32 -0400
Subject: [PATCH 23/36] Simplify edge-only node validation

---
 lib/apps/fabro-cli/src/shared/utilities.rs    |  31 ++---
 lib/apps/fabro-cli/tests/it/cmd/validate.rs   |   4 +-
 .../fabro-graphviz/src/parser/semantic.rs     | 112 ++++++++--------
 .../src/rules/edge_target_exists.rs           |  13 +-
 .../fabro-workflow/src/transforms/import.rs   | 121 +++++++++++++-----
 lib/foundation/fabro-types/src/graph.rs       |  18 +--
 .../fabro-types/src/run_event/mod.rs          |  20 +--
 7 files changed, 166 insertions(+), 153 deletions(-)

diff --git a/lib/apps/fabro-cli/src/shared/utilities.rs b/lib/apps/fabro-cli/src/shared/utilities.rs
index 8cfb05af7..c6b048a1d 100644
--- a/lib/apps/fabro-cli/src/shared/utilities.rs
+++ b/lib/apps/fabro-cli/src/shared/utilities.rs
@@ -66,43 +66,28 @@ fn print_diagnostic(d: &Diagnostic, styles: &Styles, printer: Printer) {
         _ => String::new(),
     };
     let source_prefix = source_prefix(d);
+    let body = if source_prefix.is_empty() {
+        format!("{location}: {}", d.message)
+    } else {
+        format!(": {source_prefix}{}{location}", d.message)
+    };
     match d.severity {
-        Severity::Error if source_prefix.is_empty() => fabro_util::printerr!(
-            printer,
-            "{}{location}: {} ({})",
-            styles.red.apply_to("error"),
-            d.message,
-            styles.dim.apply_to(&d.rule),
-        ),
         Severity::Error => fabro_util::printerr!(
             printer,
-            "{}: {source_prefix}{}{location} ({})",
+            "{}{body} ({})",
             styles.red.apply_to("error"),
-            d.message,
-            styles.dim.apply_to(&d.rule),
-        ),
-        Severity::Warning if source_prefix.is_empty() => fabro_util::printerr!(
-            printer,
-            "{}{location}: {} ({})",
-            styles.yellow.apply_to("warning"),
-            d.message,
             styles.dim.apply_to(&d.rule),
         ),
         Severity::Warning => fabro_util::printerr!(
             printer,
-            "{}: {source_prefix}{}{location} ({})",
+            "{}{body} ({})",
             styles.yellow.apply_to("warning"),
-            d.message,
             styles.dim.apply_to(&d.rule),
         ),
         Severity::Info => fabro_util::printerr!(
             printer,
             "{}",
-            styles.dim.apply_to(if source_prefix.is_empty() {
-                format!("info{location}: {} ({})", d.message, d.rule)
-            } else {
-                format!("info: {source_prefix}{}{location} ({})", d.message, d.rule)
-            }),
+            styles.dim.apply_to(format!("info{body} ({})", d.rule)),
         ),
     }
 }
diff --git a/lib/apps/fabro-cli/tests/it/cmd/validate.rs b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
index caeab11ca..bf38fe31a 100644
--- a/lib/apps/fabro-cli/tests/it/cmd/validate.rs
+++ b/lib/apps/fabro-cli/tests/it/cmd/validate.rs
@@ -295,12 +295,10 @@ fn edge_only_node() {
     exit_code: 1
     ----- stdout -----
     ----- stderr -----
-    Workflow: EdgeOnlyNode (3 nodes, 2 edges)
+    Workflow: EdgeOnlyNode (2 nodes, 2 edges)
     Graph: [FIXTURES]/edge_only_node.fabro
     error [node: misspelled_node]: Node 'misspelled_node' is referenced by edge 'start -> misspelled_node' but has no node declaration (edge_target_exists)
       fix: Declare node 'misspelled_node' or correct the edge endpoint
-    warning [node: misspelled_node]: LLM node 'misspelled_node' has no prompt or label attribute (prompt_on_llm_nodes)
-      fix: Add a prompt or label attribute
       × Validation failed
     ");
 }
diff --git a/lib/components/fabro-graphviz/src/parser/semantic.rs b/lib/components/fabro-graphviz/src/parser/semantic.rs
index 4e9433e6b..ed68a0fa8 100644
--- a/lib/components/fabro-graphviz/src/parser/semantic.rs
+++ b/lib/components/fabro-graphviz/src/parser/semantic.rs
@@ -1,4 +1,4 @@
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use std::time::Duration;
 
 use crate::error::Error;
@@ -57,49 +57,44 @@ fn derive_class_from_label(label: &str) -> String {
         .collect()
 }
 
-/// How a statement named a node. A node stays implicit only while every
-/// mention of it is an edge endpoint, so declaration order does not matter.
-#[derive(Clone, Copy, PartialEq, Eq)]
-enum Mention {
-    Declaration,
-    EdgeEndpoint,
+fn collect_declared_node_ids(statements: &[Statement], node_ids: &mut HashSet<String>) {
+    for statement in statements {
+        match statement {
+            Statement::Node(node) => {
+                node_ids.insert(node.id.clone());
+            }
+            Statement::Subgraph(subgraph) => {
+                collect_declared_node_ids(&subgraph.statements, node_ids);
+            }
+            _ => {}
+        }
+    }
 }
 
 struct SemanticState {
-    graph:         Graph,
-    node_defaults: HashMap<String, AttrValue>,
-    edge_defaults: HashMap<String, AttrValue>,
+    graph:             Graph,
+    declared_node_ids: HashSet<String>,
+    node_defaults:     HashMap<String, AttrValue>,
+    edge_defaults:     HashMap<String, AttrValue>,
 }
 
 impl SemanticState {
-    fn new(name: String) -> Self {
+    fn new(name: String, declared_node_ids: HashSet<String>) -> Self {
         Self {
-            graph:         Graph::new(name),
+            graph: Graph::new(name),
+            declared_node_ids,
             node_defaults: HashMap::new(),
             edge_defaults: HashMap::new(),
         }
     }
 
-    /// Insert the node if this is the first statement to mention it, and record
-    /// whether the workflow ever declares it.
-    fn ensure_node(&mut self, id: &str, mention: Mention) {
-        if !self.graph.nodes.contains_key(id) {
+    fn ensure_node(&mut self, id: &str) -> &mut Node {
+        let node_defaults = &self.node_defaults;
+        self.graph.nodes.entry(id.to_string()).or_insert_with(|| {
             let mut node = Node::new(id);
-            for (k, v) in &self.node_defaults {
-                node.attrs.insert(k.clone(), v.clone());
-            }
-            node.implicit = mention == Mention::EdgeEndpoint;
-            self.graph.nodes.insert(id.to_string(), node);
-            return;
-        }
-        if mention == Mention::Declaration {
-            let node = self
-                .graph
-                .nodes
-                .get_mut(id)
-                .expect("contains_key returned true, so get_mut cannot return None");
-            node.implicit = false;
-        }
+            node.attrs.clone_from(node_defaults);
+            node
+        })
     }
 
     fn add_class_to_node(node: &mut Node, cls: &str) {
@@ -110,12 +105,7 @@ impl SemanticState {
     }
 
     fn process_node(&mut self, node_stmt: &NodeStmt, subgraph_class: Option<&str>) {
-        self.ensure_node(&node_stmt.id, Mention::Declaration);
-        let node = self
-            .graph
-            .nodes
-            .get_mut(&node_stmt.id)
-            .expect("node was just inserted by ensure_node, so get_mut cannot return None");
+        let node = self.ensure_node(&node_stmt.id);
         if let Some(attrs) = &node_stmt.attrs {
             for (k, v) in attrs {
                 node.attrs.insert(k.clone(), convert_value(v));
@@ -131,11 +121,6 @@ impl SemanticState {
             .and_then(AttrValue::as_str)
             .map(String::from);
         if let Some(class_str) = class_str {
-            let node = self
-                .graph
-                .nodes
-                .get_mut(&node_stmt.id)
-                .expect("node was just inserted by ensure_node, so get_mut cannot return None");
             for cls in class_str.split(',') {
                 let cls = cls.trim().to_string();
                 if !cls.is_empty() && !node.classes.contains(&cls) {
@@ -147,12 +132,11 @@ impl SemanticState {
 
     fn process_edge(&mut self, edge_stmt: &EdgeStmt, subgraph_class: Option<&str>) {
         for id in &edge_stmt.nodes {
-            self.ensure_node(id, Mention::EdgeEndpoint);
+            if !self.declared_node_ids.contains(id) {
+                continue;
+            }
+            let node = self.ensure_node(id);
             if let Some(cls) = subgraph_class {
-                let node =
-                    self.graph.nodes.get_mut(id).expect(
-                        "node was just inserted by ensure_node, so get_mut cannot return None",
-                    );
                 Self::add_class_to_node(node, cls);
             }
         }
@@ -271,7 +255,9 @@ impl SemanticState {
 ///
 /// Returns an error if the AST cannot be converted to a valid graph.
 pub fn ast_to_graph(dot: &DotGraph) -> Result<Graph, Error> {
-    let mut state = SemanticState::new(dot.name.clone());
+    let mut declared_node_ids = HashSet::new();
+    collect_declared_node_ids(&dot.statements, &mut declared_node_ids);
+    let mut state = SemanticState::new(dot.name.clone(), declared_node_ids);
     let empty = HashMap::new();
     state.process_statements(&dot.statements, None, &empty, &empty);
     Ok(state.graph)
@@ -535,7 +521,7 @@ mod tests {
     }
 
     #[test]
-    fn ast_to_graph_implicit_nodes_from_edges() {
+    fn ast_to_graph_keeps_undeclared_edge_endpoints_out_of_nodes() {
         let dot = DotGraph {
             name:       "Implicit".into(),
             statements: vec![Statement::Edge(EdgeStmt {
@@ -545,14 +531,12 @@ mod tests {
         };
 
         let graph = ast_to_graph(&dot).unwrap();
-        assert!(graph.nodes.contains_key("a"));
-        assert!(graph.nodes.contains_key("b"));
-        assert!(graph.nodes["a"].implicit);
-        assert!(graph.nodes["b"].implicit);
+        assert!(graph.nodes.is_empty());
+        assert_eq!(graph.edges, vec![Edge::new("a", "b")]);
     }
 
     #[test]
-    fn ast_to_graph_marks_declared_nodes_explicit() {
+    fn ast_to_graph_includes_only_declared_edge_endpoints() {
         let dot = DotGraph {
             name:       "Declared".into(),
             statements: vec![
@@ -568,8 +552,8 @@ mod tests {
         };
 
         let graph = ast_to_graph(&dot).unwrap();
-        assert!(!graph.nodes["a"].implicit);
-        assert!(graph.nodes["b"].implicit);
+        assert!(graph.nodes.contains_key("a"));
+        assert!(!graph.nodes.contains_key("b"));
     }
 
     #[test]
@@ -577,10 +561,12 @@ mod tests {
         let dot = DotGraph {
             name:       "DeclaredLater".into(),
             statements: vec![
+                Statement::NodeDefaults(vec![("model".into(), AstValue::Str("first".into()))]),
                 Statement::Edge(EdgeStmt {
                     nodes: vec!["a".into(), "b".into()],
                     attrs: None,
                 }),
+                Statement::NodeDefaults(vec![("model".into(), AstValue::Str("second".into()))]),
                 Statement::Node(NodeStmt {
                     id:    "b".into(),
                     attrs: Some(vec![("prompt".into(), AstValue::Str("Do it".into()))]),
@@ -589,7 +575,15 @@ mod tests {
         };
 
         let graph = ast_to_graph(&dot).unwrap();
-        assert!(!graph.nodes["b"].implicit);
+        assert!(graph.nodes.contains_key("b"));
+        assert!(!graph.nodes.contains_key("a"));
+        assert_eq!(
+            graph.nodes["b"]
+                .attrs
+                .get("model")
+                .and_then(AttrValue::as_str),
+            Some("first")
+        );
     }
 
     #[test]
@@ -612,7 +606,7 @@ mod tests {
         };
 
         let graph = ast_to_graph(&dot).unwrap();
-        assert!(!graph.nodes["plan"].implicit);
-        assert!(graph.nodes["start"].implicit);
+        assert!(graph.nodes.contains_key("plan"));
+        assert!(!graph.nodes.contains_key("start"));
     }
 }
diff --git a/lib/components/fabro-validate/src/rules/edge_target_exists.rs b/lib/components/fabro-validate/src/rules/edge_target_exists.rs
index adc70283b..3cfbe2130 100644
--- a/lib/components/fabro-validate/src/rules/edge_target_exists.rs
+++ b/lib/components/fabro-validate/src/rules/edge_target_exists.rs
@@ -11,13 +11,6 @@ pub(super) fn rule() -> Box<dyn LintRule> {
 struct Rule;
 
 impl Rule {
-    /// An edge endpoint is only usable when the workflow declares it. A node
-    /// the parser synthesized from the edge itself carries no attributes, so it
-    /// would silently run as a default agent stage.
-    fn is_declared(graph: &Graph, node_id: &str) -> bool {
-        graph.nodes.get(node_id).is_some_and(|node| !node.implicit)
-    }
-
     fn diagnostic(&self, node_id: &str, from: &str, to: &str) -> Diagnostic {
         Diagnostic {
             rule: self.name().to_string(),
@@ -47,7 +40,7 @@ impl LintRule for Rule {
         let mut reported = HashSet::new();
         for edge in &graph.edges {
             for endpoint in [&edge.to, &edge.from] {
-                if !Self::is_declared(graph, endpoint) && reported.insert(endpoint) {
+                if !graph.nodes.contains_key(endpoint) && reported.insert(endpoint) {
                     diagnostics.push(self.diagnostic(endpoint, &edge.from, &edge.to));
                 }
             }
@@ -71,8 +64,8 @@ mod tests {
 
     fn undeclared_nodes(graph: &Graph) -> Vec<String> {
         Rule.apply(graph)
-            .iter()
-            .map(|d| d.node_id.clone().expect("diagnostic should name a node"))
+            .into_iter()
+            .map(|d| d.node_id.expect("diagnostic should name a node"))
             .collect()
     }
 
diff --git a/lib/components/fabro-workflow/src/transforms/import.rs b/lib/components/fabro-workflow/src/transforms/import.rs
index cfda146c3..f2c5e74fd 100644
--- a/lib/components/fabro-workflow/src/transforms/import.rs
+++ b/lib/components/fabro-workflow/src/transforms/import.rs
@@ -339,19 +339,18 @@ impl ImportTransform {
             .edges
             .retain(|edge| edge.from != placeholder_id && edge.to != placeholder_id);
 
-        for (node_id, node) in imported_graph.nodes {
+        for (node_id, mut merged_node) in imported_graph.nodes {
             if node_id == start_id || node_id == exit_id {
                 continue;
             }
 
             let prefixed_id = format!("{placeholder_id}.{node_id}");
-            let mut merged_node = Node::new(&prefixed_id);
-            merged_node.implicit = node.implicit;
+            merged_node.id.clone_from(&prefixed_id);
+            let imported_attrs = std::mem::take(&mut merged_node.attrs);
             merged_node.attrs.clone_from(&placeholder.default_attrs);
-            merged_node.attrs.extend(node.attrs);
+            merged_node.attrs.extend(imported_attrs);
             Self::remap_retry_target(&mut merged_node.attrs, placeholder_id);
 
-            merged_node.classes = node.classes;
             for class_name in &placeholder.class_names {
                 Self::push_class(&mut merged_node.classes, class_name);
             }
@@ -650,7 +649,10 @@ impl PreparedImport {
         self.graph.nodes.iter().all(|(node_id, node)| {
             ImportTransform::is_start_sentinel(node_id, node)
                 || ImportTransform::is_exit_sentinel(node_id, node)
-        })
+        }) && matches!(
+            self.graph.edges.as_slice(),
+            [edge] if edge.from == self.start_id && edge.to == self.exit_id
+        )
     }
 }
 
@@ -910,6 +912,7 @@ mod tests {
         assert!(!graph.nodes.contains_key("validate"));
         assert!(graph.nodes.contains_key("validate.lint"));
         assert!(graph.nodes.contains_key("validate.test"));
+        assert_eq!(graph.nodes["validate.lint"].id, "validate.lint");
         assert!(!graph.nodes.contains_key("validate.start"));
         assert!(!graph.nodes.contains_key("validate.exit"));
 
@@ -953,27 +956,7 @@ mod tests {
     }
 
     #[test]
-    fn imported_node_declarations_survive_splicing() {
-        let dir = tempfile::tempdir().unwrap();
-        write_file(&dir.path().join("validate.fabro"), basic_import_source());
-
-        let graph = apply_import(
-            r#"digraph Deploy {
-                start [shape=Mdiamond]
-                validate [import="./validate.fabro"]
-                exit [shape=Msquare]
-                start -> validate -> exit
-            }"#,
-            dir.path(),
-            None,
-        );
-
-        assert!(!graph.nodes["validate.lint"].implicit);
-        assert!(!graph.nodes["validate.test"].implicit);
-    }
-
-    #[test]
-    fn edge_only_node_in_imported_fragment_stays_undeclared() {
+    fn edge_only_node_in_imported_fragment_stays_missing() {
         let dir = tempfile::tempdir().unwrap();
         write_file(
             &dir.path().join("validate.fabro"),
@@ -996,8 +979,46 @@ mod tests {
             None,
         );
 
-        assert!(graph.nodes["validate.typo"].implicit);
-        assert!(!graph.nodes["validate.lint"].implicit);
+        assert!(!graph.nodes.contains_key("validate.typo"));
+        assert!(graph.nodes.contains_key("validate.lint"));
+    }
+
+    #[test]
+    fn edge_only_body_is_not_treated_as_empty_import() {
+        let dir = tempfile::tempdir().unwrap();
+        write_file(
+            &dir.path().join("validate.fabro"),
+            r"digraph validate {
+                start [shape=Mdiamond]
+                exit [shape=Msquare]
+                start -> typo -> exit
+            }",
+        );
+
+        let graph = apply_import(
+            r#"digraph Deploy {
+                start [shape=Mdiamond]
+                validate [import="./validate.fabro"]
+                exit [shape=Msquare]
+                start -> validate -> exit
+            }"#,
+            dir.path(),
+            None,
+        );
+
+        assert!(!graph.nodes.contains_key("validate.typo"));
+        assert!(
+            graph
+                .edges
+                .iter()
+                .any(|edge| edge.from == "start" && edge.to == "validate.typo")
+        );
+        assert!(
+            graph
+                .edges
+                .iter()
+                .any(|edge| edge.from == "validate.typo" && edge.to == "exit")
+        );
     }
 
     #[test]
@@ -1179,6 +1200,48 @@ mod tests {
         );
     }
 
+    #[test]
+    fn imported_start_and_exit_sentinels_must_be_declared() {
+        let dir = tempfile::tempdir().unwrap();
+        let host = r#"digraph Deploy {
+            start [shape=Mdiamond]
+            validate [import="./validate.fabro"]
+            exit [shape=Msquare]
+            start -> validate -> exit
+        }"#;
+        let cases = [
+            (
+                r#"digraph validate {
+                    work [prompt="Run checks"]
+                    exit [shape=Msquare]
+                    start -> work -> exit
+                }"#,
+                "imported workflow must have exactly one start node, found 0",
+            ),
+            (
+                r#"digraph validate {
+                    start [shape=Mdiamond]
+                    work [prompt="Run checks"]
+                    start -> work -> exit
+                }"#,
+                "imported workflow must have exactly one exit node, found 0",
+            ),
+        ];
+
+        for (source, expected_error) in cases {
+            write_file(&dir.path().join("validate.fabro"), source);
+            let graph = apply_import(host, dir.path(), None);
+
+            assert_eq!(
+                graph.nodes["validate"]
+                    .attrs
+                    .get("import_error")
+                    .and_then(AttrValue::as_str),
+                Some(expected_error)
+            );
+        }
+    }
+
     #[test]
     fn multiple_entry_nodes_poison_placeholder() {
         let dir = tempfile::tempdir().unwrap();
diff --git a/lib/foundation/fabro-types/src/graph.rs b/lib/foundation/fabro-types/src/graph.rs
index 3ed6851a6..7ef9bad99 100644
--- a/lib/foundation/fabro-types/src/graph.rs
+++ b/lib/foundation/fabro-types/src/graph.rs
@@ -119,26 +119,20 @@ pub fn shape_to_handler_type(shape: &str) -> Option<&'static str> {
 /// A node in the workflow graph.
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
 pub struct Node {
-    pub id:       String,
-    pub attrs:    HashMap<String, AttrValue>,
+    pub id:      String,
+    pub attrs:   HashMap<String, AttrValue>,
     /// CSS-like classes for model stylesheet targeting (from `class` attr and
     /// subgraph derivation).
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub classes:  Vec<String>,
-    /// True when the node was synthesized from an edge endpoint instead of a
-    /// node declaration. Validation rejects these because an edge-only node in
-    /// an executable workflow is almost always a typo.
-    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
-    pub implicit: bool,
+    pub classes: Vec<String>,
 }
 
 impl Node {
     pub fn new(id: impl Into<String>) -> Self {
         Self {
-            id:       id.into(),
-            attrs:    HashMap::new(),
-            classes:  Vec::new(),
-            implicit: false,
+            id:      id.into(),
+            attrs:   HashMap::new(),
+            classes: Vec::new(),
         }
     }
 
diff --git a/lib/foundation/fabro-types/src/run_event/mod.rs b/lib/foundation/fabro-types/src/run_event/mod.rs
index e4e99e59f..6680fff2e 100644
--- a/lib/foundation/fabro-types/src/run_event/mod.rs
+++ b/lib/foundation/fabro-types/src/run_event/mod.rs
@@ -926,8 +926,6 @@ impl<'de> Deserialize<'de> for RunEvent {
 
 #[cfg(test)]
 mod tests {
-    use std::collections::HashMap;
-
     use serde_json::json;
 
     use super::*;
@@ -992,21 +990,9 @@ mod tests {
     #[test]
     fn run_event_deserializes_adjacent_layout() {
         let settings = WorkflowSettings::default();
-        let graph = Graph {
-            name:  "test".to_string(),
-            nodes: HashMap::from([("start".to_string(), Node {
-                id:       "start".to_string(),
-                attrs:    HashMap::new(),
-                classes:  Vec::new(),
-                implicit: false,
-            })]),
-            edges: vec![Edge {
-                from:  "start".to_string(),
-                to:    "done".to_string(),
-                attrs: HashMap::new(),
-            }],
-            attrs: HashMap::new(),
-        };
+        let mut graph = Graph::new("test");
+        graph.nodes.insert("start".to_string(), Node::new("start"));
+        graph.edges.push(Edge::new("start", "done"));
 
         let line = json!({
             "id": "evt_2",

From 96f70a9aea79fbed85065732e152eb66df9f37e3 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:20:59 -0400
Subject: [PATCH 24/36] fix(timing): simplify live timing projections

---
 apps/fabro-web/app/lib/queries.ts             |  21 ++-
 apps/fabro-web/app/lib/query-keys.test.ts     |  60 ------
 apps/fabro-web/app/lib/run-actions.ts         |  10 +-
 apps/fabro-web/app/lib/run-events.test.tsx    |  24 ++-
 apps/fabro-web/app/lib/run-events.ts          |  42 ++++-
 apps/fabro-web/app/routes/run-detail.tsx      |  11 +-
 apps/fabro-web/app/routes/run-detail/model.ts |   9 -
 docs/public/api-reference/fabro-api.yaml      |  11 ++
 .../fabro-server/src/server/handler/runs.rs   |   4 +-
 lib/components/fabro-store/src/run_state.rs   | 171 ++++++++++++++----
 .../fabro-store/src/run_summary_store.rs      |   4 +-
 lib/components/fabro-store/src/slate/mod.rs   |  12 ++
 .../tests/stage_projection_round_trip.rs      |   2 +
 .../fabro-types/src/run_projection.rs         |  66 +++++--
 lib/foundation/fabro-types/src/timing.rs      |   6 -
 .../scripts/normalize-generated.ts            |   5 +
 .../src/models/batch-delete-runs-request.ts   |   2 +-
 .../src/models/batch-run-lifecycle-request.ts |   2 +-
 .../fabro-api-client/src/models/run-timing.ts |   4 +-
 .../src/models/stage-projection.ts            |   4 +
 .../src/models/stage-timing.ts                |   4 +-
 .../src/models/stage-tool-batch-projection.ts |   2 +-
 22 files changed, 311 insertions(+), 165 deletions(-)

diff --git a/apps/fabro-web/app/lib/queries.ts b/apps/fabro-web/app/lib/queries.ts
index aa7328b5e..9900a585e 100644
--- a/apps/fabro-web/app/lib/queries.ts
+++ b/apps/fabro-web/app/lib/queries.ts
@@ -1,3 +1,4 @@
+import { useCallback } from "react";
 import useSWR, { type SWRConfiguration } from "swr";
 import type {
   ApiQuestion,
@@ -181,18 +182,20 @@ export function useRunsPage(opts: RunsPageOptions = {}, enabled = true) {
 }
 
 export function useRun(id: string | undefined, refreshInterval?: number) {
+  const pollingInterval = useCallback(
+    (run: Run | null | undefined) =>
+      refreshInterval &&
+      run?.timestamps.started_at &&
+      !isTerminalRunStatus(run.lifecycle.status.kind)
+        ? refreshInterval
+        : 0,
+    [refreshInterval],
+  );
+
   return useSWR<Run | null>(
     id ? queryKeys.runs.detail(id) : null,
     () => apiNullableData(() => runsApi.retrieveRun(id!)),
-    refreshInterval
-      ? {
-          refreshInterval: (run) =>
-            run?.timestamps.started_at &&
-            !isTerminalRunStatus(run.lifecycle.status.kind)
-              ? refreshInterval
-              : 0,
-        }
-      : undefined,
+    refreshInterval ? { refreshInterval: pollingInterval } : undefined,
   );
 }
 
diff --git a/apps/fabro-web/app/lib/query-keys.test.ts b/apps/fabro-web/app/lib/query-keys.test.ts
index 52a5ccef3..31346b721 100644
--- a/apps/fabro-web/app/lib/query-keys.test.ts
+++ b/apps/fabro-web/app/lib/query-keys.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
 import { queryKeys } from "./query-keys";
-import { queryKeysForRunEvent } from "./run-events";
 
 describe("queryKeys", () => {
   test("uses semantic tuples as stable SWR keys and keeps SSE URLs explicit", () => {
@@ -61,63 +60,4 @@ describe("queryKeys", () => {
     expect(queryKeys.runs.attachUrl("run 1")).toBe("/api/v1/runs/run%201/attach");
   });
 
-  test("event-mapped keys match query hook resources", () => {
-    expect(queryKeysForRunEvent("run-1", "checkpoint.completed")).toEqual(
-      [
-        ...queryKeys.runs.filesAllScopes("run-1"),
-        queryKeys.runs.commits("run-1"),
-      ],
-    );
-    expect(queryKeysForRunEvent("run-1", "stage.completed", "stage-1")).toEqual([
-      queryKeys.runs.stages("run-1"),
-      queryKeys.runs.billing("run-1"),
-      queryKeys.runs.events("run-1", 1000),
-      queryKeys.runs.graph("run-1", "LR"),
-      queryKeys.runs.graph("run-1", "TB"),
-      queryKeys.runs.detail("run-1"),
-      queryKeys.runs.state("run-1"),
-      queryKeys.runs.stageEvents("run-1", "stage-1"),
-      queryKeys.runs.stageContextWindow("run-1", "stage-1"),
-    ]);
-    expect(queryKeysForRunEvent("run-1", "run.title.updated")).toEqual([
-      queryKeys.runs.detail("run-1"),
-    ]);
-  });
-
-  test("agent activity events invalidate per-stage resources", () => {
-    for (const event of [
-      "stage.prompt",
-      "command.started",
-      "command.completed",
-    ]) {
-      expect(queryKeysForRunEvent("run-1", event, "stage-1")).toEqual([
-        queryKeys.runs.stageEvents("run-1", "stage-1"),
-        queryKeys.runs.stageContextWindow("run-1", "stage-1"),
-      ]);
-    }
-    for (const event of ["agent.tool.started", "agent.tool.completed"]) {
-      expect(queryKeysForRunEvent("run-1", event, "stage-1")).toEqual([
-        queryKeys.runs.detail("run-1"),
-        queryKeys.runs.state("run-1"),
-        queryKeys.runs.billing("run-1"),
-        queryKeys.runs.stageEvents("run-1", "stage-1"),
-        queryKeys.runs.stageContextWindow("run-1", "stage-1"),
-      ]);
-    }
-    expect(queryKeysForRunEvent("run-1", "agent.message", "stage-1")).toEqual([
-      queryKeys.runs.detail("run-1"),
-      queryKeys.runs.state("run-1"),
-      queryKeys.runs.billing("run-1"),
-      queryKeys.runs.stageEvents("run-1", "stage-1"),
-      queryKeys.runs.stageContextWindow("run-1", "stage-1"),
-    ]);
-  });
-
-  test("agent message without a node_id still invalidates projected state", () => {
-    expect(queryKeysForRunEvent("run-1", "agent.message")).toEqual([
-      queryKeys.runs.detail("run-1"),
-      queryKeys.runs.state("run-1"),
-      queryKeys.runs.billing("run-1"),
-    ]);
-  });
 });
diff --git a/apps/fabro-web/app/lib/run-actions.ts b/apps/fabro-web/app/lib/run-actions.ts
index a45034088..bf9f1590c 100644
--- a/apps/fabro-web/app/lib/run-actions.ts
+++ b/apps/fabro-web/app/lib/run-actions.ts
@@ -111,10 +111,7 @@ export async function deleteRuns(
   request?: Request,
 ): Promise<BatchDeleteRunsResponse> {
   try {
-    // See `batchRunLifecycleAction` for the `as unknown as` rationale:
-    // openapi-generator types `uniqueItems` arrays as `Set<T>` while the wire
-    // contract is a JSON array.
-    const body = { run_ids: runIds, force } as unknown as BatchDeleteRunsRequest;
+    const body: BatchDeleteRunsRequest = { run_ids: runIds, force };
     return await apiData(() => runsApi.batchDeleteRuns(body, requestSignalOptions(request)));
   } catch (error) {
     throw lifecycleActionErrorFromError(error);
@@ -284,10 +281,7 @@ async function batchRunLifecycleAction(
   request?: Request,
 ): Promise<BatchRunLifecycleResponse> {
   try {
-    // openapi-generator's TypeScript client represents `uniqueItems` arrays as
-    // Set<T>, but the HTTP wire contract is still a JSON array. Keep an array
-    // here so Axios serializes the request body correctly.
-    const body = { run_ids: runIds } as unknown as BatchRunLifecycleRequest;
+    const body: BatchRunLifecycleRequest = { run_ids: runIds };
     switch (action) {
       case "archive":
         return await apiData(() => runsApi.batchArchiveRuns(body, requestSignalOptions(request)));
diff --git a/apps/fabro-web/app/lib/run-events.test.tsx b/apps/fabro-web/app/lib/run-events.test.tsx
index 4fce18b4d..f4b345f28 100644
--- a/apps/fabro-web/app/lib/run-events.test.tsx
+++ b/apps/fabro-web/app/lib/run-events.test.tsx
@@ -131,8 +131,6 @@ describe("queryKeysForRunEvent", () => {
   test("every inference projection transition invalidates live run state", () => {
     for (const event of [
       "agent.llm.started",
-      "agent.llm.first_output",
-      "agent.llm.retry",
       "agent.error",
     ]) {
       expect(queryKeysForRunEvent("run-1", event, "code@1")).toEqual([
@@ -142,6 +140,12 @@ describe("queryKeysForRunEvent", () => {
         queryKeys.runs.stageEvents("run-1", "code@1"),
       ]);
     }
+    for (const event of ["agent.llm.first_output", "agent.llm.retry"]) {
+      expect(queryKeysForRunEvent("run-1", event, "code@1")).toEqual([
+        queryKeys.runs.state("run-1"),
+        queryKeys.runs.stageEvents("run-1", "code@1"),
+      ]);
+    }
     expect(
       queryKeysForRunEvent("run-1", "agent.message", "code@1"),
     ).toEqual([
@@ -158,6 +162,22 @@ describe("queryKeysForRunEvent", () => {
     ]);
   });
 
+  test("ACP timing events invalidate live summaries and stage events", () => {
+    for (const event of [
+      "agent.acp.started",
+      "agent.acp.completed",
+      "agent.acp.cancelled",
+      "agent.acp.timed_out",
+    ]) {
+      expect(queryKeysForRunEvent("run-1", event, "code@1")).toEqual([
+        queryKeys.runs.detail("run-1"),
+        queryKeys.runs.state("run-1"),
+        queryKeys.runs.billing("run-1"),
+        queryKeys.runs.stageEvents("run-1", "code@1"),
+      ]);
+    }
+  });
+
   test("tool timing events invalidate live summaries and stage resources", () => {
     for (const event of ["agent.tool.started", "agent.tool.completed"]) {
       expect(queryKeysForRunEvent("run-1", event, "code@1")).toEqual([
diff --git a/apps/fabro-web/app/lib/run-events.ts b/apps/fabro-web/app/lib/run-events.ts
index 523774e18..ad5354a7b 100644
--- a/apps/fabro-web/app/lib/run-events.ts
+++ b/apps/fabro-web/app/lib/run-events.ts
@@ -118,10 +118,22 @@ const INFERENCE_EVENTS = new Set([
   "agent.error",
   "agent.session.ended",
 ]);
+const INFERENCE_TIMING_EVENTS = new Set([
+  "agent.llm.started",
+  "agent.message",
+  "agent.error",
+  "agent.session.ended",
+]);
 const TOOL_TIMING_EVENTS = new Set([
   "agent.tool.started",
   "agent.tool.completed",
 ]);
+const ACP_TIMING_EVENTS = new Set([
+  "agent.acp.started",
+  "agent.acp.completed",
+  "agent.acp.cancelled",
+  "agent.acp.timed_out",
+]);
 // Todo / task mutation events refresh `getRunState` consumers (so per-stage
 // todo projections update live) and the run events list.
 const TODO_EVENTS = new Set([
@@ -130,6 +142,14 @@ const TODO_EVENTS = new Set([
   "todo.deleted",
 ]);
 
+function liveTimingKeys(runId: string): Key[] {
+  return [
+    queryKeys.runs.detail(runId),
+    queryKeys.runs.state(runId),
+    queryKeys.runs.billing(runId),
+  ];
+}
+
 export function queryKeysForRunEvent(
   runId: string,
   event: string,
@@ -202,11 +222,9 @@ export function queryKeysForRunEvent(
   }
 
   if (INFERENCE_EVENTS.has(event)) {
-    const keys: Key[] = [
-      queryKeys.runs.detail(runId),
-      queryKeys.runs.state(runId),
-      queryKeys.runs.billing(runId),
-    ];
+    const keys = INFERENCE_TIMING_EVENTS.has(event)
+      ? liveTimingKeys(runId)
+      : [queryKeys.runs.state(runId)];
     if (stageId) {
       keys.push(queryKeys.runs.stageEvents(runId, stageId));
       if (event === "agent.message") {
@@ -217,11 +235,7 @@ export function queryKeysForRunEvent(
   }
 
   if (TOOL_TIMING_EVENTS.has(event)) {
-    const keys: Key[] = [
-      queryKeys.runs.detail(runId),
-      queryKeys.runs.state(runId),
-      queryKeys.runs.billing(runId),
-    ];
+    const keys = liveTimingKeys(runId);
     if (stageId) {
       keys.push(queryKeys.runs.stageEvents(runId, stageId));
       keys.push(queryKeys.runs.stageContextWindow(runId, stageId));
@@ -229,6 +243,14 @@ export function queryKeysForRunEvent(
     return keys;
   }
 
+  if (ACP_TIMING_EVENTS.has(event)) {
+    const keys = liveTimingKeys(runId);
+    if (stageId) {
+      keys.push(queryKeys.runs.stageEvents(runId, stageId));
+    }
+    return keys;
+  }
+
   if (event === "watchdog.timeout") {
     return stageId ? [queryKeys.runs.stageEvents(runId, stageId)] : [];
   }
diff --git a/apps/fabro-web/app/routes/run-detail.tsx b/apps/fabro-web/app/routes/run-detail.tsx
index ad2d78986..566c5d776 100644
--- a/apps/fabro-web/app/routes/run-detail.tsx
+++ b/apps/fabro-web/app/routes/run-detail.tsx
@@ -19,6 +19,7 @@ import {
 } from "../components/ui";
 import { mutateRunListCaches } from "../lib/board-cache";
 import { useDemoMode } from "../lib/demo-mode";
+import { useTickingNow } from "../lib/time";
 import { useSWRConfig } from "swr";
 import {
   useArchiveRun,
@@ -56,10 +57,7 @@ import {
   lifecycleActionVisibility,
   updateLifecycleToastState,
 } from "./run-detail/lifecycle-toasts";
-import {
-  buildRunDetailRun,
-  useTickingNow,
-} from "./run-detail/model";
+import { buildRunDetailRun } from "./run-detail/model";
 import {
   buildRunDetailTabs,
   childRouteLayoutFlags,
@@ -118,7 +116,10 @@ export default function RunDetail({ params }: { params: { id: string } }) {
     childrenCount,
   });
   const steerBarRef = useRef<SteerBarHandle | null>(null);
-  const now = useTickingNow(RUN_TIMING_REFRESH_INTERVAL_MS);
+  const now = useTickingNow(
+    summary != null && summary.timestamps.completed_at == null,
+    RUN_TIMING_REFRESH_INTERVAL_MS,
+  );
   const { fullHeight, hideSteerBar } = childRouteLayoutFlags(matches);
 
   useRunEvents(params.id);
diff --git a/apps/fabro-web/app/routes/run-detail/model.ts b/apps/fabro-web/app/routes/run-detail/model.ts
index 7cfcba1a6..758009ea7 100644
--- a/apps/fabro-web/app/routes/run-detail/model.ts
+++ b/apps/fabro-web/app/routes/run-detail/model.ts
@@ -1,6 +1,3 @@
-import { useState } from "react";
-
-import { useInterval } from "../../hooks/effects";
 import {
   isRunStatus,
   mapRunToRunItem,
@@ -12,12 +9,6 @@ export function classNames(...classes: Array<string | false | null | undefined>)
   return classes.filter(Boolean).join(" ");
 }
 
-export function useTickingNow(intervalMs: number): number {
-  const [now, setNow] = useState(() => Date.now());
-  useInterval(() => setNow(Date.now()), intervalMs);
-  return now;
-}
-
 export type RunDetailRun = ReturnType<typeof mapRunToRunItem> & {
   statusLabel: string;
   statusDot: string;
diff --git a/docs/public/api-reference/fabro-api.yaml b/docs/public/api-reference/fabro-api.yaml
index f2460a69b..b7fd14abd 100644
--- a/docs/public/api-reference/fabro-api.yaml
+++ b/docs/public/api-reference/fabro-api.yaml
@@ -10758,6 +10758,13 @@ components:
             Open inference bracket, if the event log contains one. Present means
             a model request was dispatched and no closing event has been seen —
             not that the model is computing right now.
+        acp_started_at:
+          type: ["string", "null"]
+          format: date-time
+          description: >
+            Start of an external ACP agent process, if one is running. ACP
+            agents do not expose Fabro's internal LLM brackets, so the process
+            lifetime supplies their live inference estimate.
         agent_control:
           $ref: "#/components/schemas/AgentControlState"
           description: Whether the agent is executing normally or waiting for steering after an interrupt.
@@ -12315,6 +12322,8 @@ components:
       type: object
       required:
         - wall_time_ms
+        - inference_time_ms
+        - tool_time_ms
         - active_time_ms
       properties:
         wall_time_ms:
@@ -12354,6 +12363,8 @@ components:
       type: object
       required:
         - wall_time_ms
+        - inference_time_ms
+        - tool_time_ms
         - active_time_ms
       properties:
         wall_time_ms:
diff --git a/lib/apps/fabro-server/src/server/handler/runs.rs b/lib/apps/fabro-server/src/server/handler/runs.rs
index 4b9acdf1c..0327d0cda 100644
--- a/lib/apps/fabro-server/src/server/handler/runs.rs
+++ b/lib/apps/fabro-server/src/server/handler/runs.rs
@@ -325,8 +325,8 @@ async fn run_summary_at(
         return Ok(None);
     };
     if summary.timestamps.completed_at.is_none() {
-        let cached = state.stores.runs.get_cached_run(run_id).await?;
-        if let Some(timing) = cached.and_then(|cached| cached.projection.live_run_timing(now)) {
+        let projection = state.stores.runs.get_cached_projection(run_id).await?;
+        if let Some(timing) = projection.and_then(|projection| projection.live_run_timing(now)) {
             summary.timing = Some(timing);
         }
     }
diff --git a/lib/components/fabro-store/src/run_state.rs b/lib/components/fabro-store/src/run_state.rs
index 14e86124a..644048c90 100644
--- a/lib/components/fabro-store/src/run_state.rs
+++ b/lib/components/fabro-store/src/run_state.rs
@@ -521,12 +521,17 @@ impl RunProjectionReducer for RunProjection {
                 };
                 stage.agent_tools.clone_from(&props.tools);
             }
-            // `AgentAcpStarted` is the start-of-process signal for an external
-            // ACP agent. `provider_used` is intentionally sourced from the
-            // subsequent `AgentSessionActivated` event, which carries the
-            // canonical provider/model. ACP runs without a steering hub never
-            // emit activation and so legitimately leave `provider_used`
-            // unset — matching legacy ACP behavior.
+            EventBody::AgentAcpStarted(props) => {
+                let Some(stage) = stage_at_stored_or_visit(self, stored, props.visit, event.seq)
+                else {
+                    return Ok(());
+                };
+                stage.open_acp_inference(ts);
+                // `provider_used` is intentionally sourced from the subsequent
+                // `AgentSessionActivated` event, which carries the canonical
+                // provider/model. ACP runs without a steering hub never emit
+                // activation and legitimately leave it unset.
+            }
             EventBody::CommandStarted(props) => {
                 let script_invocation = serde_json::to_value(props).map_err(|err| {
                     Error::InvalidEvent(format!("invalid command.started payload: {err}"))
@@ -553,6 +558,7 @@ impl RunProjectionReducer for RunProjection {
                 let Some(stage) = stage_at_current_visit(self, stored, event.seq) else {
                     return Ok(());
                 };
+                stage.close_acp_inference(props.duration_ms);
                 apply_agent_terminal(
                     "agent.acp",
                     stage,
@@ -565,6 +571,7 @@ impl RunProjectionReducer for RunProjection {
                 let Some(stage) = stage_at_current_visit(self, stored, event.seq) else {
                     return Ok(());
                 };
+                stage.close_acp_inference(props.duration_ms);
                 apply_agent_terminal(
                     "agent.acp",
                     stage,
@@ -577,6 +584,7 @@ impl RunProjectionReducer for RunProjection {
                 let Some(stage) = stage_at_current_visit(self, stored, event.seq) else {
                     return Ok(());
                 };
+                stage.close_acp_inference(props.duration_ms);
                 apply_agent_terminal(
                     "agent.acp",
                     stage,
@@ -595,6 +603,11 @@ impl RunProjectionReducer for RunProjection {
                 // Branches bypass the engine's StageStarted/StageCompleted
                 // lifecycle. Seed started_at so the branch stage drives a live
                 // wall-clock timer while it runs (the entry is created Running).
+                let handler = stored
+                    .node_id
+                    .as_deref()
+                    .and_then(|node_id| self.spec().graph.nodes.get(node_id))
+                    .map(|node| StageHandler::from_handler_type(node.handler_type()));
                 let is_new = stored
                     .stage_id
                     .as_ref()
@@ -605,6 +618,9 @@ impl RunProjectionReducer for RunProjection {
                 if stage.started_at.is_none() {
                     stage.started_at = Some(ts);
                 }
+                if stage.handler.is_none() {
+                    stage.handler = handler;
+                }
                 if is_new {
                     stage.graph_visit = props.graph_visit;
                     stage
@@ -1056,29 +1072,13 @@ fn open_inference_bracket(
     });
 }
 
-/// Resolve the stage's `inference` slot when it holds a bracket this event is
-/// allowed to mutate.
-///
-/// `None` when the event came from a child session, when the stage has no
-/// open bracket, or when the bracket belongs to a different session — the
-/// last case matters after failover, which discards the session and builds a
-/// new one within a single visit.
-fn matching_inference_slot<'a>(
-    state: &'a mut RunProjection,
-    stored: &RunEvent,
-    visit: u32,
-    seq: u32,
-) -> Option<&'a mut Option<StageInferenceProjection>> {
-    Some(&mut matching_inference_stage(state, stored, visit, seq)?.inference)
-}
-
 /// Resolve the stage owning a bracket this event is allowed to mutate,
 /// borrowing the whole projection so the caller can also fold elapsed time
 /// into the stage's live accumulators.
 ///
-/// Same gating as [`matching_inference_slot`]: `None` for child-session
-/// events, for a stage with no open bracket, and for a bracket belonging to a
-/// different session (which is what post-failover events look like).
+/// Returns `None` for child-session events, for a stage with no open bracket,
+/// and for a bracket belonging to a different session (which is what
+/// post-failover events look like).
 fn matching_inference_stage<'a>(
     state: &'a mut RunProjection,
     stored: &RunEvent,
@@ -1104,7 +1104,9 @@ fn matching_inference_bracket<'a>(
     visit: u32,
     seq: u32,
 ) -> Option<&'a mut StageInferenceProjection> {
-    matching_inference_slot(state, stored, visit, seq)?.as_mut()
+    matching_inference_stage(state, stored, visit, seq)?
+        .inference
+        .as_mut()
 }
 
 /// Close the bracket on a stage-addressed terminal event, folding its elapsed
@@ -1486,6 +1488,7 @@ fn finalize_unfinished_stages_after_run_failed(
         // Close any brackets still open so their spans are not dropped on the
         // floor when the live estimate is frozen into `timing` below.
         close_bracket_on_stage(stage, timestamp);
+        stage.close_open_acp_inference(timestamp);
         stage.close_open_tool_batch(timestamp);
 
         // Freeze the live estimate before flipping to a terminal state:
@@ -1613,15 +1616,16 @@ mod tests {
     };
     use fabro_types::settings::run::{DockerfileSource, EnvironmentProvider};
     use fabro_types::{
-        AgentBackend, AgentControlState, AutomationRef, BilledModelUsage, BilledTokenCounts,
-        BlockedReason, Checkpoint, CheckpointRecord, CommandTermination, EventBody,
-        FailureCategory, FailureDetail, FailureReason, Graph, McpServerStatus, Outcome,
-        PendingReason, PermissionLevel, PullRequestLink, QuestionType, ReasoningEffort,
+        AgentBackend, AgentControlState, AttrValue, AutomationRef, BilledModelUsage,
+        BilledTokenCounts, BlockedReason, Checkpoint, CheckpointRecord, CommandTermination,
+        EventBody, FailureCategory, FailureDetail, FailureReason, Graph, McpServerStatus, Node,
+        Outcome, PendingReason, PermissionLevel, PullRequestLink, QuestionType, ReasoningEffort,
         RunApprovalState, RunBlobId, RunControlAction, RunDiff, RunEvent, RunSize, RunSpec,
         RunStatus, Speed, StageContextWindowBreakdownItem, StageContextWindowCategory,
         StageContextWindowCountMethod, StageContextWindowProjection, StageContextWindowStaleness,
-        StageContextWindowWarning, StageModelUsage, StageOutcome, StageState, SubAgentStatus,
-        SuccessReason, WorkflowSettings, first_event_seq, fixtures, test_support,
+        StageContextWindowWarning, StageHandler, StageModelUsage, StageOutcome, StageState,
+        StageTiming, SubAgentStatus, SuccessReason, WorkflowSettings, first_event_seq, fixtures,
+        test_support,
     };
     use serde_json::json;
 
@@ -2930,6 +2934,49 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parallel_branch_started_uses_the_graph_handler_for_live_timing() {
+        for (handler_type, handler, expected) in [
+            (
+                "prompt",
+                StageHandler::Prompt,
+                StageTiming::new(5_000, 5_000, 0),
+            ),
+            (
+                "command",
+                StageHandler::Command,
+                StageTiming::new(5_000, 0, 5_000),
+            ),
+        ] {
+            let mut spec = test_run_spec();
+            let mut node = Node::new("review");
+            node.attrs.insert(
+                "type".to_string(),
+                AttrValue::String(handler_type.to_string()),
+            );
+            spec.graph.nodes.insert(node.id.clone(), node);
+            let mut state = RunProjection::new("Test run".to_string(), spec, Utc::now());
+            let branch = StageId::new("review", 1);
+
+            state
+                .apply_event(&test_stage_event_at(
+                    3,
+                    "2026-04-07T12:00:00Z",
+                    EventBody::ParallelBranchStarted(ParallelBranchStartedProps {
+                        index:                 0,
+                        graph_visit:           None,
+                        resumed_from_stage_id: None,
+                    }),
+                    branch.clone(),
+                ))
+                .unwrap();
+
+            let stage = state.stage(&branch).unwrap();
+            assert_eq!(stage.handler, Some(handler));
+            assert_eq!(stage.live_timing(test_dt("2026-04-07T12:00:05Z")), expected);
+        }
+    }
+
     fn start_stage(state: &mut RunProjection, stage_id: &StageId) {
         state
             .apply_event(&test_stage_event(
@@ -3074,6 +3121,66 @@ mod tests {
         assert_eq!(provider_used.model.as_deref(), Some("fake"));
     }
 
+    #[test]
+    fn acp_events_accumulate_live_inference_time() {
+        let mut state = initialized_projection();
+        let stage_id = StageId::new("code", 1);
+
+        state
+            .apply_event(&test_stage_event_at(
+                3,
+                "2026-04-07T12:00:00Z",
+                EventBody::StageStarted(StageStartedProps {
+                    graph_visit:           None,
+                    resumed_from_stage_id: None,
+                    index:                 0,
+                    handler_type:          "agent".to_string(),
+                    attempt:               1,
+                    max_attempts:          1,
+                }),
+                stage_id.clone(),
+            ))
+            .unwrap();
+        state
+            .apply_event(&test_stage_event_at(
+                4,
+                "2026-04-07T12:00:05Z",
+                EventBody::AgentAcpStarted(AgentAcpStartedProps {
+                    visit:       1,
+                    command:     "python fake_agent.py".to_string(),
+                    config_name: Some("fake".to_string()),
+                }),
+                stage_id.clone(),
+            ))
+            .unwrap();
+
+        let stage = state.stage(&stage_id).unwrap();
+        assert_eq!(
+            stage.live_timing(test_dt("2026-04-07T12:00:15Z")),
+            StageTiming::new(15_000, 10_000, 0)
+        );
+
+        state
+            .apply_event(&test_stage_event_at(
+                5,
+                "2026-04-07T12:00:17Z",
+                EventBody::AgentAcpCompleted(AgentAcpCompletedProps {
+                    stdout:      "done".to_string(),
+                    stderr:      String::new(),
+                    stop_reason: "end_turn".to_string(),
+                    duration_ms: 12_000,
+                }),
+                stage_id.clone(),
+            ))
+            .unwrap();
+
+        let stage = state.stage(&stage_id).unwrap();
+        assert_eq!(
+            stage.live_timing(test_dt("2026-04-07T12:00:20Z")),
+            StageTiming::new(20_000, 12_000, 0)
+        );
+    }
+
     #[test]
     fn agent_acp_completed_updates_stage_output_projection() {
         let mut state = initialized_projection();
diff --git a/lib/components/fabro-store/src/run_summary_store.rs b/lib/components/fabro-store/src/run_summary_store.rs
index 42e1d72a7..d80936dc7 100644
--- a/lib/components/fabro-store/src/run_summary_store.rs
+++ b/lib/components/fabro-store/src/run_summary_store.rs
@@ -3,7 +3,7 @@ use std::fmt::Write as _;
 use std::sync::LazyLock;
 
 use chrono::{DateTime, Utc};
-use fabro_types::{BilledTokenCounts, Run, RunId, RunSize, RunStatusKind, RunTiming};
+use fabro_types::{BilledTokenCounts, Run, RunId, RunSize, RunStatusKind, RunTiming, timing};
 use sqlx::sqlite::{SqliteConnection, SqliteRow};
 use sqlx::{QueryBuilder, Row as _, Sqlite, SqlitePool};
 use strum::VariantArray as _;
@@ -545,7 +545,7 @@ fn overlay_live_wall_time(run: &mut Run, now: DateTime<Utc>) {
     let Some(started_at) = run.timestamps.started_at else {
         return;
     };
-    let wall_time_ms = RunTiming::wall_time_ms_since(started_at, now);
+    let wall_time_ms = timing::elapsed_ms(started_at, now);
     run.timing = Some(
         run.timing
             .unwrap_or_else(|| RunTiming::wall_only(wall_time_ms))
diff --git a/lib/components/fabro-store/src/slate/mod.rs b/lib/components/fabro-store/src/slate/mod.rs
index 617d56565..275084dbb 100644
--- a/lib/components/fabro-store/src/slate/mod.rs
+++ b/lib/components/fabro-store/src/slate/mod.rs
@@ -327,6 +327,18 @@ impl Database {
         Ok(self.projection_cache.get(run_id).await)
     }
 
+    pub async fn get_cached_projection(
+        &self,
+        run_id: &RunId,
+    ) -> Result<Option<Arc<RunProjection>>> {
+        self.warm_projection_cache().await?;
+        Ok(self
+            .projection_cache
+            .projection_snapshot(run_id)
+            .await
+            .map(|(projection, _)| projection))
+    }
+
     pub async fn get_cached_summary(
         &self,
         run_id: &RunId,
diff --git a/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs b/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
index 22a544e69..602b6c8c7 100644
--- a/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
+++ b/lib/foundation/fabro-api/tests/stage_projection_round_trip.rs
@@ -172,6 +172,7 @@ fn stage_projection_without_inference_round_trips() {
 
     let stage: StageProjection = serde_json::from_value(value.clone()).unwrap();
     assert!(stage.inference.is_none());
+    assert!(stage.acp_started_at.is_none());
     assert!(stage.tool_batch.is_none());
     assert_eq!(stage.live_inference_ms, 0);
     assert_eq!(stage.live_tool_ms, 0);
@@ -338,6 +339,7 @@ fn stage_projection_round_trips_representative_json() {
             "first_output_kind": "text",
             "retries": 0
         },
+        "acp_started_at": "2026-04-29T12:34:00Z",
         "agent_control": "running",
         "state": "succeeded"
     });
diff --git a/lib/foundation/fabro-types/src/run_projection.rs b/lib/foundation/fabro-types/src/run_projection.rs
index e2b9ad3f6..5c63dd6bb 100644
--- a/lib/foundation/fabro-types/src/run_projection.rs
+++ b/lib/foundation/fabro-types/src/run_projection.rs
@@ -411,6 +411,12 @@ pub struct StageProjection {
     /// the authority on whether a run is actually stuck.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub inference:             Option<StageInferenceProjection>,
+    /// Start of an external ACP agent process, if one is running.
+    ///
+    /// ACP agents do not emit Fabro's internal LLM brackets, so their process
+    /// lifetime is the best available live inference estimate.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub acp_started_at:        Option<DateTime<Utc>>,
     #[serde(default)]
     pub agent_control:         AgentControlState,
     pub state:                 StageState,
@@ -568,6 +574,7 @@ impl StageProjection {
             mcp_servers: Vec::new(),
             context_window: None,
             inference: None,
+            acp_started_at: None,
             agent_control: AgentControlState::default(),
             provider_used: None,
             diff: None,
@@ -660,7 +667,9 @@ impl StageProjection {
                 let open_inference = self
                     .inference
                     .as_ref()
-                    .map_or(0, |inference| timing::elapsed_ms(inference.started_at, now));
+                    .map(|inference| inference.started_at)
+                    .or(self.acp_started_at)
+                    .map_or(0, |started_at| timing::elapsed_ms(started_at, now));
                 let open_tool = self
                     .tool_batch
                     .as_ref()
@@ -692,6 +701,30 @@ impl StageProjection {
         self.live_inference_ms = self.live_inference_ms.saturating_add(elapsed_ms);
     }
 
+    /// Record the start of an external ACP agent process.
+    pub fn open_acp_inference(&mut self, started_at: DateTime<Utc>) {
+        self.close_open_acp_inference(started_at);
+        self.acp_started_at = Some(started_at);
+    }
+
+    /// Close an ACP process with its measured duration.
+    ///
+    /// The duration covers the complete process. Use the larger value so a
+    /// replayed terminal event or a projection restored mid-process cannot
+    /// double-count it.
+    pub fn close_acp_inference(&mut self, duration_ms: u64) {
+        self.acp_started_at = None;
+        self.live_inference_ms = self.live_inference_ms.max(duration_ms);
+    }
+
+    /// Fold an open ACP process into the live accumulator at a run boundary.
+    pub fn close_open_acp_inference(&mut self, now: DateTime<Utc>) {
+        let Some(started_at) = self.acp_started_at.take() else {
+            return;
+        };
+        self.accumulate_inference_ms(timing::elapsed_ms(started_at, now));
+    }
+
     /// Record a dispatched tool call, opening a batch if none is outstanding.
     ///
     /// If a replacement root session starts work before the old session's end
@@ -768,6 +801,7 @@ impl StageProjection {
         self.live_inference_ms = 0;
         self.live_tool_ms = 0;
         self.inference = None;
+        self.acp_started_at = None;
         self.tool_batch = None;
     }
 
@@ -927,7 +961,7 @@ impl RunProjection {
     #[must_use]
     pub fn live_run_timing(&self, now: DateTime<Utc>) -> Option<RunTiming> {
         let start = self.start.as_ref()?;
-        let wall_time_ms = RunTiming::wall_time_ms_since(start.start_time, now);
+        let wall_time_ms = timing::elapsed_ms(start.start_time, now);
         let active = self
             .stages
             .values()
@@ -1291,6 +1325,23 @@ mod live_timing_tests {
         );
     }
 
+    #[test]
+    fn acp_process_counts_as_live_inference_and_uses_measured_duration() {
+        let mut stage = running(StageHandler::Agent);
+        stage.open_acp_inference(at(30));
+
+        assert_eq!(
+            stage.live_timing(at(45)),
+            StageTiming::new(45_000, 15_000, 0)
+        );
+
+        stage.close_acp_inference(14_500);
+        assert_eq!(
+            stage.live_timing(at(45)),
+            StageTiming::new(45_000, 14_500, 0)
+        );
+    }
+
     #[test]
     fn prompt_stage_counts_elapsed_as_inference() {
         let stage = running(StageHandler::Prompt);
@@ -1426,17 +1477,6 @@ mod live_timing_tests {
             "concurrent branches legitimately sum past run wall time"
         );
     }
-}
-
-#[cfg(test)]
-mod live_timing_legacy_tests {
-    use chrono::{DateTime, TimeZone, Utc};
-
-    use crate::{StageProjection, StageState, StageTiming, first_event_seq};
-
-    fn at(seconds: i64) -> DateTime<Utc> {
-        Utc.timestamp_opt(1_700_000_000 + seconds, 0).unwrap()
-    }
 
     #[test]
     fn a_legacy_stage_without_a_recorded_handler_uses_its_accumulators() {
diff --git a/lib/foundation/fabro-types/src/timing.rs b/lib/foundation/fabro-types/src/timing.rs
index 812a72ef2..c7a03d1e9 100644
--- a/lib/foundation/fabro-types/src/timing.rs
+++ b/lib/foundation/fabro-types/src/timing.rs
@@ -174,12 +174,6 @@ impl RunTiming {
             ..self
         }
     }
-
-    /// Milliseconds elapsed from `start` to `now`, clamped at zero.
-    #[must_use]
-    pub fn wall_time_ms_since(start: DateTime<Utc>, now: DateTime<Utc>) -> u64 {
-        elapsed_ms(start, now)
-    }
 }
 
 impl From<StageTiming> for RunTiming {
diff --git a/lib/packages/fabro-api-client/scripts/normalize-generated.ts b/lib/packages/fabro-api-client/scripts/normalize-generated.ts
index 4bd6f85b4..aa5dbd81e 100644
--- a/lib/packages/fabro-api-client/scripts/normalize-generated.ts
+++ b/lib/packages/fabro-api-client/scripts/normalize-generated.ts
@@ -4,6 +4,10 @@
 // blank lines at end of file. Left alone, every regeneration produces a noisy
 // whitespace diff that masks real spec/client drift. This pass strips trailing
 // whitespace from every line and ends each file with exactly one newline.
+//
+// openapi-generator maps arrays with `uniqueItems` to `Set<T>`, but Axios
+// decodes and encodes their JSON representation as arrays. Keep the generated
+// type aligned with the runtime wire value.
 
 import { Glob } from "bun";
 
@@ -14,6 +18,7 @@ for await (const path of glob.scan(".")) {
   const original = await Bun.file(path).text();
   const normalized =
     original
+      .replace(/\bSet</g, "Array<")
       .split("\n")
       .map((line) => line.replace(/\s+$/, ""))
       .join("\n")
diff --git a/lib/packages/fabro-api-client/src/models/batch-delete-runs-request.ts b/lib/packages/fabro-api-client/src/models/batch-delete-runs-request.ts
index 938a9514e..039b5ffbc 100644
--- a/lib/packages/fabro-api-client/src/models/batch-delete-runs-request.ts
+++ b/lib/packages/fabro-api-client/src/models/batch-delete-runs-request.ts
@@ -21,7 +21,7 @@ export interface BatchDeleteRunsRequest {
     /**
      * Run IDs to process, in result order.
      */
-    'run_ids': Set<string>;
+    'run_ids': Array<string>;
     /**
      * Whether to force deletion of active runs. Defaults to `false`.
      */
diff --git a/lib/packages/fabro-api-client/src/models/batch-run-lifecycle-request.ts b/lib/packages/fabro-api-client/src/models/batch-run-lifecycle-request.ts
index b9225f933..d93be0250 100644
--- a/lib/packages/fabro-api-client/src/models/batch-run-lifecycle-request.ts
+++ b/lib/packages/fabro-api-client/src/models/batch-run-lifecycle-request.ts
@@ -21,5 +21,5 @@ export interface BatchRunLifecycleRequest {
     /**
      * Run IDs to process, in result order.
      */
-    'run_ids': Set<string>;
+    'run_ids': Array<string>;
 }
diff --git a/lib/packages/fabro-api-client/src/models/run-timing.ts b/lib/packages/fabro-api-client/src/models/run-timing.ts
index d4fa62262..f0344e5d3 100644
--- a/lib/packages/fabro-api-client/src/models/run-timing.ts
+++ b/lib/packages/fabro-api-client/src/models/run-timing.ts
@@ -19,8 +19,8 @@
  */
 export interface RunTiming {
     'wall_time_ms': number;
-    'inference_time_ms'?: number;
-    'tool_time_ms'?: number;
+    'inference_time_ms': number;
+    'tool_time_ms': number;
     /**
      * Equals `inference_time_ms + tool_time_ms`.
      */
diff --git a/lib/packages/fabro-api-client/src/models/stage-projection.ts b/lib/packages/fabro-api-client/src/models/stage-projection.ts
index 8cb88c0ac..032835c95 100644
--- a/lib/packages/fabro-api-client/src/models/stage-projection.ts
+++ b/lib/packages/fabro-api-client/src/models/stage-projection.ts
@@ -130,6 +130,10 @@ export interface StageProjection {
     'mcp_servers'?: Array<McpServerProjection>;
     'context_window'?: StageContextWindowProjection | null;
     'inference'?: StageInferenceProjection | null;
+    /**
+     * Start of an external ACP agent process, if one is running. ACP agents do not expose Fabro\'s internal LLM brackets, so the process lifetime supplies their live inference estimate.
+     */
+    'acp_started_at'?: string | null;
     /**
      * Whether the agent is executing normally or waiting for steering after an interrupt.
      */
diff --git a/lib/packages/fabro-api-client/src/models/stage-timing.ts b/lib/packages/fabro-api-client/src/models/stage-timing.ts
index 5bdd92bb4..4b106816c 100644
--- a/lib/packages/fabro-api-client/src/models/stage-timing.ts
+++ b/lib/packages/fabro-api-client/src/models/stage-timing.ts
@@ -19,8 +19,8 @@
  */
 export interface StageTiming {
     'wall_time_ms': number;
-    'inference_time_ms'?: number;
-    'tool_time_ms'?: number;
+    'inference_time_ms': number;
+    'tool_time_ms': number;
     /**
      * Equals `inference_time_ms + tool_time_ms`.
      */
diff --git a/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts b/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
index c382b5dd1..971fa7c59 100644
--- a/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
+++ b/lib/packages/fabro-api-client/src/models/stage-tool-batch-projection.ts
@@ -29,5 +29,5 @@ export interface StageToolBatchProjection {
     /**
      * Calls dispatched but not yet completed, by tool call id.
      */
-    'open_call_ids': Set<string>;
+    'open_call_ids': Array<string>;
 }

From d6ac910e73639256dbf15a7cd29bd91c2e1bbf65 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:24:26 -0400
Subject: [PATCH 25/36] refactor: reuse ModelResolutionTransform instead of a
 parallel options type

`ModelResolutionOptions` was a field-for-field duplicate of the existing
public `ModelResolutionTransform`, down to a verbatim copy of its `new()`.
`pipeline::transform` then unpacked one to rebuild the other, cloning the
catalog Arc and the eligible-provider set on the way.

- Delete `ModelResolutionOptions`. `TransformOptions.model_resolution` now
  holds an `Option<ModelResolutionTransform>` directly, so the TRANSFORM
  step is `resolution.apply(graph)?` with no rebuild and no clones. This
  is consistent with `custom_transforms`, which already holds transforms.
- Add `ModelResolutionTransform::catalog()` so the VALIDATE step can reach
  the same catalog for its lint rules. That is the only new code needed.
- Drop `CatalogScope` from `operations::validate`, which was a third copy
  of the same fields. The three entry points now hand a partially built
  transform to `validate_resolving_models`, which completes it with the
  workflow's default provider once the workflow is resolved.
- Extract `validate_child_workflow` in `manager_loop`, collapsing two
  near-identical validate-and-unwrap blocks.
- Point the transform tests at their own `transform_options()` helper via
  struct-update syntax instead of respelling all seven fields, and drop a
  HashSet -> Vec -> HashSet round trip from the create test helper.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/handler/manager_loop.rs               | 57 ++++++++--------
 .../fabro-workflow/src/operations/create.rs   | 26 ++++----
 .../fabro-workflow/src/operations/validate.rs | 55 ++++++----------
 .../fabro-workflow/src/pipeline/mod.rs        |  6 +-
 .../fabro-workflow/src/pipeline/transform.rs  | 65 ++++++-------------
 .../fabro-workflow/src/pipeline/types.rs      | 29 +--------
 .../src/transforms/model_resolution.rs        |  7 ++
 .../fabro-workflow/tests/it/integration.rs    |  7 +-
 8 files changed, 101 insertions(+), 151 deletions(-)

diff --git a/lib/components/fabro-workflow/src/handler/manager_loop.rs b/lib/components/fabro-workflow/src/handler/manager_loop.rs
index ddefe84be..73c068a73 100644
--- a/lib/components/fabro-workflow/src/handler/manager_loop.rs
+++ b/lib/components/fabro-workflow/src/handler/manager_loop.rs
@@ -65,22 +65,14 @@ fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<ParsedChi
         .get("stack.child_dot_source")
         .and_then(|v| v.as_str())
     {
-        let mut validated = validate_with_catalog(
-            ValidateInput {
-                workflow:          WorkflowInput::DotSource {
-                    source:   dot.to_string(),
-                    base_dir: None,
-                },
-                settings:          WorkflowSettings::default(),
-                vars:              std::collections::HashMap::new(),
-                cwd:               cwd.clone(),
-                custom_transforms: Vec::new(),
+        let graph = validate_child_workflow(
+            WorkflowInput::DotSource {
+                source:   dot.to_string(),
+                base_dir: None,
             },
-            &services.run.catalog,
+            cwd,
+            services,
         )?;
-        validated.promote_template_undefined_variables_to_errors();
-        validated.raise_on_errors()?;
-        let (graph, _, _) = validated.into_parts();
         return Ok(ParsedChildWorkflow {
             graph,
             workflow_path: None,
@@ -115,19 +107,7 @@ fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<ParsedChi
             WorkflowInput::Bundled(workflow) => Some(workflow.path.clone()),
             WorkflowInput::Path(_) | WorkflowInput::DotSource { .. } => None,
         };
-        let mut validated = validate_with_catalog(
-            ValidateInput {
-                workflow,
-                settings: WorkflowSettings::default(),
-                vars: std::collections::HashMap::new(),
-                cwd,
-                custom_transforms: Vec::new(),
-            },
-            &services.run.catalog,
-        )?;
-        validated.promote_template_undefined_variables_to_errors();
-        validated.raise_on_errors()?;
-        let (graph, _, _) = validated.into_parts();
+        let graph = validate_child_workflow(workflow, cwd, services)?;
         return Ok(ParsedChildWorkflow {
             graph,
             workflow_path,
@@ -136,6 +116,29 @@ fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<ParsedChi
     Err(Error::handler("No child workflow source".to_string()))
 }
 
+/// Validate a child workflow against the run's catalog, failing on any error
+/// diagnostic (undefined template variables included).
+fn validate_child_workflow(
+    workflow: WorkflowInput,
+    cwd: PathBuf,
+    services: &EngineServices,
+) -> Result<Graph, Error> {
+    let mut validated = validate_with_catalog(
+        ValidateInput {
+            workflow,
+            settings: WorkflowSettings::default(),
+            vars: HashMap::new(),
+            cwd,
+            custom_transforms: Vec::new(),
+        },
+        &services.run.catalog,
+    )?;
+    validated.promote_template_undefined_variables_to_errors();
+    validated.raise_on_errors()?;
+    let (graph, _, _) = validated.into_parts();
+    Ok(graph)
+}
+
 #[async_trait]
 impl Handler for SubWorkflowHandler {
     async fn execute(
diff --git a/lib/components/fabro-workflow/src/operations/create.rs b/lib/components/fabro-workflow/src/operations/create.rs
index 3e976e824..5d5478b24 100644
--- a/lib/components/fabro-workflow/src/operations/create.rs
+++ b/lib/components/fabro-workflow/src/operations/create.rs
@@ -24,11 +24,11 @@ use crate::error::Error;
 use crate::event::{Event, append_event, to_run_event_at};
 use crate::file_resolver::FileResolver;
 use crate::pipeline::types::PersistOptions;
-use crate::pipeline::{self, ModelResolutionOptions, Persisted, TransformOptions, Validated};
+use crate::pipeline::{self, Persisted, TransformOptions, Validated};
 use crate::records::RunSpec;
 use crate::run_lookup::default_scratch_base;
 use crate::run_materialization::materialize_run;
-use crate::transforms::RenderMode;
+use crate::transforms::{ModelResolutionTransform, RenderMode};
 use crate::workflow_bundle::{RunDefinition, WorkflowBundle};
 
 #[derive(Clone, Debug)]
@@ -300,12 +300,13 @@ fn create_from_source(
         source_name: options.source_name.clone(),
         render_mode: RenderMode::Structural,
         custom_transforms: Vec::new(),
-        model_resolution: Some(ModelResolutionOptions {
-            catalog:            Arc::clone(&options.catalog),
-            default_provider:   configured_default_provider(&options.settings),
-            eligible_providers: options.configured_providers.iter().cloned().collect(),
-            catalog_fallback:   false,
-        }),
+        model_resolution: Some(
+            ModelResolutionTransform::for_eligible(
+                Arc::clone(&options.catalog),
+                options.configured_providers.iter().cloned().collect(),
+            )
+            .with_default_provider(configured_default_provider(&options.settings)),
+        ),
     })?;
 
     validated.promote_template_undefined_variables_to_errors();
@@ -336,7 +337,7 @@ pub(super) fn preprocess_and_validate(
     let catalog = options
         .model_resolution
         .as_ref()
-        .map(|resolution| resolution.catalog.as_ref());
+        .map(ModelResolutionTransform::catalog);
     Ok(pipeline::validate(transformed, catalog, &[]))
 }
 
@@ -594,12 +595,7 @@ reasoning = false
             source_name: Some("workflow.fabro".to_string()),
             render_mode,
             custom_transforms: Vec::new(),
-            model_resolution: Some(ModelResolutionOptions {
-                catalog:            test_catalog(),
-                default_provider:   None,
-                eligible_providers: test_provider_ids().into_iter().collect(),
-                catalog_fallback:   false,
-            }),
+            model_resolution: Some(ModelResolutionTransform::new(test_catalog())),
         }
     }
 
diff --git a/lib/components/fabro-workflow/src/operations/validate.rs b/lib/components/fabro-workflow/src/operations/validate.rs
index 4000443e1..41413eb9e 100644
--- a/lib/components/fabro-workflow/src/operations/validate.rs
+++ b/lib/components/fabro-workflow/src/operations/validate.rs
@@ -1,4 +1,4 @@
-use std::collections::{HashMap, HashSet};
+use std::collections::HashMap;
 use std::path::PathBuf;
 use std::sync::Arc;
 
@@ -9,8 +9,8 @@ use super::create::{configured_default_provider, preprocess_and_validate, templa
 use super::source::{ResolveWorkflowInput, WorkflowInput, resolve_workflow};
 use crate::error::Error;
 use crate::operations::RenderMode;
-use crate::pipeline::{ModelResolutionOptions, TransformOptions, Validated};
-use crate::transforms::Transform;
+use crate::pipeline::{TransformOptions, Validated};
+use crate::transforms::{ModelResolutionTransform, Transform};
 
 pub struct ValidateInput {
     pub workflow:          WorkflowInput,
@@ -22,17 +22,6 @@ pub struct ValidateInput {
     pub custom_transforms: Vec<Box<dyn Transform>>,
 }
 
-/// Which providers catalog-backed model resolution may select from. The
-/// workflow's own default provider is read from the resolved settings, so it
-/// is not part of the caller's request.
-struct CatalogScope<'a> {
-    catalog:            &'a Arc<Catalog>,
-    eligible_providers: HashSet<ProviderId>,
-    /// Fall back to the full catalog when the eligible providers cannot
-    /// supply a requested model, instead of erroring.
-    catalog_fallback:   bool,
-}
-
 /// Parse, transform, and structurally validate a DOT source string without a
 /// model catalog. Model and provider availability is left to the caller that
 /// owns a catalog — typically the server.
@@ -40,7 +29,7 @@ struct CatalogScope<'a> {
 /// Returns `Validated` even when validation produced errors. Call
 /// `validated.raise_on_errors()` if the caller wants to fail fast.
 pub fn validate(input: ValidateInput) -> Result<Validated, Error> {
-    validate_in_scope(input, None)
+    validate_resolving_models(input, None)
 }
 
 /// Parse, transform, and validate a DOT source string against `catalog`.
@@ -48,13 +37,9 @@ pub fn validate_with_catalog(
     input: ValidateInput,
     catalog: &Arc<Catalog>,
 ) -> Result<Validated, Error> {
-    validate_in_scope(
+    validate_resolving_models(
         input,
-        Some(CatalogScope {
-            catalog,
-            eligible_providers: catalog.all_provider_ids(),
-            catalog_fallback: false,
-        }),
+        Some(ModelResolutionTransform::new(Arc::clone(catalog))),
     )
 }
 
@@ -66,19 +51,24 @@ pub fn validate_with_ready_providers(
     catalog: &Arc<Catalog>,
     ready_providers: &[ProviderId],
 ) -> Result<Validated, Error> {
-    validate_in_scope(
+    validate_resolving_models(
         input,
-        Some(CatalogScope {
-            catalog,
-            eligible_providers: ready_providers.iter().cloned().collect(),
-            catalog_fallback: true,
-        }),
+        Some(
+            ModelResolutionTransform::for_eligible(
+                Arc::clone(catalog),
+                ready_providers.iter().cloned().collect(),
+            )
+            .with_catalog_fallback(true),
+        ),
     )
 }
 
-fn validate_in_scope(
+/// The workflow's own default provider is only known once the workflow is
+/// resolved, so callers hand in a partially built transform and it is
+/// completed here.
+fn validate_resolving_models(
     input: ValidateInput,
-    scope: Option<CatalogScope<'_>>,
+    model_resolution: Option<ModelResolutionTransform>,
 ) -> Result<Validated, Error> {
     let ValidateInput {
         workflow,
@@ -94,11 +84,8 @@ fn validate_in_scope(
     })
     .map_err(|err| Error::Parse(err.to_string()))?;
 
-    let model_resolution = scope.map(|scope| ModelResolutionOptions {
-        catalog:            Arc::clone(scope.catalog),
-        default_provider:   configured_default_provider(&resolved.settings),
-        eligible_providers: scope.eligible_providers,
-        catalog_fallback:   scope.catalog_fallback,
+    let model_resolution = model_resolution.map(|resolution| {
+        resolution.with_default_provider(configured_default_provider(&resolved.settings))
     });
 
     preprocess_and_validate(
diff --git a/lib/components/fabro-workflow/src/pipeline/mod.rs b/lib/components/fabro-workflow/src/pipeline/mod.rs
index 46c271907..d0ba5ae1b 100644
--- a/lib/components/fabro-workflow/src/pipeline/mod.rs
+++ b/lib/components/fabro-workflow/src/pipeline/mod.rs
@@ -22,8 +22,8 @@ pub use pull_request::{
 };
 pub use transform::transform;
 pub use types::{
-    Concluded, Executed, FinalizeOptions, Finalized, InitOptions, Initialized, LlmSpec,
-    ModelResolutionOptions, Parsed, Persisted, PullRequestOptions, ResumeState, SandboxEnvSpec,
-    TEMPLATE_UNDEFINED_VARIABLE_RULE, TransformOptions, Transformed, Validated,
+    Concluded, Executed, FinalizeOptions, Finalized, InitOptions, Initialized, LlmSpec, Parsed,
+    Persisted, PullRequestOptions, ResumeState, SandboxEnvSpec, TEMPLATE_UNDEFINED_VARIABLE_RULE,
+    TransformOptions, Transformed, Validated,
 };
 pub use validate::validate;
diff --git a/lib/components/fabro-workflow/src/pipeline/transform.rs b/lib/components/fabro-workflow/src/pipeline/transform.rs
index d73b26275..bf3b82471 100644
--- a/lib/components/fabro-workflow/src/pipeline/transform.rs
+++ b/lib/components/fabro-workflow/src/pipeline/transform.rs
@@ -3,8 +3,8 @@ use std::sync::Arc;
 use super::types::{Parsed, TransformOptions, Transformed};
 use crate::error::Error;
 use crate::transforms::{
-    FileInliningTransform, ImportTransform, ModelResolutionTransform,
-    StylesheetApplicationTransform, TemplateTransform, Transform,
+    FileInliningTransform, ImportTransform, StylesheetApplicationTransform, TemplateTransform,
+    Transform,
 };
 
 /// TRANSFORM phase: apply built-in and custom transforms to a parsed graph.
@@ -63,16 +63,9 @@ pub fn transform(parsed: Parsed, options: &TransformOptions) -> Result<Transform
     .apply_with_diagnostics(graph)?;
     diagnostics.extend(transform_diagnostics);
     let graph = StylesheetApplicationTransform.apply(graph)?;
-    let graph = if let Some(model_resolution) = &options.model_resolution {
-        ModelResolutionTransform::for_eligible(
-            Arc::clone(&model_resolution.catalog),
-            model_resolution.eligible_providers.clone(),
-        )
-        .with_default_provider(model_resolution.default_provider.clone())
-        .with_catalog_fallback(model_resolution.catalog_fallback)
-        .apply(graph)?
-    } else {
-        graph
+    let graph = match &options.model_resolution {
+        Some(model_resolution) => model_resolution.apply(graph)?,
+        None => graph,
     };
 
     // Custom transforms
@@ -101,9 +94,8 @@ mod tests {
     use super::*;
     use crate::file_resolver::FilesystemFileResolver;
     use crate::pipeline::parse::parse;
-    use crate::pipeline::types::{
-        GOAL_SELF_REFERENCE_RULE, ModelResolutionOptions, TEMPLATE_UNDEFINED_VARIABLE_RULE,
-    };
+    use crate::pipeline::types::{GOAL_SELF_REFERENCE_RULE, TEMPLATE_UNDEFINED_VARIABLE_RULE};
+    use crate::transforms::ModelResolutionTransform;
 
     fn write_file(path: &Path, contents: &str) {
         if let Some(parent) = path.parent() {
@@ -124,7 +116,7 @@ mod tests {
             source_name:       None,
             render_mode:       crate::operations::RenderMode::Strict,
             custom_transforms: vec![],
-            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
+            model_resolution:  Some(ModelResolutionTransform::new(test_catalog())),
         }
     }
 
@@ -180,13 +172,9 @@ mod tests {
         )
         .unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:       Some(dir.path().to_path_buf()),
-            file_resolver:     Some(Arc::new(FilesystemFileResolver::new(None))),
-            template_context:  fabro_template::TemplateContext::new(),
-            source_name:       None,
-            render_mode:       crate::operations::RenderMode::Strict,
-            custom_transforms: vec![],
-            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
+            current_dir: Some(dir.path().to_path_buf()),
+            file_resolver: Some(Arc::new(FilesystemFileResolver::new(None))),
+            ..transform_options()
         })
         .unwrap();
 
@@ -227,18 +215,15 @@ mod tests {
         )
         .unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:       Some(dir.path().to_path_buf()),
-            file_resolver:     Some(Arc::new(FilesystemFileResolver::new(None))),
-            template_context:  fabro_template::TemplateContext::new().with_inputs(HashMap::from([
+            current_dir: Some(dir.path().to_path_buf()),
+            file_resolver: Some(Arc::new(FilesystemFileResolver::new(None))),
+            template_context: fabro_template::TemplateContext::new().with_inputs(HashMap::from([
                 (
                     "task".to_string(),
                     toml::Value::String("Launch".to_string()),
                 ),
             ])),
-            source_name:       None,
-            render_mode:       crate::operations::RenderMode::Strict,
-            custom_transforms: vec![],
-            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
+            ..transform_options()
         })
         .unwrap();
 
@@ -357,13 +342,8 @@ mod tests {
         }"#;
         let parsed = parse(dot).unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:       None,
-            file_resolver:     None,
-            template_context:  fabro_template::TemplateContext::new(),
-            source_name:       None,
-            render_mode:       crate::operations::RenderMode::Strict,
-            custom_transforms: vec![],
-            model_resolution:  None,
+            model_resolution: None,
+            ..transform_options()
         })
         .unwrap();
         let work = &transformed.graph.nodes["work"];
@@ -394,13 +374,10 @@ mod tests {
         )
         .unwrap();
         let transformed = transform(parsed, &TransformOptions {
-            current_dir:       Some(dir.path().to_path_buf()),
-            file_resolver:     Some(Arc::new(FilesystemFileResolver::new(None))),
-            template_context:  fabro_template::TemplateContext::new(),
-            source_name:       None,
-            render_mode:       crate::operations::RenderMode::Structural,
-            custom_transforms: vec![],
-            model_resolution:  Some(ModelResolutionOptions::new(test_catalog())),
+            current_dir: Some(dir.path().to_path_buf()),
+            file_resolver: Some(Arc::new(FilesystemFileResolver::new(None))),
+            render_mode: crate::operations::RenderMode::Structural,
+            ..transform_options()
         })
         .unwrap();
 
diff --git a/lib/components/fabro-workflow/src/pipeline/types.rs b/lib/components/fabro-workflow/src/pipeline/types.rs
index 29f5fbf9e..9ff9b83fd 100644
--- a/lib/components/fabro-workflow/src/pipeline/types.rs
+++ b/lib/components/fabro-workflow/src/pipeline/types.rs
@@ -1,4 +1,4 @@
-use std::collections::{HashMap, HashSet};
+use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
@@ -28,7 +28,7 @@ use crate::runtime_store::RunStoreHandle;
 use crate::services::{EngineServices, FabroRunToolServices, RunServices};
 use crate::stage_execution::StageExecutionSeed;
 use crate::steering_hub::SteeringHub;
-use crate::transforms::{RenderMode, Transform};
+use crate::transforms::{ModelResolutionTransform, RenderMode, Transform};
 use crate::workflow_bundle::WorkflowBundle;
 
 /// Output of the PARSE phase.
@@ -367,30 +367,7 @@ pub struct TransformOptions {
     pub custom_transforms: Vec<Box<dyn Transform>>,
     /// Catalog-backed model resolution to perform. `None` preserves authored
     /// model and provider selectors for catalog-free structural validation.
-    pub model_resolution:  Option<ModelResolutionOptions>,
-}
-
-/// Catalog-backed model resolution options for the TRANSFORM phase.
-pub struct ModelResolutionOptions {
-    pub catalog:            Arc<Catalog>,
-    pub default_provider:   Option<ProviderId>,
-    pub eligible_providers: HashSet<ProviderId>,
-    /// Fall back to the full catalog when the eligible providers cannot
-    /// supply a requested model, instead of erroring.
-    pub catalog_fallback:   bool,
-}
-
-impl ModelResolutionOptions {
-    #[must_use]
-    pub fn new(catalog: Arc<Catalog>) -> Self {
-        let eligible_providers = catalog.all_provider_ids();
-        Self {
-            catalog,
-            default_provider: None,
-            eligible_providers,
-            catalog_fallback: false,
-        }
-    }
+    pub model_resolution:  Option<ModelResolutionTransform>,
 }
 
 /// Options for the FINALIZE phase.
diff --git a/lib/components/fabro-workflow/src/transforms/model_resolution.rs b/lib/components/fabro-workflow/src/transforms/model_resolution.rs
index 12f29ac5a..7fb61b9d9 100644
--- a/lib/components/fabro-workflow/src/transforms/model_resolution.rs
+++ b/lib/components/fabro-workflow/src/transforms/model_resolution.rs
@@ -52,6 +52,13 @@ impl ModelResolutionTransform {
         self
     }
 
+    /// The catalog this transform resolves against, so callers can run the
+    /// matching catalog-backed lint rules.
+    #[must_use]
+    pub fn catalog(&self) -> &Catalog {
+        &self.catalog
+    }
+
     fn resolve_model(
         &self,
         model: &str,
diff --git a/lib/components/fabro-workflow/tests/it/integration.rs b/lib/components/fabro-workflow/tests/it/integration.rs
index 51030ec05..781bbf463 100644
--- a/lib/components/fabro-workflow/tests/it/integration.rs
+++ b/lib/components/fabro-workflow/tests/it/integration.rs
@@ -4853,7 +4853,8 @@ async fn manager_loop_child_workflow_e2e() {
 
 #[tokio::test]
 async fn import_e2e_through_engine() {
-    use fabro_workflow::pipeline::{ModelResolutionOptions, TransformOptions, transform, validate};
+    use fabro_workflow::pipeline::{TransformOptions, transform, validate};
+    use fabro_workflow::transforms::ModelResolutionTransform;
 
     let dir = tempfile::tempdir().unwrap();
     let catalog = std::sync::Arc::new(
@@ -4905,7 +4906,9 @@ async fn import_e2e_through_engine() {
         source_name:       None,
         render_mode:       fabro_workflow::operations::RenderMode::Strict,
         custom_transforms: vec![],
-        model_resolution:  Some(ModelResolutionOptions::new(std::sync::Arc::clone(&catalog))),
+        model_resolution:  Some(ModelResolutionTransform::new(std::sync::Arc::clone(
+            &catalog,
+        ))),
     })
     .unwrap();
     let validated = validate(transformed, Some(catalog.as_ref()), &[]);

From 09ef90ba1e098639ea7a7fccab76a1b90129b28a Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:29:03 -0400
Subject: [PATCH 26/36] refactor: pass the catalog by value and correct the
 RenderMode docs

- Take `Arc<Catalog>` by value again through the validation entry points.
  `AppState::catalog()` returns an owned `Arc`, so `&state.catalog()` was
  cloning, borrowing the temporary, then cloning again at the leaf. Every
  consumer ends up owning the `Arc`, so by-value is the honest shape and it
  drops one clone per call. The one caller holding the catalog in a field
  now says `Arc::clone(&self.catalog)` explicitly.
- Correct the `RenderMode` doc comment. It claimed `Strict` is "used by
  run-create", but run-create renders `Structural` and promotes the
  resulting warnings to errors itself; `Strict` has no production caller.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/apps/fabro-cli/src/commands/run/runner.rs |  7 +++++-
 .../fabro-mcp-server/src/manifest_builder.rs  |  2 +-
 .../fabro-server/src/manifest_validation.rs   |  2 +-
 lib/apps/fabro-server/src/run_manifest.rs     | 24 +++++++++----------
 .../fabro-server/src/run_tool_manifest.rs     |  2 +-
 .../fabro-server/src/server/handler/graph.rs  |  2 +-
 .../fabro-server/src/server/handler/runs.rs   | 22 +++++++++--------
 .../src/handler/manager_loop.rs               |  2 +-
 .../fabro-workflow/src/operations/create.rs   |  2 +-
 .../fabro-workflow/src/operations/validate.rs | 11 ++++-----
 .../src/transforms/variable_expansion.rs      | 14 ++++++-----
 11 files changed, 48 insertions(+), 42 deletions(-)

diff --git a/lib/apps/fabro-cli/src/commands/run/runner.rs b/lib/apps/fabro-cli/src/commands/run/runner.rs
index 4c6fcf578..4e6b72b8b 100644
--- a/lib/apps/fabro-cli/src/commands/run/runner.rs
+++ b/lib/apps/fabro-cli/src/commands/run/runner.rs
@@ -263,7 +263,12 @@ impl fabro_tool::RunManifestBuilder for WorkerRunManifestBuilder {
         cwd: &Path,
         user_settings_path: &Path,
     ) -> fabro_tool::ToolResult<RunManifest> {
-        run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, &self.catalog)
+        run_tool_manifest::build_run_tool_manifest(
+            spec,
+            cwd,
+            user_settings_path,
+            Arc::clone(&self.catalog),
+        )
     }
 }
 
diff --git a/lib/apps/fabro-mcp-server/src/manifest_builder.rs b/lib/apps/fabro-mcp-server/src/manifest_builder.rs
index 8c1cb8125..53e899f1e 100644
--- a/lib/apps/fabro-mcp-server/src/manifest_builder.rs
+++ b/lib/apps/fabro-mcp-server/src/manifest_builder.rs
@@ -32,5 +32,5 @@ fn build_mcp_run_manifest(
         Catalog::from_builtin_with_overrides(&llm_catalog_settings)
             .map_err(|err| ToolError::message(err.to_string()))?,
     );
-    run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, &catalog)
+    run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, catalog)
 }
diff --git a/lib/apps/fabro-server/src/manifest_validation.rs b/lib/apps/fabro-server/src/manifest_validation.rs
index 3d872954f..cf081b69f 100644
--- a/lib/apps/fabro-server/src/manifest_validation.rs
+++ b/lib/apps/fabro-server/src/manifest_validation.rs
@@ -25,7 +25,7 @@ pub fn validate_manifest(
 pub fn validate_manifest_with_catalog(
     manifest_run_defaults: &RunLayer,
     manifest: &types::RunManifest,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
 ) -> Result<types::ValidateResponse> {
     let prepared = prepare(manifest_run_defaults, manifest)?;
     let validated =
diff --git a/lib/apps/fabro-server/src/run_manifest.rs b/lib/apps/fabro-server/src/run_manifest.rs
index 76a81db51..c075b9382 100644
--- a/lib/apps/fabro-server/src/run_manifest.rs
+++ b/lib/apps/fabro-server/src/run_manifest.rs
@@ -188,7 +188,7 @@ pub(crate) fn prepare_manifest_with_environment_defaults(
 
 pub(crate) fn validate_prepared_manifest(
     prepared: &PreparedManifest,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
 ) -> Result<Validated, WorkflowError> {
     validate_prepared_manifest_with_vars(prepared, catalog, HashMap::new())
 }
@@ -201,7 +201,7 @@ pub(crate) fn validate_prepared_manifest_structural(
 
 pub(crate) fn validate_prepared_manifest_with_vars(
     prepared: &PreparedManifest,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
     vars: HashMap<String, String>,
 ) -> Result<Validated, WorkflowError> {
     validate_with_catalog(manifest_validate_input(prepared, vars), catalog)
@@ -209,7 +209,7 @@ pub(crate) fn validate_prepared_manifest_with_vars(
 
 pub(crate) fn validate_prepared_manifest_for_preflight(
     prepared: &PreparedManifest,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
     vars: HashMap<String, String>,
     ready_providers: &[ProviderId],
 ) -> Result<Validated, WorkflowError> {
@@ -1554,7 +1554,7 @@ digraph Demo {{
         .unwrap();
         let validated = validate_prepared_manifest_for_preflight(
             &prepared,
-            &state.catalog(),
+            state.catalog(),
             HashMap::new(),
             &ready_providers,
         )
@@ -1639,7 +1639,7 @@ enabled = {clone_enabled}
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
         let resolved = materialize_run(
             prepared.settings.clone(),
             validated.graph(),
@@ -2199,7 +2199,7 @@ name = "Control Plane"
             &invalid_manifest(),
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
 
         assert!(validated.has_errors());
 
@@ -2244,7 +2244,7 @@ issues = "read"
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
         assert!(!validated.has_errors());
 
         let (response, _ok) = resolve_and_run_preflight(state.as_ref(), &prepared, &validated)
@@ -2294,7 +2294,7 @@ id = "local"
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
 
         assert!(!validated.has_errors());
 
@@ -2403,7 +2403,7 @@ id = "daytona"
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
 
         let (response, _ok) = resolve_and_run_preflight(state.as_ref(), &prepared, &validated)
             .await
@@ -2471,7 +2471,7 @@ digraph Demo {
             &manifest,
         )
         .unwrap();
-        let validated = validate_prepared_manifest(&prepared, &test_catalog()).unwrap();
+        let validated = validate_prepared_manifest(&prepared, test_catalog()).unwrap();
 
         let (response, ok) = resolve_and_run_preflight(state.as_ref(), &prepared, &validated)
             .await
@@ -2585,7 +2585,7 @@ digraph Demo {
             &manifest,
         )
         .unwrap();
-        let Err(error) = validate_prepared_manifest(&prepared, &test_catalog()) else {
+        let Err(error) = validate_prepared_manifest(&prepared, test_catalog()) else {
             panic!("unknown provider should fail static validation");
         };
 
@@ -2652,7 +2652,7 @@ digraph Demo {
         assert!(ready_providers.is_empty());
         let validated = validate_prepared_manifest_for_preflight(
             &prepared,
-            &state.catalog(),
+            state.catalog(),
             HashMap::new(),
             &ready_providers,
         )
diff --git a/lib/apps/fabro-server/src/run_tool_manifest.rs b/lib/apps/fabro-server/src/run_tool_manifest.rs
index 66204e208..a7f1f869a 100644
--- a/lib/apps/fabro-server/src/run_tool_manifest.rs
+++ b/lib/apps/fabro-server/src/run_tool_manifest.rs
@@ -14,7 +14,7 @@ pub fn build_run_tool_manifest(
     spec: &ValidatedCreateRunSpec,
     cwd: &Path,
     user_settings_path: &Path,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
 ) -> ToolResult<types::RunManifest> {
     let built = fabro_manifest::build_run_manifest(ManifestBuildInput {
         workflow:             PathBuf::from(&spec.workflow),
diff --git a/lib/apps/fabro-server/src/server/handler/graph.rs b/lib/apps/fabro-server/src/server/handler/graph.rs
index ea95b674a..364b19cad 100644
--- a/lib/apps/fabro-server/src/server/handler/graph.rs
+++ b/lib/apps/fabro-server/src/server/handler/graph.rs
@@ -52,7 +52,7 @@ async fn render_graph_from_manifest(
         Ok(prepared) => prepared,
         Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
     };
-    let validated = match run_manifest::validate_prepared_manifest(&prepared, &state.catalog()) {
+    let validated = match run_manifest::validate_prepared_manifest(&prepared, state.catalog()) {
         Ok(validated) => validated,
         Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
     };
diff --git a/lib/apps/fabro-server/src/server/handler/runs.rs b/lib/apps/fabro-server/src/server/handler/runs.rs
index a0cbcbf70..0e2c8cbcb 100644
--- a/lib/apps/fabro-server/src/server/handler/runs.rs
+++ b/lib/apps/fabro-server/src/server/handler/runs.rs
@@ -829,7 +829,7 @@ async fn run_preflight(
     let (llm_result, ready_providers) = state.resolve_llm_client_with_ready_ids().await;
     let mut validated = match run_manifest::validate_prepared_manifest_for_preflight(
         &prepared,
-        &state.catalog(),
+        state.catalog(),
         vars,
         &ready_providers,
     ) {
@@ -879,15 +879,17 @@ async fn validate_run_manifest(
         return ApiError::bad_request(format!("Run config variable interpolation failed: {err}"))
             .into_response();
     }
-    let validated =
-        match run_manifest::validate_prepared_manifest_with_vars(&prepared, &state.catalog(), vars)
-        {
-            Ok(validated) => validated,
-            Err(WorkflowError::Parse(_)) => {
-                return ApiError::bad_request("Validation failed").into_response();
-            }
-            Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
-        };
+    let validated = match run_manifest::validate_prepared_manifest_with_vars(
+        &prepared,
+        state.catalog(),
+        vars,
+    ) {
+        Ok(validated) => validated,
+        Err(WorkflowError::Parse(_)) => {
+            return ApiError::bad_request("Validation failed").into_response();
+        }
+        Err(err) => return ApiError::bad_request(err.to_string()).into_response(),
+    };
     (
         StatusCode::OK,
         Json(run_manifest::validate_response(&prepared, &validated)),
diff --git a/lib/components/fabro-workflow/src/handler/manager_loop.rs b/lib/components/fabro-workflow/src/handler/manager_loop.rs
index 73c068a73..5668954c6 100644
--- a/lib/components/fabro-workflow/src/handler/manager_loop.rs
+++ b/lib/components/fabro-workflow/src/handler/manager_loop.rs
@@ -131,7 +131,7 @@ fn validate_child_workflow(
             cwd,
             custom_transforms: Vec::new(),
         },
-        &services.run.catalog,
+        Arc::clone(&services.run.catalog),
     )?;
     validated.promote_template_undefined_variables_to_errors();
     validated.raise_on_errors()?;
diff --git a/lib/components/fabro-workflow/src/operations/create.rs b/lib/components/fabro-workflow/src/operations/create.rs
index 5d5478b24..4f810cb54 100644
--- a/lib/components/fabro-workflow/src/operations/create.rs
+++ b/lib/components/fabro-workflow/src/operations/create.rs
@@ -559,7 +559,7 @@ reasoning = false
                 cwd: PathBuf::from("."),
                 custom_transforms: Vec::new(),
             },
-            &test_catalog(),
+            test_catalog(),
         )
         .unwrap()
     }
diff --git a/lib/components/fabro-workflow/src/operations/validate.rs b/lib/components/fabro-workflow/src/operations/validate.rs
index 41413eb9e..dfcb38777 100644
--- a/lib/components/fabro-workflow/src/operations/validate.rs
+++ b/lib/components/fabro-workflow/src/operations/validate.rs
@@ -35,12 +35,9 @@ pub fn validate(input: ValidateInput) -> Result<Validated, Error> {
 /// Parse, transform, and validate a DOT source string against `catalog`.
 pub fn validate_with_catalog(
     input: ValidateInput,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
 ) -> Result<Validated, Error> {
-    validate_resolving_models(
-        input,
-        Some(ModelResolutionTransform::new(Arc::clone(catalog))),
-    )
+    validate_resolving_models(input, Some(ModelResolutionTransform::new(catalog)))
 }
 
 /// Parse, transform, and validate, resolving models against the ready
@@ -48,14 +45,14 @@ pub fn validate_with_catalog(
 /// provider-readiness selection failures.
 pub fn validate_with_ready_providers(
     input: ValidateInput,
-    catalog: &Arc<Catalog>,
+    catalog: Arc<Catalog>,
     ready_providers: &[ProviderId],
 ) -> Result<Validated, Error> {
     validate_resolving_models(
         input,
         Some(
             ModelResolutionTransform::for_eligible(
-                Arc::clone(catalog),
+                catalog,
                 ready_providers.iter().cloned().collect(),
             )
             .with_catalog_fallback(true),
diff --git a/lib/components/fabro-workflow/src/transforms/variable_expansion.rs b/lib/components/fabro-workflow/src/transforms/variable_expansion.rs
index 66434266a..311c47189 100644
--- a/lib/components/fabro-workflow/src/transforms/variable_expansion.rs
+++ b/lib/components/fabro-workflow/src/transforms/variable_expansion.rs
@@ -19,17 +19,19 @@ use crate::static_reference::{
 
 /// How the template-expansion pass should treat undefined input variables.
 ///
-/// Validate is structural — it should not fail just because the user has not
-/// bound `{{ inputs.* }}` yet. Run-start is strict — missing inputs are real
-/// errors. Splitting the two lets validate work on a bare `.fabro` while
-/// run-start preserves its current hard-fail behavior.
+/// Neither validate nor run-create should fail just because the user has not
+/// bound `{{ inputs.* }}` yet, so both render structurally. Run-create then
+/// promotes the resulting warnings to errors itself, which keeps its hard-fail
+/// behavior while still reporting every undefined variable in one pass rather
+/// than aborting on the first.
 #[derive(Clone, Copy, Debug)]
 pub enum RenderMode {
-    /// Undefined inputs are hard errors. Used by run-create.
+    /// Undefined inputs abort the pass with a hard error. No production caller
+    /// uses this today; run-create promotes structural warnings instead.
     Strict,
     /// Undefined inputs render as empty and become warning diagnostics on the
     /// returned `Validated`, so structural lints still run. Used by
-    /// `fabro validate`.
+    /// `fabro validate` and by run-create.
     Structural,
 }
 

From 40372340c0c65533b90820c762fe7b811ba3a52e Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:40:54 -0400
Subject: [PATCH 27/36] fix(tool): keep fabro_run_create validation
 catalog-free

PR #651 stopped `fabro validate` and `fabro create` from judging model and
provider availability locally, but left the `fabro_run_create` tool path
doing exactly that. Both of its callers build a *client-side* catalog and
then POST the manifest to the server, so an agent naming a server-owned
model got `Model selection failed: unknown model provider '...'` while the
same workflow succeeded through the CLI.

- `build_run_tool_manifest` now validates structurally, matching the CLI.
  It no longer takes a catalog at all.
- The MCP builder drops its `load_llm_catalog_settings` +
  `Catalog::from_builtin_with_overrides` pair, and `WorkerRunManifestBuilder`
  drops its catalog field, becoming a unit struct.
- `validate_manifest_with_catalog` had no callers left, so it is gone.
  `validate_manifest` documents why every remaining caller is catalog-free.

The new test fails with the pre-fix client-side check, reproducing the
reported error exactly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/apps/fabro-cli/src/commands/run/runner.rs | 15 +---
 .../fabro-mcp-server/src/manifest_builder.rs  | 21 +-----
 .../fabro-server/src/manifest_validation.rs   | 39 +++-------
 .../fabro-server/src/run_tool_manifest.rs     | 74 ++++++++++++++++---
 4 files changed, 81 insertions(+), 68 deletions(-)

diff --git a/lib/apps/fabro-cli/src/commands/run/runner.rs b/lib/apps/fabro-cli/src/commands/run/runner.rs
index 4e6b72b8b..13f0fc9a6 100644
--- a/lib/apps/fabro-cli/src/commands/run/runner.rs
+++ b/lib/apps/fabro-cli/src/commands/run/runner.rs
@@ -110,7 +110,6 @@ pub(crate) async fn execute(
             run_id,
             run_spec.source_directory.as_deref(),
             &run_dir,
-            Arc::clone(&catalog),
         )
     } else {
         None
@@ -237,13 +236,12 @@ fn build_fabro_run_tool_services(
     current_run_id: RunId,
     source_directory: Option<&str>,
     run_dir: &Path,
-    catalog: Arc<Catalog>,
 ) -> Option<FabroRunToolServices> {
     if worker_token.trim().is_empty() {
         return None;
     }
     let backend = ClientBackend::new(Arc::new(client))
-        .with_manifest_builder(Arc::new(WorkerRunManifestBuilder { catalog }));
+        .with_manifest_builder(Arc::new(WorkerRunManifestBuilder));
     Some(FabroRunToolServices {
         backend: Arc::new(backend),
         current_run_id,
@@ -252,9 +250,7 @@ fn build_fabro_run_tool_services(
     })
 }
 
-struct WorkerRunManifestBuilder {
-    catalog: Arc<Catalog>,
-}
+struct WorkerRunManifestBuilder;
 
 impl fabro_tool::RunManifestBuilder for WorkerRunManifestBuilder {
     fn build_run_manifest(
@@ -263,12 +259,7 @@ impl fabro_tool::RunManifestBuilder for WorkerRunManifestBuilder {
         cwd: &Path,
         user_settings_path: &Path,
     ) -> fabro_tool::ToolResult<RunManifest> {
-        run_tool_manifest::build_run_tool_manifest(
-            spec,
-            cwd,
-            user_settings_path,
-            Arc::clone(&self.catalog),
-        )
+        run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path)
     }
 }
 
diff --git a/lib/apps/fabro-mcp-server/src/manifest_builder.rs b/lib/apps/fabro-mcp-server/src/manifest_builder.rs
index 53e899f1e..b09be76de 100644
--- a/lib/apps/fabro-mcp-server/src/manifest_builder.rs
+++ b/lib/apps/fabro-mcp-server/src/manifest_builder.rs
@@ -1,11 +1,8 @@
 use std::path::Path;
-use std::sync::Arc;
 
 use fabro_api::types;
-use fabro_config::load_llm_catalog_settings;
-use fabro_model::Catalog;
 use fabro_server::run_tool_manifest;
-use fabro_tool::{RunManifestBuilder, ToolError, ToolResult, ValidatedCreateRunSpec};
+use fabro_tool::{RunManifestBuilder, ToolResult, ValidatedCreateRunSpec};
 
 #[derive(Default)]
 pub(crate) struct McpRunManifestBuilder;
@@ -17,20 +14,6 @@ impl RunManifestBuilder for McpRunManifestBuilder {
         cwd: &Path,
         user_settings_path: &Path,
     ) -> ToolResult<types::RunManifest> {
-        build_mcp_run_manifest(spec, cwd, user_settings_path)
+        run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path)
     }
 }
-
-fn build_mcp_run_manifest(
-    spec: &ValidatedCreateRunSpec,
-    cwd: &Path,
-    user_settings_path: &Path,
-) -> ToolResult<types::RunManifest> {
-    let llm_catalog_settings = load_llm_catalog_settings(Some(user_settings_path))
-        .map_err(|err| ToolError::message(err.to_string()))?;
-    let catalog = Arc::new(
-        Catalog::from_builtin_with_overrides(&llm_catalog_settings)
-            .map_err(|err| ToolError::message(err.to_string()))?,
-    );
-    run_tool_manifest::build_run_tool_manifest(spec, cwd, user_settings_path, catalog)
-}
diff --git a/lib/apps/fabro-server/src/manifest_validation.rs b/lib/apps/fabro-server/src/manifest_validation.rs
index cf081b69f..acc5e05e1 100644
--- a/lib/apps/fabro-server/src/manifest_validation.rs
+++ b/lib/apps/fabro-server/src/manifest_validation.rs
@@ -1,48 +1,31 @@
 use std::collections::HashMap;
-use std::sync::Arc;
 
 use anyhow::Result;
 use fabro_api::types;
 use fabro_config::RunLayer;
-use fabro_model::Catalog;
 use fabro_workflow::pipeline::TEMPLATE_UNDEFINED_VARIABLE_RULE;
 
 use crate::run_manifest;
 
-/// Validate a manifest without a model catalog. Model and provider
-/// availability is deferred to the server, which owns the catalog.
+/// Validate a manifest without a model catalog.
+///
+/// Every caller is a client — the CLI, an MCP server, a run worker — and a
+/// client's catalog is its own, not the server's. Judging model and provider
+/// availability here would reject workflows the server can run, so that is
+/// left to the server on create.
 pub fn validate_manifest(
     manifest_run_defaults: &RunLayer,
     manifest: &types::RunManifest,
 ) -> Result<types::ValidateResponse> {
-    let prepared = prepare(manifest_run_defaults, manifest)?;
-    let validated = run_manifest::validate_prepared_manifest_structural(&prepared)
-        .map_err(anyhow::Error::new)?;
-    Ok(run_manifest::validate_response(&prepared, &validated))
-}
-
-/// Validate a manifest including the catalog-backed model and provider rules.
-pub fn validate_manifest_with_catalog(
-    manifest_run_defaults: &RunLayer,
-    manifest: &types::RunManifest,
-    catalog: Arc<Catalog>,
-) -> Result<types::ValidateResponse> {
-    let prepared = prepare(manifest_run_defaults, manifest)?;
-    let validated =
-        run_manifest::validate_prepared_manifest(&prepared, catalog).map_err(anyhow::Error::new)?;
-    Ok(run_manifest::validate_response(&prepared, &validated))
-}
-
-fn prepare(
-    manifest_run_defaults: &RunLayer,
-    manifest: &types::RunManifest,
-) -> Result<run_manifest::PreparedManifest> {
-    run_manifest::prepare_manifest_with_environment_defaults(
+    let prepared = run_manifest::prepare_manifest_with_environment_defaults(
         manifest_run_defaults,
         &fabro_environment::seeded_catalog_layer(),
         &HashMap::new(),
         manifest,
-    )
+    )?;
+    let validated = run_manifest::validate_prepared_manifest_structural(&prepared)
+        .map_err(anyhow::Error::new)?;
+    Ok(run_manifest::validate_response(&prepared, &validated))
 }
 
 pub fn promote_template_undefined_variables_to_errors(response: &mut types::ValidateResponse) {
diff --git a/lib/apps/fabro-server/src/run_tool_manifest.rs b/lib/apps/fabro-server/src/run_tool_manifest.rs
index a7f1f869a..584b6586f 100644
--- a/lib/apps/fabro-server/src/run_tool_manifest.rs
+++ b/lib/apps/fabro-server/src/run_tool_manifest.rs
@@ -1,20 +1,22 @@
 use std::path::{Path, PathBuf};
-use std::sync::Arc;
 
 use fabro_api::types;
 use fabro_config::{CliLayer, RunGoalLayer, RunLayer};
 use fabro_manifest::{ManifestBuildInput, RunOverrideInput};
-use fabro_model::Catalog;
 use fabro_tool::{ToolError, ToolResult, ValidatedCreateRunSpec};
 use fabro_types::settings::interp::InterpString;
 
 use crate::manifest_validation;
 
+/// Build and validate a run manifest for the `fabro_run_create` tool.
+///
+/// Validation is structural. The caller is a client — an MCP server or a run
+/// worker — whose catalog is its own, not the server's, so judging model and
+/// provider availability here would reject workflows the server can run.
 pub fn build_run_tool_manifest(
     spec: &ValidatedCreateRunSpec,
     cwd: &Path,
     user_settings_path: &Path,
-    catalog: Arc<Catalog>,
 ) -> ToolResult<types::RunManifest> {
     let built = fabro_manifest::build_run_manifest(ManifestBuildInput {
         workflow:             PathBuf::from(&spec.workflow),
@@ -29,12 +31,9 @@ pub fn build_run_tool_manifest(
     })
     .map_err(|err| ToolError::from_anyhow(&err))?;
 
-    let mut validation = manifest_validation::validate_manifest_with_catalog(
-        &RunLayer::default(),
-        &built.manifest,
-        catalog,
-    )
-    .map_err(|err| ToolError::from_anyhow(&err))?;
+    let mut validation =
+        manifest_validation::validate_manifest(&RunLayer::default(), &built.manifest)
+            .map_err(|err| ToolError::from_anyhow(&err))?;
     manifest_validation::promote_template_undefined_variables_to_errors(&mut validation);
     if !validation.ok {
         return Err(ToolError::message("workflow manifest validation failed"));
@@ -106,6 +105,63 @@ mod tests {
 
     use super::*;
 
+    fn create_run_spec(workflow: &str) -> ValidatedCreateRunSpec {
+        ValidatedCreateRunSpec::try_from(CreateRunSpec {
+            workflow:         workflow.to_string(),
+            run_id:           None,
+            parent_id:        None,
+            cwd:              None,
+            goal:             None,
+            goal_file:        None,
+            inputs:           HashMap::new(),
+            labels:           HashMap::new(),
+            model:            None,
+            provider:         None,
+            environment:      None,
+            dry_run:          None,
+            auto_approve:     None,
+            preserve_sandbox: None,
+            start:            None,
+        })
+        .expect("create spec should validate")
+    }
+
+    /// The tool runs on a client, whose catalog is not the server's, so a
+    /// server-owned model must reach the server rather than fail here.
+    #[expect(
+        clippy::disallowed_methods,
+        reason = "sync test writes one workflow fixture before building the manifest"
+    )]
+    #[test]
+    fn server_owned_provider_is_not_rejected_by_tool_manifest_validation() {
+        let dir = tempfile::tempdir().expect("temp dir should be created");
+        let workflow = dir.path().join("server-model.fabro");
+        std::fs::write(
+            &workflow,
+            r#"digraph ServerModel {
+                graph [goal="Use a server-owned model"]
+                start [shape=Mdiamond]
+                work [prompt="Do work", model="private-model", provider="server-only"]
+                exit [shape=Msquare]
+                start -> work -> exit
+            }"#,
+        )
+        .expect("workflow fixture should be written");
+
+        let manifest = build_run_tool_manifest(
+            &create_run_spec(&workflow.to_string_lossy()),
+            dir.path(),
+            &dir.path().join("settings.toml"),
+        )
+        .expect("tool validation should leave provider availability to the server");
+
+        let encoded = serde_json::to_string(&manifest).expect("manifest should serialize");
+        assert!(
+            encoded.contains("server-only"),
+            "the authored provider should survive into the manifest: {encoded}"
+        );
+    }
+
     #[test]
     fn manifest_args_preserve_input_provenance() {
         let spec = ValidatedCreateRunSpec::try_from(CreateRunSpec {

From acff084afde69eed44a94d445d84ee2699452447 Mon Sep 17 00:00:00 2001
From: Release Repro <release-repro@example.com>
Date: Tue, 28 Jul 2026 14:51:47 -0400
Subject: [PATCH 28/36] refactor: simplify stage billing reuse

---
 .../app/components/stage-popover.test.tsx     |   2 +
 .../stage-renderers/fan-in-results.test.tsx   |   2 +
 .../parallel-children.test.tsx                |   2 +
 .../app/components/stage-sidebar.test.tsx     |   2 +
 apps/fabro-web/app/lib/billing.ts             |  28 +++
 apps/fabro-web/app/lib/stage-sidebar.test.ts  |  28 +--
 apps/fabro-web/app/lib/stage-sidebar.ts       |   4 +-
 apps/fabro-web/app/lib/test-fixtures.ts       |  16 +-
 .../fabro-web/app/routes/run-billing.test.tsx |  40 ++--
 apps/fabro-web/app/routes/run-billing.tsx     | 165 ++++-----------
 .../app/routes/run-stages-chat.test.tsx       |   2 +
 .../app/routes/run-stages-details.test.tsx    |  34 ++-
 apps/fabro-web/app/routes/run-stages.tsx      |  28 +--
 lib/apps/fabro-server/src/server/tests.rs     | 198 ++++++------------
 .../fabro-types/src/run_projection.rs         |  18 +-
 15 files changed, 228 insertions(+), 341 deletions(-)
 create mode 100644 apps/fabro-web/app/lib/billing.ts

diff --git a/apps/fabro-web/app/components/stage-popover.test.tsx b/apps/fabro-web/app/components/stage-popover.test.tsx
index 4a8bbb12c..3f3c9fe92 100644
--- a/apps/fabro-web/app/components/stage-popover.test.tsx
+++ b/apps/fabro-web/app/components/stage-popover.test.tsx
@@ -9,6 +9,7 @@ import { StagePopover } from "./stage-popover";
 import { deriveStageSummary } from "./stage-popover-summary";
 import type { Stage } from "../lib/stage-sidebar";
 import { generatedAxios } from "../lib/api-client";
+import { makeBilledTokenCounts } from "../lib/test-fixtures";
 
 function makeEvent(overrides: Partial<EventEnvelope>): EventEnvelope {
   return {
@@ -34,6 +35,7 @@ function makeStage(overrides: Partial<Stage> = {}): Stage {
     duration:           "1m 30s",
     startedAt:          "2026-05-24T11:58:30Z",
     providerUsed:       { mode: "policy", model: "claude-opus-4-7", reasoning_effort: "high" },
+    billing:            makeBilledTokenCounts(),
     ...overrides,
   };
 }
diff --git a/apps/fabro-web/app/components/stage-renderers/fan-in-results.test.tsx b/apps/fabro-web/app/components/stage-renderers/fan-in-results.test.tsx
index 26115eaee..9c48b1960 100644
--- a/apps/fabro-web/app/components/stage-renderers/fan-in-results.test.tsx
+++ b/apps/fabro-web/app/components/stage-renderers/fan-in-results.test.tsx
@@ -3,6 +3,7 @@ import type { EventEnvelope } from "@qltysh/fabro-api-client";
 import TestRenderer, { act } from "react-test-renderer";
 
 import { makeEventEnvelope, setupReactTestEnv } from "../../lib/test-utils";
+import { makeBilledTokenCounts } from "../../lib/test-fixtures";
 import type { Stage } from "../stage-sidebar";
 import { FanInResults } from "./fan-in-results";
 
@@ -22,6 +23,7 @@ const fanInStage: Stage = {
   visit: 1,
   startedAt: "2026-04-09T12:00:00Z",
   providerUsed: null,
+  billing: makeBilledTokenCounts(),
 };
 
 function event(seq: number, partial: Partial<EventEnvelope>): EventEnvelope {
diff --git a/apps/fabro-web/app/components/stage-renderers/parallel-children.test.tsx b/apps/fabro-web/app/components/stage-renderers/parallel-children.test.tsx
index f1313b780..e44953db5 100644
--- a/apps/fabro-web/app/components/stage-renderers/parallel-children.test.tsx
+++ b/apps/fabro-web/app/components/stage-renderers/parallel-children.test.tsx
@@ -4,6 +4,7 @@ import TestRenderer, { act } from "react-test-renderer";
 import { MemoryRouter } from "react-router";
 
 import { makeEventEnvelope, setupReactTestEnv } from "../../lib/test-utils";
+import { makeBilledTokenCounts } from "../../lib/test-fixtures";
 import type { Stage } from "../stage-sidebar";
 import { ParallelChildren } from "./parallel-children";
 
@@ -23,6 +24,7 @@ const parallelStage: Stage = {
   visit: 1,
   startedAt: "2026-04-09T12:00:00Z",
   providerUsed: null,
+  billing: makeBilledTokenCounts(),
 };
 
 function event(partial: Partial<EventEnvelope>): EventEnvelope {
diff --git a/apps/fabro-web/app/components/stage-sidebar.test.tsx b/apps/fabro-web/app/components/stage-sidebar.test.tsx
index 69cf0c097..663734196 100644
--- a/apps/fabro-web/app/components/stage-sidebar.test.tsx
+++ b/apps/fabro-web/app/components/stage-sidebar.test.tsx
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import TestRenderer, { act } from "react-test-renderer";
 import { MemoryRouter } from "react-router";
 
+import { makeBilledTokenCounts } from "../lib/test-fixtures";
 import { StageSidebar, type Stage } from "./stage-sidebar";
 
 function makeStage(overrides: Partial<Stage> = {}): Stage {
@@ -17,6 +18,7 @@ function makeStage(overrides: Partial<Stage> = {}): Stage {
     duration:  "--",
     startedAt: null,
     providerUsed: null,
+    billing: makeBilledTokenCounts(),
     ...overrides,
   };
 }
diff --git a/apps/fabro-web/app/lib/billing.ts b/apps/fabro-web/app/lib/billing.ts
new file mode 100644
index 000000000..8d7e2cbf7
--- /dev/null
+++ b/apps/fabro-web/app/lib/billing.ts
@@ -0,0 +1,28 @@
+import type { BilledTokenCounts } from "@qltysh/fabro-api-client";
+
+export interface BillingTokenBucket {
+  label: string;
+  value: number;
+}
+
+export function billableOutputTokens(billing: BilledTokenCounts): number {
+  return billing.output_tokens + billing.reasoning_tokens;
+}
+
+/** The disjoint token buckets shown in every billing breakdown. */
+export function billingTokenBuckets(billing: BilledTokenCounts): BillingTokenBucket[] {
+  return [
+    { label: "Cache read", value: billing.cache_read_tokens },
+    { label: "Cache creation", value: billing.cache_write_tokens },
+    { label: "Uncached", value: billing.input_tokens },
+    { label: "Output", value: billableOutputTokens(billing) },
+  ];
+}
+
+export function hasBillingUsage(billing: BilledTokenCounts): boolean {
+  return (
+    billing.total_tokens !== 0 ||
+    (billing.total_usd_micros ?? 0) !== 0 ||
+    billingTokenBuckets(billing).some((bucket) => bucket.value !== 0)
+  );
+}
diff --git a/apps/fabro-web/app/lib/stage-sidebar.test.ts b/apps/fabro-web/app/lib/stage-sidebar.test.ts
index e1cc9092b..53cfa1b2a 100644
--- a/apps/fabro-web/app/lib/stage-sidebar.test.ts
+++ b/apps/fabro-web/app/lib/stage-sidebar.test.ts
@@ -3,6 +3,7 @@ import type { PaginatedRunStageList, StageHandler, StageState } from "@qltysh/fa
 
 import type { Stage } from "../components/stage-sidebar";
 import { aggregateGraphNodeStatus, formatStageLabel, mapRunStagesToSidebarStages } from "./stage-sidebar";
+import { makeBilledTokenCounts } from "./test-fixtures";
 
 function makeStage(nodeId: string, visit: number, status: StageState): Stage {
   return {
@@ -17,7 +18,7 @@ function makeStage(nodeId: string, visit: number, status: StageState): Stage {
     duration: "--",
     startedAt: null,
     providerUsed: null,
-    billing: null,
+    billing: makeBilledTokenCounts(),
   };
 }
 
@@ -39,7 +40,7 @@ describe("mapRunStagesToSidebarStages", () => {
             model: "gpt-5.5",
             reasoning_effort: "high",
           },
-          billing: {
+          billing: makeBilledTokenCounts({
             input_tokens: 28_640,
             output_tokens: 7_550,
             total_tokens: 43_690,
@@ -47,7 +48,7 @@ describe("mapRunStagesToSidebarStages", () => {
             cache_read_tokens: 4_800,
             cache_write_tokens: 1_500,
             total_usd_micros: 720_000,
-          },
+          }),
         },
         {
           id: "apply-changes@2",
@@ -56,14 +57,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "running",
           node_id: "apply",
           visit: 2,
-          billing: {
-            input_tokens: 0,
-            output_tokens: 0,
-            total_tokens: 0,
-            reasoning_tokens: 0,
-            cache_read_tokens: 0,
-            cache_write_tokens: 0,
-          },
+          billing: makeBilledTokenCounts(),
         },
       ],
       meta: { has_more: false },
@@ -84,8 +78,8 @@ describe("mapRunStagesToSidebarStages", () => {
     });
     // Each visit keeps its own tokens and cost, so the stage popover never
     // shows a sibling visit's usage.
-    expect(result[0].billing?.total_usd_micros).toBe(720_000);
-    expect(result[1].billing?.total_usd_micros).toBeUndefined();
+    expect(result[0].billing.total_usd_micros).toBe(720_000);
+    expect(result[1].billing.total_usd_micros).toBeUndefined();
     expect(formatStageLabel(result[0])).toBe("Apply Changes");
 
     expect(result[1].id).toBe("apply-changes@2");
@@ -105,6 +99,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "succeeded",
           node_id: "start",
           visit: 1,
+          billing: makeBilledTokenCounts(),
         },
         {
           id: "verify@1",
@@ -113,6 +108,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "succeeded",
           node_id: "verify",
           visit: 1,
+          billing: makeBilledTokenCounts(),
         },
         {
           id: "exit@1",
@@ -121,6 +117,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "succeeded",
           node_id: "exit",
           visit: 1,
+          billing: makeBilledTokenCounts(),
         },
       ],
       meta: { has_more: false },
@@ -140,6 +137,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "running",
           node_id: "verify",
           visit: 1,
+          billing: makeBilledTokenCounts(),
         },
       ],
       meta: { has_more: false },
@@ -159,6 +157,7 @@ describe("mapRunStagesToSidebarStages", () => {
           node_id: "work",
           visit: 1,
           graph_visit: 1,
+          billing: makeBilledTokenCounts(),
         },
         {
           id: "work@2",
@@ -169,6 +168,7 @@ describe("mapRunStagesToSidebarStages", () => {
           visit: 2,
           graph_visit: 1,
           resumed_from_stage_id: "work@1",
+          billing: makeBilledTokenCounts(),
         },
       ],
       meta: { has_more: false },
@@ -194,6 +194,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "succeeded",
           node_id: "verify",
           visit: 1,
+          billing: makeBilledTokenCounts(),
         },
       ],
       meta: { has_more: false },
@@ -214,6 +215,7 @@ describe("mapRunStagesToSidebarStages", () => {
           status: "pending",
           node_id: "approval",
           visit: 1,
+          billing: makeBilledTokenCounts(),
         },
       ],
       meta: { has_more: false },
diff --git a/apps/fabro-web/app/lib/stage-sidebar.ts b/apps/fabro-web/app/lib/stage-sidebar.ts
index 191681459..5aefb1166 100644
--- a/apps/fabro-web/app/lib/stage-sidebar.ts
+++ b/apps/fabro-web/app/lib/stage-sidebar.ts
@@ -32,7 +32,7 @@ export interface Stage {
    * Tokens and cost for this visit alone, priced the same way the Billing tab
    * prices its per-node rows. All-zero counts mean the stage called no model.
    */
-  billing: BilledTokenCounts | null;
+  billing: BilledTokenCounts;
 }
 
 export const ACTIVE_STAGE_STATES: ReadonlySet<StageState> = new Set([
@@ -108,7 +108,7 @@ export function mapRunStagesToSidebarStages(
         : "--",
       startedAt: stage.started_at ?? null,
       providerUsed: stage.provider_used ?? null,
-      billing: stage.billing ?? null,
+      billing: stage.billing,
     });
   }
   return stages;
diff --git a/apps/fabro-web/app/lib/test-fixtures.ts b/apps/fabro-web/app/lib/test-fixtures.ts
index c625ebe7d..521e46e14 100644
--- a/apps/fabro-web/app/lib/test-fixtures.ts
+++ b/apps/fabro-web/app/lib/test-fixtures.ts
@@ -1,4 +1,4 @@
-import type { Principal } from "@qltysh/fabro-api-client";
+import type { BilledTokenCounts, Principal } from "@qltysh/fabro-api-client";
 
 export const TEST_PRINCIPAL: Principal = {
   kind:        "user",
@@ -6,3 +6,17 @@ export const TEST_PRINCIPAL: Principal = {
   login:       "test",
   auth_method: "dev_token",
 };
+
+export function makeBilledTokenCounts(
+  overrides: Partial<BilledTokenCounts> = {},
+): BilledTokenCounts {
+  return {
+    cache_read_tokens: 0,
+    cache_write_tokens: 0,
+    input_tokens: 0,
+    output_tokens: 0,
+    reasoning_tokens: 0,
+    total_tokens: 0,
+    ...overrides,
+  };
+}
diff --git a/apps/fabro-web/app/routes/run-billing.test.tsx b/apps/fabro-web/app/routes/run-billing.test.tsx
index 99f6ece5d..efb86e73d 100644
--- a/apps/fabro-web/app/routes/run-billing.test.tsx
+++ b/apps/fabro-web/app/routes/run-billing.test.tsx
@@ -2,11 +2,12 @@ import { afterEach, describe, expect, mock, test } from "bun:test";
 import TestRenderer from "react-test-renderer";
 
 import type {
-  BilledTokenCounts,
   RunBilling,
   StageTiming,
 } from "@qltysh/fabro-api-client";
 
+import { makeBilledTokenCounts } from "../lib/test-fixtures";
+
 function stageTiming(wall_time_ms = 0, inference_time_ms = 0, tool_time_ms = 0): StageTiming {
   return {
     wall_time_ms,
@@ -24,25 +25,12 @@ mock.module("../lib/queries", () => ({
 
 const { default: RunBillingRoute } = await import("./run-billing");
 
-function zeroBilling(overrides: Partial<BilledTokenCounts> = {}): BilledTokenCounts {
-  return {
-    cache_read_tokens: 0,
-    cache_write_tokens: 0,
-    input_tokens: 0,
-    output_tokens: 0,
-    reasoning_tokens: 0,
-    total_tokens: 0,
-    total_usd_micros: null,
-    ...overrides,
-  };
-}
-
 function billing(overrides: Partial<RunBilling> = {}): RunBilling {
   return {
     stages: [],
     totals: {
       timing: stageTiming(),
-      ...zeroBilling(),
+      ...makeBilledTokenCounts(),
     },
     by_model: [],
     ...overrides,
@@ -86,21 +74,21 @@ describe("RunBilling", () => {
           {
             stage: { id: "start", name: "start" },
             model: null,
-            billing: zeroBilling(),
+            billing: makeBilledTokenCounts(),
             timing: stageTiming(),
             state: "succeeded",
           },
           {
             stage: { id: "command", name: "command" },
             model: null,
-            billing: zeroBilling(),
+            billing: makeBilledTokenCounts(),
             timing: stageTiming(61000),
             state: "succeeded",
           },
         ],
         totals: {
           timing: stageTiming(61000),
-          ...zeroBilling(),
+          ...makeBilledTokenCounts(),
         },
       }),
     );
@@ -121,7 +109,7 @@ describe("RunBilling", () => {
           {
             stage: { id: "start", name: "start" },
             model: null,
-            billing: zeroBilling(),
+            billing: makeBilledTokenCounts(),
             timing: stageTiming(),
             state: "succeeded",
           },
@@ -131,7 +119,7 @@ describe("RunBilling", () => {
               provider: "anthropic",
               model_id: "claude-sonnet-4-5",
             },
-            billing: zeroBilling({
+            billing: makeBilledTokenCounts({
               input_tokens: 1200,
               output_tokens: 300,
               total_tokens: 1500,
@@ -143,7 +131,7 @@ describe("RunBilling", () => {
         ],
         totals: {
           timing: stageTiming(42000),
-          ...zeroBilling({
+          ...makeBilledTokenCounts({
             input_tokens: 1200,
             output_tokens: 300,
             total_tokens: 1500,
@@ -157,7 +145,7 @@ describe("RunBilling", () => {
               model_id: "claude-sonnet-4-5",
             },
             stages: 1,
-            billing: zeroBilling({
+            billing: makeBilledTokenCounts({
               input_tokens: 1200,
               output_tokens: 300,
               total_tokens: 1500,
@@ -204,7 +192,7 @@ describe("RunBilling", () => {
                 model_id: "claude-opus-4-6",
                 speed: "fast",
               },
-              billing: zeroBilling({
+              billing: makeBilledTokenCounts({
                 input_tokens: 1200,
                 output_tokens: 300,
                 total_tokens: 1500,
@@ -217,7 +205,7 @@ describe("RunBilling", () => {
           ],
           totals: {
             timing: stageTiming(),
-            ...zeroBilling({
+            ...makeBilledTokenCounts({
               input_tokens: 1200,
               output_tokens: 300,
               total_tokens: 1500,
@@ -232,7 +220,7 @@ describe("RunBilling", () => {
                 speed: "fast",
               },
               stages: 1,
-              billing: zeroBilling({
+              billing: makeBilledTokenCounts({
                 input_tokens: 1200,
                 output_tokens: 300,
                 total_tokens: 1500,
@@ -268,4 +256,4 @@ describe("RunBilling", () => {
       Date.now = originalNow;
     }
   });
-});
\ No newline at end of file
+});
diff --git a/apps/fabro-web/app/routes/run-billing.tsx b/apps/fabro-web/app/routes/run-billing.tsx
index 20b60e775..1973ffb10 100644
--- a/apps/fabro-web/app/routes/run-billing.tsx
+++ b/apps/fabro-web/app/routes/run-billing.tsx
@@ -2,6 +2,11 @@ import { Fragment, useMemo } from "react";
 
 import { EmptyState } from "../components/state";
 import { Tooltip } from "../components/ui";
+import {
+  billableOutputTokens,
+  billingTokenBuckets,
+  hasBillingUsage,
+} from "../lib/billing";
 import {
   formatDurationMs,
   formatTokenCount,
@@ -11,6 +16,7 @@ import { useRunBilling } from "../lib/queries";
 import { IN_FLIGHT_STAGE_STATES } from "../lib/stage-sidebar";
 import { useTickingNow } from "../lib/time";
 import type {
+  BilledTokenCounts,
   BillingModelRef,
   RunBilling,
   RunBillingStage,
@@ -39,23 +45,15 @@ function isInFlight(stage: RunBillingStage): boolean {
 
 function isVisibleRow(row: MappedStageRow): boolean {
   if (row.inFlight) return true;
-  return (
-    (row.inputTokens ?? 0) > 0 ||
-    (row.outputTokens ?? 0) > 0 ||
-    (row.totalUsdMicros ?? 0) > 0
-  );
+  return row.billing != null && hasBillingUsage(row.billing);
 }
 
 interface MappedStageRow {
-  stage:            string;
-  model:            string | null;
-  inputTokens:      number | null;
-  outputTokens:     number | null;
-  cacheReadTokens:  number | null;
-  cacheWriteTokens: number | null;
-  wallTimeMs:       number;
-  totalUsdMicros:   number | null | undefined;
-  inFlight:         boolean;
+  stage:      string;
+  model:      string | null;
+  billing:    BilledTokenCounts | null;
+  wallTimeMs: number;
+  inFlight:   boolean;
 }
 
 function liveWallTimeMs(stage: RunBillingStage, now: number): number {
@@ -73,49 +71,28 @@ export const handle = { wide: true };
 function mapStageRow(stage: RunBillingStage, wallTimeMs: number): MappedStageRow {
   const hasModel = stage.model != null;
   return {
-    stage:            stage.stage.name,
-    model:            formatModelRef(stage.model),
-    inputTokens:      hasModel ? stage.billing.input_tokens : null,
-    outputTokens:     hasModel
-      ? stage.billing.output_tokens + stage.billing.reasoning_tokens
-      : null,
-    cacheReadTokens:  hasModel ? stage.billing.cache_read_tokens : null,
-    cacheWriteTokens: hasModel ? stage.billing.cache_write_tokens : null,
+    stage: stage.stage.name,
+    model: formatModelRef(stage.model),
+    billing: hasModel ? stage.billing : null,
     wallTimeMs,
-    totalUsdMicros:   stage.billing.total_usd_micros,
-    inFlight:         isInFlight(stage),
+    inFlight: isInFlight(stage),
   };
 }
 
 /** Hover breakdown of the disjoint token buckets behind an `in / out` count. */
-function TokenBreakdown({
-  cacheReadTokens,
-  cacheWriteTokens,
-  inputTokens,
-  outputTokens,
-}: {
-  cacheReadTokens:  number;
-  cacheWriteTokens: number;
-  inputTokens:      number;
-  outputTokens:     number;
-}) {
-  const rows = [
-    { label: "Cache read", value: cacheReadTokens },
-    { label: "Cache creation", value: cacheWriteTokens },
-    { label: "Uncached", value: inputTokens },
-    { label: "Output", value: outputTokens },
-  ];
+function TokenBreakdown({ billing }: { billing: BilledTokenCounts }) {
+  const buckets = billingTokenBuckets(billing);
   return (
     <div className="min-w-44 py-0.5">
-      <div className="mb-1.5 border-b border-line pb-1 font-medium text-fg-2">
+      <div className="border-line text-fg-2 mb-1.5 border-b pb-1 font-medium">
         Tokens in / out
       </div>
       <dl className="grid grid-cols-[1fr_auto] gap-x-6 gap-y-1">
-        {rows.map((row) => (
-          <Fragment key={row.label}>
-            <dt className="text-fg-3">{row.label}</dt>
-            <dd className="text-right font-mono tabular-nums text-fg">
-              {formatTokens(row.value)}
+        {buckets.map((bucket) => (
+          <Fragment key={bucket.label}>
+            <dt className="text-fg-3">{bucket.label}</dt>
+            <dd className="text-fg text-right font-mono tabular-nums">
+              {formatTokens(bucket.value)}
             </dd>
           </Fragment>
         ))}
@@ -128,42 +105,16 @@ function TokenBreakdown({
  * Renders an `input / output` token count. When the row has model usage,
  * hovering the count reveals the cache breakdown.
  */
-function TokensCell({
-  inputTokens,
-  outputTokens,
-  cacheReadTokens,
-  cacheWriteTokens,
-}: {
-  inputTokens:      number | null;
-  outputTokens:     number | null;
-  cacheReadTokens:  number | null;
-  cacheWriteTokens: number | null;
-}) {
+function TokensCell({ billing }: { billing: BilledTokenCounts | null }) {
   const display = (
     <>
-      {formatTokens(inputTokens)} <span className="text-fg-muted">/</span>{" "}
-      {formatTokens(outputTokens)}
+      {formatTokens(billing?.input_tokens)} <span className="text-fg-muted">/</span>{" "}
+      {formatTokens(billing ? billableOutputTokens(billing) : null)}
     </>
   );
-  if (
-    inputTokens == null ||
-    outputTokens == null ||
-    cacheReadTokens == null ||
-    cacheWriteTokens == null
-  ) {
-    return display;
-  }
+  if (!billing) return display;
   return (
-    <Tooltip
-      label={
-        <TokenBreakdown
-          cacheReadTokens={cacheReadTokens}
-          cacheWriteTokens={cacheWriteTokens}
-          inputTokens={inputTokens}
-          outputTokens={outputTokens}
-        />
-      }
-    >
+    <Tooltip label={<TokenBreakdown billing={billing} />}>
       <span>{display}</span>
     </Tooltip>
   );
@@ -189,15 +140,14 @@ export default function RunBilling({ params }: { params: { id: string } }) {
     if (!billing) return [];
     return billing.by_model
       .map((entry) => ({
-        model:            formatModelRef(entry.model) ?? EMPTY_VALUE,
-        stages:           entry.stages,
-        inputTokens:      entry.billing.input_tokens,
-        outputTokens:     entry.billing.output_tokens + entry.billing.reasoning_tokens,
-        cacheReadTokens:  entry.billing.cache_read_tokens,
-        cacheWriteTokens: entry.billing.cache_write_tokens,
-        totalUsdMicros:   entry.billing.total_usd_micros,
+        model:   formatModelRef(entry.model) ?? EMPTY_VALUE,
+        stages:  entry.stages,
+        billing: entry.billing,
       }))
-      .sort((a, b) => (b.totalUsdMicros ?? -1) - (a.totalUsdMicros ?? -1));
+      .sort(
+        (a, b) =>
+          (b.billing.total_usd_micros ?? -1) - (a.billing.total_usd_micros ?? -1),
+      );
   }, [billing]);
 
   // Re-derive only the in-flight rows on each tick; everything else stays put.
@@ -218,16 +168,7 @@ export default function RunBilling({ params }: { params: { id: string } }) {
     : (billing?.totals.timing.wall_time_ms ?? 0);
 
   const hasLlmStages = (billing?.by_model.length ?? 0) > 0;
-  const totalInput = hasLlmStages ? (billing?.totals.input_tokens ?? null) : null;
-  const totalOutput = hasLlmStages && billing
-    ? billing.totals.output_tokens + billing.totals.reasoning_tokens
-    : null;
-  const totalCacheRead = hasLlmStages
-    ? (billing?.totals.cache_read_tokens ?? null)
-    : null;
-  const totalCacheWrite = hasLlmStages
-    ? (billing?.totals.cache_write_tokens ?? null)
-    : null;
+  const totalBilling = hasLlmStages && billing ? billing.totals : null;
   const totalUsdMicros = billing?.totals.total_usd_micros;
   const modelStageCount = modelBreakdown.reduce((sum, row) => sum + row.stages, 0);
   const visibleRows = rows.filter(isVisibleRow);
@@ -268,18 +209,13 @@ export default function RunBilling({ params }: { params: { id: string } }) {
                   {row.model ?? EMPTY_VALUE}
                 </td>
                 <td className="px-4 py-3 text-right font-mono text-xs tabular-nums text-fg-3">
-                  <TokensCell
-                    inputTokens={row.inputTokens}
-                    outputTokens={row.outputTokens}
-                    cacheReadTokens={row.cacheReadTokens}
-                    cacheWriteTokens={row.cacheWriteTokens}
-                  />
+                  <TokensCell billing={row.billing} />
                 </td>
                 <td className="px-4 py-3 text-right font-mono text-xs text-fg-3">
                   {formatDurationMs(row.wallTimeMs)}
                 </td>
                 <td className="px-4 py-3 text-right font-mono text-xs text-fg-3">
-                  {formatUsdMicrosOrDash(row.totalUsdMicros)}
+                  {formatUsdMicrosOrDash(row.billing?.total_usd_micros)}
                 </td>
               </tr>
             ))}
@@ -289,12 +225,7 @@ export default function RunBilling({ params }: { params: { id: string } }) {
               <td className="px-4 py-3 font-medium text-fg">Total</td>
               <td className="px-4 py-3 text-xs text-fg-muted">All models</td>
               <td className="px-4 py-3 text-right font-mono text-xs tabular-nums font-medium text-fg">
-                <TokensCell
-                  inputTokens={totalInput}
-                  outputTokens={totalOutput}
-                  cacheReadTokens={totalCacheRead}
-                  cacheWriteTokens={totalCacheWrite}
-                />
+                <TokensCell billing={totalBilling} />
               </td>
               <td className="px-4 py-3 text-right font-mono text-xs font-medium text-fg">
                 {formatDurationMs(totalWallTimeMs)}
@@ -328,15 +259,10 @@ export default function RunBilling({ params }: { params: { id: string } }) {
                       {row.stages}
                     </td>
                     <td className="px-4 py-3 text-right font-mono text-xs tabular-nums text-fg-3">
-                      <TokensCell
-                        inputTokens={row.inputTokens}
-                        outputTokens={row.outputTokens}
-                        cacheReadTokens={row.cacheReadTokens}
-                        cacheWriteTokens={row.cacheWriteTokens}
-                      />
+                      <TokensCell billing={row.billing} />
                     </td>
                     <td className="px-4 py-3 text-right font-mono text-xs text-fg-3">
-                      {formatUsdMicrosOrDash(row.totalUsdMicros)}
+                      {formatUsdMicrosOrDash(row.billing.total_usd_micros)}
                     </td>
                   </tr>
                 ))}
@@ -348,12 +274,7 @@ export default function RunBilling({ params }: { params: { id: string } }) {
                     {modelStageCount}
                   </td>
                   <td className="px-4 py-3 text-right font-mono text-xs tabular-nums font-medium text-fg">
-                    <TokensCell
-                      inputTokens={totalInput}
-                      outputTokens={totalOutput}
-                      cacheReadTokens={totalCacheRead}
-                      cacheWriteTokens={totalCacheWrite}
-                    />
+                    <TokensCell billing={totalBilling} />
                   </td>
                   <td className="px-4 py-3 text-right font-mono text-xs font-medium text-fg">
                     {formatUsdMicrosOrDash(totalUsdMicros)}
diff --git a/apps/fabro-web/app/routes/run-stages-chat.test.tsx b/apps/fabro-web/app/routes/run-stages-chat.test.tsx
index c4307ebbc..1142ae6b8 100644
--- a/apps/fabro-web/app/routes/run-stages-chat.test.tsx
+++ b/apps/fabro-web/app/routes/run-stages-chat.test.tsx
@@ -3,6 +3,7 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { StageState } from "@qltysh/fabro-api-client";
 
 import type { Stage } from "../lib/stage-sidebar";
+import { makeBilledTokenCounts } from "../lib/test-fixtures";
 import { StageChatView } from "./run-stages";
 
 function stage(overrides: Partial<Stage> = {}): Stage {
@@ -18,6 +19,7 @@ function stage(overrides: Partial<Stage> = {}): Stage {
     resumedFromStageId: null,
     startedAt: "2026-04-09T12:00:00Z",
     providerUsed: null,
+    billing: makeBilledTokenCounts(),
     ...overrides,
   };
 }
diff --git a/apps/fabro-web/app/routes/run-stages-details.test.tsx b/apps/fabro-web/app/routes/run-stages-details.test.tsx
index 2f453c63e..4483ec4e9 100644
--- a/apps/fabro-web/app/routes/run-stages-details.test.tsx
+++ b/apps/fabro-web/app/routes/run-stages-details.test.tsx
@@ -7,6 +7,7 @@ import type {
   StageModelUsage,
 } from "@qltysh/fabro-api-client";
 
+import { makeBilledTokenCounts } from "../lib/test-fixtures";
 import { EventDetails, ModelUsagePopover } from "./run-stages";
 
 const RUN_START = "2026-04-09T12:00:00Z";
@@ -84,19 +85,7 @@ const PROVIDER_USED: StageModelUsage = {
   reasoning_effort: "max",
 };
 
-function billing(partial: Partial<BilledTokenCounts>): BilledTokenCounts {
-  return {
-    input_tokens: 0,
-    output_tokens: 0,
-    total_tokens: 0,
-    reasoning_tokens: 0,
-    cache_read_tokens: 0,
-    cache_write_tokens: 0,
-    ...partial,
-  };
-}
-
-function popoverMarkup(counts: BilledTokenCounts | null): string {
+function popoverMarkup(counts: BilledTokenCounts): string {
   return renderToStaticMarkup(
     <ModelUsagePopover providerUsed={PROVIDER_USED} billing={counts} />,
   );
@@ -105,7 +94,7 @@ function popoverMarkup(counts: BilledTokenCounts | null): string {
 describe("ModelUsagePopover billing", () => {
   test("shows the visit's token buckets and cost next to the model", () => {
     const html = popoverMarkup(
-      billing({
+      makeBilledTokenCounts({
         input_tokens: 28_640,
         output_tokens: 7_550,
         reasoning_tokens: 1_200,
@@ -131,7 +120,7 @@ describe("ModelUsagePopover billing", () => {
   });
 
   test("omits the token section for a stage that called no model", () => {
-    const html = popoverMarkup(billing({}));
+    const html = popoverMarkup(makeBilledTokenCounts());
 
     expect(html).toContain("kimi-k3");
     expect(html).not.toContain("Tokens");
@@ -140,7 +129,11 @@ describe("ModelUsagePopover billing", () => {
 
   test("still shows tokens when nothing priced the stage", () => {
     const html = popoverMarkup(
-      billing({ input_tokens: 1_000, output_tokens: 500, total_tokens: 1_500 }),
+      makeBilledTokenCounts({
+        input_tokens: 1_000,
+        output_tokens: 500,
+        total_tokens: 1_500,
+      }),
     );
 
     expect(html).toContain("Uncached");
@@ -148,10 +141,13 @@ describe("ModelUsagePopover billing", () => {
     expect(html).not.toContain("Cost");
   });
 
-  test("renders the model rows alone when the stage list carried no billing", () => {
-    const html = popoverMarkup(null);
+  test("shows a provider-reported cost when token counts are unavailable", () => {
+    const html = popoverMarkup(
+      makeBilledTokenCounts({ total_usd_micros: 720_000 }),
+    );
 
     expect(html).toContain("kimi-k3");
-    expect(html).not.toContain("Tokens");
+    expect(html).toContain("Cost");
+    expect(html).toContain("$0.72");
   });
 });
diff --git a/apps/fabro-web/app/routes/run-stages.tsx b/apps/fabro-web/app/routes/run-stages.tsx
index 246f3b2ed..0f03c6a98 100644
--- a/apps/fabro-web/app/routes/run-stages.tsx
+++ b/apps/fabro-web/app/routes/run-stages.tsx
@@ -69,6 +69,7 @@ import {
   formatTokenCount,
   formatUsdMicros,
 } from "../lib/format";
+import { billingTokenBuckets, hasBillingUsage } from "../lib/billing";
 import { plural } from "../lib/plural";
 import {
   useRun,
@@ -870,27 +871,10 @@ export function formatStageModelUsageLabel(
 
 const POPOVER_NUMBER = "block text-right font-mono tabular-nums";
 
-/**
- * The disjoint token buckets behind a stage's usage, labelled and ordered to
- * match the Billing tab's breakdown so the two views read the same. `Uncached`
- * is input that missed the cache; `Output` folds in reasoning tokens.
- */
-function stageTokenBuckets(billing: BilledTokenCounts) {
-  return [
-    { label: "Cache read", value: billing.cache_read_tokens },
-    { label: "Cache creation", value: billing.cache_write_tokens },
-    { label: "Uncached", value: billing.input_tokens },
-    {
-      label: "Output",
-      value: billing.output_tokens + billing.reasoning_tokens,
-    },
-  ];
-}
-
 /** Tokens and cost for this stage visit alone. */
 function StageBillingRows({ billing }: { billing: BilledTokenCounts }) {
-  const buckets = stageTokenBuckets(billing);
-  if (buckets.every((bucket) => bucket.value === 0)) return null;
+  if (!hasBillingUsage(billing)) return null;
+  const buckets = billingTokenBuckets(billing);
   const cost = formatUsdMicros(billing.total_usd_micros);
   return (
     <div className="mt-3">
@@ -920,7 +904,7 @@ export function ModelUsagePopover({
   billing,
 }: {
   providerUsed: StageModelUsage;
-  billing: BilledTokenCounts | null;
+  billing: BilledTokenCounts;
 }) {
   return (
     <>
@@ -943,7 +927,7 @@ export function ModelUsagePopover({
           <PopoverRow label="Speed">{providerUsed.speed}</PopoverRow>
         )}
       </PopoverRows>
-      {billing && <StageBillingRows billing={billing} />}
+      <StageBillingRows billing={billing} />
     </>
   );
 }
@@ -1977,7 +1961,7 @@ function EventsToolbar({
   filteredCount: number;
   totalCount: number;
   providerUsed: StageModelUsage | null;
-  billing: BilledTokenCounts | null;
+  billing: BilledTokenCounts;
   events: EventEnvelope[];
   runId: string;
   stageId: string;
diff --git a/lib/apps/fabro-server/src/server/tests.rs b/lib/apps/fabro-server/src/server/tests.rs
index 69f6fabc3..b3d57cfa2 100644
--- a/lib/apps/fabro-server/src/server/tests.rs
+++ b/lib/apps/fabro-server/src/server/tests.rs
@@ -5259,6 +5259,64 @@ fn test_billed_usage(
     .unwrap()
 }
 
+async fn create_billed_retry_run(state: &Arc<AppState>, run_id: RunId) {
+    create_durable_run_with_events(state, run_id, &[
+        workflow_event::Event::RunSubmitted {
+            definition_blob: None,
+        },
+        workflow_event::Event::RunStarting,
+        workflow_event::Event::RunRunning,
+    ])
+    .await;
+
+    append_scoped_stage_event(
+        state,
+        run_id,
+        "verify",
+        1,
+        &workflow_event::Event::StageFailed {
+            node_id:    "verify".to_string(),
+            name:       "Verify".to_string(),
+            index:      1,
+            failure:    FailureDetail::new("try again", FailureCategory::TransientInfra),
+            will_retry: true,
+            timing:     fabro_types::StageTiming::wall_only(1200),
+            billing:    Some(test_billed_usage("gpt-old", 100, 10)),
+            actor:      None,
+        },
+    )
+    .await;
+    append_scoped_stage_event(
+        state,
+        run_id,
+        "verify",
+        2,
+        &workflow_event::Event::StageCompleted {
+            node_id: "verify".to_string(),
+            name: "Verify".to_string(),
+            index: 1,
+            timing: fabro_types::StageTiming::wall_only(800),
+            status: "succeeded".to_string(),
+            preferred_label: None,
+            suggested_next_ids: Vec::new(),
+            billing: Some(test_billed_usage("gpt-new", 200, 20)),
+            failure: None,
+            notes: None,
+            files_touched: Vec::new(),
+            context_updates: None,
+            jump_to_node: None,
+            context_values: None,
+            node_visits: None,
+            loop_failure_signatures: None,
+            restart_failure_signatures: None,
+            response: None,
+            attempt: 2,
+            max_attempts: 2,
+        },
+    )
+    .await;
+}
+
 #[tokio::test]
 async fn list_run_stages_distinguishes_visits() {
     let state = test_app_state_with_isolated_storage();
@@ -5654,65 +5712,9 @@ async fn run_billing_sums_usage_across_retry_visits_and_uses_latest_model() {
     let state = test_app_state_with_isolated_storage();
     let app = crate::test_support::build_test_router(Arc::clone(&state));
     let run_id = RunId::new();
-    let failed_usage = test_billed_usage("gpt-old", 100, 10);
+
+    create_billed_retry_run(&state, run_id).await;
     let success_usage = test_billed_usage("gpt-new", 200, 20);
-
-    create_durable_run_with_events(&state, run_id, &[
-        workflow_event::Event::RunSubmitted {
-            definition_blob: None,
-        },
-        workflow_event::Event::RunStarting,
-        workflow_event::Event::RunRunning,
-    ])
-    .await;
-
-    append_scoped_stage_event(
-        &state,
-        run_id,
-        "verify",
-        1,
-        &workflow_event::Event::StageFailed {
-            node_id:    "verify".to_string(),
-            name:       "Verify".to_string(),
-            index:      1,
-            failure:    FailureDetail::new("try again", FailureCategory::TransientInfra),
-            will_retry: true,
-            timing:     fabro_types::StageTiming::wall_only(1200),
-            billing:    Some(failed_usage),
-            actor:      None,
-        },
-    )
-    .await;
-    append_scoped_stage_event(
-        &state,
-        run_id,
-        "verify",
-        2,
-        &workflow_event::Event::StageCompleted {
-            node_id: "verify".to_string(),
-            name: "Verify".to_string(),
-            index: 1,
-            timing: fabro_types::StageTiming::wall_only(800),
-            status: "succeeded".to_string(),
-            preferred_label: None,
-            suggested_next_ids: Vec::new(),
-            billing: Some(success_usage.clone()),
-            failure: None,
-            notes: None,
-            files_touched: Vec::new(),
-            context_updates: None,
-            jump_to_node: None,
-            context_values: None,
-            node_visits: None,
-            loop_failure_signatures: None,
-            restart_failure_signatures: None,
-            response: None,
-            attempt: 2,
-            max_attempts: 2,
-        },
-    )
-    .await;
-
     let mut latest_outcome: Outcome<Option<fabro_model::BilledModelUsage>> = Outcome::success();
     latest_outcome.usage = Some(success_usage);
     latest_outcome.timing = Some(fabro_types::StageTiming::wall_only(800));
@@ -5746,7 +5748,6 @@ async fn run_billing_sums_usage_across_retry_visits_and_uses_latest_model() {
     .unwrap();
 
     let response = app
-        .clone()
         .oneshot(
             Request::builder()
                 .method("GET")
@@ -5793,72 +5794,16 @@ async fn run_billing_sums_usage_across_retry_visits_and_uses_latest_model() {
 
 /// The stage popover reads `billing` off the stages list, so it must be scoped
 /// to one visit — unlike the Billing tab's rows, which sum every visit of a
-/// node. This exercises the same two-visit history as
-/// `run_billing_sums_usage_across_retry_visits_and_uses_latest_model`.
+/// node.
 #[tokio::test]
 async fn list_run_stages_reports_billing_per_visit() {
     let state = test_app_state_with_isolated_storage();
     let app = crate::test_support::build_test_router(Arc::clone(&state));
     let run_id = RunId::new();
 
-    create_durable_run_with_events(&state, run_id, &[
-        workflow_event::Event::RunSubmitted {
-            definition_blob: None,
-        },
-        workflow_event::Event::RunStarting,
-        workflow_event::Event::RunRunning,
-    ])
-    .await;
-
-    append_scoped_stage_event(
-        &state,
-        run_id,
-        "verify",
-        1,
-        &workflow_event::Event::StageFailed {
-            node_id:    "verify".to_string(),
-            name:       "Verify".to_string(),
-            index:      1,
-            failure:    FailureDetail::new("try again", FailureCategory::TransientInfra),
-            will_retry: true,
-            timing:     fabro_types::StageTiming::wall_only(1200),
-            billing:    Some(test_billed_usage("gpt-old", 100, 10)),
-            actor:      None,
-        },
-    )
-    .await;
-    append_scoped_stage_event(
-        &state,
-        run_id,
-        "verify",
-        2,
-        &workflow_event::Event::StageCompleted {
-            node_id: "verify".to_string(),
-            name: "Verify".to_string(),
-            index: 1,
-            timing: fabro_types::StageTiming::wall_only(800),
-            status: "succeeded".to_string(),
-            preferred_label: None,
-            suggested_next_ids: Vec::new(),
-            billing: Some(test_billed_usage("gpt-new", 200, 20)),
-            failure: None,
-            notes: None,
-            files_touched: Vec::new(),
-            context_updates: None,
-            jump_to_node: None,
-            context_values: None,
-            node_visits: None,
-            loop_failure_signatures: None,
-            restart_failure_signatures: None,
-            response: None,
-            attempt: 2,
-            max_attempts: 2,
-        },
-    )
-    .await;
+    create_billed_retry_run(&state, run_id).await;
 
     let response = app
-        .clone()
         .oneshot(
             Request::builder()
                 .method("GET")
@@ -5895,23 +5840,8 @@ async fn list_run_stages_reports_zero_billing_for_a_stage_that_called_no_model()
         workflow_event::Event::RunRunning,
     ])
     .await;
-    append_scoped_stage_event(
-        &state,
-        run_id,
-        "script",
-        1,
-        &workflow_event::Event::StageStarted {
-            graph_visit:           None,
-            resumed_from_stage_id: None,
-            node_id:               "script".to_string(),
-            name:                  "Script".to_string(),
-            index:                 0,
-            handler_type:          "command".to_string(),
-            attempt:               1,
-            max_attempts:          1,
-        },
-    )
-    .await;
+    let started = stage_started_event("script", "command");
+    append_scoped_stage_event(&state, run_id, "script", 1, &started).await;
 
     let response = app
         .oneshot(
diff --git a/lib/foundation/fabro-types/src/run_projection.rs b/lib/foundation/fabro-types/src/run_projection.rs
index 987edf03d..6acdbbff0 100644
--- a/lib/foundation/fabro-types/src/run_projection.rs
+++ b/lib/foundation/fabro-types/src/run_projection.rs
@@ -545,10 +545,11 @@ impl StageProjection {
     /// A provider-reported cost always wins. Otherwise the catalog prices the
     /// recorded tokens for the stage's model. The stored counts pass through
     /// untouched when there is no catalog, no model, or no price for that
-    /// model, which leaves `total_usd_micros` as `None` rather than zero.
+    /// model. Empty usage also passes through untouched. These cases leave
+    /// `total_usd_micros` as `None` rather than zero.
     #[must_use]
     pub fn billed_usage(&self, catalog: Option<&Catalog>) -> Cow<'_, BilledTokenCounts> {
-        if self.usage.total_usd_micros.is_some() {
+        if self.usage.total_usd_micros.is_some() || self.usage.is_zero() {
             return Cow::Borrowed(&self.usage);
         }
         let (Some(catalog), Some(model)) = (catalog, self.model.as_ref()) else {
@@ -1052,4 +1053,17 @@ mod iter_stages_tests {
             None
         );
     }
+
+    #[test]
+    fn billed_usage_leaves_zero_tokens_uncosted() {
+        let mut stage = priced_stage(None);
+        stage.usage = BilledTokenCounts::default();
+
+        assert_eq!(
+            stage
+                .billed_usage(Some(Catalog::builtin()))
+                .total_usd_micros,
+            None
+        );
+    }
 }

From 0681d1e6eedd68fe4a78703ec6accab50392bdca Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:52:02 -0400
Subject: [PATCH 29/36] docs: clarify run-create undefined variable handling

---
 .../fabro-workflow/src/transforms/variable_expansion.rs  | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/lib/components/fabro-workflow/src/transforms/variable_expansion.rs b/lib/components/fabro-workflow/src/transforms/variable_expansion.rs
index 311c47189..e739c21a4 100644
--- a/lib/components/fabro-workflow/src/transforms/variable_expansion.rs
+++ b/lib/components/fabro-workflow/src/transforms/variable_expansion.rs
@@ -19,11 +19,10 @@ use crate::static_reference::{
 
 /// How the template-expansion pass should treat undefined input variables.
 ///
-/// Neither validate nor run-create should fail just because the user has not
-/// bound `{{ inputs.* }}` yet, so both render structurally. Run-create then
-/// promotes the resulting warnings to errors itself, which keeps its hard-fail
-/// behavior while still reporting every undefined variable in one pass rather
-/// than aborting on the first.
+/// Both validate and run-create render structurally so they can report every
+/// unbound `{{ inputs.* }}` variable in one pass rather than aborting on the
+/// first. Run-create then promotes the resulting warnings to errors, which
+/// keeps its hard-fail behavior.
 #[derive(Clone, Copy, Debug)]
 pub enum RenderMode {
     /// Undefined inputs abort the pass with a hard error. No production caller

From 1b987528dd2420553048d096bba8583fd1b564e6 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 14:57:05 -0400
Subject: [PATCH 30/36] Simplify artifact version history

---
 apps/fabro-web/app/routes/run-artifacts.tsx   | 234 ++++++++++++------
 .../app/routes/run-artifacts/group.test.ts    |  53 ++--
 .../app/routes/run-artifacts/group.ts         |  46 +---
 3 files changed, 195 insertions(+), 138 deletions(-)

diff --git a/apps/fabro-web/app/routes/run-artifacts.tsx b/apps/fabro-web/app/routes/run-artifacts.tsx
index df719716a..a314973c9 100644
--- a/apps/fabro-web/app/routes/run-artifacts.tsx
+++ b/apps/fabro-web/app/routes/run-artifacts.tsx
@@ -1,11 +1,14 @@
-import { useMemo, useState } from "react";
+import { useMemo } from "react";
 import { useParams } from "react-router";
+import { Disclosure, DisclosureButton, DisclosurePanel } from "@headlessui/react";
 import { ArrowDownTrayIcon, ChevronRightIcon, PaperClipIcon } from "@heroicons/react/24/outline";
+import type { RunArtifactEntry } from "@qltysh/fabro-api-client";
 
 import { EmptyState, ErrorState, LoadingState } from "../components/state";
 import { StageSidebar } from "../components/stage-sidebar";
 import { stageArtifactDownloadUrl } from "../lib/api-client";
 import { formatBytes } from "../lib/format";
+import { plural } from "../lib/plural";
 import { useRunArtifacts, useRunStages } from "../lib/queries";
 import { mapRunStagesToSidebarStages } from "../lib/stage-sidebar";
 import type { ArtifactFile, ArtifactVersion } from "./run-artifacts/group";
@@ -26,7 +29,12 @@ export default function RunArtifacts() {
     <div className="flex gap-6">
       <StageSidebar stages={stages} runId={id!} activeLink="artifacts" />
       <div className="min-w-0 flex-1">
-        <RunArtifactsBody runId={id!} artifactsQuery={artifactsQuery} stages={stages} />
+        <RunArtifactsBody
+          runId={id!}
+          artifactsQuery={artifactsQuery}
+          stagesQuery={stagesQuery}
+          stages={stages}
+        />
       </div>
     </div>
   );
@@ -35,27 +43,50 @@ export default function RunArtifacts() {
 function RunArtifactsBody({
   runId,
   artifactsQuery,
+  stagesQuery,
   stages,
 }: {
   runId: string;
   artifactsQuery: ReturnType<typeof useRunArtifacts>;
+  stagesQuery: ReturnType<typeof useRunStages>;
   stages: ReturnType<typeof mapRunStagesToSidebarStages>;
 }) {
-  const entries = artifactsQuery.data?.data ?? [];
-  const files = useMemo(() => groupArtifactsByFile(entries, stages), [entries, stages]);
-
-  if (artifactsQuery.error) {
+  const error = artifactsQuery.error ?? stagesQuery.error;
+  if (error) {
     return (
       <ErrorState
         title="Couldn't load artifacts"
-        description={errorMessage(artifactsQuery.error)}
-        onRetry={() => void artifactsQuery.mutate()}
+        description={errorMessage(error)}
+        onRetry={() => {
+          if (artifactsQuery.error) void artifactsQuery.mutate();
+          if (stagesQuery.error) void stagesQuery.mutate();
+        }}
       />
     );
   }
-  if (artifactsQuery.data === undefined) {
+  if (artifactsQuery.data === undefined || stagesQuery.data === undefined) {
     return <LoadingState label="Loading artifacts…" />;
   }
+  return (
+    <ArtifactFiles
+      runId={runId}
+      entries={artifactsQuery.data?.data ?? []}
+      stages={stages}
+    />
+  );
+}
+
+function ArtifactFiles({
+  runId,
+  entries,
+  stages,
+}: {
+  runId: string;
+  entries: readonly RunArtifactEntry[];
+  stages: ReturnType<typeof mapRunStagesToSidebarStages>;
+}) {
+  const files = useMemo(() => groupArtifactsByFile(entries, stages), [entries, stages]);
+
   if (files.length === 0) {
     return (
       <EmptyState
@@ -75,7 +106,7 @@ function ArtifactList({ runId, files }: { runId: string; files: readonly Artifac
     let storedBytes = 0;
     for (const file of files) {
       captures += file.versions.length;
-      latestBytes += file.latest.size;
+      latestBytes += file.versions[0].size;
       for (const version of file.versions) storedBytes += version.size;
     }
     return { captures, latestBytes, storedBytes };
@@ -86,14 +117,17 @@ function ArtifactList({ runId, files }: { runId: string; files: readonly Artifac
 
   return (
     <div className="space-y-4">
-      <div className="flex items-baseline justify-between gap-4">
+      <div className="flex flex-wrap items-baseline justify-between gap-4">
         <h2 className="text-sm font-medium text-fg">
-          {files.length} {files.length === 1 ? "file" : "files"}
+          {files.length} {plural(files.length, "file", "files")}
           {versioned && (
-            <span className="font-normal text-fg-muted"> · {captures} versions</span>
+            <span className="font-normal text-fg-muted">
+              {" "}
+              · {captures} {plural(captures, "version", "versions")}
+            </span>
           )}
         </h2>
-        <span className="text-xs tabular-nums text-fg-muted">
+        <span className="text-xs text-fg-muted tabular-nums">
           {versioned
             ? `${formatBytes(latestBytes)} latest · ${formatBytes(storedBytes)} stored`
             : `${formatBytes(latestBytes)} total`}
@@ -110,81 +144,114 @@ function ArtifactList({ runId, files }: { runId: string; files: readonly Artifac
 }
 
 function ArtifactFileRow({ runId, file }: { runId: string; file: ArtifactFile }) {
-  const [expanded, setExpanded] = useState(false);
-  const earlier = file.versions.slice(1);
+  const hasEarlier = file.versions.length > 1;
+  const latest = file.versions[0];
 
   return (
-    <div className="border-t border-line first:border-t-0">
-      <div className="flex items-center gap-4 px-4 py-2.5">
-        {earlier.length > 0 ? (
-          <button
-            type="button"
-            aria-expanded={expanded}
-            onClick={() => setExpanded((prev) => !prev)}
-            className="shrink-0 rounded-md p-1 text-fg-3 transition-colors hover:bg-overlay hover:text-fg-2 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500"
-          >
-            <span className="sr-only">Show earlier versions of {file.name}</span>
-            <ChevronRightIcon
-              className={`size-3.5 transition-transform ${expanded ? "rotate-90" : ""}`}
-              aria-hidden="true"
-            />
-          </button>
-        ) : (
-          <span className="size-5 shrink-0" aria-hidden="true" />
-        )}
+    <Disclosure as="div" className="border-t border-line first:border-t-0">
+      {({ open }) => (
+        <>
+          <div className="flex items-center gap-2 px-3 py-2.5 sm:gap-4 sm:px-4">
+            {hasEarlier ? (
+              <DisclosureButton className="group shrink-0 rounded-md p-1 text-fg-3 transition-colors hover:bg-overlay hover:text-fg-2 focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500">
+                <span className="sr-only">
+                  {open ? "Hide" : "Show"} earlier versions of {file.name}
+                </span>
+                <ChevronRightIcon
+                  className="size-3.5 transition-transform group-data-open:rotate-90"
+                  aria-hidden="true"
+                />
+              </DisclosureButton>
+            ) : (
+              <span className="size-5 shrink-0" aria-hidden="true" />
+            )}
 
-        <span className="flex min-w-0 flex-1 font-mono text-xs" title={file.path}>
-          <span className="shrink-0 text-fg-muted">{file.dir}</span>
-          <span className="truncate text-fg-2">{file.name}</span>
-        </span>
+            <span className="min-w-0 flex-1" title={file.path}>
+              <span className="block truncate font-mono text-xs">
+                <span className="text-fg-muted">{file.dir}</span>
+                <span className="text-fg-2">{file.name}</span>
+              </span>
+              <span className="mt-0.5 block truncate text-[11px] text-fg-3 md:hidden">
+                <VersionLabel version={latest} />
+              </span>
+            </span>
 
-        {earlier.length > 0 && (
-          <span className="shrink-0 rounded-full bg-overlay-strong px-2 py-0.5 text-[11px] text-fg-3">
-            {file.versions.length} versions
-          </span>
-        )}
+            {hasEarlier && (
+              <span className="hidden shrink-0 rounded-full bg-overlay-strong px-2 py-0.5 text-[11px] text-fg-3 lg:inline">
+                {file.versions.length}{" "}
+                {plural(file.versions.length, "version", "versions")}
+              </span>
+            )}
 
-        <span className="shrink-0 text-xs text-fg-3">{file.latest.stageLabel}</span>
-        <span className="shrink-0 text-xs tabular-nums text-fg-muted">
-          {formatBytes(file.latest.size)}
-        </span>
-        <DownloadLink runId={runId} path={file.path} version={file.latest} />
-      </div>
+            <span className="hidden max-w-48 shrink-0 truncate text-xs text-fg-3 md:inline">
+              <VersionLabel version={latest} />
+            </span>
+            <span className="shrink-0 text-xs text-fg-muted tabular-nums">
+              {formatBytes(latest.size)}
+            </span>
+            <DownloadLink runId={runId} file={file} version={latest} />
+          </div>
 
-      {expanded && earlier.length > 0 && (
-        <ul className="border-t border-line bg-black/15 py-1">
-          {earlier.map((version) => (
-            <li
-              key={`${version.stageId}#${version.retry}`}
-              className="flex items-center gap-4 py-1.5 pl-14 pr-4 hover:bg-overlay"
+          {hasEarlier && (
+            <DisclosurePanel
+              as="ul"
+              className="border-t border-line bg-black/15 py-1"
             >
-              <span className="min-w-0 flex-1 truncate text-xs text-fg-3">
-                {version.stageLabel}
-                {version.retry > 1 && (
-                  <span className="ml-2 text-fg-muted">attempt {version.retry}</span>
-                )}
-              </span>
-              <span className="shrink-0 text-xs tabular-nums text-fg-muted">
-                {formatBytes(version.size)}
-              </span>
-              <SizeDelta delta={version.delta} />
-              <DownloadLink runId={runId} path={file.path} version={version} />
-            </li>
-          ))}
-        </ul>
+              <EarlierVersions runId={runId} file={file} />
+            </DisclosurePanel>
+          )}
+        </>
       )}
-    </div>
+    </Disclosure>
   );
 }
 
+function EarlierVersions({ runId, file }: { runId: string; file: ArtifactFile }) {
+  return (
+    <>
+      {file.versions.map((version, index) =>
+        index === 0 ? null : (
+          <li
+            key={`${version.stageId}#${version.retry}`}
+            className="flex items-center gap-2 py-1.5 pr-3 pl-10 hover:bg-overlay sm:gap-4 sm:pr-4 sm:pl-14"
+          >
+            <span className="min-w-0 flex-1 truncate text-xs text-fg-3">
+              <VersionLabel version={version} />
+            </span>
+            <span className="shrink-0 text-xs text-fg-muted tabular-nums">
+              {formatBytes(version.size)}
+            </span>
+            <SizeDelta delta={version.delta} />
+            <DownloadLink runId={runId} file={file} version={version} />
+          </li>
+        ),
+      )}
+    </>
+  );
+}
+
+function VersionLabel({ version }: { version: ArtifactVersion }) {
+  const attempt = attemptLabel(version);
+  return (
+    <>
+      {version.stageLabel}
+      {attempt && <span className="ml-2 text-fg-muted">{attempt}</span>}
+    </>
+  );
+}
+
+function attemptLabel(version: ArtifactVersion): string | null {
+  return version.retry > 1 ? `attempt ${version.retry}` : null;
+}
+
 function SizeDelta({ delta }: { delta: number | null }) {
   if (delta === null) {
-    return <span className="shrink-0 text-[11px] tabular-nums text-fg-muted">first</span>;
+    return <span className="shrink-0 text-[11px] text-fg-muted tabular-nums">first</span>;
   }
   const tone = delta < 0 ? "text-amber" : "text-mint";
   const sign = delta < 0 ? "−" : "+";
   return (
-    <span className={`shrink-0 text-[11px] tabular-nums ${tone}`}>
+    <span className={`shrink-0 text-[11px] ${tone} tabular-nums`}>
       {sign}
       {formatBytes(Math.abs(delta))}
     </span>
@@ -193,31 +260,34 @@ function SizeDelta({ delta }: { delta: number | null }) {
 
 function DownloadLink({
   runId,
-  path,
+  file,
   version,
 }: {
   runId: string;
-  path: string;
+  file: ArtifactFile;
   version: ArtifactVersion;
 }) {
-  const href = stageArtifactDownloadUrl(runId, version.stageId, path, version.retry);
+  const href = stageArtifactDownloadUrl(
+    runId,
+    version.stageId,
+    file.path,
+    version.retry,
+  );
+  const attempt = attemptLabel(version);
+  const source = attempt ? `${version.stageLabel}, ${attempt}` : version.stageLabel;
   return (
     <a
       href={href}
-      download={basename(path)}
+      download={file.name}
+      aria-label={`Download ${file.name} from ${source}`}
       className="inline-flex shrink-0 items-center gap-1 rounded-md px-2 py-1 text-xs text-fg-3 transition-colors hover:bg-overlay hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500"
     >
       <ArrowDownTrayIcon className="size-3.5" aria-hidden="true" />
-      Download
+      <span className="hidden sm:inline">Download</span>
     </a>
   );
 }
 
-function basename(path: string): string {
-  const idx = path.lastIndexOf("/");
-  return idx >= 0 ? path.slice(idx + 1) : path;
-}
-
 function errorMessage(error: unknown): string | undefined {
   return error instanceof Error ? error.message : undefined;
 }
diff --git a/apps/fabro-web/app/routes/run-artifacts/group.test.ts b/apps/fabro-web/app/routes/run-artifacts/group.test.ts
index a4cfa2ff9..72762c13e 100644
--- a/apps/fabro-web/app/routes/run-artifacts/group.test.ts
+++ b/apps/fabro-web/app/routes/run-artifacts/group.test.ts
@@ -81,24 +81,46 @@ describe("groupArtifactsByFile", () => {
     expect(files[0].versions).toHaveLength(4);
   });
 
-  test("orders versions newest first using stage start time, not stage name", () => {
+  test("orders versions newest first using the API stage order", () => {
+    const stages = [
+      stage("implement_plan", "2026-07-27T20:00:00Z"),
+      stage("simplify", "2026-07-27T18:43:11Z"),
+    ];
     const files = groupArtifactsByFile(
       [
-        artifact("consolidate_reviews", REPORT, 14323),
-        artifact("fix_review_findings", REPORT, 17483),
         artifact("implement_plan", REPORT, 8422),
         artifact("simplify", REPORT, 13162),
       ],
-      STAGES,
+      stages,
+    );
+
+    expect(files[0].versions.map((v) => v.stageLabel)).toEqual([
+      "simplify",
+      "implement_plan",
+    ]);
+    expect(files[0].versions[0].size).toBe(13162);
+  });
+
+  test.each([
+    ["equal", "2026-07-27T18:43:11Z", "2026-07-27T18:43:11Z"],
+    ["missing", null, null],
+  ])("preserves API order when stage timestamps are %s", (_case, firstAt, secondAt) => {
+    const stages = [
+      stage("implement_plan", firstAt),
+      stage("simplify", secondAt),
+    ];
+    const files = groupArtifactsByFile(
+      [
+        artifact("simplify", REPORT, 13162),
+        artifact("implement_plan", REPORT, 8422),
+      ],
+      stages,
     );
 
     expect(files[0].versions.map((v) => v.stageLabel)).toEqual([
-      "fix_review_findings",
-      "consolidate_reviews",
       "simplify",
       "implement_plan",
     ]);
-    expect(files[0].latest.size).toBe(17483);
   });
 
   test("reports the byte change each capture introduced, oldest capture first", () => {
@@ -155,25 +177,10 @@ describe("groupArtifactsByFile", () => {
     );
 
     expect(files[0].versions.map((v) => v.retry)).toEqual([2, 1]);
-    expect(files[0].latest.size).toBe(13162);
+    expect(files[0].versions[0].size).toBe(13162);
     expect(files[0].versions.map((v) => v.delta)).toEqual([4162, null]);
   });
 
-  test("falls back to a stable order when stages have not loaded yet", () => {
-    const files = groupArtifactsByFile(
-      [
-        artifact("simplify", REPORT, 13162),
-        artifact("implement_plan", REPORT, 8422),
-      ],
-      [],
-    );
-
-    expect(files[0].versions.map((v) => v.stageLabel)).toEqual([
-      "simplify",
-      "implement_plan",
-    ]);
-  });
-
   test("returns no files when every capture came from a control node", () => {
     const files = groupArtifactsByFile(
       [artifact("start", ".ai/reports/pre-existing.md", 12402)],
diff --git a/apps/fabro-web/app/routes/run-artifacts/group.ts b/apps/fabro-web/app/routes/run-artifacts/group.ts
index 99ee84f83..b3577e3c6 100644
--- a/apps/fabro-web/app/routes/run-artifacts/group.ts
+++ b/apps/fabro-web/app/routes/run-artifacts/group.ts
@@ -20,8 +20,7 @@ export interface ArtifactFile {
   /** Directory prefix including the trailing slash, or "" at the root. */
   dir: string;
   name: string;
-  versions: ArtifactVersion[];
-  latest: ArtifactVersion;
+  versions: readonly [ArtifactVersion, ...ArtifactVersion[]];
 }
 
 export function splitArtifactPath(path: string): { dir: string; name: string } {
@@ -36,29 +35,10 @@ interface StageInfo {
   order: number;
 }
 
-/**
- * Chronological position of each stage, keyed by stage ID.
- *
- * Stage IDs are `node@visit`, where `visit` counts visits to that one node — it
- * is not a run-wide ordinal, so it cannot order stages against each other.
- * `startedAt` is the only run-wide clock available here.
- */
+/** Stage display data keyed by ID, preserving the API's event order. */
 function stageInfoById(stages: readonly Stage[]): Map<string, StageInfo> {
-  const chronological = stages
-    .map((stage, index) => ({ stage, index }))
-    .sort((a, b) => {
-      const at = a.stage.startedAt;
-      const bt = b.stage.startedAt;
-      // Stages that have not started yet sort last but keep a stable order.
-      if (at === null && bt === null) return a.index - b.index;
-      if (at === null) return 1;
-      if (bt === null) return -1;
-      const cmp = at.localeCompare(bt);
-      return cmp !== 0 ? cmp : a.index - b.index;
-    });
-
   const info = new Map<string, StageInfo>();
-  chronological.forEach(({ stage }, order) => {
+  stages.forEach((stage, order) => {
     info.set(stage.id, { label: formatStageLabel(stage), order });
   });
   return info;
@@ -77,21 +57,18 @@ export function groupArtifactsByFile(
   stages: readonly Stage[],
 ): ArtifactFile[] {
   const stageInfo = stageInfoById(stages);
-  const byPath = new Map<string, Array<ArtifactVersion & { order: number }>>();
+  const byPath = new Map<string, [ArtifactVersion, ...ArtifactVersion[]]>();
 
   for (const entry of entries) {
     if (!isVisibleStage(entry.node_slug)) continue;
 
-    // Until the stages request resolves there is no clock to order by, so
-    // unresolved stages fall back to a stable sort on stage ID.
     const info = stageInfo.get(entry.stage_id);
-    const version: ArtifactVersion & { order: number } = {
+    const version: ArtifactVersion = {
       stageId: entry.stage_id,
       stageLabel: info?.label ?? entry.node_slug,
       retry: entry.retry,
       size: entry.size,
       delta: null,
-      order: info?.order ?? Number.MAX_SAFE_INTEGER,
     };
     const bucket = byPath.get(entry.relative_path);
     if (bucket) bucket.push(version);
@@ -103,18 +80,21 @@ export function groupArtifactsByFile(
     // Oldest first, so each version's delta is the change that capture introduced.
     versions.sort(
       (a, b) =>
-        a.order - b.order || a.retry - b.retry || a.stageId.localeCompare(b.stageId),
+        (stageInfo.get(a.stageId)?.order ?? -1) -
+          (stageInfo.get(b.stageId)?.order ?? -1) ||
+        a.retry - b.retry ||
+        a.stageId.localeCompare(b.stageId),
     );
     versions.forEach((version, index) => {
       version.delta = index === 0 ? null : version.size - versions[index - 1].size;
     });
 
-    const newestFirst = versions.slice().reverse();
-    const latest = newestFirst[0];
+    versions.reverse();
+    const latest = versions[0];
     const { dir, name } = splitArtifactPath(path);
     files.push({
-      file: { path, dir, name, versions: newestFirst, latest },
-      order: latest.order,
+      file: { path, dir, name, versions },
+      order: stageInfo.get(latest.stageId)?.order ?? -1,
     });
   }
 

From 8e066ecf7b16d357545d1dec015cdb38c7c114e6 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 15:14:23 -0400
Subject: [PATCH 31/36] refactor: remove duplicated review target rendering and
 validation

The review question sentence was written in four places and the URL
safety rules in three. Collapse each to one definition.

- Add `ReviewTarget::question_text_with_link` as the single definition of
  the question wording. `question_text()` and the Slack header both use
  it, so a wording change is now one edit.
- Delete `ReviewTargetKind::noun()`. The enum already derives
  `strum::Display` with the same snake_case output.
- Share one `review_target_line` helper between the console interviewer
  and the CLI attach client, which held a byte-identical copy. Print only
  the URL: `question.text` already carries the label and the noun.
- Trim the web-side check to the URL scheme, host, and credentials, which
  are what a raw `href` can act on. Label length and control characters
  cannot affect the DOM and stay server-side.
- Split validation from presentation in the web UI. `safeReviewTarget`
  returns the target or null, and each caller picks its own fallback, so
  an unsafe target now falls back to the same Markdown rendering as a
  question with no target.
- Derive the resource noun from `kind` in the web UI instead of
  hardcoding "document".
- Use `ReviewTargetKind.DOCUMENT` and the shared `isRecord` guard when
  parsing events, instead of a raw string and a hand-rolled object check
  that accepted arrays.
- Drop `deny_unknown_fields` from the wire struct. The OpenAPI schema
  leaves `additionalProperties` permissive, so an added field would
  otherwise make persisted events unreadable.
- Import `ReviewTarget` by name, and stop naming Slack in a fabro-types
  error message.
- Document that `review_target=true` replaces the gate's `label`.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../app/components/interview-dock.tsx         | 21 ++++--
 .../app/components/review-target-question.tsx | 69 +++++++------------
 .../app/components/stage-renderers/helpers.ts | 27 ++++----
 .../components/stage-renderers/human-qa.tsx   | 11 +--
 docs/public/reference/dot-language.mdx        |  2 +-
 docs/public/workflows/human-in-the-loop.mdx   |  3 +
 lib/apps/fabro-cli/src/commands/run/attach.rs |  9 +--
 lib/components/fabro-interview/src/console.rs | 47 +++++++------
 lib/components/fabro-interview/src/lib.rs     |  2 +-
 lib/components/fabro-slack/src/blocks.rs      |  7 +-
 lib/foundation/fabro-types/src/interview.rs   | 37 +++++-----
 .../fabro-types/src/run_event/misc.rs         |  6 +-
 12 files changed, 122 insertions(+), 119 deletions(-)

diff --git a/apps/fabro-web/app/components/interview-dock.tsx b/apps/fabro-web/app/components/interview-dock.tsx
index 5012f53c1..953481d8d 100644
--- a/apps/fabro-web/app/components/interview-dock.tsx
+++ b/apps/fabro-web/app/components/interview-dock.tsx
@@ -22,9 +22,14 @@ import {
 } from "../lib/mutations";
 import { ApiError } from "../lib/api-client";
 import { displayLabel } from "./interview-label";
-import { ReviewTargetQuestion } from "./review-target-question";
+import {
+  ReviewTargetQuestion,
+  safeReviewTarget,
+} from "./review-target-question";
 import { ErrorMessage } from "./ui";
 
+const QUESTION_TEXT = "text-pretty text-base/6 font-medium text-fg";
+
 const PRIMARY_BUTTON =
   "inline-flex items-center justify-center gap-1.5 rounded-lg bg-teal-500 px-3.5 py-2 text-sm font-medium text-on-primary transition-colors hover:bg-teal-300 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-teal-500";
 
@@ -78,6 +83,7 @@ function InterviewQuestionDock({
   const submitMutation = useSubmitInterviewAnswer(runId);
   const [error, setError] = useState<string | null>(null);
   const submitting = submitMutation.isMutating;
+  const reviewTarget = safeReviewTarget(question.review_target);
 
   const submit = useCallback(
     async (answer: SubmitInterviewAnswer) => {
@@ -100,11 +106,14 @@ function InterviewQuestionDock({
       />
       <div className="space-y-5 px-5 py-4 sm:px-6">
         <div>
-          <ReviewTargetQuestion
-            reviewTarget={question.review_target}
-            fallbackText={question.text}
-            className="text-pretty text-base/6 font-medium text-fg"
-          />
+          {reviewTarget ? (
+            <ReviewTargetQuestion
+              target={reviewTarget}
+              className={QUESTION_TEXT}
+            />
+          ) : (
+            <p className={QUESTION_TEXT}>{question.text}</p>
+          )}
           <p className="mt-1 text-xs/5 text-fg-muted">
             {questionTypeLabel(question.question_type)}
           </p>
diff --git a/apps/fabro-web/app/components/review-target-question.tsx b/apps/fabro-web/app/components/review-target-question.tsx
index 99c041923..22961f95f 100644
--- a/apps/fabro-web/app/components/review-target-question.tsx
+++ b/apps/fabro-web/app/components/review-target-question.tsx
@@ -1,76 +1,59 @@
 import { ArrowTopRightOnSquareIcon } from "@heroicons/react/20/solid";
-import {
-  ReviewTargetKind,
-  type ReviewTarget,
-} from "@qltysh/fabro-api-client";
-
-const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/u;
-const UNSAFE_LINK_DELIMITER = /[<>|]/u;
-
-function unicodeScalarCount(value: string): number {
-  return Array.from(value).length;
-}
-
-function hasSafeReviewTarget(target: ReviewTarget | null | undefined): target is ReviewTarget {
-  if (
-    !target ||
-    target.kind !== ReviewTargetKind.DOCUMENT ||
-    !target.label.trim() ||
-    target.label !== target.label.trim() ||
-    unicodeScalarCount(target.label) > 200 ||
-    CONTROL_CHARACTER.test(target.label) ||
-    !target.url ||
-    target.url !== target.url.trim() ||
-    unicodeScalarCount(target.url) > 2048 ||
-    CONTROL_CHARACTER.test(target.url) ||
-    UNSAFE_LINK_DELIMITER.test(target.url)
-  ) {
-    return false;
-  }
+import type { ReviewTarget } from "@qltysh/fabro-api-client";
 
+/**
+ * Re-check the URL before putting it in an `href`. The server already rejects
+ * unsafe targets (see `ReviewTarget::new` in
+ * `lib/foundation/fabro-types/src/interview.rs`), but React does not sanitize
+ * `href`, so a `javascript:` URL reaching this component would execute. Length
+ * and control-character limits stay server-side; they cannot affect the DOM.
+ */
+export function safeReviewTarget(
+  target: ReviewTarget | null | undefined,
+): ReviewTarget | null {
+  if (!target?.url || !target.label) return null;
   try {
     const parsed = new URL(target.url);
-    return (
+    const safe =
       (parsed.protocol === "http:" || parsed.protocol === "https:") &&
       Boolean(parsed.host) &&
       !parsed.username &&
-      !parsed.password
-    );
+      !parsed.password;
+    return safe ? target : null;
   } catch {
-    return false;
+    return null;
   }
 }
 
+/**
+ * The review question sentence, with the target label as an external link.
+ * Mirrors `ReviewTarget::question_text_with_link` in
+ * `lib/foundation/fabro-types/src/interview.rs`.
+ */
 export function ReviewTargetQuestion({
-  reviewTarget,
-  fallbackText,
+  target,
   className,
 }: {
-  reviewTarget: ReviewTarget | null | undefined;
-  fallbackText: string;
+  target: ReviewTarget;
   className?: string;
 }) {
-  if (!hasSafeReviewTarget(reviewTarget)) {
-    return <p className={className}>{fallbackText}</p>;
-  }
-
   return (
     <p className={className}>
       Review the{" "}
       <a
-        href={reviewTarget.url}
+        href={target.url}
         target="_blank"
         rel="noopener noreferrer"
         referrerPolicy="no-referrer"
         className="inline-flex items-baseline gap-1 font-semibold text-teal-300 underline decoration-teal-500/50 underline-offset-2 transition-colors hover:text-fg focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500"
       >
-        <span>{reviewTarget.label}</span>
+        <span>{target.label}</span>
         <ArrowTopRightOnSquareIcon
           className="size-3 shrink-0 self-center"
           aria-hidden="true"
         />
       </a>{" "}
-      document, then choose the next action.
+      {target.kind}, then choose the next action.
     </p>
   );
 }
diff --git a/apps/fabro-web/app/components/stage-renderers/helpers.ts b/apps/fabro-web/app/components/stage-renderers/helpers.ts
index 6ddcba7a0..024c086c8 100644
--- a/apps/fabro-web/app/components/stage-renderers/helpers.ts
+++ b/apps/fabro-web/app/components/stage-renderers/helpers.ts
@@ -1,10 +1,14 @@
-import { StageOutcome } from "@qltysh/fabro-api-client";
-import type {
-  EventEnvelope,
-  ReviewTarget,
-} from "@qltysh/fabro-api-client";
+import { ReviewTargetKind, StageOutcome } from "@qltysh/fabro-api-client";
+import type { EventEnvelope, ReviewTarget } from "@qltysh/fabro-api-client";
 
-import { getArray, getNumber, getObject, getString, type UnknownRecord } from "../../lib/unknown";
+import {
+  getArray,
+  getNumber,
+  getObject,
+  getString,
+  isRecord,
+  type UnknownRecord,
+} from "../../lib/unknown";
 
 const STAGE_OUTCOMES: ReadonlySet<string> = new Set(Object.values(StageOutcome));
 
@@ -80,12 +84,11 @@ function parseInterviewOptions(value: unknown): InterviewOption[] {
 }
 
 function parseReviewTarget(value: unknown): ReviewTarget | null {
-  if (!value || typeof value !== "object") return null;
-  const record = value as UnknownRecord;
-  const label = getString(record, "label");
-  const url = getString(record, "url");
-  const kind = getString(record, "kind");
-  if (!label || !url || kind !== "document") return null;
+  if (!isRecord(value)) return null;
+  const label = getString(value, "label");
+  const url = getString(value, "url");
+  const kind = getString(value, "kind");
+  if (!label || !url || kind !== ReviewTargetKind.DOCUMENT) return null;
   return { label, url, kind };
 }
 
diff --git a/apps/fabro-web/app/components/stage-renderers/human-qa.tsx b/apps/fabro-web/app/components/stage-renderers/human-qa.tsx
index c2180c0ef..11ed93b28 100644
--- a/apps/fabro-web/app/components/stage-renderers/human-qa.tsx
+++ b/apps/fabro-web/app/components/stage-renderers/human-qa.tsx
@@ -10,7 +10,10 @@ import {
 import type { EventEnvelope } from "@qltysh/fabro-api-client";
 
 import type { Stage } from "../stage-sidebar";
-import { ReviewTargetQuestion } from "../review-target-question";
+import {
+  ReviewTargetQuestion,
+  safeReviewTarget,
+} from "../review-target-question";
 import { Tooltip } from "../ui";
 import { formatAbsoluteTs, formatDurationMs } from "../../lib/format";
 import { ACTIVE_STAGE_STATES } from "../../lib/stage-sidebar";
@@ -149,6 +152,7 @@ function QuestionBlock({
   stageActive: boolean;
 }) {
   const { question, resolution } = pair;
+  const reviewTarget = safeReviewTarget(question.reviewTarget);
   return (
     <article className="space-y-3">
       <header className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
@@ -169,10 +173,9 @@ function QuestionBlock({
       </header>
 
       <div className="rounded-lg bg-panel p-4 outline-1 -outline-offset-1 outline-line">
-        {question.reviewTarget ? (
+        {reviewTarget ? (
           <ReviewTargetQuestion
-            reviewTarget={question.reviewTarget}
-            fallbackText={question.question}
+            target={reviewTarget}
             className="text-sm/6 text-fg-2"
           />
         ) : (
diff --git a/docs/public/reference/dot-language.mdx b/docs/public/reference/dot-language.mdx
index a341f1145..d19ccb806 100644
--- a/docs/public/reference/dot-language.mdx
+++ b/docs/public/reference/dot-language.mdx
@@ -267,7 +267,7 @@ For the first node in each branch, `fidelity` resolves from the fork-to-branch e
 | Attribute | Type | Description |
 |---|---|---|
 | `question_type` | String | Optional interview question type override: `yes_no`, `confirmation`, `multiple_choice`, `multi_select`, or `freeform`. Defaults to `freeform` when the gate only has a freeform edge; otherwise defaults to `multiple_choice`. |
-| `review_target` | Boolean | When `true`, read and validate the typed `review_target` context value, then present it as the primary link in the question. See [Review targets](/workflows/human-in-the-loop#review-targets). |
+| `review_target` | Boolean | When `true`, read and validate the typed `review_target` context value, then present it as the primary link in the question. Fabro generates the question text, so the node's `label` is not used. See [Review targets](/workflows/human-in-the-loop#review-targets). |
 | `human.default_choice` | String | Target node to use when the question times out. |
 
 ### Manager loop (sub-workflow) nodes
diff --git a/docs/public/workflows/human-in-the-loop.mdx b/docs/public/workflows/human-in-the-loop.mdx
index bf95362eb..f1cb0bfa7 100644
--- a/docs/public/workflows/human-in-the-loop.mdx
+++ b/docs/public/workflows/human-in-the-loop.mdx
@@ -99,6 +99,9 @@ Fabro then presents this question:
 The link uses the target URL from context. The example uses a placeholder
 secret, not a live Quarry document.
 
+Fabro generates this question text from the target. A `label` on the gate is
+not used while `review_target=true`.
+
 The target object has three required fields:
 
 | Field | Meaning |
diff --git a/lib/apps/fabro-cli/src/commands/run/attach.rs b/lib/apps/fabro-cli/src/commands/run/attach.rs
index 122ae8b1f..cd356ffa0 100644
--- a/lib/apps/fabro-cli/src/commands/run/attach.rs
+++ b/lib/apps/fabro-cli/src/commands/run/attach.rs
@@ -452,13 +452,8 @@ async fn ask_attach_question(question: Question, styles: &'static Styles) -> Ans
         let rendered = styles.render_markdown(context_text);
         eprint!("{rendered}");
     }
-    if let Some(target) = &question.review_target {
-        eprintln!(
-            "Review {}: {} — {}",
-            target.kind().noun(),
-            target.label(),
-            target.url()
-        );
+    if let Some(line) = fabro_interview::review_target_line(&question) {
+        eprintln!("{line}");
     }
     eprintln!("{} {}", styles.bold_cyan.apply_to("?"), question.text);
 
diff --git a/lib/components/fabro-interview/src/console.rs b/lib/components/fabro-interview/src/console.rs
index bc4de4c15..b96114765 100644
--- a/lib/components/fabro-interview/src/console.rs
+++ b/lib/components/fabro-interview/src/console.rs
@@ -111,15 +111,16 @@ fn parse_non_tty_freeform_response(prompt_read: PromptRead) -> Answer {
     }
 }
 
-fn review_target_line(question: &Question) -> Option<String> {
-    question.review_target.as_ref().map(|target| {
-        format!(
-            "Review {}: {} — {}",
-            target.kind().noun(),
-            target.label(),
-            target.url()
-        )
-    })
+/// The review target line printed above a question in terminal clients, which
+/// cannot render a hyperlink label. The label and resource noun are already in
+/// `question.text`, so only the URL is shown. Shared with `fabro-cli`'s attach
+/// client.
+#[must_use]
+pub fn review_target_line(question: &Question) -> Option<String> {
+    question
+        .review_target
+        .as_ref()
+        .map(|target| format!("Review link: {}", target.url()))
 }
 
 /// Ask a multiple-choice question using dialoguer's `Select` widget on a TTY.
@@ -332,26 +333,32 @@ mod tests {
     }
 
     #[test]
-    fn review_target_line_includes_label_and_url() {
-        let mut question = Question::new("Review", QuestionType::MultipleChoice);
-        question.review_target = Some(
-            fabro_types::ReviewTarget::new(
-                "Quarry review exercise",
-                "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
-                fabro_types::ReviewTargetKind::Document,
-            )
-            .unwrap(),
-        );
+    fn review_target_line_shows_only_the_url() {
+        let target = fabro_types::ReviewTarget::new(
+            "Quarry review exercise",
+            "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+            fabro_types::ReviewTargetKind::Document,
+        )
+        .unwrap();
+        let mut question = Question::new(target.question_text(), QuestionType::MultipleChoice);
+        question.review_target = Some(target);
 
         assert_eq!(
             review_target_line(&question).as_deref(),
             Some(
-                "Review document: Quarry review exercise — \
+                "Review link: \
                  https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef"
             )
         );
     }
 
+    #[test]
+    fn review_target_line_is_absent_without_a_target() {
+        let question = Question::new("Approve?", QuestionType::YesNo);
+
+        assert_eq!(review_target_line(&question), None);
+    }
+
     #[test]
     fn find_matching_option_by_key_case_insensitive() {
         let options = vec![InterviewOption {
diff --git a/lib/components/fabro-interview/src/lib.rs b/lib/components/fabro-interview/src/lib.rs
index e32f4bd30..4493f98ca 100644
--- a/lib/components/fabro-interview/src/lib.rs
+++ b/lib/components/fabro-interview/src/lib.rs
@@ -222,7 +222,7 @@ pub trait Interviewer: Send + Sync {
 // Re-export all implementors at the crate root
 pub use auto_approve::AutoApproveInterviewer;
 pub use callback::CallbackInterviewer;
-pub use console::ConsoleInterviewer;
+pub use console::{ConsoleInterviewer, review_target_line};
 pub use control::{ControlInterviewer, SubmitError};
 pub use control_protocol::{
     WORKER_CONTROL_INVALID_CURSOR_REASON, WORKER_CONTROL_PONG_TIMEOUT_REASON,
diff --git a/lib/components/fabro-slack/src/blocks.rs b/lib/components/fabro-slack/src/blocks.rs
index 51c60010b..48aa9378f 100644
--- a/lib/components/fabro-slack/src/blocks.rs
+++ b/lib/components/fabro-slack/src/blocks.rs
@@ -102,11 +102,8 @@ fn header_section(question: &Question, run_web_url: Option<&str>) -> Value {
     let mut text = question.review_target.as_ref().map_or_else(
         || format!("*{}*", escape_slack_controls(&question.text)),
         |target| {
-            format!(
-                "*Review the {} {}, then choose the next action.*",
-                slack_link(target.url(), target.label()),
-                target.kind().noun()
-            )
+            let link = slack_link(target.url(), target.label());
+            format!("*{}*", target.question_text_with_link(&link))
         },
     );
     if !question.stage.is_empty() {
diff --git a/lib/foundation/fabro-types/src/interview.rs b/lib/foundation/fabro-types/src/interview.rs
index 157fc31c6..729ad6250 100644
--- a/lib/foundation/fabro-types/src/interview.rs
+++ b/lib/foundation/fabro-types/src/interview.rs
@@ -7,25 +7,15 @@ use crate::run_event::InterviewOption;
 const REVIEW_TARGET_LABEL_MAX_CHARS: usize = 200;
 const REVIEW_TARGET_URL_MAX_CHARS: usize = 2048;
 
-/// The type of resource a human should review.
-#[derive(
-    Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, strum::Display, strum::EnumString,
-)]
+/// The type of resource a human should review. `Display` renders the noun used
+/// in review question text ("document").
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, strum::Display)]
 #[serde(rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
 pub enum ReviewTargetKind {
     Document,
 }
 
-impl ReviewTargetKind {
-    #[must_use]
-    pub const fn noun(self) -> &'static str {
-        match self {
-            Self::Document => "document",
-        }
-    }
-}
-
 /// A validated external resource presented as the primary subject of a human
 /// review question.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
@@ -71,12 +61,21 @@ impl ReviewTarget {
         self.kind
     }
 
+    /// The question text shown to a human, with the label rendered as plain
+    /// text.
     #[must_use]
     pub fn question_text(&self) -> String {
+        self.question_text_with_link(&self.label)
+    }
+
+    /// The same sentence as [`Self::question_text`], with the label replaced by
+    /// a client-specific rendering of the link (Slack `<url|label>` syntax, for
+    /// example). This is the single definition of the review question wording.
+    #[must_use]
+    pub fn question_text_with_link(&self, rendered_link: &str) -> String {
         format!(
-            "Review the {} {}, then choose the next action.",
-            self.label,
-            self.kind.noun()
+            "Review the {rendered_link} {}, then choose the next action.",
+            self.kind
         )
     }
 }
@@ -93,7 +92,7 @@ pub enum ReviewTargetError {
     EmptyUrl,
     #[error("review target URL must be at most {REVIEW_TARGET_URL_MAX_CHARS} characters")]
     UrlTooLong,
-    #[error("review target URL must not contain control characters or Slack link delimiters")]
+    #[error("review target URL must not contain control characters or link delimiters")]
     UrlContainsUnsafeCharacters,
     #[error("review target URL must be a valid absolute URL")]
     InvalidUrl,
@@ -154,8 +153,10 @@ impl<'de> Deserialize<'de> for ReviewTarget {
     where
         D: serde::Deserializer<'de>,
     {
+        // Unknown fields are ignored so the OpenAPI contract (which leaves
+        // `additionalProperties` permissive) and this deserializer agree, and
+        // so an unknown key in a persisted event cannot fail the whole event.
         #[derive(Deserialize)]
-        #[serde(deny_unknown_fields)]
         struct WireReviewTarget {
             label: String,
             url:   String,
diff --git a/lib/foundation/fabro-types/src/run_event/misc.rs b/lib/foundation/fabro-types/src/run_event/misc.rs
index ad8b1b4a5..13612c677 100644
--- a/lib/foundation/fabro-types/src/run_event/misc.rs
+++ b/lib/foundation/fabro-types/src/run_event/misc.rs
@@ -1,7 +1,9 @@
 use serde::{Deserialize, Serialize};
 
 use super::ExecOutputTail;
-use crate::{CommandTermination, ParallelBranchResult, PullRequestLink, StageId, StageOutcome};
+use crate::{
+    CommandTermination, ParallelBranchResult, PullRequestLink, ReviewTarget, StageId, StageOutcome,
+};
 
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
 pub struct InterviewOption {
@@ -66,7 +68,7 @@ pub struct InterviewStartedProps {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub context_display: Option<String>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub review_target:   Option<crate::ReviewTarget>,
+    pub review_target:   Option<ReviewTarget>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]

From 3d8cf48f9b8dacd03c5dfc781d22544260e1539a Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 15:24:58 -0400
Subject: [PATCH 32/36] fix(web): harden collapsible run docks

---
 .../app/components/interview-dock.tsx         |  53 ++++--
 .../app/components/run-dock.test.tsx          | 118 +++++++++++++
 apps/fabro-web/app/components/run-dock.tsx    |  79 +++++----
 .../app/components/steer-bar.test.tsx         | 124 +++++++++++++-
 apps/fabro-web/app/components/steer-bar.tsx   |  28 +++-
 apps/fabro-web/app/lib/class-names.ts         |   5 +
 apps/fabro-web/app/routes/run-detail.test.ts  |  22 ++-
 apps/fabro-web/app/routes/run-detail.tsx      |  51 ++++--
 .../run-detail/docked-controls.test.tsx       | 158 ++++++++++++++++++
 .../app/routes/run-detail/docked-controls.tsx |  52 ++++--
 .../app/routes/run-detail/header.tsx          |   3 +-
 apps/fabro-web/app/routes/run-detail/model.ts |   4 -
 .../app/routes/run-detail/tabs-shell.tsx      |   2 +-
 13 files changed, 612 insertions(+), 87 deletions(-)
 create mode 100644 apps/fabro-web/app/components/run-dock.test.tsx
 create mode 100644 apps/fabro-web/app/lib/class-names.ts
 create mode 100644 apps/fabro-web/app/routes/run-detail/docked-controls.test.tsx

diff --git a/apps/fabro-web/app/components/interview-dock.tsx b/apps/fabro-web/app/components/interview-dock.tsx
index e53804772..b2d46cb1f 100644
--- a/apps/fabro-web/app/components/interview-dock.tsx
+++ b/apps/fabro-web/app/components/interview-dock.tsx
@@ -18,14 +18,16 @@ import { ApiError } from "../lib/api-client";
 import { displayLabel } from "./interview-label";
 import {
   DockComposer,
-  DockSpinner,
   RunDockShell,
   DOCK_CHOICE_BUTTON,
   DOCK_CHOICE_BUTTON_SELECTED,
   DOCK_HEADER_BUTTON,
-  DOCK_PRIMARY_BUTTON,
 } from "./run-dock";
-import { ErrorMessage } from "./ui";
+import { Spinner } from "./state";
+import {
+  ErrorMessage,
+  PRIMARY_BUTTON_CLASS,
+} from "./ui";
 
 /**
  * Options stack into a list once a label is long enough that a row of pills
@@ -118,7 +120,7 @@ function InterviewQuestionDock({
       }
       body={
         <>
-          <p className="max-w-[78ch] text-pretty text-base/6 font-medium text-fg">
+          <p className="max-w-[78ch] text-base/6 font-medium text-pretty text-fg">
             {question.text}
           </p>
           {question.context_display && (
@@ -154,7 +156,7 @@ function ContextPanel({ text }: { text: string }) {
           aria-hidden="true"
         />
         Context from preceding stage
-        <span className="ml-auto truncate pl-3 font-sans text-xs normal-case tracking-normal group-open:hidden">
+        <span className="ml-auto truncate pl-3 font-sans text-xs tracking-normal normal-case group-open:hidden">
           {contextPreview(text)}
         </span>
       </summary>
@@ -167,9 +169,18 @@ function ContextPanel({ text }: { text: string }) {
 
 /** First line of the context, for the collapsed summary. */
 export function contextPreview(text: string): string {
-  const line = text.split("\n").find((candidate) => candidate.trim()) ?? "";
-  const trimmed = line.trim();
-  return trimmed.length > 60 ? `${trimmed.slice(0, 60).trimEnd()}…` : trimmed;
+  let lineStart = 0;
+  while (lineStart < text.length) {
+    const newline = text.indexOf("\n", lineStart);
+    const lineEnd = newline === -1 ? text.length : newline;
+    const line = text.slice(lineStart, lineEnd).trim();
+    if (line) {
+      return line.length > 60 ? `${line.slice(0, 60).trimEnd()}…` : line;
+    }
+    if (newline === -1) break;
+    lineStart = newline + 1;
+  }
+  return "";
 }
 
 function QuestionBody({
@@ -240,9 +251,13 @@ function YesNoBody({
         aria-label="Answer yes"
         disabled={submitting}
         onClick={() => void onSubmit({ kind: "yes" })}
-        className={DOCK_PRIMARY_BUTTON}
+        className={PRIMARY_BUTTON_CLASS}
       >
-        {submitting ? <DockSpinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
+        {submitting ? (
+          <Spinner className="size-4" />
+        ) : (
+          <CheckIcon className="size-4" aria-hidden="true" />
+        )}
         Yes
       </button>
     </div>
@@ -262,9 +277,13 @@ function ConfirmationBody({
         type="button"
         disabled={submitting}
         onClick={() => void onSubmit({ kind: "yes" })}
-        className={DOCK_PRIMARY_BUTTON}
+        className={PRIMARY_BUTTON_CLASS}
       >
-        {submitting ? <DockSpinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
+        {submitting ? (
+          <Spinner className="size-4" />
+        ) : (
+          <CheckIcon className="size-4" aria-hidden="true" />
+        )}
         Confirm
       </button>
     </div>
@@ -390,9 +409,13 @@ function MultiSelectBody({
           type="button"
           disabled={submitting || selectedKeys.length === 0}
           onClick={() => void onSubmit({ kind: "multi_selected", option_keys: selectedKeys })}
-          className={DOCK_PRIMARY_BUTTON}
+          className={PRIMARY_BUTTON_CLASS}
         >
-          {submitting ? <DockSpinner /> : <CheckIcon className="size-4" aria-hidden="true" />}
+          {submitting ? (
+            <Spinner className="size-4" />
+          ) : (
+            <CheckIcon className="size-4" aria-hidden="true" />
+          )}
           Submit selection
         </button>
       </div>
@@ -414,7 +437,7 @@ function FreeformAnswer({
       onSubmit={(text) => onSubmit({ kind: "text", text })}
       placeholder={placeholder}
       submitLabel="Send"
-      pending={submitting}
+      submitting={submitting}
       ariaLabel="Interview answer"
     />
   );
diff --git a/apps/fabro-web/app/components/run-dock.test.tsx b/apps/fabro-web/app/components/run-dock.test.tsx
new file mode 100644
index 000000000..56c5a1599
--- /dev/null
+++ b/apps/fabro-web/app/components/run-dock.test.tsx
@@ -0,0 +1,118 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+import TestRenderer, { act } from "react-test-renderer";
+
+import { setupReactTestEnv } from "../lib/test-utils";
+import { DockComposer } from "./run-dock";
+
+const mountedRenderers: TestRenderer.ReactTestRenderer[] = [];
+let teardownReactEnv: (() => void) | undefined;
+
+beforeEach(() => {
+  teardownReactEnv = setupReactTestEnv();
+});
+
+afterEach(() => {
+  for (const renderer of mountedRenderers.splice(0)) {
+    act(() => renderer.unmount());
+  }
+  teardownReactEnv?.();
+  teardownReactEnv = undefined;
+});
+
+describe("DockComposer", () => {
+  test("describes its keyboard behavior to assistive technology", () => {
+    let renderer!: TestRenderer.ReactTestRenderer;
+    act(() => {
+      renderer = TestRenderer.create(
+        <DockComposer
+          onSubmit={() => Promise.resolve(true)}
+          placeholder="Write a message"
+          submitLabel="Send"
+          submitting={false}
+          ariaLabel="Message"
+        />,
+      );
+    });
+    mountedRenderers.push(renderer);
+
+    const textarea = renderer.root.findByType("textarea");
+    const instruction = renderer.root.findByProps({
+      id: textarea.props["aria-describedby"],
+    });
+    expect(instruction.children.join("")).toBe(
+      "Press Enter to send. Press Shift+Enter for a new line.",
+    );
+    expect(textarea.props.name).toBeUndefined();
+  });
+
+  test("does not submit Enter while an IME composition is active", async () => {
+    const onSubmit = mock(() => Promise.resolve(true));
+    const preventDefault = mock(() => undefined);
+    let renderer!: TestRenderer.ReactTestRenderer;
+    act(() => {
+      renderer = TestRenderer.create(
+        <DockComposer
+          onSubmit={onSubmit}
+          placeholder="Write a message"
+          submitLabel="Send"
+          submitting={false}
+          ariaLabel="Message"
+        />,
+      );
+    });
+    mountedRenderers.push(renderer);
+    const textarea = renderer.root.findByType("textarea");
+
+    act(() => textarea.props.onChange({ target: { value: "draft" } }));
+    await act(async () => {
+      textarea.props.onKeyDown({
+        key: "Enter",
+        shiftKey: false,
+        nativeEvent: { isComposing: true },
+        preventDefault,
+      });
+    });
+
+    expect(preventDefault).not.toHaveBeenCalled();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  test("submits Enter after composition ends", async () => {
+    const onSubmit = mock(() => Promise.resolve(true));
+    const preventDefault = mock(() => undefined);
+    let renderer!: TestRenderer.ReactTestRenderer;
+    act(() => {
+      renderer = TestRenderer.create(
+        <DockComposer
+          onSubmit={onSubmit}
+          placeholder="Write a message"
+          submitLabel="Send"
+          submitting={false}
+          ariaLabel="Message"
+        />,
+      );
+    });
+    mountedRenderers.push(renderer);
+    const textarea = renderer.root.findByType("textarea");
+
+    act(() => textarea.props.onChange({ target: { value: "  ready  " } }));
+    await act(async () => {
+      textarea.props.onKeyDown({
+        key: "Enter",
+        shiftKey: false,
+        nativeEvent: { isComposing: false },
+        preventDefault,
+      });
+    });
+
+    expect(preventDefault).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledWith("ready");
+  });
+});
diff --git a/apps/fabro-web/app/components/run-dock.tsx b/apps/fabro-web/app/components/run-dock.tsx
index ab684522b..4e26daa3a 100644
--- a/apps/fabro-web/app/components/run-dock.tsx
+++ b/apps/fabro-web/app/components/run-dock.tsx
@@ -7,11 +7,17 @@ import {
   type Ref,
 } from "react";
 import {
-  ArrowPathIcon,
   ArrowUturnLeftIcon,
   ChevronUpIcon,
 } from "@heroicons/react/20/solid";
 
+import { classNames } from "../lib/class-names";
+import { Spinner } from "./state";
+import {
+  INPUT_CLASS,
+  PRIMARY_BUTTON_CLASS,
+} from "./ui";
+
 /**
  * Shared chrome for the two controls docked at the bottom of the run detail
  * route: the interview question panel and the steering composer.
@@ -29,15 +35,9 @@ import {
 /** Ceiling on the expanded dock, so a long body cannot take the page. */
 const DOCK_MAX_HEIGHT = "max-h-[60vh]";
 
-/** Pinned actions never take more than half the dock. */
-const ACTIONS_MAX_HEIGHT = "max-h-[50%]";
-
 export const DOCK_HEADER_BUTTON =
   "inline-flex shrink-0 items-center gap-1.5 rounded-md bg-overlay px-2 py-1 text-xs font-medium text-fg-2 outline-1 -outline-offset-1 outline-line-strong transition-colors hover:bg-overlay-strong hover:text-fg focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-overlay disabled:hover:text-fg-2";
 
-export const DOCK_PRIMARY_BUTTON =
-  "inline-flex items-center justify-center gap-1.5 rounded-lg bg-teal-500 px-3.5 py-2 text-sm font-medium text-on-primary transition-colors hover:bg-teal-300 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-teal-500";
-
 export const DOCK_CHOICE_BUTTON =
   "inline-flex items-center justify-center gap-1.5 rounded-lg bg-overlay px-3.5 py-2 text-left text-sm font-medium text-fg-2 outline-1 -outline-offset-1 outline-line-strong transition-colors hover:bg-overlay-strong hover:text-fg focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-teal-500 disabled:cursor-not-allowed disabled:opacity-60";
 
@@ -57,6 +57,7 @@ export type DockTone = "waiting" | "alert" | "idle";
 export interface RunDockShellProps {
   /** Accessible name for the docked region. */
   label: string;
+  className?: string;
   tone: DockTone;
   /** Short state phrase, e.g. "Awaiting input". */
   status: string;
@@ -76,6 +77,7 @@ export interface RunDockShellProps {
 
 export function RunDockShell({
   label,
+  className,
   tone,
   status,
   stage,
@@ -91,7 +93,11 @@ export function RunDockShell({
   return (
     <section
       aria-label={label}
-      className={`flex flex-col ${collapsed ? "" : DOCK_MAX_HEIGHT}`}
+      className={classNames(
+        "flex flex-col",
+        !collapsed && DOCK_MAX_HEIGHT,
+        className,
+      )}
     >
       <div className="flex shrink-0 items-center gap-2.5 px-5 py-2 sm:px-6">
         <StatusDot tone={tone} />
@@ -145,9 +151,7 @@ export function RunDockShell({
           display classes cannot collide in the cascade. */}
       <div
         id={contentId}
-        className={
-          collapsed ? "hidden" : "flex min-h-0 flex-1 flex-col"
-        }
+        className={collapsed ? "hidden" : "flex min-h-0 flex-1 flex-col"}
       >
         {body && (
           <div className="min-h-0 flex-1 space-y-3 overflow-y-auto border-t border-line px-5 pt-3.5 pb-1 sm:px-6">
@@ -155,9 +159,10 @@ export function RunDockShell({
           </div>
         )}
         <div
-          className={`flex shrink-0 flex-col gap-2.5 overflow-y-auto px-5 pt-2.5 pb-3.5 sm:px-6 ${ACTIONS_MAX_HEIGHT} ${
-            body ? "" : "border-t border-line"
-          }`}
+          className={classNames(
+            "flex max-h-[50%] shrink-0 flex-col gap-2.5 overflow-y-auto px-5 pt-2.5 pb-3.5 sm:px-6",
+            !body && "border-t border-line",
+          )}
         >
           {actions}
         </div>
@@ -186,10 +191,6 @@ function StatusDot({ tone }: { tone: DockTone }) {
   );
 }
 
-export function DockSpinner() {
-  return <ArrowPathIcon className="size-4 animate-spin" aria-hidden="true" />;
-}
-
 export interface DockComposerProps {
   /**
    * Sends the trimmed text. Resolve `true` to clear the box; resolve `false`
@@ -199,8 +200,10 @@ export interface DockComposerProps {
   placeholder: string;
   submitLabel: string;
   pendingLabel?: string;
-  pending: boolean;
+  submitting: boolean;
+  disabled?: boolean;
   ariaLabel: string;
+  className?: string;
   maxLength?: number;
   textareaRef?: Ref<HTMLTextAreaElement>;
 }
@@ -216,15 +219,19 @@ export function DockComposer({
   placeholder,
   submitLabel,
   pendingLabel,
-  pending,
+  submitting,
+  disabled = false,
   ariaLabel,
+  className,
   maxLength,
   textareaRef,
 }: DockComposerProps) {
   const [value, setValue] = useState("");
   const fieldId = useId();
+  const instructionId = `${fieldId}-instruction`;
   const trimmed = value.trim();
-  const canSend = trimmed.length > 0 && !pending;
+  const composerDisabled = disabled || submitting;
+  const canSend = trimmed.length > 0 && !composerDisabled;
 
   async function send() {
     if (!canSend) return;
@@ -238,34 +245,44 @@ export function DockComposer({
   }
 
   function handleKeyDown(event: KeyboardEvent<HTMLTextAreaElement>) {
-    if (event.key === "Enter" && !event.shiftKey) {
+    if (
+      event.key === "Enter" &&
+      !event.shiftKey &&
+      !event.nativeEvent.isComposing
+    ) {
       event.preventDefault();
       void send();
     }
   }
 
   return (
-    <form onSubmit={handleSubmit} className="group flex items-end gap-2">
+    <form
+      onSubmit={handleSubmit}
+      className={classNames("group flex items-end gap-2", className)}
+    >
       <label className="sr-only" htmlFor={fieldId}>
         {ariaLabel}
       </label>
+      <p id={instructionId} className="sr-only">
+        Press Enter to send. Press Shift+Enter for a new line.
+      </p>
       <textarea
         id={fieldId}
         ref={textareaRef}
-        name="answer"
         aria-label={ariaLabel}
+        aria-describedby={instructionId}
         rows={1}
         value={value}
         maxLength={maxLength}
         onChange={(event) => setValue(event.target.value)}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
-        disabled={pending}
-        className="block w-full resize-none rounded-lg bg-panel-alt px-3.5 py-2.5 text-base/6 text-fg outline-1 -outline-offset-1 outline-line-strong placeholder:text-fg-muted focus:outline-2 focus:-outline-offset-1 focus:outline-teal-500 disabled:opacity-60 sm:text-sm/5"
+        disabled={composerDisabled}
+        className={`${INPUT_CLASS} min-w-0 flex-1 resize-none disabled:opacity-60`}
       />
       <p
         aria-hidden="true"
-        className="pointer-events-none flex shrink-0 items-center gap-1 pb-2.5 text-xs whitespace-nowrap text-fg-muted opacity-0 transition-opacity group-focus-within:opacity-100"
+        className="pointer-events-none hidden shrink-0 items-center gap-1 pb-2.5 text-xs whitespace-nowrap text-fg-muted opacity-0 transition-opacity group-focus-within:opacity-100 md:flex"
       >
         <kbd className="rounded bg-overlay px-1 font-mono text-[0.6875rem]">
           Enter
@@ -283,17 +300,17 @@ export function DockComposer({
       <button
         type="submit"
         disabled={!canSend}
-        className={DOCK_PRIMARY_BUTTON}
+        className={PRIMARY_BUTTON_CLASS}
       >
-        {pending ? (
-          <DockSpinner />
+        {submitting ? (
+          <Spinner className="size-4" />
         ) : (
           <ArrowUturnLeftIcon
             className="size-3.5 -scale-x-100"
             aria-hidden="true"
           />
         )}
-        {pending && pendingLabel ? pendingLabel : submitLabel}
+        {submitting && pendingLabel ? pendingLabel : submitLabel}
       </button>
     </form>
   );
diff --git a/apps/fabro-web/app/components/steer-bar.test.tsx b/apps/fabro-web/app/components/steer-bar.test.tsx
index a9c74714c..b13498af6 100644
--- a/apps/fabro-web/app/components/steer-bar.test.tsx
+++ b/apps/fabro-web/app/components/steer-bar.test.tsx
@@ -1,10 +1,67 @@
-import { describe, expect, test } from "bun:test";
-
 import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+import { createRef } from "react";
+import TestRenderer, { act } from "react-test-renderer";
+
+import { setupReactTestEnv } from "../lib/test-utils";
+
+let steerPending = false;
+let interruptPending = false;
+const steerTrigger = mock(() => Promise.resolve(undefined));
+const interruptTrigger = mock(() => Promise.resolve(undefined));
+
+mock.module("../lib/mutations", () => ({
+  useSteerRun: () => ({
+    isMutating: steerPending,
+    trigger: steerTrigger,
+  }),
+  useInterruptRun: () => ({
+    isMutating: interruptPending,
+    trigger: interruptTrigger,
+  }),
+}));
+
+const {
   isInterruptDisabled,
   isSteerDockCollapsed,
+  SteerBar,
   steerStatusLabel,
-} from "./steer-bar";
+} = await import("./steer-bar");
+type SteerBarHandle = import("./steer-bar").SteerBarHandle;
+mock.restore();
+
+const mountedRenderers: TestRenderer.ReactTestRenderer[] = [];
+let teardownReactEnv: (() => void) | undefined;
+
+function textFromNode(node: TestRenderer.ReactTestInstance): string {
+  return node.children
+    .map((child) =>
+      typeof child === "string" ? child : textFromNode(child),
+    )
+    .join("");
+}
+
+beforeEach(() => {
+  teardownReactEnv = setupReactTestEnv();
+  steerPending = false;
+  interruptPending = false;
+  steerTrigger.mockClear();
+  interruptTrigger.mockClear();
+});
+
+afterEach(() => {
+  for (const renderer of mountedRenderers.splice(0)) {
+    act(() => renderer.unmount());
+  }
+  teardownReactEnv?.();
+  teardownReactEnv = undefined;
+});
 
 describe("SteerBar", () => {
   test("prevents a second interrupt while one is in flight or already settled", () => {
@@ -25,4 +82,65 @@ describe("SteerBar", () => {
     expect(isSteerDockCollapsed(true, true)).toBe(false);
     expect(isSteerDockCollapsed(false, true)).toBe(false);
   });
+
+  test("the focus handle expands a collapsed dock before focusing", async () => {
+    const focus = mock(() => undefined);
+    const ref = createRef<SteerBarHandle>();
+    let renderer!: TestRenderer.ReactTestRenderer;
+    await act(async () => {
+      renderer = TestRenderer.create(
+        <SteerBar ref={ref} runId="run-1" />,
+        {
+          createNodeMock: (element) =>
+            element.type === "textarea" ? { focus } : null,
+        },
+      );
+    });
+    mountedRenderers.push(renderer);
+
+    act(() => {
+      renderer.root
+        .findByProps({ "aria-label": "Collapse Steer running agent" })
+        .props.onClick();
+    });
+    expect(
+      renderer.root.findByProps({
+        "aria-label": "Expand Steer running agent",
+      }),
+    ).toBeDefined();
+
+    act(() => ref.current?.focus());
+    expect(
+      renderer.root.findByProps({
+        "aria-label": "Collapse Steer running agent",
+      }),
+    ).toBeDefined();
+    expect(focus).not.toHaveBeenCalled();
+
+    await act(
+      async () =>
+        await new Promise((resolve) => {
+          setTimeout(resolve, 0);
+        }),
+    );
+    expect(focus).toHaveBeenCalledTimes(1);
+  });
+
+  test("interrupt progress disables the composer without calling it sending", async () => {
+    interruptPending = true;
+    let renderer!: TestRenderer.ReactTestRenderer;
+    await act(async () => {
+      renderer = TestRenderer.create(<SteerBar runId="run-1" />);
+    });
+    mountedRenderers.push(renderer);
+
+    const submit = renderer.root.findByProps({ type: "submit" });
+    expect(submit.props.disabled).toBe(true);
+    expect(textFromNode(submit)).toBe("Send");
+    expect(
+      renderer.root
+        .findAllByType("button")
+        .map(textFromNode),
+    ).toContain("Interrupting…");
+  });
 });
diff --git a/apps/fabro-web/app/components/steer-bar.tsx b/apps/fabro-web/app/components/steer-bar.tsx
index 7c229d77f..1b6e61f7c 100644
--- a/apps/fabro-web/app/components/steer-bar.tsx
+++ b/apps/fabro-web/app/components/steer-bar.tsx
@@ -7,6 +7,7 @@ import {
 import { StopIcon } from "@heroicons/react/20/solid";
 
 import { ApiError } from "../lib/api-client";
+import { classNames } from "../lib/class-names";
 import { useInterruptRun, useSteerRun } from "../lib/mutations";
 import {
   DockComposer,
@@ -64,11 +65,20 @@ export function SteerBar({
   const interruptDisabled = isInterruptDisabled(waitingForSteer, pending);
   const collapsed = isSteerDockCollapsed(collapsePreferred, waitingForSteer);
 
-  useImperativeHandle(ref, () => ({
-    focus() {
-      textareaRef.current?.focus();
-    },
-  }));
+  useImperativeHandle(
+    ref,
+    () => ({
+      focus() {
+        if (!collapsed) {
+          textareaRef.current?.focus();
+          return;
+        }
+        setCollapsePreferred(false);
+        setTimeout(() => textareaRef.current?.focus(), 0);
+      },
+    }),
+    [collapsed],
+  );
 
   async function sendSteering(text: string) {
     setErrorMessage(null);
@@ -106,7 +116,10 @@ export function SteerBar({
           type="button"
           onClick={() => void fireInterrupt()}
           disabled={interruptDisabled}
-          className={`${DOCK_HEADER_BUTTON} text-amber outline-amber/40 hover:bg-amber/15 hover:text-amber focus-visible:outline-amber disabled:hover:bg-overlay disabled:hover:text-amber`}
+          className={classNames(
+            DOCK_HEADER_BUTTON,
+            "text-amber outline-amber/40 hover:bg-amber/15 hover:text-amber focus-visible:outline-amber disabled:hover:bg-overlay disabled:hover:text-amber",
+          )}
         >
           <StopIcon className="size-3" aria-hidden="true" />
           {interrupt.isMutating ? "Interrupting…" : "Interrupt"}
@@ -119,7 +132,8 @@ export function SteerBar({
             placeholder="Steer the agent…"
             submitLabel="Send"
             pendingLabel="Sending…"
-            pending={pending}
+            submitting={steer.isMutating}
+            disabled={pending}
             ariaLabel="Steering message"
             maxLength={STEER_MAX_LENGTH}
             textareaRef={textareaRef}
diff --git a/apps/fabro-web/app/lib/class-names.ts b/apps/fabro-web/app/lib/class-names.ts
new file mode 100644
index 000000000..2f79da4ee
--- /dev/null
+++ b/apps/fabro-web/app/lib/class-names.ts
@@ -0,0 +1,5 @@
+export function classNames(
+  ...classes: Array<string | false | null | undefined>
+): string {
+  return classes.filter(Boolean).join(" ");
+}
diff --git a/apps/fabro-web/app/routes/run-detail.test.ts b/apps/fabro-web/app/routes/run-detail.test.ts
index 6abd07b4f..82f3da58c 100644
--- a/apps/fabro-web/app/routes/run-detail.test.ts
+++ b/apps/fabro-web/app/routes/run-detail.test.ts
@@ -183,13 +183,33 @@ import {
   lifecycleActionVisibility,
 } from "./run-detail/lifecycle-toasts";
 
-const { default: RunDetail } = await import("./run-detail");
+const {
+  default: RunDetail,
+  resolveDockClearance,
+} = await import("./run-detail");
 mock.restore();
 type LifecycleToastState = import("./run-detail/lifecycle-toasts").LifecycleToastState;
 type RunDetailActionResult = import("./run-detail/lifecycle-toasts").RunDetailActionResult;
 
 const h = createElement;
 
+describe("resolveDockClearance", () => {
+  test("uses only a current dock measurement", () => {
+    const measurement = { identity: "run_1:steer", height: 108 };
+
+    expect(resolveDockClearance(null, measurement, false)).toBe("0px");
+    expect(
+      resolveDockClearance("run_1:interview", measurement, true),
+    ).toBe("18rem");
+    expect(resolveDockClearance("run_2:steer", measurement, false)).toBe(
+      "5rem",
+    );
+    expect(resolveDockClearance("run_1:steer", measurement, false)).toBe(
+      "108px",
+    );
+  });
+});
+
 function makeRunSummary({
   status = "succeeded",
   diffSummary = null as any,
diff --git a/apps/fabro-web/app/routes/run-detail.tsx b/apps/fabro-web/app/routes/run-detail.tsx
index 02e55ff3c..2e8f1a44e 100644
--- a/apps/fabro-web/app/routes/run-detail.tsx
+++ b/apps/fabro-web/app/routes/run-detail.tsx
@@ -71,6 +71,23 @@ export const handle = { hideHeader: true };
 
 type LifecycleTrigger = () => Promise<LifecycleMutationResult | undefined>;
 
+export interface DockMeasurement {
+  identity: string;
+  height: number;
+}
+
+export function resolveDockClearance(
+  dockIdentity: string | null,
+  measurement: DockMeasurement | null,
+  hasPendingQuestions: boolean,
+): string {
+  if (dockIdentity === null) return "0px";
+  if (measurement?.identity === dockIdentity) {
+    return `${measurement.height}px`;
+  }
+  return hasPendingQuestions ? "18rem" : "5rem";
+}
+
 export function meta({ data }: any) {
   const run = data?.run;
   return [{ title: run ? `${run.title} — Fabro` : "Run — Fabro" }];
@@ -102,7 +119,8 @@ export default function RunDetail({ params }: { params: { id: string } }) {
   const { mutate } = useSWRConfig();
   const [deleteDialogOpen, setDeleteDialogOpen] = useState(false);
   const [deletePending, setDeletePending] = useState(false);
-  const [dockHeight, setDockHeight] = useState<number | null>(null);
+  const [dockMeasurement, setDockMeasurement] =
+    useState<DockMeasurement | null>(null);
   const { push, dismiss } = useToast();
   const lifecycleToastStateRef = useRef(createLifecycleToastState());
   const filesCount = runQuery.data?.diff?.files_changed ?? null;
@@ -145,6 +163,15 @@ export default function RunDetail({ params }: { params: { id: string } }) {
     },
     [handleLifecycleMutationResult],
   );
+  const handleDockHeightChange = useCallback(
+    (identity: string, height: number | null) => {
+      setDockMeasurement((current) => {
+        if (height !== null) return { identity, height };
+        return current?.identity === identity ? null : current;
+      });
+    },
+    [],
+  );
 
   if (runQuery.isLoading && !run) {
     return <div className="py-12" />;
@@ -309,13 +336,16 @@ export default function RunDetail({ params }: { params: { id: string } }) {
   // Reserve exactly the dock's rendered height. The constants are only the
   // first frame, before the dock has been measured; a fixed reservation lets
   // a tall question panel cover the content it is asking about.
-  const dockVisible = hasPendingQuestions || !hideSteerBar;
-  const dockClearance =
-    dockVisible && dockHeight !== null
-      ? `${dockHeight}px`
-      : hasPendingQuestions
-        ? "18rem"
-        : "5rem";
+  const dockIdentity = hasPendingQuestions
+    ? `${params.id}:interview`
+    : hideSteerBar
+      ? null
+      : `${params.id}:steer`;
+  const dockClearance = resolveDockClearance(
+    dockIdentity,
+    dockMeasurement,
+    hasPendingQuestions,
+  );
   const rootStyle = {
     "--fabro-interview-dock-clearance": dockClearance,
   } as CSSProperties;
@@ -374,15 +404,16 @@ export default function RunDetail({ params }: { params: { id: string } }) {
           />
 
           <RunDetailDockedControls
+            key={dockIdentity ?? "hidden"}
             runId={params.id}
-            hideSteerBar={hideSteerBar}
+            dockIdentity={dockIdentity}
             hasPendingQuestions={hasPendingQuestions}
             pendingQuestions={pendingQuestions}
             sidebarWidth={sidebarWidth}
             isResizing={isResizing}
             steerBarRef={steerBarRef}
             waitingForSteer={waitingForSteer}
-            onHeightChange={setDockHeight}
+            onHeightChange={handleDockHeightChange}
           />
         </div>
       )}
diff --git a/apps/fabro-web/app/routes/run-detail/docked-controls.test.tsx b/apps/fabro-web/app/routes/run-detail/docked-controls.test.tsx
new file mode 100644
index 000000000..7db4835d1
--- /dev/null
+++ b/apps/fabro-web/app/routes/run-detail/docked-controls.test.tsx
@@ -0,0 +1,158 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+import { createElement, createRef } from "react";
+import TestRenderer, { act } from "react-test-renderer";
+
+import { setupReactTestEnv } from "../../lib/test-utils";
+
+mock.module("../../components/interview-dock", () => ({
+  InterviewDock: () => createElement("div", null, "Interview"),
+}));
+mock.module("../../components/steer-bar", () => ({
+  SteerBar: () => createElement("div", null, "Steer"),
+}));
+
+const { RunDetailDockedControls } = await import("./docked-controls");
+mock.restore();
+
+const mountedRenderers: TestRenderer.ReactTestRenderer[] = [];
+const observerCallbacks: ResizeObserverCallback[] = [];
+const dockNode = { offsetHeight: 999 };
+let originalResizeObserver: typeof ResizeObserver | undefined;
+let teardownReactEnv: (() => void) | undefined;
+
+function resizeEntry(blockSize: number): ResizeObserverEntry {
+  return {
+    borderBoxSize: [{ blockSize, inlineSize: 600 }],
+  } as unknown as ResizeObserverEntry;
+}
+
+function renderDock({
+  identity,
+  hasPendingQuestions = false,
+  onHeightChange,
+}: {
+  identity: string | null;
+  hasPendingQuestions?: boolean;
+  onHeightChange: (identity: string, height: number | null) => void;
+}) {
+  return (
+    <RunDetailDockedControls
+      key={identity ?? "hidden"}
+      runId="run-1"
+      dockIdentity={identity}
+      hasPendingQuestions={hasPendingQuestions}
+      pendingQuestions={[]}
+      sidebarWidth={0}
+      isResizing={false}
+      steerBarRef={createRef()}
+      waitingForSteer={false}
+      onHeightChange={onHeightChange}
+    />
+  );
+}
+
+beforeEach(() => {
+  teardownReactEnv = setupReactTestEnv();
+  observerCallbacks.length = 0;
+  originalResizeObserver = globalThis.ResizeObserver;
+  globalThis.ResizeObserver = class ResizeObserver {
+    constructor(callback: ResizeObserverCallback) {
+      observerCallbacks.push(callback);
+    }
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  } as typeof ResizeObserver;
+});
+
+afterEach(() => {
+  for (const renderer of mountedRenderers.splice(0)) {
+    act(() => renderer.unmount());
+  }
+  if (originalResizeObserver) {
+    globalThis.ResizeObserver = originalResizeObserver;
+  } else {
+    delete (globalThis as { ResizeObserver?: typeof ResizeObserver })
+      .ResizeObserver;
+  }
+  teardownReactEnv?.();
+  teardownReactEnv = undefined;
+});
+
+describe("RunDetailDockedControls", () => {
+  test("reports border-box height only when the height changes", () => {
+    const onHeightChange = mock(
+      (_identity: string, _height: number | null) => undefined,
+    );
+    let renderer!: TestRenderer.ReactTestRenderer;
+    act(() => {
+      renderer = TestRenderer.create(
+        renderDock({ identity: "run-1:steer", onHeightChange }),
+        {
+          createNodeMock: () => dockNode,
+        },
+      );
+    });
+    mountedRenderers.push(renderer);
+    const callback = observerCallbacks[0]!;
+
+    act(() => callback([resizeEntry(108)], {} as ResizeObserver));
+    act(() => callback([resizeEntry(108)], {} as ResizeObserver));
+    act(() => callback([resizeEntry(120)], {} as ResizeObserver));
+
+    expect(onHeightChange).toHaveBeenCalledTimes(2);
+    expect(onHeightChange.mock.calls).toEqual([
+      ["run-1:steer", 108],
+      ["run-1:steer", 120],
+    ]);
+  });
+
+  test("clears the old identity when the dock changes or hides", () => {
+    const onHeightChange = mock(
+      (_identity: string, _height: number | null) => undefined,
+    );
+    let renderer!: TestRenderer.ReactTestRenderer;
+    act(() => {
+      renderer = TestRenderer.create(
+        renderDock({ identity: "run-1:steer", onHeightChange }),
+        {
+          createNodeMock: () => dockNode,
+        },
+      );
+    });
+    mountedRenderers.push(renderer);
+    act(() =>
+      observerCallbacks[0]!([resizeEntry(108)], {} as ResizeObserver),
+    );
+
+    act(() => {
+      renderer.update(
+        renderDock({
+          identity: "run-1:interview",
+          hasPendingQuestions: true,
+          onHeightChange,
+        }),
+      );
+    });
+    act(() =>
+      observerCallbacks[1]!([resizeEntry(220)], {} as ResizeObserver),
+    );
+    act(() => {
+      renderer.update(renderDock({ identity: null, onHeightChange }));
+    });
+
+    expect(onHeightChange.mock.calls).toEqual([
+      ["run-1:steer", 108],
+      ["run-1:steer", null],
+      ["run-1:interview", 220],
+      ["run-1:interview", null],
+    ]);
+  });
+});
diff --git a/apps/fabro-web/app/routes/run-detail/docked-controls.tsx b/apps/fabro-web/app/routes/run-detail/docked-controls.tsx
index 2b99fab39..5efebc648 100644
--- a/apps/fabro-web/app/routes/run-detail/docked-controls.tsx
+++ b/apps/fabro-web/app/routes/run-detail/docked-controls.tsx
@@ -1,4 +1,5 @@
 import {
+  useCallback,
   useRef,
   useState,
   type ReactNode,
@@ -17,12 +18,12 @@ import {
   SECONDARY_BUTTON_CLASS,
   Tooltip,
 } from "../../components/ui";
+import { classNames } from "../../lib/class-names";
 import {
   AskFabroUnavailableReasonEnum,
   type ApiQuestion,
   type AskFabro,
 } from "@qltysh/fabro-api-client";
-import { classNames } from "./model";
 
 const ASK_FABRO_UNAVAILABLE_TOOLTIPS: Record<
   AskFabroUnavailableReasonEnum,
@@ -130,7 +131,7 @@ function AskFabroTriggerButton({
 
 export function RunDetailDockedControls({
   runId,
-  hideSteerBar,
+  dockIdentity,
   hasPendingQuestions,
   pendingQuestions,
   sidebarWidth,
@@ -140,7 +141,7 @@ export function RunDetailDockedControls({
   onHeightChange,
 }: {
   runId: string;
-  hideSteerBar: boolean;
+  dockIdentity: string | null;
   hasPendingQuestions: boolean;
   pendingQuestions: ApiQuestion[];
   sidebarWidth: number;
@@ -151,16 +152,39 @@ export function RunDetailDockedControls({
    * Reports the dock's rendered height so the page can reserve exactly that
    * much room beneath the scrolling content.
    */
-  onHeightChange: (height: number | null) => void;
+  onHeightChange: (identity: string, height: number | null) => void;
 }) {
   const dockRef = useRef<HTMLDivElement | null>(null);
-  const visible = hasPendingQuestions || !hideSteerBar;
+  const reportedHeightRef = useRef<number | null>(null);
+  const visible = dockIdentity !== null;
+  const reportHeight = useCallback(
+    (height: number | null) => {
+      if (dockIdentity === null || reportedHeightRef.current === height) return;
+      reportedHeightRef.current = height;
+      onHeightChange(dockIdentity, height);
+    },
+    [dockIdentity, onHeightChange],
+  );
+  const setDockRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      dockRef.current = node;
+      if (node === null) reportHeight(null);
+    },
+    [reportHeight],
+  );
 
-  // `offsetHeight` rather than the entry's content box: the dock carries a
-  // top border, and the page has to clear the border too.
   useResizeObserver(
     dockRef,
-    () => onHeightChange(dockRef.current?.offsetHeight ?? null),
+    (entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const borderBoxSize = Array.isArray(entry.borderBoxSize)
+        ? entry.borderBoxSize[0]
+        : (entry.borderBoxSize as unknown as ResizeObserverSize);
+      reportHeight(
+        borderBoxSize?.blockSize ?? dockRef.current?.offsetHeight ?? null,
+      );
+    },
     visible,
   );
 
@@ -168,12 +192,12 @@ export function RunDetailDockedControls({
 
   return (
     <div
-      ref={dockRef}
-      className={`fixed bottom-0 left-0 z-30 border-t border-line bg-page ${
-        isResizing
-          ? ""
-          : "transition-[right] duration-300 ease-[cubic-bezier(0.16,1,0.3,1)]"
-      }`}
+      ref={setDockRef}
+      className={classNames(
+        "fixed bottom-0 left-0 z-30 border-t border-line bg-page",
+        !isResizing &&
+          "transition-[right] duration-300 ease-[cubic-bezier(0.16,1,0.3,1)]",
+      )}
       style={{ right: sidebarWidth }}
     >
       {hasPendingQuestions ? (
diff --git a/apps/fabro-web/app/routes/run-detail/header.tsx b/apps/fabro-web/app/routes/run-detail/header.tsx
index efc68f09b..70b323156 100644
--- a/apps/fabro-web/app/routes/run-detail/header.tsx
+++ b/apps/fabro-web/app/routes/run-detail/header.tsx
@@ -35,10 +35,11 @@ import {
   formatDurationMs,
   formatRelativeTime,
 } from "../../lib/format";
+import { classNames } from "../../lib/class-names";
 import { useRunPullRequest } from "../../lib/queries";
 import { sandboxRuntime } from "../../lib/run-sandbox-lifecycle";
 import { ActionsMenu, type ActionsMenuProps } from "./actions";
-import { classNames, type RunDetailRun } from "./model";
+import type { RunDetailRun } from "./model";
 
 export interface RunDetailHeaderActions {
   approval: {
diff --git a/apps/fabro-web/app/routes/run-detail/model.ts b/apps/fabro-web/app/routes/run-detail/model.ts
index 7cfcba1a6..e0b853ce9 100644
--- a/apps/fabro-web/app/routes/run-detail/model.ts
+++ b/apps/fabro-web/app/routes/run-detail/model.ts
@@ -8,10 +8,6 @@ import {
   type Run,
 } from "../../data/runs";
 
-export function classNames(...classes: Array<string | false | null | undefined>) {
-  return classes.filter(Boolean).join(" ");
-}
-
 export function useTickingNow(intervalMs: number): number {
   const [now, setNow] = useState(() => Date.now());
   useInterval(() => setNow(Date.now()), intervalMs);
diff --git a/apps/fabro-web/app/routes/run-detail/tabs-shell.tsx b/apps/fabro-web/app/routes/run-detail/tabs-shell.tsx
index cca7630bd..5674ea275 100644
--- a/apps/fabro-web/app/routes/run-detail/tabs-shell.tsx
+++ b/apps/fabro-web/app/routes/run-detail/tabs-shell.tsx
@@ -1,7 +1,7 @@
 import { Link, Outlet, type UIMatch } from "react-router";
 
+import { classNames } from "../../lib/class-names";
 import { sandboxTabVisible, type MaybeSandbox } from "../../lib/run-sandbox-lifecycle";
-import { classNames } from "./model";
 
 interface RunDetailTabDefinition {
   name: string;

From c1335421e4062e522dc8b8919b4b08fb11098a09 Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 15:31:20 -0400
Subject: [PATCH 33/36] fix: stop a pipe in a link label from splitting Slack
 link markup

`slack_link` builds `<url|label>`, and `escape_slack_controls` covers
Slack's documented escapes (`&`, `<`, `>`) but not `|`. Slack has no
escape for `|`, so a label containing one splits the markup and can make
Slack reject the block.

`is_safe_slack_link_url` already guards the URL half against `|`; the
label half was unguarded. It did not matter before because the only
labels were "Open in Fabro" and a PR number. Review target labels are
model-authored, so this is now reachable.

Replace `|` inside link labels, which keeps the link working. Plain-text
labels are untouched, since `|` is fine outside link markup.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 lib/components/fabro-slack/src/blocks.rs | 34 +++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/lib/components/fabro-slack/src/blocks.rs b/lib/components/fabro-slack/src/blocks.rs
index 48aa9378f..f9484b07f 100644
--- a/lib/components/fabro-slack/src/blocks.rs
+++ b/lib/components/fabro-slack/src/blocks.rs
@@ -426,9 +426,18 @@ fn lifecycle_pull_request_text(pull_request: &RunLifecyclePullRequest<'_>) -> St
     text
 }
 
+/// Render `label` as a link to `url` in Slack's `<url|label>` syntax, falling
+/// back to plain text when the URL cannot be embedded safely.
+///
+/// `escape_slack_controls` covers Slack's documented escapes (`&`, `<`, `>`)
+/// but Slack has no escape for `|`, which separates the URL from the label.
+/// A `|` in the label would split the markup and can make Slack reject the
+/// whole block, so it is replaced inside link labels only. Labels can be
+/// model-authored (a review target label, for example), so this is reachable.
 fn slack_link(url: &str, label: &str) -> String {
     if is_safe_slack_link_url(url) {
-        format!("<{}|{}>", url, escape_slack_controls(label))
+        let label = escape_slack_controls(label).replace('|', "/");
+        format!("<{url}|{label}>")
     } else {
         escape_slack_controls(label)
     }
@@ -669,6 +678,29 @@ mod tests {
         );
     }
 
+    #[test]
+    fn review_target_label_pipe_cannot_split_the_slack_link() {
+        let mut q = Question::new("Review", QuestionType::MultipleChoice);
+        q.review_target = Some(
+            fabro_types::ReviewTarget::new(
+                "Draft | v2",
+                "https://quarry.lithos.computer/tmp/0123456789abcdef0123456789abcdef",
+                fabro_types::ReviewTargetKind::Document,
+            )
+            .unwrap(),
+        );
+
+        let blocks = question_to_blocks("run-1", "q-1", &q, None);
+        let header = serde_json::to_value(&blocks).unwrap()[0]["text"]["text"]
+            .as_str()
+            .unwrap()
+            .to_string();
+
+        // Exactly one `|`: the one separating the URL from the label.
+        assert_eq!(header.matches('|').count(), 1);
+        assert!(header.contains("|Draft / v2>"));
+    }
+
     #[test]
     fn header_omits_link_when_url_missing() {
         let q = Question::new("Approve Plan", QuestionType::YesNo);

From e21e6bcdf92db669a85271539f2c84eddff4dee7 Mon Sep 17 00:00:00 2001
From: Release Repro <release-repro@example.com>
Date: Tue, 28 Jul 2026 15:38:35 -0400
Subject: [PATCH 34/36] refactor(sandbox): harden activation recovery

---
 .../src/server/handler/sessions.rs            |   4 +
 .../fabro-sandbox/src/daytona/mod.rs          |  92 +++++-
 lib/components/fabro-sandbox/src/docker.rs    | 267 ++++++++++--------
 lib/components/fabro-sandbox/src/local.rs     |   3 +
 lib/components/fabro-sandbox/src/sandbox.rs   |   5 +-
 .../fabro-sandbox/src/test_support.rs         |  37 +++
 .../fabro-workflow/src/lifecycle/mod.rs       |  21 +-
 .../fabro-workflow/src/pipeline/execute.rs    |   7 +
 .../src/pipeline/execute/tests.rs             |  46 ++-
 .../fabro-workflow/src/pipeline/initialize.rs |   2 +
 lib/foundation/fabro-core/src/error.rs        |  32 +++
 11 files changed, 375 insertions(+), 141 deletions(-)

diff --git a/lib/apps/fabro-server/src/server/handler/sessions.rs b/lib/apps/fabro-server/src/server/handler/sessions.rs
index c25d7ca27..d571078b1 100644
--- a/lib/apps/fabro-server/src/server/handler/sessions.rs
+++ b/lib/apps/fabro-server/src/server/handler/sessions.rs
@@ -730,6 +730,10 @@ async fn build_agent_session(
     let sandbox = reconnect_for_run(sandbox_instance, daytona_api_key, Some(run_id))
         .await
         .map_err(AskFabroBuildError::SandboxUnavailable)?;
+    sandbox
+        .activate()
+        .await
+        .map_err(|err| AskFabroBuildError::SandboxUnavailable(anyhow::Error::new(err)))?;
     let sandbox: Arc<dyn fabro_agent::Sandbox> = Arc::from(sandbox);
     // No optional web-tool dependencies: `AskFabroToolAccessPolicy` denies
     // `web_search` and `web_fetch`, and both `tools()` and the prompt are
diff --git a/lib/components/fabro-sandbox/src/daytona/mod.rs b/lib/components/fabro-sandbox/src/daytona/mod.rs
index c4e01e6ff..8de651f54 100644
--- a/lib/components/fabro-sandbox/src/daytona/mod.rs
+++ b/lib/components/fabro-sandbox/src/daytona/mod.rs
@@ -62,6 +62,7 @@ pub(crate) const DAYTONA_DASHBOARD_SANDBOXES_URL: &str =
     "https://app.daytona.io/dashboard/sandboxes";
 const FABRO_SANDBOX_USER_AGENT: &str = concat!("fabro-sandbox/", env!("CARGO_PKG_VERSION"));
 const DAYTONA_PROBE_TIMEOUT: Duration = Duration::from_secs(20);
+const DAYTONA_START_TIMEOUT: Duration = Duration::from_mins(1);
 /// Upper bound on explicit and Drop-triggered Daytona session deletion so a
 /// stalled REST call cannot block cancellation/timeout paths indefinitely.
 const DAYTONA_SESSION_CLOSE_TIMEOUT: Duration = Duration::from_secs(10);
@@ -1376,6 +1377,14 @@ impl Sandbox for DaytonaSandbox {
         if current.state == Some(SandboxState::Started) {
             return Ok(());
         }
+        if current.state == Some(SandboxState::Starting) {
+            return current
+                .wait_for_start(Some(DAYTONA_START_TIMEOUT))
+                .await
+                .map_err(|e| {
+                    crate::Error::context("Failed to wait for Daytona sandbox activation", e)
+                });
+        }
         self.start().await
     }
 
@@ -2534,10 +2543,12 @@ fn build_bash_session_command(
 
 #[cfg(test)]
 mod tests {
+    use std::sync::atomic::AtomicU32;
+
     use daytona_api_client::models::api_key_list::Permissions;
     use fabro_util::error::collect_chain;
-    use httpmock::Method::GET;
-    use httpmock::MockServer;
+    use httpmock::Method::{GET, POST};
+    use httpmock::{HttpMockResponse, MockServer};
 
     use super::*;
     use crate::sandbox::BASH_PROBE_MARKER;
@@ -2640,7 +2651,7 @@ mod tests {
         })
     }
 
-    fn sandbox_body(name: &str, state: &str) -> serde_json::Value {
+    fn sandbox_body(name: &str, state: SandboxState) -> serde_json::Value {
         serde_json::json!({
             "id": name,
             "organizationId": "org-1",
@@ -2655,7 +2666,7 @@ mod tests {
             "gpu": 0.0,
             "memory": 4.0,
             "disk": 20.0,
-            "state": state
+            "state": state.to_string()
         })
     }
 
@@ -2824,7 +2835,17 @@ mod tests {
                     .header("authorization", "Bearer dtn_test");
                 then.status(200)
                     .header("content-type", "application/json")
-                    .json_body(sandbox_body("test-sandbox", "started"));
+                    .json_body(sandbox_body("test-sandbox", SandboxState::Started));
+            })
+            .await;
+        let start_sandbox = server
+            .mock_async(|when, then| {
+                when.method(POST)
+                    .path("/sandbox/test-sandbox/start")
+                    .header("authorization", "Bearer dtn_test");
+                then.status(200)
+                    .header("content-type", "application/json")
+                    .json_body(sandbox_body("test-sandbox", SandboxState::Started));
             })
             .await;
         let sandbox = mock_daytona_sandbox(&server, "dtn_test", DaytonaConfig::default()).await;
@@ -2838,12 +2859,71 @@ mod tests {
             .set(sdk_sandbox)
             .expect("test sandbox should initialize once");
 
+        let get_calls_before = get_sandbox.calls_async().await;
         sandbox
             .activate()
             .await
             .expect("an active sandbox should require no restart");
 
-        get_sandbox.assert_calls_async(2).await;
+        assert_eq!(get_sandbox.calls_async().await, get_calls_before + 1);
+        start_sandbox.assert_calls_async(0).await;
+    }
+
+    #[tokio::test]
+    async fn activate_waits_for_a_daytona_start_already_in_progress() {
+        let server = MockServer::start_async().await;
+        let response_count = Arc::new(AtomicU32::new(0));
+        let get_sandbox = server
+            .mock_async({
+                let response_count = Arc::clone(&response_count);
+                move |when, then| {
+                    when.method(GET)
+                        .path("/sandbox/test-sandbox")
+                        .header("authorization", "Bearer dtn_test");
+                    then.respond_with(move |_| {
+                        let state = if response_count.fetch_add(1, Ordering::Relaxed) == 1 {
+                            SandboxState::Starting
+                        } else {
+                            SandboxState::Started
+                        };
+                        HttpMockResponse::builder()
+                            .status(200)
+                            .header("content-type", "application/json")
+                            .body(sandbox_body("test-sandbox", state).to_string())
+                            .build()
+                    });
+                }
+            })
+            .await;
+        let start_sandbox = server
+            .mock_async(|when, then| {
+                when.method(POST)
+                    .path("/sandbox/test-sandbox/start")
+                    .header("authorization", "Bearer dtn_test");
+                then.status(200)
+                    .header("content-type", "application/json")
+                    .json_body(sandbox_body("test-sandbox", SandboxState::Started));
+            })
+            .await;
+        let sandbox = mock_daytona_sandbox(&server, "dtn_test", DaytonaConfig::default()).await;
+        let sdk_sandbox = sandbox
+            .client
+            .get("test-sandbox")
+            .await
+            .expect("test sandbox should load");
+        sandbox
+            .sandbox
+            .set(sdk_sandbox)
+            .expect("test sandbox should initialize once");
+
+        let get_calls_before = get_sandbox.calls_async().await;
+        sandbox
+            .activate()
+            .await
+            .expect("an in-progress start should be awaited");
+
+        assert_eq!(get_sandbox.calls_async().await, get_calls_before + 2);
+        start_sandbox.assert_calls_async(0).await;
     }
 
     #[tokio::test]
diff --git a/lib/components/fabro-sandbox/src/docker.rs b/lib/components/fabro-sandbox/src/docker.rs
index 50556550c..6236d425d 100644
--- a/lib/components/fabro-sandbox/src/docker.rs
+++ b/lib/components/fabro-sandbox/src/docker.rs
@@ -15,7 +15,7 @@ use bollard::container::{
 use bollard::errors::Error as DockerError;
 use bollard::exec::{CreateExecOptions, StartExecOptions, StartExecResults};
 use bollard::image::CreateImageOptions;
-use bollard::models::HostConfig;
+use bollard::models::{ContainerInspectResponse, HostConfig};
 use fabro_github::GitHubCredentials;
 use fabro_types::{CommandOutputStream, CommandTermination, RunId};
 use fabro_util::time::elapsed_ms;
@@ -145,6 +145,13 @@ enum EnsureImageOutcome {
     Pulled,
 }
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq, strum::Display)]
+#[strum(serialize_all = "lowercase")]
+enum ContainerStartAction {
+    Start,
+    Unpause,
+}
+
 impl DockerSandbox {
     pub fn new(
         config: DockerSandboxOptions,
@@ -154,7 +161,25 @@ impl DockerSandbox {
         clone_branch: Option<String>,
     ) -> crate::Result<Self> {
         let docker = Docker::connect_with_local_defaults().map_err(crate::Error::docker_connect)?;
-        Ok(Self {
+        Ok(Self::with_docker_client(
+            docker,
+            config,
+            github_app,
+            run_id,
+            clone_origin_url,
+            clone_branch,
+        ))
+    }
+
+    fn with_docker_client(
+        docker: Docker,
+        config: DockerSandboxOptions,
+        github_app: Option<GitHubCredentials>,
+        run_id: Option<RunId>,
+        clone_origin_url: Option<String>,
+        clone_branch: Option<String>,
+    ) -> Self {
+        Self {
             docker,
             config,
             github_app,
@@ -169,7 +194,7 @@ impl DockerSandbox {
             cached_os_version: std::sync::OnceLock::new(),
             rg_available: OnceCell::const_new(),
             event_callback: None,
-        })
+        }
     }
 
     pub async fn reconnect(
@@ -755,24 +780,26 @@ impl DockerSandbox {
         verify_managed_labels(container_id, &labels, self.run_id.as_ref())
     }
 
-    async fn inspect_labels(&self, container_id: &str) -> crate::Result<HashMap<String, String>> {
-        let inspect = self
-            .docker
+    async fn inspect_container(
+        &self,
+        container_id: &str,
+    ) -> crate::Result<ContainerInspectResponse> {
+        self.docker
             .inspect_container(container_id, None::<InspectContainerOptions>)
             .await
-            .map_err(|e| {
-                if docker_not_found(&e) {
-                    crate::Error::message(format!("Docker container '{container_id}' is gone"))
+            .map_err(|source| {
+                let message = if docker_not_found(&source) {
+                    format!("Docker container '{container_id}' is gone")
                 } else {
-                    crate::Error::message(format!(
-                        "Failed to inspect Docker container '{container_id}': {e}"
-                    ))
-                }
-            })?;
-        Ok(inspect
-            .config
-            .and_then(|config| config.labels)
-            .unwrap_or_default())
+                    format!("Failed to inspect Docker container '{container_id}'")
+                };
+                crate::Error::context(message, source)
+            })
+    }
+
+    async fn inspect_labels(&self, container_id: &str) -> crate::Result<HashMap<String, String>> {
+        let inspect = self.inspect_container(container_id).await?;
+        Ok(container_labels(&inspect))
     }
 
     async fn ensure_name_available(&self) -> crate::Result<Option<String>> {
@@ -835,6 +862,67 @@ impl DockerSandbox {
             .map_err(|e| crate::Error::context("Failed to upload file to container", e))
     }
 
+    fn begin_start(&self) -> Instant {
+        self.emit(SandboxEvent::StartStarted {
+            provider: "docker".into(),
+        });
+        Instant::now()
+    }
+
+    async fn set_container_running(
+        &self,
+        container_id: &str,
+        labels: &HashMap<String, String>,
+        action: ContainerStartAction,
+    ) -> crate::Result<()> {
+        let result = match action {
+            ContainerStartAction::Start => {
+                self.docker
+                    .start_container(container_id, None::<StartContainerOptions<String>>)
+                    .await
+            }
+            ContainerStartAction::Unpause => self.docker.unpause_container(container_id).await,
+        };
+        if let Err(source) = result {
+            if !docker_not_modified(&source) {
+                return Err(crate::Error::context(
+                    format!(
+                        "Failed to {action} Docker container '{container_id}' with labels {labels:?}"
+                    ),
+                    source,
+                ));
+            }
+        }
+        Ok(())
+    }
+
+    async fn complete_start(
+        &self,
+        started: Instant,
+        container_id: &str,
+        labels: &HashMap<String, String>,
+        action: ContainerStartAction,
+    ) -> crate::Result<()> {
+        if let Err(error) = self
+            .set_container_running(container_id, labels, action)
+            .await
+        {
+            return self.start_error(error);
+        }
+        if let Err(error) = self.probe_bash(None).await {
+            return self.start_error(crate::Error::context(
+                format!("Docker container '{container_id}' health check"),
+                error,
+            ));
+        }
+
+        self.emit(SandboxEvent::StartCompleted {
+            provider:    "docker".into(),
+            duration_ms: elapsed_ms(started),
+        });
+        Ok(())
+    }
+
     fn start_error(&self, error: crate::Error) -> crate::Result<()> {
         self.emit(SandboxEvent::StartFailed {
             provider: "docker".into(),
@@ -1230,6 +1318,24 @@ fn verify_managed_labels(
     Ok(())
 }
 
+fn container_labels(inspect: &ContainerInspectResponse) -> HashMap<String, String> {
+    inspect
+        .config
+        .as_ref()
+        .and_then(|config| config.labels.clone())
+        .unwrap_or_default()
+}
+
+fn activation_action(inspect: &ContainerInspectResponse) -> Option<ContainerStartAction> {
+    let Some(state) = inspect.state.as_ref() else {
+        return Some(ContainerStartAction::Start);
+    };
+    if state.running != Some(true) {
+        return Some(ContainerStartAction::Start);
+    }
+    (state.paused == Some(true)).then_some(ContainerStartAction::Unpause)
+}
+
 fn docker_not_found(error: &DockerError) -> bool {
     matches!(error, DockerError::DockerResponseServerError {
         status_code: 404,
@@ -1418,93 +1524,40 @@ impl Sandbox for DockerSandbox {
     }
 
     async fn start(&self) -> crate::Result<()> {
-        self.emit(SandboxEvent::StartStarted {
-            provider: "docker".into(),
-        });
-        let start = Instant::now();
+        let started = self.begin_start();
         let container_id = self.container_id()?.to_string();
-        let labels = match self.inspect_labels(&container_id).await {
-            Ok(labels) => labels,
-            Err(e) => return self.start_error(e),
+        let inspect = match self.inspect_container(&container_id).await {
+            Ok(inspect) => inspect,
+            Err(error) => return self.start_error(error),
         };
-        if let Err(e) = verify_managed_labels(&container_id, &labels, self.run_id.as_ref()) {
-            return self.start_error(e);
+        let labels = container_labels(&inspect);
+        if let Err(error) = verify_managed_labels(&container_id, &labels, self.run_id.as_ref()) {
+            return self.start_error(error);
         }
-
-        if let Err(e) = self
-            .docker
-            .start_container(&container_id, None::<StartContainerOptions<String>>)
+        let action = activation_action(&inspect).unwrap_or(ContainerStartAction::Start);
+        self.complete_start(started, &container_id, &labels, action)
             .await
-        {
-            if !docker_not_modified(&e) {
-                return self.start_error(crate::Error::context(
-                    format!(
-                        "Failed to start Docker container '{container_id}' with labels {labels:?}"
-                    ),
-                    e,
-                ));
-            }
-        }
-
-        if let Err(e) = self.probe_bash(None).await {
-            return self.start_error(crate::Error::context(
-                format!("Docker container '{container_id}' health check"),
-                e,
-            ));
-        }
-
-        let duration_ms = elapsed_ms(start);
-        self.emit(SandboxEvent::StartCompleted {
-            provider: "docker".into(),
-            duration_ms,
-        });
-        Ok(())
     }
 
     async fn activate(&self) -> crate::Result<()> {
         let container_id = self.container_id()?.to_string();
-        let inspect = self
-            .docker
-            .inspect_container(&container_id, None::<InspectContainerOptions>)
-            .await
-            .map_err(|e| {
-                if docker_not_found(&e) {
-                    crate::Error::message(format!("Docker container '{container_id}' is gone"))
-                } else {
-                    crate::Error::message(format!(
-                        "Failed to inspect Docker container '{container_id}': {e}"
-                    ))
-                }
-            })?;
-        let labels = inspect
-            .config
-            .and_then(|config| config.labels)
-            .unwrap_or_default();
+        let inspect = self.inspect_container(&container_id).await?;
+        let labels = container_labels(&inspect);
         verify_managed_labels(&container_id, &labels, self.run_id.as_ref())?;
-        if inspect
-            .state
-            .as_ref()
-            .is_some_and(|state| state.running == Some(true))
-        {
-            if inspect
-                .state
-                .is_some_and(|state| state.paused != Some(true))
-            {
-                return Ok(());
-            }
-            if let Err(e) = self.docker.unpause_container(&container_id).await {
-                if !docker_not_modified(&e) {
-                    return Err(crate::Error::context(
-                        format!(
-                            "Failed to unpause Docker container '{container_id}' with labels {labels:?}"
-                        ),
-                        e,
-                    ));
-                }
-            }
+        let Some(action) = activation_action(&inspect) else {
             return Ok(());
+        };
+        match action {
+            ContainerStartAction::Unpause => {
+                self.set_container_running(&container_id, &labels, action)
+                    .await
+            }
+            ContainerStartAction::Start => {
+                let started = self.begin_start();
+                self.complete_start(started, &container_id, &labels, action)
+                    .await
+            }
         }
-        self.start().await
     }
 
     async fn stop(&self) -> crate::Result<()> {
@@ -2195,9 +2248,7 @@ mod tests {
                     .header("content-type", "application/json")
                     .json_body(serde_json::json!({
                         "Config": {
-                            "Labels": {
-                                "sh.fabro.managed": "true"
-                            }
+                            "Labels": managed_labels::for_run(None)
                         },
                         "State": {
                             "Running": true,
@@ -2548,22 +2599,14 @@ mod tests {
     }
 
     fn test_docker_sandbox(docker: Docker, container_id: &str) -> DockerSandbox {
-        let sandbox = DockerSandbox {
+        let sandbox = DockerSandbox::with_docker_client(
             docker,
-            config: DockerSandboxOptions::default(),
-            github_app: None,
-            run_id: None,
-            clone_origin_url: None,
-            clone_branch: None,
-            container_id: OnceCell::new(),
-            repo_cloned: OnceCell::new(),
-            working_directory: OnceCell::new(),
-            origin_url: OnceCell::new(),
-            cached_platform: std::sync::OnceLock::new(),
-            cached_os_version: std::sync::OnceLock::new(),
-            rg_available: OnceCell::new(),
-            event_callback: None,
-        };
+            DockerSandboxOptions::default(),
+            None,
+            None,
+            None,
+            None,
+        );
         sandbox
             .container_id
             .set(container_id.to_string())
diff --git a/lib/components/fabro-sandbox/src/local.rs b/lib/components/fabro-sandbox/src/local.rs
index 6af6c4e8d..937abdc64 100644
--- a/lib/components/fabro-sandbox/src/local.rs
+++ b/lib/components/fabro-sandbox/src/local.rs
@@ -836,6 +836,9 @@ impl Sandbox for LocalSandbox {
     }
 
     async fn activate(&self) -> crate::Result<()> {
+        // Local sandboxes have no provider resource that can stop or pause.
+        // Resume paths still call `start()` to recreate the directory and
+        // verify Bash.
         Ok(())
     }
 
diff --git a/lib/components/fabro-sandbox/src/sandbox.rs b/lib/components/fabro-sandbox/src/sandbox.rs
index 90fdd9bcb..b29ccea39 100644
--- a/lib/components/fabro-sandbox/src/sandbox.rs
+++ b/lib/components/fabro-sandbox/src/sandbox.rs
@@ -1134,11 +1134,12 @@ pub trait Sandbox: Send + Sync {
         remote_path: &str,
     ) -> crate::Result<()>;
     async fn initialize(&self) -> crate::Result<()>;
-    /// Ensure the sandbox is active and ready for ordinary operations.
+    /// Ensure the provider resource is running and not paused before access.
     ///
     /// This access-time operation must be idempotent. Providers that can stop
     /// independently should avoid restarting an already-active sandbox. This
-    /// method does not keep a sandbox active between calls.
+    /// lightweight check does not require the full health verification done by
+    /// [`Sandbox::start`], and it does not keep a sandbox active between calls.
     async fn activate(&self) -> crate::Result<()> {
         self.start().await
     }
diff --git a/lib/components/fabro-sandbox/src/test_support.rs b/lib/components/fabro-sandbox/src/test_support.rs
index a1f9e102b..65ff4af25 100644
--- a/lib/components/fabro-sandbox/src/test_support.rs
+++ b/lib/components/fabro-sandbox/src/test_support.rs
@@ -1,5 +1,6 @@
 use std::collections::HashMap;
 use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::Duration;
 
 use async_trait::async_trait;
@@ -38,6 +39,8 @@ pub struct MockSandbox {
     pub captured_working_dirs: Mutex<Vec<Option<String>>>,
     /// Captures the `env_vars` argument from `exec_command` calls.
     pub captured_env_vars:     Mutex<Option<HashMap<String, String>>>,
+    pub active:                AtomicBool,
+    pub activate_error:        Option<String>,
     pub activate_calls:        Mutex<u32>,
     pub start_calls:           Mutex<u32>,
     pub stop_calls:            Mutex<u32>,
@@ -52,6 +55,8 @@ pub struct MockSandbox {
     /// filtering.
     pub walk_files:            Vec<SandboxFile>,
     pub walk_files_error:      Option<String>,
+    pub walk_files_called:     AtomicBool,
+    pub walked_while_inactive: AtomicBool,
     /// Reported by `exec_command_streaming`. Set to `false` to model a
     /// provider that cannot separate stdout from stderr.
     pub streams_separated:     bool,
@@ -82,6 +87,14 @@ impl MockSandbox {
         *self.stop_calls.lock().expect("stop_calls lock poisoned")
     }
 
+    pub fn walk_files_was_called(&self) -> bool {
+        self.walk_files_called.load(Ordering::Relaxed)
+    }
+
+    pub fn walked_while_inactive(&self) -> bool {
+        self.walked_while_inactive.load(Ordering::Relaxed)
+    }
+
     pub fn delete_count(&self) -> u32 {
         *self
             .delete_calls
@@ -107,6 +120,12 @@ impl MockSandbox {
         self.walk_files_error = Some(error.into());
         self
     }
+
+    #[must_use]
+    pub fn with_activate_error(mut self, error: impl Into<String>) -> Self {
+        self.activate_error = Some(error.into());
+        self
+    }
 }
 
 impl MockSandbox {
@@ -140,6 +159,8 @@ impl Default for MockSandbox {
             captured_commands:     Mutex::new(Vec::new()),
             captured_working_dirs: Mutex::new(Vec::new()),
             captured_env_vars:     Mutex::new(None),
+            active:                AtomicBool::new(true),
+            activate_error:        None,
             activate_calls:        Mutex::new(0),
             start_calls:           Mutex::new(0),
             stop_calls:            Mutex::new(0),
@@ -150,6 +171,8 @@ impl Default for MockSandbox {
             exec_error:            None,
             walk_files:            Vec::new(),
             walk_files_error:      None,
+            walk_files_called:     AtomicBool::new(false),
+            walked_while_inactive: AtomicBool::new(false),
             streams_separated:     true,
         }
     }
@@ -376,6 +399,11 @@ impl Sandbox for MockSandbox {
         relative_start: &str,
         options: &WalkOptions,
     ) -> crate::Result<Vec<SandboxFile>> {
+        self.walk_files_called.store(true, Ordering::Relaxed);
+        if !self.active.load(Ordering::Relaxed) {
+            self.walked_while_inactive.store(true, Ordering::Relaxed);
+            return Err(crate::Error::message("Sandbox is stopped"));
+        }
         if let Some(error) = &self.walk_files_error {
             return Err(crate::Error::message(error.clone()));
         }
@@ -439,6 +467,7 @@ impl Sandbox for MockSandbox {
     }
 
     async fn initialize(&self) -> crate::Result<()> {
+        self.active.store(true, Ordering::Relaxed);
         self.emit(SandboxEvent::Initializing {
             provider: "mock".into(),
         });
@@ -458,16 +487,24 @@ impl Sandbox for MockSandbox {
             .activate_calls
             .lock()
             .expect("activate_calls lock poisoned") += 1;
+        if let Some(error) = &self.activate_error {
+            return Err(crate::Error::context(
+                "Mock sandbox activation failed",
+                std::io::Error::other(error.clone()),
+            ));
+        }
         self.start().await
     }
 
     async fn start(&self) -> crate::Result<()> {
         *self.start_calls.lock().expect("start_calls lock poisoned") += 1;
+        self.active.store(true, Ordering::Relaxed);
         Ok(())
     }
 
     async fn stop(&self) -> crate::Result<()> {
         *self.stop_calls.lock().expect("stop_calls lock poisoned") += 1;
+        self.active.store(false, Ordering::Relaxed);
         Ok(())
     }
 
diff --git a/lib/components/fabro-workflow/src/lifecycle/mod.rs b/lib/components/fabro-workflow/src/lifecycle/mod.rs
index cf442f497..64a6323f2 100644
--- a/lib/components/fabro-workflow/src/lifecycle/mod.rs
+++ b/lib/components/fabro-workflow/src/lifecycle/mod.rs
@@ -284,11 +284,10 @@ impl RunLifecycle<WorkflowGraph> for WorkflowLifecycle {
         }
         // A provider may auto-stop while the run is paused between nodes.
         self.sandbox.activate().await.map_err(|err| {
-            CoreError::Other(format!(
-                "failed to activate sandbox before node {:?}: {}",
-                node.id(),
-                err.display_with_causes()
-            ))
+            CoreError::context(
+                format!("failed to activate sandbox before node {}", node.id()),
+                err,
+            )
         })?;
         if let Some(on_node) = &self.on_node {
             on_node(node.id());
@@ -343,11 +342,13 @@ impl RunLifecycle<WorkflowGraph> for WorkflowLifecycle {
         // Human, wait, and paused stages can return after a long period with
         // no sandbox traffic. Reactivate before artifact and checkpoint work.
         self.sandbox.activate().await.map_err(|err| {
-            CoreError::Other(format!(
-                "failed to activate sandbox after node attempt {:?}: {}",
-                ctx.node.id(),
-                err.display_with_causes()
-            ))
+            CoreError::context(
+                format!(
+                    "failed to activate sandbox after node attempt {}",
+                    ctx.node.id()
+                ),
+                err,
+            )
         })?;
         self.artifact.after_attempt(ctx, state).await?;
         self.event.after_attempt(ctx, state).await?;
diff --git a/lib/components/fabro-workflow/src/pipeline/execute.rs b/lib/components/fabro-workflow/src/pipeline/execute.rs
index e89006ab0..a82fd7c8a 100644
--- a/lib/components/fabro-workflow/src/pipeline/execute.rs
+++ b/lib/components/fabro-workflow/src/pipeline/execute.rs
@@ -276,6 +276,13 @@ pub async fn execute(init: Initialized) -> Executed {
         Err(fabro_core::Error::Blocked { message }) => {
             (Err(Error::engine(message)), initial_context)
         }
+        Err(error @ fabro_core::Error::Context { .. }) => (
+            Err(Error::engine_with_source(
+                "Pipeline lifecycle operation failed",
+                error,
+            )),
+            initial_context,
+        ),
         Err(e) => (Err(Error::engine(e.to_string())), initial_context),
     };
 
diff --git a/lib/components/fabro-workflow/src/pipeline/execute/tests.rs b/lib/components/fabro-workflow/src/pipeline/execute/tests.rs
index 6807277e8..5faa9c1ac 100644
--- a/lib/components/fabro-workflow/src/pipeline/execute/tests.rs
+++ b/lib/components/fabro-workflow/src/pipeline/execute/tests.rs
@@ -649,8 +649,7 @@ impl HandlerTrait for SlowHandler {
 }
 
 struct StopsSandboxHandler {
-    sandbox:                   Arc<MockSandbox>,
-    observed_activation_count: Arc<AtomicU32>,
+    sandbox: Arc<MockSandbox>,
 }
 
 #[async_trait]
@@ -663,8 +662,6 @@ impl HandlerTrait for StopsSandboxHandler {
         _run_dir: &Path,
         _services: &crate::handler::EngineServices,
     ) -> std::result::Result<Outcome, Error> {
-        self.observed_activation_count
-            .store(self.sandbox.activate_count(), Ordering::Relaxed);
         self.sandbox
             .stop()
             .await
@@ -828,36 +825,63 @@ async fn execute_runs_simple_workflow() {
     assert_eq!(outcome.status, StageOutcome::Succeeded);
 }
 
+#[tokio::test]
+async fn execute_preserves_sandbox_activation_error_chain() {
+    let dir = tempfile::tempdir().unwrap();
+    let sandbox: Arc<dyn Sandbox> =
+        Arc::new(MockSandbox::linux().with_activate_error("provider unavailable"));
+
+    let error = run_graph(
+        make_registry(),
+        test_emitter_arc("test-run"),
+        sandbox,
+        &simple_graph(),
+        &test_run_options(dir.path(), "test-run"),
+    )
+    .await
+    .expect_err("sandbox activation should fail");
+
+    assert_eq!(error.causes(), vec![
+        "failed to activate sandbox before node start",
+        "Mock sandbox activation failed",
+        "provider unavailable",
+    ]);
+}
+
 #[tokio::test]
 async fn execute_reactivates_sandbox_after_a_stage_can_leave_it_stopped() {
     let dir = tempfile::tempdir().unwrap();
     let sandbox = Arc::new(MockSandbox::linux());
-    let observed_activation_count = Arc::new(AtomicU32::new(0));
     let mut registry = make_registry();
     registry.register(
         "start",
         Box::new(StopsSandboxHandler {
-            sandbox:                   Arc::clone(&sandbox),
-            observed_activation_count: Arc::clone(&observed_activation_count),
+            sandbox: Arc::clone(&sandbox),
         }),
     );
     let sandbox_for_run: Arc<dyn Sandbox> = sandbox.clone();
+    let mut run_options = test_run_options(dir.path(), "test-run");
+    run_options
+        .settings
+        .run
+        .artifacts
+        .include
+        .push("**/*".to_string());
 
     let outcome = run_graph(
         registry,
         test_emitter_arc("test-run"),
         sandbox_for_run,
         &simple_graph(),
-        &test_run_options(dir.path(), "test-run"),
+        &run_options,
     )
     .await
     .unwrap();
 
     assert_eq!(outcome.status, StageOutcome::Succeeded);
-    assert_eq!(observed_activation_count.load(Ordering::Relaxed), 1);
     assert_eq!(sandbox.stop_count(), 1);
-    assert_eq!(sandbox.activate_count(), 2);
-    assert_eq!(sandbox.start_count(), 2);
+    assert!(sandbox.walk_files_was_called());
+    assert!(!sandbox.walked_while_inactive());
 }
 
 #[tokio::test]
diff --git a/lib/components/fabro-workflow/src/pipeline/initialize.rs b/lib/components/fabro-workflow/src/pipeline/initialize.rs
index 149a9ee59..0f02db0c2 100644
--- a/lib/components/fabro-workflow/src/pipeline/initialize.rs
+++ b/lib/components/fabro-workflow/src/pipeline/initialize.rs
@@ -392,6 +392,8 @@ pub async fn initialize(
     });
 
     if attach_existing {
+        // Resume needs the full provider health check. `activate()` is the
+        // lighter access-time operation used after a run is already active.
         sandbox
             .start()
             .await
diff --git a/lib/foundation/fabro-core/src/error.rs b/lib/foundation/fabro-core/src/error.rs
index ea99e87d9..fc4bfbdeb 100644
--- a/lib/foundation/fabro-core/src/error.rs
+++ b/lib/foundation/fabro-core/src/error.rs
@@ -55,6 +55,12 @@ pub enum Error {
     StallTimeout { node_id: String },
     #[error("{detail}")]
     Handler { detail: Box<HandlerErrorDetail> },
+    #[error("{message}")]
+    Context {
+        message: String,
+        #[source]
+        source:  Box<dyn std::error::Error + Send + Sync + 'static>,
+    },
     #[error("{0}")]
     Other(String),
 }
@@ -72,6 +78,16 @@ impl Error {
         }
     }
 
+    pub fn context(
+        message: impl Into<String>,
+        source: impl std::error::Error + Send + Sync + 'static,
+    ) -> Self {
+        Self::Context {
+            message: message.into(),
+            source:  Box::new(source),
+        }
+    }
+
     pub fn is_retryable(&self) -> bool {
         matches!(self, Self::Handler { detail } if detail.retryable)
     }
@@ -94,6 +110,8 @@ pub type Result<T> = std::result::Result<T, Error>;
 
 #[cfg(test)]
 mod tests {
+    use std::error::Error as _;
+
     use super::*;
     use crate::outcome::FailureCategory;
 
@@ -153,6 +171,20 @@ mod tests {
         assert!(!not_retryable.is_retryable());
     }
 
+    #[test]
+    fn core_error_context_preserves_source() {
+        let error = Error::context(
+            "failed to activate sandbox",
+            std::io::Error::other("provider unavailable"),
+        );
+
+        assert_eq!(error.to_string(), "failed to activate sandbox");
+        assert_eq!(
+            error.source().map(ToString::to_string).as_deref(),
+            Some("provider unavailable")
+        );
+    }
+
     #[test]
     fn core_error_handler_to_fail_outcome() {
         let err = Error::handler(HandlerErrorDetail {

From 7bacd4cf12f4a638e78419273987c9b606a5254f Mon Sep 17 00:00:00 2001
From: Release Repro <release-repro@example.com>
Date: Tue, 28 Jul 2026 16:10:47 -0400
Subject: [PATCH 35/36] refactor(workflow): scan for outermost JSON objects
 everywhere

Replace the include_nested flag and its two wrapper functions with a
single outermost-only scanner. Routing extraction used the nested scan
and reverse iteration, so a routing object nested inside a wrapper could
win over its parent -- the same bug class this branch fixes for custom
schemas. No caller needs nested candidates.

Custom schema validation now walks candidates from the end and takes the
last one that parses, instead of parsing only the final candidate. Prose
after the object can contain braces, and outermost-only scanning made
that trailing text a candidate that shadowed the real JSON. Schema errors
are still reported from the last parsable object, so an earlier object
that happens to validate cannot mask a later violation.

Add direct scanner coverage for nesting, adjacent objects, unclosed
braces, and braces inside strings.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../src/handler/structured_output.rs          | 152 +++++++++++-------
 1 file changed, 94 insertions(+), 58 deletions(-)

diff --git a/lib/components/fabro-workflow/src/handler/structured_output.rs b/lib/components/fabro-workflow/src/handler/structured_output.rs
index 888256b21..fc89f6581 100644
--- a/lib/components/fabro-workflow/src/handler/structured_output.rs
+++ b/lib/components/fabro-workflow/src/handler/structured_output.rs
@@ -224,18 +224,13 @@ pub(crate) fn apply_validated_output(
     }
 }
 
-/// Find all balanced `{...}` JSON object substrings in the text.
+/// Find the outermost balanced `{...}` JSON object substrings in the text, in
+/// document order. Objects nested inside a match are skipped.
+///
+/// An unbalanced `{` does not suppress complete objects around or inside it:
+/// the scan only skips ahead past a *matched* object, so it still walks into a
+/// region that failed to close.
 fn find_json_objects(text: &str) -> Vec<&str> {
-    find_json_objects_with_nested(text, true)
-}
-
-/// Find balanced `{...}` JSON object substrings in the text, skipping objects
-/// nested within a previous match.
-fn find_outermost_json_objects(text: &str) -> Vec<&str> {
-    find_json_objects_with_nested(text, false)
-}
-
-fn find_json_objects_with_nested(text: &str, include_nested: bool) -> Vec<&str> {
     let mut results = Vec::new();
     let bytes = text.as_bytes();
     let mut i = 0;
@@ -261,9 +256,7 @@ fn find_json_objects_with_nested(text: &str, include_nested: bool) -> Vec<&str>
                         depth -= 1;
                         if depth == 0 {
                             results.push(&text[start..=j]);
-                            if !include_nested {
-                                i = j;
-                            }
+                            i = j;
                             break;
                         }
                     }
@@ -282,7 +275,8 @@ pub(crate) fn terminal_json_object(text: &str) -> Option<&str> {
     let trimmed = text.trim_end();
     find_json_objects(trimmed)
         .into_iter()
-        .find(|candidate| trimmed.ends_with(candidate))
+        .next_back()
+        .filter(|candidate| trimmed.ends_with(candidate))
 }
 
 pub(crate) fn extract_status_fields(text: &str, outcome: &mut Outcome) -> bool {
@@ -347,21 +341,32 @@ fn validate_custom_response_text(
     validator: &Validator,
     text: &str,
 ) -> Result<ValidatedStructuredOutput, StructuredOutputError> {
-    let candidates = find_outermost_json_objects(text);
-    let Some(candidate) = candidates.last() else {
-        return Err(StructuredOutputError::new(
+    // Prose after the object can contain braces, so the last candidate is not
+    // always JSON. Take the last one that parses; report its schema errors
+    // rather than falling back to an earlier object that happens to validate.
+    let candidates = find_json_objects(text);
+    let mut invalid_json = None;
+    for candidate in candidates.iter().rev() {
+        match serde_json::from_str::<Value>(candidate) {
+            Ok(parsed) => {
+                validate_value_against_validator(validator, &parsed)?;
+                return Ok(ValidatedStructuredOutput { value: parsed });
+            }
+            Err(err) if invalid_json.is_none() => invalid_json = Some(err.to_string()),
+            Err(_) => {}
+        }
+    }
+
+    Err(match invalid_json {
+        Some(message) => StructuredOutputError::new(
+            StructuredOutputErrorKind::InvalidJson,
+            format!("invalid JSON object: {message}"),
+        ),
+        None => StructuredOutputError::new(
             StructuredOutputErrorKind::NoJsonObject,
             "no JSON object found in response",
-        ));
-    };
-    let parsed = serde_json::from_str::<Value>(candidate).map_err(|err| {
-        StructuredOutputError::new(
-            StructuredOutputErrorKind::InvalidJson,
-            format!("invalid JSON object: {err}"),
-        )
-    })?;
-    validate_value_against_validator(validator, &parsed)?;
-    Ok(ValidatedStructuredOutput { value: parsed })
+        ),
+    })
 }
 
 fn validate_value_against_validator(
@@ -477,6 +482,24 @@ mod tests {
         }
     }
 
+    /// A schema whose required field is itself an object, so validating the
+    /// innermost `{...}` in the response would fail.
+    fn issue_schema() -> OutputSchemaKind {
+        schema(serde_json::json!({
+            "type": "object",
+            "required": ["issue"],
+            "properties": {
+                "issue": {
+                    "type": "object",
+                    "required": ["number"],
+                    "properties": {
+                        "number": { "type": "integer" }
+                    }
+                }
+            }
+        }))
+    }
+
     #[test]
     fn validates_routing_json_and_applies_fields() {
         let validated = validate_response_text(
@@ -573,21 +596,8 @@ mod tests {
 
     #[test]
     fn validates_custom_schema_against_outermost_object() {
-        let schema = schema(serde_json::json!({
-            "type": "object",
-            "required": ["issue"],
-            "properties": {
-                "issue": {
-                    "type": "object",
-                    "required": ["number"],
-                    "properties": {
-                        "number": { "type": "integer" }
-                    }
-                }
-            }
-        }));
-
-        let validated = validate_response_text(&schema, r#"{"issue":{"number":19}}"#).unwrap();
+        let validated =
+            validate_response_text(&issue_schema(), r#"{"issue":{"number":19}}"#).unwrap();
 
         assert_eq!(
             validated.value,
@@ -597,22 +607,8 @@ mod tests {
 
     #[test]
     fn validates_last_outermost_object_when_response_has_trailing_prose() {
-        let schema = schema(serde_json::json!({
-            "type": "object",
-            "required": ["issue"],
-            "properties": {
-                "issue": {
-                    "type": "object",
-                    "required": ["number"],
-                    "properties": {
-                        "number": { "type": "integer" }
-                    }
-                }
-            }
-        }));
-
         let validated = validate_response_text(
-            &schema,
+            &issue_schema(),
             r#"ignore {"issue":{"number":1}} final {"issue":{"number":19}} trailing"#,
         )
         .unwrap();
@@ -623,6 +619,46 @@ mod tests {
         );
     }
 
+    #[test]
+    fn validates_last_parsable_object_when_trailing_prose_contains_braces() {
+        let schema = schema(serde_json::json!({
+            "type": "object",
+            "required": ["passed"],
+            "properties": {
+                "passed": { "type": "boolean" }
+            }
+        }));
+
+        let validated = validate_response_text(
+            &schema,
+            "{\"passed\":true}\n\nLet me know if {this works} for you.",
+        )
+        .unwrap();
+
+        assert_eq!(validated.value, serde_json::json!({"passed": true}));
+    }
+
+    #[test]
+    fn find_json_objects_returns_outermost_objects_only() {
+        let cases = [
+            (r#"{"a":{"b":1}}"#, vec![r#"{"a":{"b":1}}"#]),
+            (r#"{"a":1} {"b":2}"#, vec![r#"{"a":1}"#, r#"{"b":2}"#]),
+            (r#"{"a":1}{"b":2}"#, vec![r#"{"a":1}"#, r#"{"b":2}"#]),
+            // An unclosed outer brace must not hide the complete object inside it.
+            (r#"{ {"a":1}"#, vec![r#"{"a":1}"#]),
+            (r#"{"a":1} {"#, vec![r#"{"a":1}"#]),
+            // An unterminated string swallows the rest of its own candidate.
+            (r#"{"a": "x} {"b":2}"#, vec![r#"{"b":2}"#]),
+            // Braces inside strings are not delimiters.
+            (r#"{"a":"} {"}"#, vec![r#"{"a":"} {"}"#]),
+            ("no json here", vec![]),
+        ];
+
+        for (text, expected) in cases {
+            assert_eq!(find_json_objects(text), expected, "input: {text}");
+        }
+    }
+
     #[test]
     fn custom_schema_validation_errors_are_reported() {
         let schema = schema(serde_json::json!({

From 4727ee8e755cda8cdaa7ba3593012565f7061e1d Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 16:26:41 -0400
Subject: [PATCH 36/36] Harden sandbox clone retries

---
 lib/components/fabro-github/src/lib.rs        |  39 +++-
 .../fabro-sandbox/src/clone_retry.rs          | 153 +++++++++----
 .../fabro-sandbox/src/clone_source.rs         |  54 +++++
 .../fabro-sandbox/src/daytona/mod.rs          | 171 +++++++-------
 lib/components/fabro-sandbox/src/docker.rs    | 212 +++++++++++-------
 lib/components/fabro-sandbox/src/error.rs     |   6 +-
 6 files changed, 417 insertions(+), 218 deletions(-)

diff --git a/lib/components/fabro-github/src/lib.rs b/lib/components/fabro-github/src/lib.rs
index bac1f5fbc..bfb62741f 100644
--- a/lib/components/fabro-github/src/lib.rs
+++ b/lib/components/fabro-github/src/lib.rs
@@ -194,6 +194,12 @@ pub enum GitHubCredentials {
 }
 
 impl GitHubCredentials {
+    /// Whether resolving these credentials mints a new installation token.
+    #[must_use]
+    pub fn mints_installation_token(&self) -> bool {
+        matches!(self, Self::App(_))
+    }
+
     pub fn from_env(app_id: Option<&str>) -> Result<Option<Self>, String> {
         Ok(GitHubAppCredentials::from_env(app_id)?.map(Self::App))
     }
@@ -372,7 +378,7 @@ pub fn parse_github_owner_repo(url: &str) -> anyhow::Result<(String, String)> {
     let path = path.trim_end_matches('/');
     let path = path.strip_suffix(".git").unwrap_or(path);
 
-    let mut parts = path.splitn(3, '/');
+    let mut parts = path.split('/');
     let owner = parts
         .next()
         .filter(|s| !s.is_empty())
@@ -381,6 +387,9 @@ pub fn parse_github_owner_repo(url: &str) -> anyhow::Result<(String, String)> {
         .next()
         .filter(|s| !s.is_empty())
         .ok_or_else(|| anyhow!("Missing repo in GitHub URL: {display_url}"))?;
+    if parts.next().is_some() {
+        bail!("GitHub URL must identify one repository: {display_url}");
+    }
 
     Ok((owner.to_string(), repo.to_string()))
 }
@@ -1388,6 +1397,16 @@ mod tests {
         assert_eq!(repo, "repo");
     }
 
+    #[test]
+    fn parse_rejects_extra_path_components() {
+        let error = parse_github_owner_repo("https://github.com/owner/repo/issues").unwrap_err();
+
+        assert!(
+            error.to_string().contains("must identify one repository"),
+            "got: {error}"
+        );
+    }
+
     // -----------------------------------------------------------------------
     // ssh_url_to_https
     // -----------------------------------------------------------------------
@@ -2312,6 +2331,24 @@ mod tests {
         assert!(!fresh.near_expiry(std::time::Duration::from_mins(15)));
     }
 
+    #[test]
+    fn only_app_credentials_mint_installation_tokens() {
+        let app = GitHubCredentials::App(GitHubAppCredentials {
+            app_id:          "test".to_string(),
+            private_key_pem: test_rsa_key().to_string(),
+            slug:            None,
+        });
+        let pat = GitHubCredentials::Pat("ghp_personal".to_string());
+        let installation = GitHubCredentials::Installation(InstallationToken {
+            token:      "ghs_installation".to_string(),
+            expires_at: chrono::Utc::now() + chrono::Duration::minutes(30),
+        });
+
+        assert!(app.mints_installation_token());
+        assert!(!pat.mints_installation_token());
+        assert!(!installation.mints_installation_token());
+    }
+
     #[test]
     fn validate_static_github_token_rejects_installation_tokens() {
         validate_static_github_token("ghp_personal").unwrap();
diff --git a/lib/components/fabro-sandbox/src/clone_retry.rs b/lib/components/fabro-sandbox/src/clone_retry.rs
index d94a52485..f0f3f0572 100644
--- a/lib/components/fabro-sandbox/src/clone_retry.rs
+++ b/lib/components/fabro-sandbox/src/clone_retry.rs
@@ -1,19 +1,12 @@
 //! Retry for the first repository clone in a clone-based sandbox.
 //!
-//! Clone-based providers mint a GitHub installation access token and clone with
-//! it in the same breath. GitHub replicates a new token to its edge cache sites
-//! asynchronously, so a clone that starts within a second of the mint can be
-//! rejected before the token is visible to the site serving it. On a private
-//! repository that rejection arrives as `Repository not found.`, because GitHub
-//! answers unauthorized reads with 404 rather than 403.
+//! Clone-based providers can mint a GitHub App installation token and clone
+//! with it immediately. GitHub can reject that first clone before the token is
+//! available to the git endpoint. On a private repository, the rejection can
+//! arrive as `Repository not found.` or an authentication failure.
 //!
-//! A successful mint is what makes that message safe to retry.
-//! `resolve_clone_credentials` already fails loudly on every deterministic
-//! explanation for a clone 404: the installation lookup 404s when the App is
-//! not installed for the owner, and token creation 422s when the installation
-//! does not cover the repository. So once credentials are in hand, `not found`
-//! from the clone itself cannot mean "no access" — the repository exists and
-//! the token covers it.
+//! Only a token minted during the current clone operation makes those messages
+//! safe to retry. Static PATs and pre-minted installation tokens fail fast.
 //!
 //! Retries reuse the same token on purpose. Replication of a given token only
 //! makes progress, so each attempt strictly improves the odds, while re-minting
@@ -22,6 +15,7 @@
 use std::future::Future;
 use std::time::Duration;
 
+use fabro_types::SandboxProviderKind;
 use fabro_util::backoff::BackoffPolicy;
 use tokio::time;
 
@@ -39,6 +33,23 @@ pub(crate) enum CloneRetryReason {
     TransientInfra,
 }
 
+/// What a clone failure message tells us about retry safety.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum CloneMessageClass {
+    Retry(CloneRetryReason),
+    Permanent,
+    Unknown,
+}
+
+impl CloneMessageClass {
+    pub(crate) fn retry_reason(self) -> Option<CloneRetryReason> {
+        match self {
+            Self::Retry(reason) => Some(reason),
+            Self::Permanent | Self::Unknown => None,
+        }
+    }
+}
+
 /// Message fragments that mean the clone failed on infrastructure.
 ///
 /// These are safe to retry whether or not the clone was authenticated.
@@ -76,24 +87,35 @@ const TOKEN_REPLICATION_HINTS: &[&str] = &[
 
 /// Classify a failed clone by its rendered message.
 ///
-/// `has_credentials` gates the token-replication reading. Without credentials
-/// there is no token to replicate, so `not found` on a public clone means the
-/// URL names a repository that is not there — that should fail immediately
-/// rather than burn 12 seconds of backoff.
-pub(crate) fn classify_message(message: &str, has_credentials: bool) -> Option<CloneRetryReason> {
+/// `token_was_freshly_minted` gates the token-replication reading. A static
+/// credential cannot become valid during backoff, so auth failures for it are
+/// permanent.
+pub(crate) fn classify_message(message: &str, token_was_freshly_minted: bool) -> CloneMessageClass {
     let lower = message.to_ascii_lowercase();
 
     if TRANSIENT_HINTS.iter().any(|hint| lower.contains(hint)) {
-        return Some(CloneRetryReason::TransientInfra);
+        return CloneMessageClass::Retry(CloneRetryReason::TransientInfra);
     }
-    if has_credentials
-        && TOKEN_REPLICATION_HINTS
-            .iter()
-            .any(|hint| lower.contains(hint))
+    if TOKEN_REPLICATION_HINTS
+        .iter()
+        .any(|hint| lower.contains(hint))
     {
-        return Some(CloneRetryReason::TokenReplication);
+        return if token_was_freshly_minted {
+            CloneMessageClass::Retry(CloneRetryReason::TokenReplication)
+        } else {
+            CloneMessageClass::Permanent
+        };
     }
-    None
+    let permanent = lower.contains("could not read username")
+        || lower.contains("terminal prompts disabled")
+        || lower.contains("permission denied")
+        || (lower.contains("permission to") && lower.contains("denied"))
+        || (lower.contains("destination path") && lower.contains("already exists"))
+        || (lower.contains("remote branch") && lower.contains("not found"));
+    if permanent {
+        return CloneMessageClass::Permanent;
+    }
+    CloneMessageClass::Unknown
 }
 
 /// Backoff between clone attempts: 3s, then 9s.
@@ -112,13 +134,13 @@ fn backoff() -> BackoffPolicy {
 
 /// Run a clone, repeating it while the failure looks transient.
 ///
-/// `attempt` receives the 1-based attempt number so the caller can clear
-/// leftovers from the previous try before cloning again. `classify` decides
-/// whether an error is worth repeating; `None` returns it to the caller
-/// untouched. The error from the final attempt is returned as-is, so callers
-/// keep the cause chain they would have had without retries.
+/// `attempt` receives the 1-based attempt number. `classify` decides whether an
+/// error is worth repeating; `None` returns it to the caller untouched. When a
+/// deadline is present, a retry starts only when its backoff fits before that
+/// deadline. The final error is returned as-is.
 pub(crate) async fn retry_clone<T, E, Attempt, Fut, Classify>(
-    provider: &'static str,
+    provider: SandboxProviderKind,
+    deadline: Option<time::Instant>,
     mut attempt: Attempt,
     classify: Classify,
 ) -> Result<T, E>
@@ -137,11 +159,16 @@ where
                     return Err(err);
                 };
                 let delay = backoff.delay_for_attempt(attempt_number);
+                if deadline.is_some_and(|deadline| {
+                    delay >= deadline.saturating_duration_since(time::Instant::now())
+                }) {
+                    return Err(err);
+                }
                 // The failure text can carry git stderr, so log the category
                 // rather than the message. The caller still reports the full
                 // error if the attempts run out.
                 tracing::warn!(
-                    provider,
+                    provider = %provider,
                     attempt = attempt_number,
                     max_attempts = MAX_ATTEMPTS,
                     reason = %reason,
@@ -184,26 +211,33 @@ mod tests {
     fn private_repo_not_found_after_a_successful_mint_is_a_replication_lag() {
         assert_eq!(
             classify_message("repository not found: Repository not found.", true),
-            Some(CloneRetryReason::TokenReplication)
+            CloneMessageClass::Retry(CloneRetryReason::TokenReplication)
         );
     }
 
     #[test]
-    fn not_found_without_credentials_is_a_wrong_url() {
+    fn not_found_without_a_fresh_token_is_permanent() {
         assert_eq!(
             classify_message("repository not found: Repository not found.", false),
-            None
+            CloneMessageClass::Permanent
         );
     }
 
     #[test]
-    fn auth_failure_with_credentials_is_a_replication_lag() {
+    fn auth_failure_with_a_fresh_token_is_a_replication_lag() {
         assert_eq!(
             classify_message(
                 "fatal: Authentication failed for 'https://github.com/owner/repo'",
                 true
             ),
-            Some(CloneRetryReason::TokenReplication)
+            CloneMessageClass::Retry(CloneRetryReason::TokenReplication)
+        );
+        assert_eq!(
+            classify_message(
+                "fatal: Authentication failed for 'https://github.com/owner/repo'",
+                false
+            ),
+            CloneMessageClass::Permanent
         );
     }
 
@@ -217,7 +251,7 @@ mod tests {
         ] {
             assert_eq!(
                 classify_message(message, false),
-                Some(CloneRetryReason::TransientInfra),
+                CloneMessageClass::Retry(CloneRetryReason::TransientInfra),
                 "expected {message:?} to be transient"
             );
         }
@@ -232,12 +266,20 @@ mod tests {
         ] {
             assert_eq!(
                 classify_message(message, true),
-                None,
+                CloneMessageClass::Permanent,
                 "expected {message:?} to fail fast"
             );
         }
     }
 
+    #[test]
+    fn unrecognized_failures_remain_unknown() {
+        assert_eq!(
+            classify_message("git clone stopped for an unexpected reason", true),
+            CloneMessageClass::Unknown
+        );
+    }
+
     #[test]
     fn backoff_waits_seconds_not_milliseconds() {
         let backoff = backoff();
@@ -250,7 +292,8 @@ mod tests {
         let attempts = Attempts::default();
 
         let result = retry_clone(
-            "test",
+            SandboxProviderKind::Docker,
+            None,
             |attempt| {
                 attempts.record(attempt);
                 async move { Ok::<_, String>(attempt) }
@@ -268,7 +311,8 @@ mod tests {
         let attempts = Attempts::default();
 
         let result = retry_clone(
-            "test",
+            SandboxProviderKind::Docker,
+            None,
             |attempt| {
                 attempts.record(attempt);
                 async move {
@@ -292,7 +336,8 @@ mod tests {
         let attempts = Attempts::default();
 
         let result = retry_clone(
-            "test",
+            SandboxProviderKind::Docker,
+            None,
             |attempt| {
                 attempts.record(attempt);
                 async move { Err::<(), _>(format!("Repository not found. (attempt {attempt})")) }
@@ -314,7 +359,8 @@ mod tests {
         let attempts = Attempts::default();
 
         let result = retry_clone(
-            "test",
+            SandboxProviderKind::Docker,
+            None,
             |attempt| {
                 attempts.record(attempt);
                 async move { Err::<(), _>("permission denied".to_string()) }
@@ -330,4 +376,25 @@ mod tests {
             "a deterministic failure should not wait out the backoff"
         );
     }
+
+    #[tokio::test(start_paused = true)]
+    async fn deadline_stops_retry_when_backoff_does_not_fit() {
+        let attempts = Attempts::default();
+        let deadline = time::Instant::now() + Duration::from_secs(2);
+
+        let result = retry_clone(
+            SandboxProviderKind::Docker,
+            Some(deadline),
+            |attempt| {
+                attempts.record(attempt);
+                async move { Err::<(), _>("temporary failure".to_string()) }
+            },
+            ALWAYS_RETRY,
+        )
+        .await;
+
+        assert_eq!(result, Err("temporary failure".to_string()));
+        assert_eq!(attempts.recorded(), vec![1]);
+        assert_eq!(time::Instant::now() + Duration::from_secs(2), deadline);
+    }
 }
diff --git a/lib/components/fabro-sandbox/src/clone_source.rs b/lib/components/fabro-sandbox/src/clone_source.rs
index 8988f3d47..1a90c6b21 100644
--- a/lib/components/fabro-sandbox/src/clone_source.rs
+++ b/lib/components/fabro-sandbox/src/clone_source.rs
@@ -32,6 +32,8 @@ pub(crate) fn github_repo_layout(
             "Clone-based sandboxes currently support GitHub repository origins only: {err}"
         ))
     })?;
+    validate_path_component("owner", &owner)?;
+    validate_path_component("repository", &repo)?;
     let workspace_root = trim_root(workspace_root);
     let repos_root = trim_root(repos_root);
     let repos_owner_path = sandbox::join_sandbox_path(repos_root, &owner);
@@ -48,6 +50,27 @@ pub(crate) fn github_repo_layout(
     })
 }
 
+fn validate_path_component(label: &str, component: &str) -> crate::Result<()> {
+    let is_safe = !matches!(component, "." | "..")
+        && component
+            .bytes()
+            .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_' | b'.'));
+    if !is_safe {
+        return Err(crate::Error::message(format!(
+            "GitHub {label} is not a safe repository path component"
+        )));
+    }
+    Ok(())
+}
+
+pub(crate) fn repo_symlink_command(layout: &GitHubRepoLayout) -> String {
+    format!(
+        "ln -s {} {}",
+        sandbox::shell_quote(&layout.primary_repo_path),
+        sandbox::shell_quote(&layout.primary_repo_link),
+    )
+}
+
 fn trim_root(root: &str) -> &str {
     let trimmed = root.trim_end_matches('/');
     if trimmed.is_empty() { "/" } else { trimmed }
@@ -204,6 +227,37 @@ mod tests {
         assert_eq!(layout.execution_directory, "/workspace/fabro");
     }
 
+    #[test]
+    fn github_layout_rejects_path_traversal_components() {
+        for origin in [
+            "https://github.com/../widgets",
+            "https://github.com/acme/..",
+            "https://github.com/%2e%2e/widgets",
+        ] {
+            let error = github_repo_layout(origin, "/workspace", "/repos")
+                .expect_err("unsafe path component should fail");
+            assert!(
+                error.to_string().contains("safe repository path component"),
+                "got {error} for {origin}"
+            );
+        }
+    }
+
+    #[test]
+    fn repo_symlink_command_quotes_both_paths() {
+        let layout = github_repo_layout(
+            "https://github.com/fabro-sh/fabro",
+            "/work space",
+            "/repo root",
+        )
+        .unwrap();
+
+        assert_eq!(
+            repo_symlink_command(&layout),
+            "ln -s '/repo root/fabro-sh/fabro' '/work space/fabro'"
+        );
+    }
+
     #[test]
     fn record_origin_strips_credentials() {
         assert_eq!(
diff --git a/lib/components/fabro-sandbox/src/daytona/mod.rs b/lib/components/fabro-sandbox/src/daytona/mod.rs
index 39798e54a..6390bb1ef 100644
--- a/lib/components/fabro-sandbox/src/daytona/mod.rs
+++ b/lib/components/fabro-sandbox/src/daytona/mod.rs
@@ -15,7 +15,7 @@ use daytona_sdk::toolbox_types::Command as SessionCommandResult;
 use daytona_sdk::{DaytonaError, SessionCommandLogsResult};
 use fabro_github::GitHubCredentials;
 use fabro_static::EnvVars;
-use fabro_types::{CommandOutputStream, CommandTermination, RunId};
+use fabro_types::{CommandOutputStream, CommandTermination, RunId, SandboxProviderKind};
 use fabro_util::time::elapsed_ms;
 use rand::Rng;
 use tokio::runtime::Handle;
@@ -1049,6 +1049,10 @@ impl Sandbox for DaytonaSandbox {
                 let layout =
                     clone_source::github_repo_layout(&origin_url, WORKING_DIRECTORY, REPOS_ROOT)
                         .map_err(|err| self.fail_init(init_start, err))?;
+                let token_was_freshly_minted = self
+                    .github_app
+                    .as_ref()
+                    .is_some_and(GitHubCredentials::mints_installation_token);
                 self.emit(SandboxEvent::GitCloneStarted {
                     url:    origin_url.clone(),
                     branch: branch.clone(),
@@ -1056,40 +1060,26 @@ impl Sandbox for DaytonaSandbox {
                 let clone_start = Instant::now();
 
                 let (username, password) = match &self.github_app {
-                    Some(creds) => {
-                        let (owner, repo) = fabro_github::parse_github_owner_repo(&origin_url)
-                            .map_err(|e| {
-                                let err = crate::Error::message(format!(
-                                    "Failed to parse GitHub URL for clone: {e}"
-                                ));
-                                self.emit(SandboxEvent::GitCloneFailed {
-                                    url:    origin_url.clone(),
-                                    error:  err.to_string(),
-                                    causes: err.causes(),
-                                });
-                                self.fail_init(init_start, err)
-                            })?;
-                        fabro_github::resolve_clone_credentials(
-                            &fabro_github::GitHubContext::new(
-                                creds,
-                                &fabro_github::github_api_base_url(),
-                            ),
-                            &owner,
-                            &repo,
-                        )
-                        .await
-                        .map_err(|e| {
-                            let err = crate::Error::message(format!(
-                                "Failed to get GitHub App credentials for clone: {e}"
-                            ));
-                            self.emit(SandboxEvent::GitCloneFailed {
-                                url:    origin_url.clone(),
-                                error:  err.to_string(),
-                                causes: err.causes(),
-                            });
-                            self.fail_init(init_start, err)
-                        })?
-                    }
+                    Some(creds) => fabro_github::resolve_clone_credentials(
+                        &fabro_github::GitHubContext::new(
+                            creds,
+                            &fabro_github::github_api_base_url(),
+                        ),
+                        &layout.owner,
+                        &layout.repo,
+                    )
+                    .await
+                    .map_err(|e| {
+                        let err = crate::Error::message(format!(
+                            "Failed to get GitHub App credentials for clone: {e}"
+                        ));
+                        self.emit(SandboxEvent::GitCloneFailed {
+                            url:    origin_url.clone(),
+                            error:  err.to_string(),
+                            causes: err.causes(),
+                        });
+                        self.fail_init(init_start, err)
+                    })?,
                     None => (None, None),
                 };
 
@@ -1154,13 +1144,11 @@ impl Sandbox for DaytonaSandbox {
                     self.fail_init(init_start, err)
                 })?;
 
-                let clone_token = password.clone();
-                let has_credentials = password.is_some();
                 let clone_result = clone_retry::retry_clone(
-                    "daytona",
-                    |attempt| {
+                    SandboxProviderKind::Daytona,
+                    None,
+                    |_attempt| {
                         let git_svc = &git_svc;
-                        let fs_svc = &fs_svc;
                         let origin = origin_url.as_str();
                         let target = layout.primary_repo_path.as_str();
                         let options = daytona_sdk::GitCloneOptions {
@@ -1169,18 +1157,9 @@ impl Sandbox for DaytonaSandbox {
                             password: password.clone(),
                             ..Default::default()
                         };
-                        async move {
-                            if attempt > 1 {
-                                // git removes the directory it created when it
-                                // exits on its own, but a clone killed part-way
-                                // leaves a partial checkout that the next
-                                // `git clone` would refuse to write into.
-                                let _ = fs_svc.delete_file(target, true).await;
-                            }
-                            git_svc.clone(origin, target, options).await
-                        }
+                        async move { git_svc.clone(origin, target, options).await }
                     },
-                    |err: &DaytonaError| classify_clone_failure(err, has_credentials),
+                    |err: &DaytonaError| classify_clone_failure(err, token_was_freshly_minted),
                 )
                 .await;
 
@@ -1196,7 +1175,7 @@ impl Sandbox for DaytonaSandbox {
                             });
                             self.fail_init(init_start, err)
                         })?;
-                        let symlink_cmd = daytona_symlink_command(&layout);
+                        let symlink_cmd = clone_source::repo_symlink_command(&layout);
                         let symlink_result = process_svc
                             .execute_command(
                                 &wrap_bash_command(&symlink_cmd),
@@ -1248,8 +1227,8 @@ impl Sandbox for DaytonaSandbox {
                         let _ = self.origin_url.set(origin_url.clone());
                         self.set_working_directory(layout.execution_directory.clone())
                             .map_err(|err| self.fail_init(init_start, err))?;
-                        if let Some(token) = clone_token {
-                            match fabro_github::embed_token_in_url(&origin_url, &token) {
+                        if let Some(token) = password.as_deref() {
+                            match fabro_github::embed_token_in_url(&origin_url, token) {
                                 Ok(auth_url) => {
                                     let cmd = format!(
                                         "git -c maintenance.auto=0 remote set-url origin {}",
@@ -1532,7 +1511,7 @@ impl Sandbox for DaytonaSandbox {
         // Only a GitHub App installation token can be re-minted; a static PAT or
         // a pre-minted Installation token is fixed, so re-embedding it changes
         // nothing. Short-circuit to Skipped before the resolve + set-url exec.
-        if !matches!(creds, GitHubCredentials::App(_)) {
+        if !creds.mints_installation_token() {
             return Ok(RefreshOutcome::Skipped);
         }
 
@@ -2492,24 +2471,30 @@ fn daytona_bash_session_probe_outcome(execution: crate::Result<ExecResult>) -> c
 /// inside the sandbox, so its stderr comes back through the toolbox as the
 /// error message — the credential race has to be matched on text. Daytona's own
 /// transport failures are visible structurally.
-fn classify_clone_failure(err: &DaytonaError, has_credentials: bool) -> Option<CloneRetryReason> {
-    let transient_transport = match err {
-        DaytonaError::Timeout { .. } | DaytonaError::RateLimit { .. } => true,
-        DaytonaError::Api { status_code, .. } => (500..600).contains(status_code),
-        DaytonaError::NotFound { .. } | DaytonaError::General(_) => false,
-    };
-    if transient_transport {
-        return Some(CloneRetryReason::TransientInfra);
+fn classify_clone_failure(
+    err: &DaytonaError,
+    token_was_freshly_minted: bool,
+) -> Option<CloneRetryReason> {
+    // A Daytona request timeout does not prove that the remote clone stopped.
+    // Retrying could overlap the still-running first request.
+    if matches!(err, DaytonaError::Timeout { .. }) {
+        return None;
     }
-    clone_retry::classify_message(err.message(), has_credentials)
-}
 
-fn daytona_symlink_command(layout: &clone_source::GitHubRepoLayout) -> String {
-    format!(
-        "ln -s {} {}",
-        shell_quote(&layout.primary_repo_path),
-        shell_quote(&layout.primary_repo_link),
-    )
+    match clone_retry::classify_message(err.message(), token_was_freshly_minted) {
+        clone_retry::CloneMessageClass::Retry(reason) => Some(reason),
+        clone_retry::CloneMessageClass::Permanent => None,
+        clone_retry::CloneMessageClass::Unknown => match err {
+            DaytonaError::RateLimit { .. } => Some(CloneRetryReason::TransientInfra),
+            DaytonaError::Api { status_code, .. } if (500..600).contains(status_code) => {
+                Some(CloneRetryReason::TransientInfra)
+            }
+            DaytonaError::Timeout { .. }
+            | DaytonaError::Api { .. }
+            | DaytonaError::NotFound { .. }
+            | DaytonaError::General(_) => None,
+        },
+    }
 }
 
 /// Wrap Bash source in the canonical non-login Bash transport.
@@ -2879,21 +2864,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn daytona_symlink_command_links_workspace_repo_to_repos_checkout() {
-        let layout = clone_source::github_repo_layout(
-            "https://github.com/fabro-sh/fabro",
-            WORKING_DIRECTORY,
-            REPOS_ROOT,
-        )
-        .unwrap();
-
-        assert_eq!(
-            daytona_symlink_command(&layout),
-            "ln -s /home/daytona/repos/fabro-sh/fabro /home/daytona/workspace/fabro"
-        );
-    }
-
     #[test]
     fn clone_not_found_after_a_successful_mint_is_retried() {
         // The exact error from run 01KYM99DF27JRRW4XSYZBP27K7: git's stderr,
@@ -2914,7 +2884,6 @@ mod tests {
     #[test]
     fn clone_transient_transport_failures_are_retried() {
         for err in [
-            DaytonaError::timeout("request timed out"),
             DaytonaError::rate_limit("too many requests"),
             DaytonaError::api(503, ""),
         ] {
@@ -2926,6 +2895,34 @@ mod tests {
         }
     }
 
+    #[test]
+    fn clone_timeout_is_not_retried_without_remote_termination() {
+        let err = DaytonaError::timeout("request timed out");
+
+        assert_eq!(classify_clone_failure(&err, true), None);
+    }
+
+    #[test]
+    fn clone_api_failure_message_takes_precedence_over_status() {
+        let not_found = DaytonaError::api(500, "repository not found: Repository not found.");
+        assert_eq!(
+            classify_clone_failure(&not_found, true),
+            Some(CloneRetryReason::TokenReplication)
+        );
+        assert_eq!(classify_clone_failure(&not_found, false), None);
+
+        for message in [
+            "fatal: destination path 'fabro' already exists",
+            "remote: Permission to fabro-sh/fabro.git denied",
+        ] {
+            assert_eq!(
+                classify_clone_failure(&DaytonaError::api(500, message), true),
+                None,
+                "expected {message:?} to take precedence over HTTP 500"
+            );
+        }
+    }
+
     #[test]
     fn clone_client_errors_are_not_retried() {
         for err in [
diff --git a/lib/components/fabro-sandbox/src/docker.rs b/lib/components/fabro-sandbox/src/docker.rs
index c9fd3ce4c..ecb4431ac 100644
--- a/lib/components/fabro-sandbox/src/docker.rs
+++ b/lib/components/fabro-sandbox/src/docker.rs
@@ -3,7 +3,7 @@ use std::fmt::Write as _;
 use std::io::Cursor;
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
-use std::time::{Instant, SystemTime, UNIX_EPOCH};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use async_trait::async_trait;
 use bollard::Docker;
@@ -17,7 +17,7 @@ use bollard::exec::{CreateExecOptions, StartExecOptions, StartExecResults};
 use bollard::image::CreateImageOptions;
 use bollard::models::HostConfig;
 use fabro_github::GitHubCredentials;
-use fabro_types::{CommandOutputStream, CommandTermination, RunId};
+use fabro_types::{CommandOutputStream, CommandTermination, RunId, SandboxProviderKind};
 use fabro_util::time::elapsed_ms;
 use futures::StreamExt;
 use tokio::io::{AsyncWriteExt, duplex};
@@ -46,6 +46,7 @@ const DOCKER_BASH_REQUIREMENT: &str = "Docker sandboxes require /bin/bash for ev
 pub(crate) const WORKING_DIRECTORY: &str = "/workspace";
 pub(crate) const REPOS_ROOT: &str = "/repos";
 const GIT_CLONE_DEPTH: usize = 10;
+const GIT_CLONE_TIMEOUT: Duration = Duration::from_mins(5);
 #[cfg(test)]
 const EXEC_STOP_POLL_SLEEP_SECONDS: &str = "0.005";
 #[cfg(not(test))]
@@ -55,6 +56,11 @@ const EXEC_TERM_GRACE_SECONDS: &str = "0.02";
 #[cfg(not(test))]
 const EXEC_TERM_GRACE_SECONDS: &str = "0.2";
 
+struct DockerCloneFailure {
+    error:        crate::Error,
+    retry_reason: Option<clone_retry::CloneRetryReason>,
+}
+
 fn env_entry_name(entry: &str) -> &str {
     entry.split_once('=').map_or(entry, |(name, _)| name)
 }
@@ -656,40 +662,30 @@ impl DockerSandbox {
         Ok(())
     }
 
-    /// Render a failed `git clone` exit into an error, with the auth URL
-    /// masked.
+    /// Preserve a failed `git clone` result while masking the auth URL.
     fn clone_failure_error(
         &self,
-        stderr: &str,
+        result: ExecResult,
         auth_url: Option<&fabro_redact::DisplaySafeUrl>,
     ) -> crate::Error {
-        let stderr = redact_auth_url(stderr, auth_url);
-        crate::Error::message(if self.github_app.is_none() {
-            format!(
-                "Git clone failed: {stderr}. If this is a private repository, configure a GitHub App with `fabro install` and install it for your organization."
-            )
+        let error = result
+            .into_exec_error_with_redactor("git clone", |output| redact_auth_url(output, auth_url));
+        let message = if self.github_app.is_none() {
+            "Git clone failed. If this is a private repository, configure a GitHub App with \
+             `fabro install` and install it for your organization."
         } else {
-            format!("Failed to clone repo into Docker sandbox: {stderr}")
-        })
+            "Failed to clone repository into Docker sandbox"
+        };
+        crate::Error::context(message, error)
     }
 
-    /// Clear a checkout left behind by a failed clone, before cloning again.
-    ///
-    /// git removes the directory it created when it exits on its own, but a
-    /// clone killed by the exec timeout leaves a partial checkout that the next
-    /// `git clone` would refuse to write into. Best-effort: if the removal
-    /// fails, the retry surfaces the real error.
-    async fn clear_partial_clone(&self, repo_path: &str) {
-        let command = format!("rm -rf {}", shell_quote(repo_path));
-        if let Err(err) = self
-            .docker_exec_shell(&command, 30_000, Some("/"), None, None)
-            .await
-        {
-            tracing::debug!(
-                error = %crate::display_for_log(&err),
-                "Failed to clear partial clone before retry"
-            );
-        }
+    fn report_clone_failure(&self, origin_url: &str, err: crate::Error) -> crate::Error {
+        self.emit(SandboxEvent::GitCloneFailed {
+            url:    origin_url.to_string(),
+            error:  err.to_string(),
+            causes: err.causes(),
+        });
+        err
     }
 
     async fn clone_github_repo(
@@ -699,12 +695,10 @@ impl DockerSandbox {
     ) -> crate::Result<()> {
         self.verify_git_available().await?;
         let layout = clone_source::github_repo_layout(&origin_url, WORKING_DIRECTORY, REPOS_ROOT)?;
-
-        self.emit(SandboxEvent::GitCloneStarted {
-            url:    origin_url.clone(),
-            branch: branch.clone(),
-        });
-        let clone_start = Instant::now();
+        let token_was_freshly_minted = self
+            .github_app
+            .as_ref()
+            .is_some_and(GitHubCredentials::mints_installation_token);
 
         let auth_url = match &self.github_app {
             Some(creds) => Some(
@@ -725,41 +719,101 @@ impl DockerSandbox {
             .as_ref()
             .map_or(origin_url.as_str(), |url| url.as_raw_url().as_str());
 
-        let command = git_clone_and_link_command(clone_url, branch.as_deref(), &layout);
-        let has_credentials = auth_url.is_some();
+        self.emit(SandboxEvent::GitCloneStarted {
+            url:    origin_url.clone(),
+            branch: branch.clone(),
+        });
+        let clone_start = Instant::now();
 
+        let prepare_command = format!(
+            "mkdir -p {} {}",
+            shell_quote(WORKING_DIRECTORY),
+            shell_quote(&layout.repos_owner_path),
+        );
+        match self
+            .docker_exec_shell(&prepare_command, 10_000, Some("/"), None, None)
+            .await
+        {
+            Ok(result) if result.is_success() => {}
+            Ok(result) => {
+                let err = result.into_exec_error("prepare Docker repository checkout");
+                return Err(self.report_clone_failure(&origin_url, err));
+            }
+            Err(err) => {
+                return Err(self.report_clone_failure(&origin_url, err));
+            }
+        }
+
+        let command = git_clone_command(clone_url, branch.as_deref(), &layout.primary_repo_path);
+        let clone_deadline = time::Instant::now() + GIT_CLONE_TIMEOUT;
         let clone_result = clone_retry::retry_clone(
-            "docker",
-            |attempt| {
+            SandboxProviderKind::Docker,
+            Some(clone_deadline),
+            |_attempt| {
                 let command = command.as_str();
                 let auth_url = auth_url.as_ref();
-                let repo_path = layout.primary_repo_path.as_str();
                 async move {
-                    if attempt > 1 {
-                        self.clear_partial_clone(repo_path).await;
+                    let remaining = clone_deadline.saturating_duration_since(time::Instant::now());
+                    let timeout_ms = u64::try_from(remaining.as_millis()).unwrap_or(u64::MAX);
+                    if timeout_ms == 0 {
+                        return Err(DockerCloneFailure {
+                            error:        crate::Error::message(
+                                "Docker git clone deadline expired before retry",
+                            ),
+                            retry_reason: None,
+                        });
                     }
                     let result = self
-                        .docker_exec_shell(command, 300_000, Some("/"), None, None)
-                        .await?;
+                        .docker_exec_shell_streaming(
+                            command,
+                            Some(timeout_ms),
+                            Some("/"),
+                            None,
+                            None,
+                            None,
+                        )
+                        .await
+                        .map_err(|error| DockerCloneFailure {
+                            error:        crate::Error::context(
+                                "Docker git clone transport failed",
+                                error,
+                            ),
+                            retry_reason: None,
+                        })?
+                        .result;
                     if result.is_success() {
                         return Ok(());
                     }
-                    Err(self.clone_failure_error(&result.stderr, auth_url))
+                    let retry_reason =
+                        classify_docker_clone_result(&result, token_was_freshly_minted);
+                    Err(DockerCloneFailure {
+                        error: self.clone_failure_error(result, auth_url),
+                        retry_reason,
+                    })
                 }
             },
-            |err: &crate::Error| {
-                clone_retry::classify_message(&err.display_with_causes(), has_credentials)
-            },
+            |failure: &DockerCloneFailure| failure.retry_reason,
         )
         .await;
 
-        if let Err(err) = clone_result {
-            self.emit(SandboxEvent::GitCloneFailed {
-                url:    origin_url,
-                error:  err.to_string(),
-                causes: err.causes(),
-            });
-            return Err(err);
+        if let Err(failure) = clone_result {
+            let err = failure.error;
+            return Err(self.report_clone_failure(&origin_url, err));
+        }
+
+        let symlink_command = clone_source::repo_symlink_command(&layout);
+        match self
+            .docker_exec_shell(&symlink_command, 10_000, Some("/"), None, None)
+            .await
+        {
+            Ok(result) if result.is_success() => {}
+            Ok(result) => {
+                let err = result.into_exec_error("create Docker workspace repo symlink");
+                return Err(self.report_clone_failure(&origin_url, err));
+            }
+            Err(err) => {
+                return Err(self.report_clone_failure(&origin_url, err));
+            }
         }
 
         let _ = self.repo_cloned.set(true);
@@ -1215,19 +1269,17 @@ fn git_clone_command(clone_url: &str, branch: Option<&str>, checkout_path: &str)
     command
 }
 
-fn git_clone_and_link_command(
-    clone_url: &str,
-    branch: Option<&str>,
-    layout: &clone_source::GitHubRepoLayout,
-) -> String {
-    format!(
-        "mkdir -p {} {} && {} && ln -s {} {}",
-        shell_quote(WORKING_DIRECTORY),
-        shell_quote(&layout.repos_owner_path),
-        git_clone_command(clone_url, branch, &layout.primary_repo_path),
-        shell_quote(&layout.primary_repo_path),
-        shell_quote(&layout.primary_repo_link),
-    )
+fn classify_docker_clone_result(
+    result: &ExecResult,
+    token_was_freshly_minted: bool,
+) -> Option<clone_retry::CloneRetryReason> {
+    let stderr = clone_retry::classify_message(&result.stderr, token_was_freshly_minted);
+    match stderr {
+        clone_retry::CloneMessageClass::Unknown => {
+            clone_retry::classify_message(&result.stdout, token_was_freshly_minted).retry_reason()
+        }
+        class => class.retry_reason(),
+    }
 }
 
 fn host_config(config: &DockerSandboxOptions) -> HostConfig {
@@ -2031,7 +2083,7 @@ impl Sandbox for DockerSandbox {
         // Only a GitHub App installation token can be re-minted; a static PAT or
         // a pre-minted Installation token is fixed, so re-embedding it changes
         // nothing. Short-circuit to Skipped before the resolve + set-url exec.
-        if !matches!(creds, GitHubCredentials::App(_)) {
+        if !creds.mints_installation_token() {
             return Ok(RefreshOutcome::Skipped);
         }
 
@@ -2208,20 +2260,16 @@ mod tests {
     }
 
     #[test]
-    fn clone_and_link_command_creates_workspace_symlink_to_repos_checkout() {
-        let layout = clone_source::github_repo_layout(
-            "https://github.com/fabro-sh/fabro",
-            "/workspace",
-            "/repos",
-        )
-        .unwrap();
-        let command =
-            git_clone_and_link_command("https://github.com/fabro-sh/fabro", Some("main"), &layout);
+    fn clone_result_uses_stderr_before_stdout() {
+        let result = ExecResult {
+            stdout:      "Could not resolve host: github.com".to_string(),
+            stderr:      "fatal: destination path 'fabro' already exists".to_string(),
+            exit_code:   Some(128),
+            termination: CommandTermination::Exited,
+            duration_ms: 1,
+        };
 
-        assert_eq!(
-            command,
-            "mkdir -p /workspace /repos/fabro-sh && git -c maintenance.auto=0 -c gc.auto=0 clone --branch main --single-branch --depth 10 --no-tags -- https://github.com/fabro-sh/fabro /repos/fabro-sh/fabro && ln -s /repos/fabro-sh/fabro /workspace/fabro"
-        );
+        assert_eq!(classify_docker_clone_result(&result, true), None);
     }
 
     #[test]
diff --git a/lib/components/fabro-sandbox/src/error.rs b/lib/components/fabro-sandbox/src/error.rs
index d872f9ac3..8d6bf0d73 100644
--- a/lib/components/fabro-sandbox/src/error.rs
+++ b/lib/components/fabro-sandbox/src/error.rs
@@ -143,11 +143,7 @@ pub(crate) fn classify_exec_failure(stderr: &str) -> Option<&'static str> {
     } else if lower.contains("could not resolve host") || lower.contains("network is unreachable") {
         Some("network failure inside sandbox - check DNS / egress from the run container")
     } else if lower.contains("repository not found") {
-        Some(
-            "github 404 - the repo does not exist, the App installation does not \
-             include it, or a freshly minted installation token has not replicated \
-             to GitHub's edge cache yet (github answers unauthorized reads with 404)",
-        )
+        Some("github 404 - repository is unavailable to the current credentials")
     } else if lower.contains("no such remote") && lower.contains("origin") {
         Some("origin remote missing - push credentials could not be installed")
     } else if lower.contains("not a git repository")