# FactoryRun Page UI

**Status:** **Approved target-state behavior; U2 active + U3 recovery owner-approved/final**  
**First realization:** I1; rich observability I4.

## Page Job

Answer:

```text
What is this FactoryRun doing now?
Which Task/Agent is active?
What already happened?
What is waiting/failed and why?
Is work safely checkpointed?
What can I do next?
```

## Header / Context

Breadcrumb Project / Plan / FactoryRun. Show status/reason, elapsed time, selected graph scope, provider, current task(s), counts and primary action appropriate to state: Cancel, Retry/Resolve, View Review/ChangeSet, etc.

The owner-approved U2 active frame freezes the I1 header as:

```text
Plan title + FactoryRun ID
Running / elapsed / Plan / Goal / Scope
View Plan / overflow / separated destructive Cancel Run
```

Approved FactoryRun tabs:

```text
Overview | Tasks | AgentRuns | Timeline | ChangeSet
```

## I1 Operational Layout

The final U2/U3 composition is:

```text
TOP
  Task Progress & Topology
  Active AgentRuns / Recovery & Attempts

BOTTOM
  Latest Activity
  WIP / Checkpoint Safety
  ChangeSet / Review
  Current / Next / Attention
```

### Task Progress & Topology

Accessible task table/list shows:

```text
Task
State
Depends on
AgentRun
Started
Duration
```

It must preserve actual concurrency and dependency state rather than flattening work into a fake sequential progress bar. The approved U2 fixture shows one completed Task, two concurrently running Tasks, one dependency-blocked Task and one queued downstream Task.

### Active AgentRuns

Each active AgentRun card shows the human-readable Task first, then:

```text
AgentRun ID / Running
Attempt
Model
Account
Workspace
Started / elapsed
Last activity
Checkpoint state
```

Multiple active AgentRuns are visible simultaneously.

### Latest Activity

Use meaningful state-changing events such as Workspace creation, Task completion, Attempt start, source checkpoint, test completion and latest progress. Raw tool logs remain secondary evidence.

### WIP / Checkpoint Safety

WIP safety is first-class and must state explicitly:

```text
WIP is safely persisted
latest checkpoint
checkpoint age
cleanup eligibility
compute may be disposable; accepted WIP is durable
```

The healthy active state reassures the owner that they can leave the run and recovery can continue from the last checkpoint after interruption.

### ChangeSet / Review

During active execution, the ChangeSet panel shows the future handoff truthfully:

```text
ChangeSet (pending)
Will be created when all Tasks complete
```

Do not expose an active `View ChangeSet` action before a real ChangeSet exists.

### Current / Next / Attention

A compact operational summary answers:

```text
CURRENT   currently running Task / AgentRun
NEXT      next Task, including why it is blocked/queued
ATTENTION whether human action is required
```

It does not duplicate the full Task topology.

Failure state prioritizes reason, preserved-work status and safe next action over logs.

## I4 Rich Observability Target

Add graph visualization, live agent messages, structured tool activity, diffs/files, checkpoints, retries/attempts, artifacts and token/cost data. Do not replace I1 identity/state architecture; these are richer projections.

Suggested desktop at I4:

```text
┌──────────── graph / task progress ───────────────┐
├─────────────────────────┬────────────────────────┤
│ active agent/chat/tools │ context/files/diff     │
├─────────────────────────┴────────────────────────┤
│ timeline / attempts / checkpoints / artifacts    │
└──────────────────────────────────────────────────┘
```

## Task / Agent Relationships

Each graph/list node shows Task status + assigned AgentRun(s). Clicking Agent opens Agent page; Task opens Plan context; ChangeSet/Review clickable. Multi-agent concurrency is visible simultaneously.

## Waiting / Failure / Retry

Explicit reason categories: dependency, human approval, connection, provider/model/account capacity, workspace/infrastructure, review changes, verification failure, cancellation. Show whether WIP is safely checkpointed and whether retry creates a new Attempt.

The owner-approved U3 preserves the approved U2 FactoryRun page identity/composition and transforms it into a waiting/failure/recovery state. It does not redesign the page merely because the state changed.

U3 answers before raw logs:

```text
what failed
why
what AWP already did
whether WIP is safe
latest safe checkpoint
what happens next
whether user action is required
```

Retry creates a new immutable Attempt where required; the failed Attempt remains historical provenance.

## States

- queued/starting;
- active;
- waiting/blocked;
- failure/retryable/resolving;
- cancelling/cancelled;
- completed;
- stale/realtime disconnected while authoritative state remains queryable.

Loading/error states preserve Run identity/context.

## Responsive / Accessibility

Graph is never the only representation; accessible task list is always available. Medium collapses side context. Small prioritizes current task/agent/status with graph/timeline drill-in. Live updates are throttled/announced selectively to avoid accessibility noise.

Checkpoint/WIP safety has textual meaning in addition to status color/iconography.

## URL Truth

Stable FactoryRun route; selected Task/Agent/tab/attempt may be URL state. Back navigation preserves Project/Plan context.

## Increment Realization

I1: U2 active, U3 waiting/failure/retry and completion links. I4: full observability. I5: CI evidence status inside timeline; I8 incident links.

## High-Fidelity Requirements

