Loomworks Phase 66 — CR-drafting handoff: spend visibility and the pause preference

Version: v0.2 Date: 2026-05-30 Phase: 66 (resolved — 65 left for credit purchase) Type: CR-drafting handoff Produced alongside: loomworks-phase-66-scoping-note-spend-visibility-and-pause-v0_2 Target executor: Claude Code (CR drafting) Repos affected: loomworks (frontend) primary; loomworks-engine (substrate); loomworks-record Supersedes: v0.1 (phase 65→66; pre-flight already run — items folded in; build focus moved to the finding-B park/resume design)

Plain-language summary

What this document does. It hands the approved Phase 66 scope to CR drafting. CC's pre-flight has already run (results in the scoping note §6), so this handoff is no longer "verify these names" — it is "draft the CR against these confirmed facts, with the park/resume mechanism as the load-bearing build step."

Decision needed from CC at drafting: design the async park/resume mechanism (the one piece pre-flight flagged as net-new and large), and decide the resume strategy (re-cost after approval vs. cache pre-approval work). Give it its own checkpoint.

1. Scope, restated tightly

Phase A. Two capabilities, shipping together:

1. Spend visibility — all metered rooms. Actual per-run cost (from the post-run consumption flow) + balance movement (from /me/credits). No substrate change for visibility.
2. Spend-pause preference — default on. Async Shaping/Rendering spend parks and surfaces an approval card before debit. The card shows the cost cap ("up to N"), not the exact cost — the exact cost is unknowable pre-run (scoping §2.3, finding F). Card carries approve / decline / stop-pausing. Manifestation shows-and-proceeds (does not pause) in Phase A.

Out of scope: Manifestation pause (Phase B — synchronous-to-job re-architecture); funding-source/commitment gate (depends on lot provenance + purchase); per-lot balance readouts.

2. Confirmed substrate facts (from CC pre-flight — do not re-verify)

These are settled. Draft against them.

• Gate seam: gate_room_spend / gated_room_complete (credit/gate.py, credit/room_gate.py). Park point is inside gated_room_complete, between gate check and model call. Three call sites: agents/shaping.py, agents/render_specialist.py, engagement/manifestation_organization.py.
• Preference field: mirror persons.exhaustion_preference (TEXT NULL + CHECK, migration 0064) but add a server_default so the spend-pause field defaults ON.
• Settings surface: mirror ExhaustionPreferenceSection.tsx.
• ApprovalCard third action: dispatcher is binary, but action_params (JSONB) rides into the approve handler — the stop-pausing preference-write can ride there, or fire a separate PATCH /me/settings. CR drafting picks one.
• Cost cap: the card shows input-tokens + max_tokens as the ceiling. Actual cost shows on the visibility surface after the run.

3. The load-bearing build step — async park/resume (finding B)

This is the piece CC flagged as net-new and large. It gets its own checkpoint.

• shaping_jobs has no parked state and no resume — both built from scratch.
• render_jobs has awaiting_external (Phase 34) as a park precedent, but resume is poll-driven, not approval-driven — it re-dispatches a fresh continuation on external completion. There is no approval-driven resume anywhere today.
• CR drafting must design: (1) a pending-approval job state on shaping_jobs and on render_jobs (distinct from awaiting_external); (2) an approval-driven resume that re-enters the agent at the spend point after the card is approved. Resume strategy is a real fork to specify: re-run gate+model after approval (re-costs, simplest, but the displayed cap may differ from the re-run) vs. cache the pre-approval work and resume mid-function (more faithful, more complex). Recommend re-cost unless caching is cheap, since the cap is a ceiling not a commitment.

4. Build-step structure to draft against

Visibility first (no substrate dependency, ships value alone). Park/resume isolated to its own checkpoint.

1. Visibility surface (frontend). Actual per-run cost + balance movement, all metered rooms. Reads consumption flow + /me/credits.
2. Spend-pause preference field (substrate). New person-level field, default ON via server_default; migration mirroring 0064.
3. Async park/resume (substrate) — OWN CHECKPOINT. Pending-approval state + pre-debit park branch + approval-driven resume. Per §3.
4. Approval card (frontend + dispatcher wiring). Shows the cost cap; approve / decline / stop-pausing; the third writes the preference.
5. Settings surface + re-enable affordance (frontend). Spend-pause toggle mirroring ExhaustionPreferenceSection, plus re-enable from the visibility surface.

Help text on the preference states the Manifestation gap plainly (pause applies to rendering and shaping; Manifestation shows and proceeds until Phase B).

5. Halt thresholds to specify in the CR

• Step 3 (park/resume) exceeds its checkpoint estimate → halt; the Operator decides whether to split shaping vs. render park/resume into separate steps.
• The park branch touches the synchronous Manifestation path (it must not) → halt; that is Phase B.
• Any step's existing-test refactor exceeds ~30 tests → halt and propose splitting the refactor into its own step.

6. Seed check for CR drafting

Confirm alignment with loomworks-candidate-seed-v0_9: default-on pause = "the Operator approves spend" as the out-of-box stance; in-card off-switch = Operator authority to relax; "only show what is available" = cards stop appearing when pause is off. If any REQ row would introduce an automatic spend state-transition the Operator has not authorized, raise it against the seed before drafting.

Action path

1. Operator: approve the scoping note (v0.2) first. This handoff is actioned after that.
2. Save: ask Claude Code to create loomworks-record/phases/phase-66-spend-visibility-and-pause/ and commit both the scoping note and this handoff there.
3. CR drafting: open a new Claude.ai chat and paste the block below to Claude Code.

Paste to Claude Code for CR drafting

Loomworks Phase 66 — draft the spend-visibility-and-pause CR. Scope and confirmed
substrate facts are in
loomworks-record/phases/phase-66-spend-visibility-and-pause/loomworks-phase-66-cr-drafting-handoff-v0_2.md
and the scoping note v0.2 beside it. Pre-flight already ran — do not re-verify the
names in handoff §2; draft against them.

Draft a CR (next CR number after 2026-095) with build steps per handoff §4:
1. Visibility surface (frontend) — actual per-run cost + balance movement.
2. Spend-pause preference field — mirror persons.exhaustion_preference (migration
   0064) but ADD a server_default so it defaults ON.
3. Async park/resume (OWN CHECKPOINT, per handoff §3) — pending-approval state on
   shaping_jobs and render_jobs (distinct from awaiting_external) + approval-driven
   resume re-entering the agent at the spend point. Specify the resume-strategy
   fork: re-cost after approval vs. cache pre-approval work. Recommend re-cost.
4. Approval card — shows the cost CAP (input + max_tokens), not exact cost (exact
   is unknowable pre-run, finding F); approve / decline / stop-pausing; the third
   writes the pause preference off (via action_params or a PATCH /me/settings).
5. Settings surface + re-enable affordance — mirror ExhaustionPreferenceSection.

Manifestation does NOT pause in this CR (Phase B). Pause applies to shaping +
rendering only; help text states this. Halt thresholds per handoff §5. Seed check
per handoff §6.

Produce the CR with a plain-language summary at the top, versioned filename and
title, and the step-3 checkpoint clearly marked. Pre-flight inspection of any
remaining unverified detail before writing REQ rows; report findings if scope shifts.