Pulumi converge orchestration

Platform-admin recovery for stuck stacks, state drift, and intentional converge. Full procedure: pulumi-runtime.runbook.md (sibling overview: pulumi-converge-orchestration.runbook.md).

Mental model

Substrate	Role	Wipe-safe?
D1 oracle (cloud_resource + cloud_resource_config)	Source of intent	No — never wipe as recovery
R2 Pulumi state cache	Engine working memory	Yes — wipe + reconverge is canonical
Cloud APIs	Reality	n/a

CLI-first recipes

Four primitives — same verbs as the Pulumi CLI (preview / up / refresh / destroy). The action field is required (no default).

# Dry-run a box converge
nayaone-admin api adminRunPulumiConverge --body '{
  "scope": { "kind": "box", "id": "<box-ulid>" },
  "action": "preview"
}'

# Apply (up)
nayaone-admin api adminRunPulumiConverge --body '{
  "scope": { "kind": "box", "id": "<box-ulid>" },
  "action": "up"
}'

# Re-read cloud into the checkpoint without mutating resources
nayaone-admin api adminRunPulumiConverge --body '{
  "scope": { "kind": "box", "id": "<box-ulid>" },
  "action": "refresh"
}'

# Tear down cloud resources; D1 intent row is preserved
nayaone-admin api adminRunPulumiConverge --body '{
  "scope": { "kind": "box", "id": "<box-ulid>" },
  "action": "destroy"
}'

# Wipe R2 state cache for a scope (then reconverge with action: up)
nayaone-admin api adminClearPulumiStateCache

# Cancel a held state lock
nayaone-admin api adminCancelPulumiState --body '{
  "scope": { "kind": "box", "id": "<box-ulid>" }
}'

REST fallback: POST /admin-api/pulumi-state/converge · DELETE /admin-api/pulumi-state/cache · POST /admin-api/pulumi-state/cancel.

Full area listing: CLI reference → pulumi-state.

Symptom → first action

Symptom	First action
Lock held / “another update in progress”	adminCancelPulumiState, then re-dispatch up
State drift (checkpoint ≠ cloud)	adminClearPulumiStateCache then action: up, or action: refresh then up
Want a dry-run	action: preview

Related surfaces

• Admin UI: /admin/oracle?tab=cache and per-box Settings → Pulumi.
• Local batch CLI: bun scripts/reroll.ts in n1-cloud (see Fleet reroll).
• MCP: n1_admin_pulumi_converge / n1_admin_pulumi_wipe_cache.