I1 requires U2 active and U3 failure/waiting states. Both are now owner-approved/final. I4 later extends the same page identity with richer concurrent-agent/content density rather than replacing U2/U3 lifecycle semantics.

## Target State

FactoryRun is the observable orchestration-instance page over AWP-owned run semantics and Fabro/provider mechanics. It reconstructs progress, concurrency, attempts, waiting/recovery and produced work while keeping Task/Plan relationships intact.

## Primary Users / Jobs

- owner/operator: confirm the factory is progressing and determine whether intervention is required;
- engineering lead: inspect concurrent Task/Agent execution, retries and work safety;
- developer/reviewer: follow an AgentRun/ChangeSet/Review from its execution context.

## Entry / Exit Points

Entry: Plan/Task execution link, Home/Execution collection, Agent/Review breadcrumb, Attention item, search. Exit: Task/Plan, Agent detail, ChangeSet/Review, evidence/CI, Incident, or provider-native debugging link when needed.

## User Journeys

### J1 — Observe active work

```text
open FactoryRun
 -> orient on current scope/status
 -> scan topology/list for concurrent active/waiting Tasks
 -> inspect active AgentRun + latest progress
 -> verify WIP/checkpoint safety
 -> open Agent or Task detail
 -> return with selected node/context preserved
```

### J2 — Understand a wait

```text
WAITING/BLOCKED
 -> read waiting-for + since + why + owner + latest progress
 -> inspect dependency/Approval/Connection/capacity source
 -> no action if autonomous recovery is active
 -> act only when attention policy requires it
 -> Run auto-continues when blocker clears
```

### J3 — Recover from failure without losing work

```text
failure
 -> classify reason
 -> show checkpoint/WIP safety first
 -> show attempts already made
 -> Retry/Resolve or open Incident according to policy
 -> new Attempt where required
 -> verify recovered progress
```

### J4 — Follow produced change

```text
Task/Agent completes
 -> ChangeSet collected
 -> FactoryRun shows exact candidate link
 -> Review starts
 -> open Review/ChangeSet
 -> FactoryRun remains historical orchestration context
```

## Data / Source of Truth

FactoryRun/Task orchestration state and lifecycle events are AWP domain truth. Fabro workflow/run/node IDs are provider mappings. AgentRun/Attempt/Workspace and WIP/checkpoint identities come from their domains. Realtime/tool logs/telemetry are projections/evidence and never override persisted run state.

## Actions / Authorization

Cancel, retry, steer/resolver escalation and protected correction actions are capability/policy checked. A normal coding agent does not gain Factory control authority simply because its activity is displayed here. Provider-native debug links are read/debug escape hatches, not alternate lifecycle control.

## Async / Duplicate-Mutation Safety

Cancel/retry/resolve acknowledges immediately, records durable command/Attempt identity, prevents duplicate submit and survives navigation. Retry semantics explicitly state whether a new Attempt/Workspace is created. Stale/disconnected views disable unsafe mutation until authoritative refresh.

## Invariants From Day 1

- task topology and accessible list reflect the same Task/FactoryRun state;
- multi-agent concurrency is visible;
- failure never hides whether WIP is safe;
- retry/attempt history is immutable and attributable;
- provider/Fabro IDs never replace AWP identity;
- waiting always explains itself before raw logs;
- active execution shows current/next/attention without duplicating lifecycle truth;
- U3 preserves U2 page identity while changing state semantics.

## Current Implementation State

Target page behavior and I1 U2/U3 visual authority are final. Production implementation has not yet started.

## Deferred Realization

I4 adds chat/tool/diff/files/cost depth, I5 CI context and I8 Incident links. The underlying FactoryRun/AgentRun/Attempt identity model exists from I1.

## Temporary Dogfood Behavior

I1 may use the approved dense task/agent/timeline layout without the final interactive graph or embedded rich chat. It must expose concurrency, waiting reasons, Attempt provenance and WIP/checkpoint safety.

## Related Contracts / Decisions

- [`../domains/factory.md`](../domains/factory.md)
- [`../domains/agents.md`](../domains/agents.md)
- [`../workflows/factory-execution.md`](../workflows/factory-execution.md)
- [`plan.md`](plan.md), [`agent.md`](agent.md), [`review.md`](review.md), [`incident.md`](incident.md)
- [`../../plans/AWP-U2-FACTORYRUN-HIGH-FIDELITY-BRIEF.md`](../../plans/AWP-U2-FACTORYRUN-HIGH-FIDELITY-BRIEF.md)
- Fabro remains behind `FactoryProvider`; AWP owns lifecycle meaning.

## Visual Mockup Authority

Owner-approved final authorities:

```text
U2  ../../mockups/i1/u2-factory-active.html
U3  ../../mockups/i1/u3-waiting-failure-retry.html
CSS ../../mockups/i1/awp-i1-final.css
JS  ../../mockups/i1/awp-i1-final.js
```

U2 and U3 are **APPROVED / FINAL** as of 2026-08-20. Material page relocation or state-semantic change requires explicit design/spec amendment.

## Acceptance

A user can tell whether a run is making progress, what is running where, whether work is safe, why it waits/fails and what action is allowed without opening Kubernetes/Fabro logs.