Orchestrator movement along the assembly line

[williamthorsen]

Parent: #22
Depends on: #23

Description

The orchestrator agent currently snaps to its target position when the run status changes (via the diff system detecting stationIndex/level changes). This ticket adds animated walk transitions so the orchestrator walks left-to-right along level 0 between stations as the run progresses and transitions between levels at the review area via ladders (vertical teleport).

This builds on the 2D layout MVP (#23), which is already merged.

Current behavior

• run-to-scene.ts mapper computes the orchestrator's target position from CanonicalRunStatus (rightmost active phase, always level: 0)
• agent-differ.ts detects when stationIndex, stackOffset, or level changes → categorizes as "moved"
• FactoryScene.updateAgents() calls actor.walkTo(newPos) for moved agents — straight-line movement
• AgentActor.walkTo() uses Excalibur's moveTo() at WALK_SPEED = 100; if called while already walking, silently returns (no queue, no cancel)
• Orchestrator animation state is always 'working' during in-progress runs

Design decisions

1. Orchestrator level during review: Goes to the highest reviewer level (reviewerCount - 1) to "oversee from top." Deterministic from reviewer count.

2. Concurrent walks: Cancel-and-restart — cancel current walk via Excalibur's clearActions(), start new walk from the actor's current position toward the new target. Avoids stale intermediate destinations from rapid status updates.

3. Architecture: Add walkPath(waypoints) to AgentActor with a generation counter for safe async cancellation. Path computation as a pure function in the layout module (computeWalkPath), using ladder geometry from LayoutResult.

4. Orchestrator animation: Change from 'working' to 'idle' — the orchestrator oversees, it doesn't do work. Walking animation is handled internally by walkPath. Will be replaced by 'resting' in Phase 4.

Acceptance criteria

Must have

• Orchestrator walks from station to station along level 0 when the active phase changes
• Walking animation plays during horizontal movement
• Orchestrator transitions between levels at the review area (vertical teleport is acceptable)
• Movement is status-driven: triggered by CanonicalRunStatus changes, not scripted
• If the page loads mid-run, orchestrator snaps to the correct position (no animation replay)
• Concurrent walk requests are handled gracefully (cancel-and-restart)

Should have

• Orchestrator pauses briefly at a station before walking to the next
• Walking to upper-floor reviewers follows a logical path: horizontal to ladder, vertical, horizontal to station

Nice to have

• Smooth deceleration when arriving at a station

Files

File	Action
packages/factory/src/client/game/mappers/run-to-scene.ts	Modify
packages/factory/src/client/game/layout/walk-path.ts	Create
packages/factory/src/client/game/actors/AgentActor.ts	Modify
packages/factory/src/client/game/scenes/FactoryScene.ts	Modify
packages/factory/src/client/game/state/agent-state-resolver.ts	Modify
+ corresponding __tests__/ files for each	Modify/Create

[williamthorsen]

Implementation plan

Step 1: Orchestrator level during review phase

File: packages/factory/src/client/game/mappers/run-to-scene.ts

In buildOrchestratorAgent, when the orchestrator is at the review station and there are multiple parallel reviewers, set level to the highest reviewer level instead of always 0.

Changes:

• Compute orchestratorLevel: if station === REVIEW_STATION_INDEX and parallelReview has reviewerCount > 1, set to reviewerCount - 1; otherwise 0
• Update the existingAtStation filter to match on orchestratorLevel instead of hardcoded 0
• Define local constant REVIEW_STATION_INDEX = 3 (avoids cross-module dependency from mappers to layout)

Tests: packages/factory/src/client/game/mappers/__tests__/run-to-scene.test.ts

• Add: orchestrator at review with 2 reviewers → level: 1
• Add: orchestrator at review with 3 reviewers → level: 2
• Add: orchestrator at review with 1 reviewer → level: 0
• Add: orchestrator at non-review station → level: 0
• Update existing test for stackOffset computation at review station with multiple reviewers

---

Step 2: Path computation function

New file: packages/factory/src/client/game/layout/walk-path.ts

Pure function that computes walk waypoints between two positions using ladder geometry from LayoutResult.

export interface Waypoint {
  x: number;
  y: number;
  teleport: boolean;  // true = snap position, false = walk animation
}

export function computeWalkPath(
  source: { x: number; y: number },
  destination: { x: number; y: number },
  layout: LayoutResult,
): Waypoint[]

Logic:

• Same Y (same level): single waypoint { ...destination, teleport: false }
• Different Y (level change): up to 3 waypoints:
  1. Walk horizontally to layout.ladders[0].x (skip if source already there)
  2. Teleport vertically to destination Y
  3. Walk horizontally to destination X (skip if ladder X equals destination X)
• All ladders share the same X coordinate, so ladders[0].x is the transition point

Reuses: LayoutResult from platform-layout.ts — already exposes ladders: LadderSegment[] with { x, bottomY, topY }

New test file: packages/factory/src/client/game/layout/__tests__/walk-path.test.ts

• Same-level: single waypoint
• Ascending (level 0 → 1): 3 waypoints
• Descending (level 1 → 0): 3 waypoints
• Source at ladder X: 2 waypoints (skip first horizontal)
• Destination at ladder X: 2 waypoints (skip last horizontal)
• No ladders in layout: fallback single waypoint

---

Step 3: AgentActor walkPath with cancel-and-restart

File: packages/factory/src/client/game/actors/AgentActor.ts

Add walkPath(waypoints: ReadonlyArray<Waypoint>): Promise<void> method with:

• Cancel-and-restart: if isWalking, call this.actions.clearActions() first
• Generation counter (walkGeneration): incremented on each walkPath call; after each await, check generation !== this.walkGeneration to detect cancellation
• Teleport waypoints: snap this.pos directly (no moveTo)
• Zero-distance skip: skip waypoints where actor is already at that position
• Animation: walking animation during horizontal segments; pending state restored after full path

Deprecate walkTo() as a wrapper around walkPath (single non-teleport waypoint) for backward compatibility.

Import Waypoint type from ../layout/walk-path.js.

Tests: packages/factory/src/client/game/actors/__tests__/AgentActor.test.ts

• Multi-waypoint walk: moveTo called for each non-teleport waypoint sequentially
• Teleport waypoint: position snaps without moveTo
• Cancel-and-restart: second walkPath calls clearActions(), starts new walk
• Cancelled walk does not restore animation state
• Zero-distance waypoint skipped
• Rewrite existing "returns immediately when called while already walking" test to test cancel-and-restart instead

---

Step 4: FactoryScene uses walkPath for moved agents

File: packages/factory/src/client/game/scenes/FactoryScene.ts

In updateAgents, replace:

actor.walkTo(vec(pos.x, pos.y))

with:

const source = { x: actor.pos.x, y: actor.pos.y };
const waypoints = computeWalkPath(source, destination, this.layout);
actor.walkPath(waypoints)

Import computeWalkPath from ../layout/walk-path.js.

Tests: packages/factory/src/client/game/scenes/__tests__/FactoryScene.test.ts

• Update existing "triggers walkTo when an agent changes position" to assert walkPath instead
• Add: agent level change triggers multi-segment walkPath

---

Step 5: Orchestrator animation state → idle

File: packages/factory/src/client/game/state/agent-state-resolver.ts

Change orchestrator state from buildStateInfo(agent, 'working') to buildStateInfo(agent, 'idle').

The orchestrator oversees — it doesn't do work. idle shows it standing at the station observing. Walking animation is handled internally by walkPath.

Tests: packages/factory/src/client/game/state/__tests__/agent-state-resolver.test.ts

• Update expected orchestrator state from 'working' to 'idle'

---

Implementation order

Step 1 (mapper) ─┐
                  ├─ Step 3 (AgentActor) ─── Step 4 (FactoryScene)
Step 2 (walk-path)┘
Step 5 (animation state) ── independent, any time

Steps 1 and 2 are independent and can be done first. Step 3 depends on Step 2 types. Step 4 depends on Steps 2+3.

Verification

1. pnpm run ws typecheck — type-check passes
2. pnpm run ws test — all tests pass (existing + new)
3. pnpm run check — full quality gates pass
4. Manual: start dev server (pnpm run dev), select a run with parallel reviewers, verify:
   • Orchestrator walks horizontally between stations as phases change
   • At review station, orchestrator walks to ladder, teleports up, walks to position
   • When review completes, orchestrator descends and walks to next station
   • Rapid status changes: orchestrator cancels current walk and redirects
   • Page reload mid-run: orchestrator snaps to correct position