Artifact bundle

Every orchestration attempt writes a bundle of durable artifacts under .lumenflow/artifacts/orchestration/<INIT-ID>/attempt-<N>/. The bundle is what lets humans, local agents, and compatible remote orchestration surfaces resume the same initiative without trading emails or screenshots.

Directory layout

.lumenflow/artifacts/orchestration/
└── INIT-056/
    ├── attempt-0/
    │   ├── plan.json
    │   ├── launch.json
    │   ├── status.json
    │   └── handoffs/
    │       ├── WU-2632.md
    │       └── WU-2634.md
    └── attempt-1/
        ├── plan.json
        ├── launch.json
        ├── status.json
        └── handoffs/
            └── WU-2632.md

Attempts are monotonic — once an attempt-N directory exists, the next invocation writes attempt-(N+1). The attempt number maps 1:1 to the launch_attempt field every receipt records.

plan.json — the dependency graph

{
  "initiative": "INIT-056",
  "launch_attempt": 1,
  "logical_waves": [0, 1, 2],
  "waves": [
    {
      "planned_wave": 0,
      "logical_wave": 0,
      "logical_waves": [0],
      "wus": [{ "id": "WU-2632", "lane": "Framework: ControlPlaneSdk", "logical_wave": 0 }]
    }
  ]
}

• logical_wave is the dependency distance from a root. It does not change unless the graph changes.
• planned_wave is the orchestrator’s launch grouping — normally equal to logical_wave but a single planned wave can contain multiple logical waves if capacity or lane limits cluster them.

launch.json — durable handoff receipts

{
  "initiative": "INIT-056",
  "launch_attempt": 1,
  "logical_waves": [0],
  "handoffs": [
    {
      "wu_id": "WU-2632",
      "lane": "Framework: ControlPlaneSdk",
      "logical_wave": 0,
      "launch_attempt": 1,
      "handoff_artifact_path": ".lumenflow/artifacts/orchestration/INIT-056/attempt-1/handoffs/WU-2632.md",
      "handoff_format": "markdown",
      "orchestration_state": "handoff_emitted",
      "emitted_at": "2026-04-17T10:00:00.000Z"
    }
  ]
}

Every handoff becomes a row in launch.json. Emitting a handoff is not launching a worker — it just records that the orchestrator prepared the artifact. Downstream evidence (worktree, delegation pickup, stamp) is what promotes a WU past handoff_emitted.

status.json — reconciled initiative state

{
  "initiative": "INIT-056",
  "launch_attempt": 1,
  "logical_waves": [0, 1, 2],
  "available_capacity": 2,
  "max_active_workers": 3,
  "blocked_by_integrity": false,
  "next_safe_actions": [
    { "type": "launch_wu", "wu_id": "WU-2634", "reason": "Ready to launch.", "logical_wave": 1 },
    {
      "type": "wait",
      "wu_id": "WU-2633",
      "reason": "Waiting for WU-2632 to complete.",
      "logical_wave": 1
    }
  ],
  "wus": [
    {
      "wu_id": "WU-2632",
      "orchestration_state": "done",
      "yaml_status": "done",
      "logical_wave": 0,
      "launch_attempt": 1,
      "contamination_paths": [],
      "queued_by_capacity": false
    }
  ]
}

This file is the machine-readable truth. Every CLI / MCP / remote surface renders a projection of it. The schema is enforced by the control-plane SDK via parseOrchestrationStatusDocument().

handoffs/ — per-WU bootstrap payloads

One file per emitted handoff. The file extension reflects the handoff_format:

• .xml for Claude Code (Task invocations).
• .md for Codex / Gemini / generic markdown clients.

These files are the durable handoff source for launch-mode orchestration:

• orchestrate:initiative -c and continuous mode print the file paths by default instead of inlining the payload bodies.
• --print-handoffs replays the stored artifact content inline for manual copy/paste.
• Supported clients receive the same load-bearing handoff contract as wu:brief; orchestration reads from the stored artifact instead of assembling a second prompt shape for stdout.

Humans can copy these into their agent manually; cloud launchers ship them over the wire automatically.

Logical wave vs launch attempt

Two orthogonal concepts that people used to conflate:

	logical_wave	launch_attempt
Changes when…	The dependency graph changes.	Every time you invoke orchestrate:initiative -c.
Source of truth	The initiative’s WU YAML deps.	The next free attempt-N dir.
Filename usage	Field inside plan / launch / status.	The directory name itself.
Meaning	”This WU is in wave 2 of the DAG."	"This is the 3rd time we tried to launch.”

Older manifests under .lumenflow/artifacts/waves/ used wave-N to mean both. INIT-056 retired that path; every new orchestration attempt writes a bundle under orchestration/<INIT>/attempt-N/ instead.

Related

• Lifecycle — which phase writes what.
• Control-plane SDK — OrchestrationPlanDocument, OrchestrationLaunchDocument, OrchestrationStatusDocument types + parsers.