@nanobpm/nano-workforce 0.26.0

package/workers/arm-merge/worker.ts

@@ -0,0 +1,18 @@
+// pr.arm-merge — arm the merge poller: park the PR in `waiting_merge` so the next poll pass
+// evaluates its mergeability and correlates `merge-ready`. Reached both on entry to the merge
+// stage (after dependencies clear) and after a human answers a merge escalation (re-check).
+import type { AppJobHandler } from "@nanobpm/urban";
+
+interface In extends Record<string, unknown> {
+  prKey: string;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  await app.data.table("pull_requests", "pr_key").update(job.variables.prKey, {
+    status: "waiting_merge",
+    updated_at: new Date().toISOString(),
+  });
+  return {};
+};
+
+export default handler;

package/workers/finalize/worker.ts

@@ -0,0 +1,89 @@
+// pr.finalize — the PR has converged. Record the final round and either (a) hand off to the
+// merge stage (start the `merge-loop` process and park the PR in `waiting_deps`) when auto-merge
+// is on, or (b) close the PR out as `converged` (review-only mode).
+import type { AppJobHandler } from "@nanobpm/urban";
+import { AUTO_MERGE, startMerge } from "../../app/service.ts";
+
+// Extends Record so the declared fields are typed while the job may still carry
+// other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
+interface In extends Record<string, unknown> {
+  prKey: string;
+  repo: string;
+  prNumber: number;
+  prUrl: string;
+  round: number;
+  summary?: string;
+}
+
+const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
+function transcriptOf(vars: Record<string, unknown>): string | null {
+  const env = vars[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
+  return typeof env?.output === "string" ? env.output : null;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  // `summary` is left undefined when absent so the write boundary omits it: the
+  // nullable `rounds.summary` stays NULL and `pull_requests.outcome` is untouched
+  // rather than being coerced to "".
+  const { prKey, repo, prNumber, prUrl, round, summary } = job.variables;
+  const now = new Date().toISOString();
+
+  await app.data.table("rounds", "id").insert({
+    pr_key: prKey,
+    round_no: round,
+    status: "converged",
+    summary,
+    transcript: transcriptOf(job.variables),
+    started_at: now,
+    ended_at: now,
+  });
+
+  // In auto-merge mode, start the separate merge-loop instance (keyed on prKey) that lands the
+  // PR *before* advancing the row into the merge stage. Best-effort: a failure here must not fail
+  // the convergence finalize. But we only flip the PR into the non-terminal `waiting_deps` status
+  // once merge-loop is actually running — otherwise the PR would be parked in a merge-stage status
+  // with no process behind it, and `submitPr` refuses to restart it (only `cancel` recovers). On
+  // failure we leave the PR terminal as `converged` so a human/operator can (re)start merge.
+  let status = "converged";
+  if (AUTO_MERGE) {
+    try {
+      const { mergeProcessKey } = await startMerge(app.data, app.engine, {
+        repo,
+        number: prNumber,
+        url: prUrl,
+        prKey,
+        round,
+      });
+      // `startMerge` can resolve without throwing yet with a null key (mirroring the engine's
+      // nullable `processInstanceKey`). Only park the PR in the merge-stage `waiting_deps` status
+      // when merge-loop is actually running — otherwise leave it terminal as `converged` so a
+      // human/operator can (re)start merge rather than stranding it with no process behind it.
+      if (mergeProcessKey != null) {
+        status = "waiting_deps";
+      } else {
+        app.log("error", `finalize: merge-loop start returned no process key for ${prKey}; leaving PR converged`);
+      }
+    } catch (err) {
+      app.log("error", `finalize: could not start merge-loop for ${prKey}; leaving PR converged`, {
+        err: String(err),
+      });
+    }
+  }
+
+  // Converged bookkeeping is recorded in both modes; `outcome`/`converged_at` capture the review
+  // result. In auto-merge mode (when merge-loop started) the *status* moves into the merge stage
+  // rather than resting at `converged`, so the merge poller starts watching immediately.
+  await app.data.table("pull_requests", "pr_key").update(prKey, {
+    status,
+    current_round: round,
+    outcome: summary,
+    converged_at: now,
+    updated_at: now,
+    open_escalation_id: null,
+    open_escalation_question: null,
+  });
+
+  return {};
+};
+
+export default handler;

package/workers/mark-merged/worker.ts

@@ -0,0 +1,21 @@
+// pr.mark-merged — the PR has landed (directly or via the merge queue). Record the terminal
+// `merged` state; the merge audit trail is written by pr.merge, so this only closes the row out.
+import type { AppJobHandler } from "@nanobpm/urban";
+
+interface In extends Record<string, unknown> {
+  prKey: string;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const now = new Date().toISOString();
+  await app.data.table("pull_requests", "pr_key").update(job.variables.prKey, {
+    status: "merged",
+    merged_at: now,
+    updated_at: now,
+    open_escalation_id: null,
+    open_escalation_question: null,
+  });
+  return {};
+};
+
+export default handler;

package/workers/merge/worker.ts

@@ -0,0 +1,119 @@
+// pr.merge — attempt to land the PR (SPEC §11). Returns `mergeStatus`:
+//   • merged  — landed now (direct merge)            → process marks it merged
+//   • queued  — added to the repo's merge queue       → process waits for `merge-landed`
+//   • blocked — GitHub refused (conflict / failing gate / perms) → escalate to a human, who
+//               resolves it and replies to retry (the process re-arms and re-polls).
+// HOW it lands is governed by the target repo's published merge protocol (#43): a `mergify-queue`
+// repo (e.g. Magikcraft/nano-bpm, auto-merge OFF) is landed by posting `@mergifyio queue` and
+// waiting for the queue, NOT a direct `gh pr merge` — which that repo refuses. The actual gh/API
+// calls live in app/github.ts; this worker records the attempt in the `merges` audit table and
+// shapes the escalation payload on a block.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { enqueueViaComment, mergePr } from "../../app/github.ts";
+import { MERGE_ADMIN, MERGE_METHOD } from "../../app/service.ts";
+import { loadMergeProtocol } from "../../app/mergeProtocol.ts";
+import { checkBaseTarget } from "../../app/baseGuard.ts";
+
+interface In extends Record<string, unknown> {
+  prKey: string;
+  repo: string;
+  prNumber: number;
+}
+
+interface Out extends Record<string, unknown> {
+  mergeStatus: "merged" | "queued" | "blocked";
+  status?: string;
+  question?: string;
+}
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const { prKey, repo, prNumber } = job.variables;
+  const token = process.env.GITHUB_TOKEN ?? "";
+  const now = new Date().toISOString();
+
+  // Dead-end-base guard (#60): never land a PR into a base branch that has itself already merged
+  // to the default branch — the merge would land into a dead branch and never reach `main`.
+  // GitHub only auto-retargets a PR when its base is *deleted* on merge; a merged-but-undeleted
+  // base (typical in a stacked epic) stays the target and reads CLEAN, so nothing else catches it.
+  // Best-effort: a transport hiccup leaves `deadEnd:false`, so this never blocks a valid merge.
+  const guard = await checkBaseTarget(repo, prNumber, token).catch(() => null);
+  if (guard?.deadEnd) {
+    await app.data.table("merges", "id").insert({
+      pr_key: prKey,
+      outcome: "blocked",
+      method: "base-guard",
+      detail: `base '${guard.base}' has already merged into '${guard.defaultBranch}' (dead-end target)`,
+      at: now,
+    });
+    return {
+      mergeStatus: "blocked",
+      status: "blocked",
+      question:
+        `This PR targets '${guard.base}', which has already merged into '${guard.defaultBranch}'. ` +
+        `Merging now would land into a dead-end branch and never reach '${guard.defaultBranch}'. ` +
+        `Retarget it (gh pr edit ${prNumber} --repo ${repo} --base ${guard.defaultBranch}), then reply to retry.`,
+    };
+  }
+
+  // Load the repo protocol for every worker invocation. A retry after fix-ci/rebase is a fresh
+  // landing attempt, so land-method decisions must not be latched across earlier heads.
+  const protocol = await loadMergeProtocol(repo, token).catch(() => null);
+  const method = protocol?.land.method ?? "gh-merge";
+
+  let outcome: "merged" | "queued" | "blocked";
+  let detail: string;
+  let auditMethod: string;
+
+  if (method === "mergify-queue") {
+    // Land via the repo's on-demand queue: post the enqueue comment; the poller's queued→landed
+    // watch (service.ts block 3) then advances the process when the queue merges it.
+    const comment = protocol?.land.comment ?? "@mergifyio queue";
+    const ok = await enqueueViaComment(repo, prNumber, token, comment);
+    outcome = ok ? "queued" : "blocked";
+    detail = ok ? `enqueued via "${comment}"` : `failed to post enqueue comment "${comment}"`;
+    auditMethod = "queue-comment";
+  } else if (method === "ui") {
+    // The repo requires a human to click Merge; Merlin can't. Escalate rather than pretend.
+    outcome = "blocked";
+    detail = "repo merge protocol requires a manual UI merge (land.method=ui)";
+    auditMethod = "ui";
+  } else {
+    const admin = method === "admin" || MERGE_ADMIN;
+    const res = await mergePr(repo, prNumber, token, { method: MERGE_METHOD, admin });
+    // No usable transport → treat as a block so a human is asked to configure/merge, rather than
+    // silently completing the process without landing the PR.
+    outcome = res?.outcome ?? "blocked";
+    detail = res?.detail ?? "no GitHub transport available (configure gh or GITHUB_TOKEN)";
+    auditMethod = outcome === "queued" ? "queue" : MERGE_METHOD;
+  }
+
+  await app.data.table("merges", "id").insert({
+    pr_key: prKey,
+    outcome,
+    method: auditMethod,
+    detail,
+    at: now,
+  });
+
+  if (outcome === "queued") {
+    await app.data.table("pull_requests", "pr_key").update(prKey, {
+      status: "queued",
+      updated_at: now,
+    });
+    return { mergeStatus: "queued" };
+  }
+  if (outcome === "merged") {
+    return { mergeStatus: "merged" };
+  }
+  // blocked → hand the escalation machinery a concrete question.
+  const docHint = protocol?.doc ? ` See the repo's merge protocol (${protocol.doc}).` : "";
+  return {
+    mergeStatus: "blocked",
+    status: "blocked",
+    question:
+      `Automated merge was blocked: ${detail}. ` +
+      `Resolve it on GitHub (rebase / fix a required check / grant merge rights), then reply to retry.${docHint}`,
+  };
+};
+
+export default handler;

