Improve subagent position and representation of artifacts

[williamthorsen]

Problem

The Factory visualization currently shows at most one artifact box per phase (architecture, planning, implementation). We can't see who produced which artifacts or how many there are.

Current limitations

• buildArtifacts() creates at most 3 artifacts (one each for architecture, planning, implementation), collapsing multiple planning artifacts into a single box
• artifactPosition() returns a single fixed position per station — no support for multiple artifacts at one station
• Artifact size (15x15) is hardcoded in ArtifactActor
• Phases codeSimplifier and holisticReview are ignored despite having artifact fields in the data model
• Positioning uses magic numbers (+30 x-offset, -60 y-offset) rather than named constants

Proposed solution

Create a visual box for each individual artifact, with configurable constants for size, position, and spacing:

• Position of the agent can be specified relative to the center of the station
• Position of the first artifact can be specified relative to the center of the station and its primary y coordinate
• Size of each artifact is specified in a { height: number, width: number } constant; use the same units as those used for other dimensions in the Factory
• Gap between artifacts is specified in a constant

Multiple artifacts at the same station are arranged horizontally (left-to-right).

The eventual goal (out of scope for this ticket) is to allow the user to view any of the artifacts by clicking on its box.

Key design decisions

Dual-source data strategy: The CanonicalRunStatus has artifact data in two places:

1. Top-level artifacts: ArtifactEntry[] (v2 format) — rich metadata per artifact with filename, agent, phase, etc.
2. Per-phase fields (e.g., architecture.artifact, planning.artifacts[]) — simpler, always present

Use the top-level array when populated (one visual box per entry), falling back to phase fields for v1 compatibility. The fallback now also covers codeSimplifier and holisticReview.

Horizontal layout: Artifacts at the same station are arranged in a horizontal row. With default sizing (12px width + 4px gap = 16px per artifact), 5 artifacts span 80px — well within the 150px station spacing.

Acceptance criteria

• Each individual artifact in the run data produces its own visual box (not one box per phase)
• Artifact box dimensions use a named { width, height } constant (not hardcoded in the actor)
• Gap between artifacts at the same station uses a named constant
• First artifact position relative to station center uses named offset constants
• codeSimplifier and holisticReview artifacts are rendered when present
• All existing tests pass; new tests cover multi-artifact positioning and dual-source logic
• When CanonicalRunStatus.artifacts (top-level array) is populated, it is used as primary data source
• Falls back to phase-specific fields when top-level array is undefined

Files to modify

File	Change
packages/factory/src/client/game/layout/platform-layout.ts	Add layout constants, update artifactPosition signature, expose artifactSize
packages/factory/src/client/game/mappers/run-to-scene.ts	Add indexAtStation to ArtifactConfig, rewrite buildArtifacts() with dual-source logic
packages/factory/src/client/game/actors/ArtifactActor.ts	Accept optional size, add color entries for simplifier/holistic
packages/factory/src/client/game/scenes/FactoryScene.ts	Update rendering to use new artifactPosition signature
packages/factory/src/client/game/layout/__tests__/platform-layout.test.ts	Update and add artifact position tests
packages/factory/src/client/game/actors/__tests__/ArtifactActor.test.ts	Add size and color tests
packages/factory/src/client/game/mappers/__tests__/run-to-scene.test.ts	Add comprehensive multi-artifact tests

[williamthorsen]

Implementation plan

Context

Currently, the Factory visualization shows at most one artifact box per phase (architecture, planning, implementation), even though the data model supports multiple artifacts per phase (e.g., planning.artifacts: string[]). Additionally, artifact box size is hardcoded (15x15), positioning uses magic numbers, and phases like codeSimplifier and holisticReview are ignored despite having artifact fields.

Goal: Create a visual box for each individual artifact, with configurable size, positioning, and spacing constants. Artifacts at the same station are arranged horizontally (left-to-right).

Implementation steps

Step 1: Add artifact layout constants to LayoutConfig

File: packages/factory/src/client/game/layout/platform-layout.ts

Add to LayoutConfig interface:

artifactSize: { width: number; height: number };
artifactGap: number;
artifactOffsetX: number;  // x offset of first artifact from station center
artifactOffsetY: number;  // y offset from baseY

Add to DEFAULT_CONFIG:

artifactSize: { width: 12, height: 12 },
artifactGap: 4,
artifactOffsetX: 20,   // right of station center (matches current +30 intent)
artifactOffsetY: -60,   // above platform (matches current behavior)

Step 2: Update artifactPosition() to support multiple artifacts per station

File: packages/factory/src/client/game/layout/platform-layout.ts

Change signature from artifactPosition(stationIndex) to artifactPosition(stationIndex, indexAtStation).

New implementation:

function artifactPosition(stationIndex: number, indexAtStation: number): { x: number; y: number } {
  const stationX = c.startX + stationIndex * c.stationSpacing;
  return {
    x: stationX + c.artifactOffsetX + indexAtStation * (c.artifactSize.width + c.artifactGap),
    y: c.baseY + c.artifactOffsetY,
  };
}

