Templates: failed seed left marked up-to-date forever

[dascalescuro]

Symptom

scripts/prepare-templates.ts creates a tpl-* branch, then seeds it. If create succeeds and a later step fails (awaitConnectionString, resolveBranchDsn, or seedTemplate), the next deploy/run sees the branch name in listBranches() and logs it as up-to-date, skipping recreate/re-seed.

Learners who fork that template get an empty or broken sandbox for that lesson.

Red loop (logic already exercised)

1. Create template name not in existing → createBranch succeeds → add name to Xata.
2. Seed (or DSN) throws → script exits non-zero.
3. Re-run: existing.has(name) → skip with (up-to-date).

Where

• scripts/prepare-templates.ts (~lines 219–237) — existence check only; no “seeded successfully” marker / delete-on-failure

Suggested direction

On failure after create: delete the branch (or mark incomplete). On success-only: treat as up-to-date. Alternatively re-seed / verify seed before skipping.

Notes

Diagnosed with /diagnosing-bugs. Deploy impact if template prep fails mid-lesson after the branch already exists.

[dascalescuro]

This was generated by AI during triage.

Triage verification

Confirmed by code inspection of the deploy template-prep loop: if a branch name already appears in the listed branches set, the run logs it as up-to-date and skips create/seed. There is no success marker and no delete-on-failure after create. A create-then-fail sequence therefore leaves a permanent skip on the next run.

Redundancy: Idle/orphan cleanup and stale-template prune exist elsewhere for user / stale tpl-* lifecycle; they do not fix “created but never successfully seeded in this prep run.”
Prior rejection: no .out-of-scope/ entries.

Recommendation applied: bug + ready-for-agent (deterministic script logic; can be covered with a harness or careful control-flow change without product UI).

Agent Brief

Category: bug
Summary: Do not treat a template branch as up-to-date unless it was successfully prepared

Current behavior:
Template preparation creates a per-lesson template branch, then obtains a DSN and seeds it. If anything after create fails, the process exits, but the branch remains. The next run sees the name among existing branches and skips it as up-to-date. Learners forking that template can get an empty or broken sandbox for that lesson.

Desired behavior:
A template name should only be skipped when prior preparation is known-good (or equivalently: a failed prep must not leave a branch that future runs will skip). On failure after create, either remove the incomplete branch before exiting, or otherwise ensure the next run re-attempts prepare/seed instead of skipping. Successful prepares continue to skip recreate when truly up-to-date (name still encodes seed hash as today).

Key interfaces:

• Deploy-time template preparation entrypoint that lists existing branches, creates missing tpl-* names, awaits connection strings, resolves DSNs, and seeds
• Branch create / delete APIs already used by the app’s branch lifecycle — reuse delete (or equivalent) for incomplete templates
• Template naming that includes seed hash — unchanged; still the identity for “this lesson seed version”

Acceptance criteria:

• If create succeeds and a later prep step fails, a subsequent prep run does not skip that template as up-to-date without repairing or recreating it
• Successful prepare still skips an already-good template with the same name/hash
• Failure still fails the overall prep command (non-zero exit) so deploy does not silently continue with a known-bad template
• No change to how user sandbox forks choose the template once a template is correctly prepared

Out of scope:

• Redesigning template naming / hashing
• User-branch idle cleanup or orphan sweep behavior beyond what’s needed for incomplete templates
• Changing lesson seed SQL content