package/workers/persist-escalation/worker.ts

@@ -0,0 +1,107 @@
+// pr.persist-escalation — records the round that raised an escalation and opens an escalation
+// row for a human to answer. Handles both the agent-raised path (status = needs_input | blocked)
+// and the MAX_ROUNDS guard (status = blocked, question set by the process). Returns
+// `escalationId` for the UI.
+import type { AppJobHandler } from "@nanobpm/urban";
+
+// Extends Record so the declared fields are typed while the job may still carry
+// other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
+interface In extends Record<string, unknown> {
+  prKey: string;
+  round: number;
+  status?: string;
+  summary?: string;
+  question?: string;
+  // False on the "review stalled" arm: `persist-round` already recorded this `round` as
+  // `addressed`, so this escalation must not insert a second `rounds` row for the same
+  // `pr_key`/`round_no` (which would record one round as both addressed and blocked). Absent
+  // on the agent-raised / max-rounds arms, where no prior round row exists — so it defaults on.
+  recordRound?: boolean;
+}
+
+// A string variable, or undefined when it is absent, empty, or whitespace-only.
+// The write boundary owns *type* defaults (undefined -> column DEFAULT/NULL); this
+// owns a *domain* rule: a blank prompt or status counts as "missing" so it can't
+// reach the escalation control flow or the UI answer form.
+function nonBlank(v: unknown): string | undefined {
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
+const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
+function transcriptOf(vars: Record<string, unknown>): string | null {
+  const env = vars[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
+  return typeof env?.output === "string" ? env.output : null;
+}
+
+// Synthesize a concrete, answerable question when the agent left one blank. A blank question is
+// almost always a *no-result* round: a prompt-less agent that never wrote its result file, so
+// `status` is empty and `gw-status` falls through its default `f_escalate` arm (the empty
+// "(no question provided)" escalations on Magikcraft/nano-bpm #597/#599). Throwing here parked a
+// `JobNoRetries` incident that could NOT be diagnosed or remediated from the UI. Instead we open
+// an escalation a human can actually answer, with the agent's transcript attached below it.
+function fabricateQuestion(rawStatus: string | undefined, hasTranscript: boolean): string {
+  const tail = hasTranscript
+    ? " Review the agent's response shown below, then reply with how it should proceed — or cancel and resubmit."
+    : " No agent response was captured. Reply with how it should proceed, or cancel and resubmit.";
+  if (!rawStatus) {
+    return "The review agent finished without a machine-readable result (no status was reported), " +
+      "so this round could not be classified as converged, addressed, or a specific request." + tail;
+  }
+  return `The review agent reported status "${rawStatus}" without a question, so this round ` +
+    "could not be resolved automatically." + tail;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const { prKey, round, summary } = job.variables;
+  // `status` drives the escalation kind (control flow); a blank/absent status is an
+  // unclassified escalation -> a question needing input. `question` is denormalised
+  // onto pull_requests below and bound by the UI answer form, so it must be a
+  // concrete, non-blank value. `summary` is left undefined so the write boundary
+  // omits it and the nullable column stays NULL.
+  const rawStatus = nonBlank(job.variables.status);
+  const status = rawStatus ?? "needs_input";
+  const transcript = transcriptOf(job.variables);
+  // A blank question must never open an unanswerable escalation. Every legitimate arm sets a
+  // concrete question — the agent contract requires one for needs_input/blocked, and the
+  // max-rounds + review-timeout arms set a literal via the model. When one is still missing
+  // (a no-result round through the `gw-status` default), fabricate an actionable question that
+  // references the attached transcript rather than throwing (which parked an un-remediable
+  // incident). This keeps the loop recoverable entirely from the UI.
+  const question = nonBlank(job.variables.question) ?? fabricateQuestion(rawStatus, transcript != null);
+  const kind = status === "needs_input" ? "question" : "blocker";
+  const now = new Date().toISOString();
+
+  // Skip the round insert when the caller already recorded this round (the "review stalled"
+  // arm runs after `persist-round`): re-inserting would duplicate the `pr_key`/`round_no` row.
+  if (job.variables.recordRound !== false) {
+    await app.data.table("rounds", "id").insert({
+      pr_key: prKey,
+      round_no: round,
+      status,
+      summary,
+      transcript,
+      started_at: now,
+      ended_at: now,
+    });
+  }
+  const escalationId = await app.data.table("escalations", "id").insert({
+    pr_key: prKey,
+    round_no: round,
+    kind,
+    question,
+    transcript,
+    status: "open",
+    asked_at: now,
+  });
+  await app.data.table("pull_requests", "pr_key").update(prKey, {
+    status: "escalated",
+    current_round: round,
+    updated_at: now,
+    open_escalation_id: Number(escalationId),
+    open_escalation_question: question,
+  });
+
+  return { escalationId: Number(escalationId) };
+};
+
+export default handler;

package/workers/persist-round/worker.ts

@@ -0,0 +1,52 @@
+// pr.persist-round — records a completed round (an `addressed` round where the agent pushed
+// changes, or a `waiting` round where there was nothing to triage yet) and parks the PR in
+// `waiting_review` so the poller starts watching for / soliciting the next review.
+//
+// Data access goes through the injected app datasource gateway (`app.data.table<T>`), the RAD
+// `Table<T>` surface — `rounds.insert(...)` / `pull_requests.update(...)`, not hand-written SQL.
+import type { AppJobHandler } from "@nanobpm/urban";
+
+// Extends Record so the declared fields are typed while the job may still carry
+// other process variables (e.g. io.nanobpm.agentResult, read by transcriptOf).
+interface In extends Record<string, unknown> {
+  prKey: string;
+  round: number;
+  status?: string;
+  summary?: string;
+}
+
+// The harness records the agent's full (byte-capped) stdout on the result envelope; keep it
+// for audit so a human can see what the agent did this round.
+const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
+function transcriptOf(vars: Record<string, unknown>): string | null {
+  const env = vars[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
+  return typeof env?.output === "string" ? env.output : null;
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  // This worker is the "addressed"/"waiting" path, so `status` resolves to one of those
+  // domain values. `summary` is left undefined when absent: the write boundary omits it so the
+  // nullable `rounds.summary` column stays NULL rather than being coerced to "".
+  const { prKey, round, status = "addressed", summary } = job.variables;
+  const now = new Date().toISOString();
+
+  await app.data.table("rounds", "id").insert({
+    pr_key: prKey,
+    round_no: round,
+    status,
+    summary,
+    transcript: transcriptOf(job.variables),
+    started_at: now,
+    ended_at: now,
+  });
+  await app.data.table("pull_requests", "pr_key").update(prKey, {
+    status: "waiting_review",
+    current_round: round,
+    waiting_since: now,
+    updated_at: now,
+  });
+
+  return {};
+};
+
+export default handler;

package/workers/persist-task-escalation/worker.ts

@@ -0,0 +1,112 @@
+// pr.persist-task-escalation — an implementation agent escalated a task during the
+// fan-out (issue #25). It reported `status = "escalated"` with a `question` and,
+// ideally, a work-preserving DRAFT PR, then completed its job. This worker records
+// that escalation and parks the plan on a per-task human answer:
+//   • opens (or refreshes) a `plan_escalations` row (status = open),
+//   • marks the `plan_tasks` row `escalated` with the question / draft PR / corr key,
+//   • re-points the plan's denormalised "open task escalation" fields at the
+//     oldest still-open escalation, so the page's single answer form surfaces it.
+//
+// The process then parks the child at the `feature-escalation-answered` message
+// catch (correlationKey `<plan_key>:<task_id>`). Answering it (page form or
+// `/hooks/feature-answer`) resumes the child, which re-dispatches the SAME task.
+//
+// Retry-safe: if an open escalation already exists for this corr key (a worker
+// re-activation before the wait subscription opened), it is UPDATED, not
+// duplicated — a fresh escalation row is only created after the previous one was
+// answered.
+import type { AppJobHandler } from "@nanobpm/urban";
+import {
+  featureCorrKey,
+  planEscalations,
+  planTasks,
+  refreshOpenTaskEscalation,
+} from "../../app/plan.ts";
+
+interface TaskIn {
+  id?: unknown;
+  title?: unknown;
+}
+interface In extends Record<string, unknown> {
+  planKey: string;
+  task?: TaskIn;
+  question?: unknown;
+  pr?: unknown;
+  summary?: unknown;
+}
+interface Out extends Record<string, unknown> {
+  escalationId: number;
+}
+
+// A non-blank trimmed string, else undefined. A blank question/PR must not reach
+// the UI answer form or masquerade as preserved work.
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const taskId = str(job.variables.task?.id);
+  if (!taskId) {
+    // No task binding means we cannot correlate a resume — fail loudly rather
+    // than silently parking a token that can never be answered.
+    throw new Error("persist-task-escalation: missing task.id in child scope");
+  }
+  const corrKey = featureCorrKey(planKey, taskId);
+  const question = str(job.variables.question);
+  if (!question) {
+    // A blank question would surface a non-actionable placeholder in the answer
+    // form and, on a retry, overwrite a previously recorded question. The output
+    // contract requires `question` for an escalation — fail loudly, like the
+    // missing-task.id guard above, rather than park an unanswerable escalation.
+    throw new Error("persist-task-escalation: missing question for escalated task");
+  }
+  const draftPr = str(job.variables.pr) ?? null;
+  // Prior-attempt context the escalating agent reported. Persist it so the UI
+  // and any later resume/debugging keep the task's summary instead of NULL.
+  const summary = str(job.variables.summary) ?? null;
+  const ts = new Date().toISOString();
+
+  const escTable = planEscalations(app.data);
+  const existing = (await escTable.find({ corr_key: corrKey, status: "open" }))
+    .sort((a, b) => b.id - a.id)[0];
+  let escalationId: number;
+  if (existing) {
+    await escTable.update(existing.id, {
+      question,
+      draft_pr_key: draftPr ?? existing.draft_pr_key,
+    });
+    escalationId = existing.id;
+  } else {
+    escalationId = Number(
+      await escTable.insert({
+        plan_key: planKey,
+        task_id: taskId,
+        corr_key: corrKey,
+        question,
+        draft_pr_key: draftPr,
+        status: "open",
+        asked_at: ts,
+      }),
+    );
+  }
+
+  for (const t of await planTasks(app.data).find({ plan_key: planKey, task_id: taskId })) {
+    await planTasks(app.data).update(t.id, {
+      status: "escalated",
+      open_question: question,
+      // Clear any answer from a prior (already-answered) escalation so the task
+      // row stays aligned with the currently-open question — otherwise a
+      // re-escalated task would show a stale answer next to the new question.
+      answer: null,
+      draft_pr_key: draftPr ?? t.draft_pr_key,
+      summary: summary ?? t.summary,
+      corr_key: corrKey,
+      updated_at: ts,
+    });
+  }
+
+  await refreshOpenTaskEscalation(app.data, planKey);
+  return { escalationId };
+};
+
+export default handler;

package/workers/record-plan/worker.ts

@@ -0,0 +1,135 @@
+// pr.record-plan — persists the plan the `senior:plan` agent emitted, LEVELIZES the task
+// DAG into ordered waves (issue #20), and hands the process the first wave to run.
+//
+// The planner emits `{ tasks: [{ id?, title?, prompt, dependsOn? }] }`. This worker:
+//   • assigns each task a stable `id` (planner slug, else `t<index>`) and an index,
+//   • computes each task's `wave` from its `dependsOn` DAG (app/waves.ts): independent
+//     tasks share a wave, a dependent task lands 1 + max(dep wave),
+//   • writes one `plan_tasks` row per task (status `pending`, with its `wave`) and one
+//     `plan_task_deps` row per dependency edge (idempotent: cleared + rewritten per plan),
+//   • records the task count, moves the plan to `dispatched`, and emits `currentWave = 0`
+//     plus `waveCount` so the wave loop (`select-wave → implement → record-wave`) can run.
+//
+// If the planner emits a malformed DAG (cycle / unknown or self dependency / duplicate id),
+// levelization can't order the tasks. Rather than dead-lock the plan we DEGRADE to the old
+// flat behaviour — a single wave (wave 0) of all tasks, run fully in parallel — and log a
+// warning; the ordering is lost but every task still runs. No `plan_task_deps` are recorded
+// in that case (the edges were invalid).
+import type { AppJobHandler } from "@nanobpm/urban";
+import { planTaskDeps, planTasks } from "../../app/plan.ts";
+import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
+
+interface RawTask {
+  id?: unknown;
+  title?: unknown;
+  prompt?: unknown;
+  dependsOn?: unknown;
+}
+interface In extends Record<string, unknown> {
+  planKey: string;
+  tasks?: RawTask[];
+  note?: string;
+}
+interface NormalTask {
+  id: string;
+  title: string;
+  prompt: string;
+  dependsOn: string[];
+}
+interface Out extends Record<string, unknown> {
+  currentWave: number;
+  waveCount: number;
+}
+
+const str = (v: unknown): string => (typeof v === "string" ? v : v == null ? "" : String(v));
+const strList = (v: unknown): string[] =>
+  Array.isArray(v) ? v.map((x) => str(x).trim()).filter((s) => s !== "") : [];
+
+const handler: AppJobHandler<In, Out> = async (job, app) => {
+  const { planKey, note } = job.variables;
+  const raw = Array.isArray(job.variables.tasks) ? job.variables.tasks : [];
+  const ts = new Date().toISOString();
+
+  const tasks: NormalTask[] = raw.map((t, i) => {
+    const id = str(t?.id).trim() || `t${i + 1}`;
+    return {
+      id,
+      title: str(t?.title).trim() || id,
+      prompt: str(t?.prompt),
+      // Dedupe: a planner-emitted `["a","a"]` would otherwise violate the
+      // `plan_task_deps` PK on the second edge insert and fail the job.
+      dependsOn: [...new Set(strList(t?.dependsOn))],
+    };
+  });
+
+  // Levelize the DAG. A malformed graph degrades to a single all-parallel wave (see header).
+  const forLevel: WaveTask[] = tasks.map((t) => ({ id: t.id, dependsOn: t.dependsOn }));
+  let waveOf = new Map<string, number>();
+  let waveCount = tasks.length > 0 ? 1 : 0;
+  let depsValid = true;
+  try {
+    const levelled = computeWaves(forLevel);
+    waveOf = levelled.waveOf;
+    waveCount = levelled.waveCount;
+  } catch (err) {
+    if (!(err instanceof WaveError)) throw err;
+    depsValid = false;
+    // The DAG is unusable (cycle / self / unknown dep, or a DUPLICATE task id). Rewrite every
+    // task to a guaranteed-unique positional id and drop deps: the wave loop's task_id-keyed
+    // maps (select-wave / record-wave) would otherwise collide on duplicate ids and silently
+    // lose updates, leaving some rows stuck `pending`. Ordering is lost; all tasks run flat.
+    tasks.forEach((t, i) => {
+      t.id = `t${i + 1}`;
+    });
+    waveOf = new Map();
+    for (const t of tasks) waveOf.set(t.id, 0);
+    app.log("warn", `record-plan: ${planKey} plan not levelizable, running flat`, {
+      err: err.message,
+    });
+  }
+
+  // Idempotency: a retry (or re-run) of this job must not duplicate rows for the same plan.
+  const taskTable = planTasks(app.data);
+  const existing = await taskTable.find({ plan_key: planKey });
+  for (const row of existing) await taskTable.delete(row.id);
+  // `plan_task_deps` is keyed on `plan_key`, so one delete clears the plan's whole edge set.
+  const depTable = planTaskDeps(app.data);
+  await depTable.delete(planKey);
+
+  for (let i = 0; i < tasks.length; i++) {
+    const t = tasks[i];
+    await taskTable.insert({
+      plan_key: planKey,
+      task_index: i,
+      task_id: t.id,
+      title: t.title,
+      prompt: t.prompt,
+      status: "pending",
+      wave: waveOf.get(t.id) ?? 0,
+      created_at: ts,
+      updated_at: ts,
+    });
+    if (depsValid) {
+      for (const dep of t.dependsOn) {
+        await depTable.insert({
+          plan_key: planKey,
+          task_id: t.id,
+          depends_on_task_id: dep,
+        });
+      }
+    }
+  }
+
+  const patch: Record<string, unknown> = {
+    status: tasks.length > 0 ? "dispatched" : "done",
+    task_count: tasks.length,
+    updated_at: ts,
+  };
+  if (tasks.length === 0) patch.outcome = note ? str(note) : "planner emitted no tasks";
+  await app.data.table("plans", "plan_key").update(planKey, patch);
+
+  // Kick off the wave loop at wave 0.
+  return { currentWave: 0, waveCount };
+};
+
+export default handler;