Expose artifactSize on LayoutResult so FactoryScene can pass it to ArtifactActor:

export interface LayoutResult {
  // ... existing ...
  artifactPosition(stationIndex: number, indexAtStation: number): { x: number; y: number };
  artifactSize: { width: number; height: number };
}

Step 3: Add indexAtStation to ArtifactConfig

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

export interface ArtifactConfig {
  type: string;
  stationIndex: number;
  indexAtStation: number;  // 0-based position within this station's artifacts
}

Step 4: Rewrite buildArtifacts() to produce individual artifacts

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

Dual-source strategy:

• When status.artifacts (top-level ArtifactEntry[]) is populated, use it as primary source — one ArtifactConfig per entry
• Fall back to phase-specific fields otherwise, now extracting ALL phases (including codeSimplifier and holisticReview)

Key additions:

• PHASE_TO_STATION map: maps ArtifactEntry.phase strings to station indices (with aliases for naming variations)
• buildArtifactsFromEntries(): groups top-level entries by station, assigns indexAtStation
• buildArtifactsFromPhases(): iterates all phase fields, creates individual entries for planning.artifacts array items
• Helper to track per-station count for indexAtStation assignment

Change createSceneConfig() to pass full status to buildArtifacts() instead of just status.phases.

Step 5: Update ArtifactActor to accept configurable size

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

• Add optional size parameter: constructor(type: string, position: Vector, size?: { width: number; height: number })
• Default to { width: 15, height: 15 } for backward compatibility
• Add new color entries to ARTIFACT_COLORS: simplifier -> PALETTE.magenta, holistic -> PALETTE.darkCyan

Step 6: Update FactoryScene rendering

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

Update buildStaticElements():

for (const artifact of config.artifacts) {
  const pos = this.layout.artifactPosition(artifact.stationIndex, artifact.indexAtStation);
  this.add(new ArtifactActor(artifact.type, vec(pos.x, pos.y), this.layout.artifactSize));
}

Step 7: Update tests

platform-layout.test.ts — Update artifactPosition test to pass indexAtStation, add tests for sequential positions and custom config.

ArtifactActor.test.ts — Add tests for custom size parameter and new color types (simplifier, holistic).

run-to-scene.test.ts — Update existing artifact test to expect indexAtStation. Add tests for:

• Individual artifacts per planning entry (3 planning.artifacts -> 3 configs at station 1)
• Top-level artifacts array as primary source
• Fallback to phase fields when top-level is undefined
• codeSimplifier and holisticReview artifact inclusion
• Correct indexAtStation for multiple artifacts at same station

fixtures.ts — No changes needed (already has artifacts: undefined in createMockRunStatus, tests override as needed).

Existing utilities to reuse

• isPresent() in run-to-scene.ts:42 — null/undefined guard
• PHASE_NAMES in role-types.ts:6 — canonical phase name list
• emptyPhases() / createMockRunStatus() / createCompletedRunPhases() in __test-helpers__/fixtures.ts

Verification

1. pnpm run ws typecheck in packages/factory/ — ensure no type errors
2. pnpm run ws test in packages/factory/ — all tests pass
3. pnpm run ws lint in packages/factory/ — no lint errors
4. Visual: pnpm run dev and load a completed run to see multiple artifact boxes at stations

[williamthorsen]

Implementation discovery: phase name disambiguation

ArtifactEntry.phase values from the agents package use data-model names (codeSimplifier, holisticReview), but the Factory visualization layer uses different aliases in PHASE_NAMES (simplifier, holistic). The PHASE_TO_STATION map needed explicit entries for both naming conventions — relying solely on PHASE_NAMES from role-types.ts was insufficient for the primary (top-level artifacts) data path.

This is a general pattern to watch for: the agents and Factory share a domain model but use different naming conventions at different layers. Any future mapping between ArtifactEntry fields and station indices will need the same aliasing.

[williamthorsen]

Implementation discovery: PALETTE.magenta color conflict

The plan proposed PALETTE.magenta (#FF55FF) for the simplifier artifact color, but this is already assigned to the orchestrator role in ROLE_TYPE_COLORS. While ARTIFACT_COLORS and ROLE_TYPE_COLORS are separate maps, using the same hex value would cause visual ambiguity in the scene. Used PALETTE.darkMagenta (#AA00AA) for simplifier instead to maintain visual distinction.

[williamthorsen]

Implementation discovery: empty array vs undefined in dual-source fallback

The dual-source buildArtifacts() function has three distinct boundary conditions for status.artifacts:

• undefined — no top-level array exists (v1 data), falls back to phase fields
• [] — empty array exists (v2 data with no artifacts yet), falls back to phase fields
• populated array — uses primary path

The undefined and populated cases are obvious, but [] (empty array) is a real runtime scenario (e.g., a run that has started but produced no artifacts yet) and was initially untested. The condition isPresent(status.artifacts) && status.artifacts.length > 0 handles all three correctly, but the empty-array boundary needed its own test to prevent regressions.