@coreplane/switchboard 1.259.0 → 1.260.1

package/dist/assets/src/core/coordinator/driver.ts

@@ -7,7 +7,13 @@
 // bot answer becomes the machine's return, and what is left to the platform's
 // retry: a call that throws inside a step is the platform's to ask again under
 // the one policy (twelve times, two minutes apart, constant — long enough for a
-// bot deploy and its rollover), and the driver never catches it.
+// bot deploy and its rollover), and the driver never catches it mid-step. A
+// throw that escapes a unit's pipeline anyway — a stored answer the mappers
+// cannot read, retries exhausted, the platform's own refusal — is told once as
+// the unit's ending (kind `failed`, cause `step_threw`, the step and round and
+// the throw's one line, issue 2100) before it is rethrown to fail the
+// instance, so the unit's row never reads as the bare "no ending was
+// recorded" seal.
 //
 // Every step's stored output is the bot's reply as the wire carried it — the
 // status and the text of a JSON object the bot stamped with its clock (`at`) —
@@ -33,7 +39,7 @@
 // plan's re-issue. A task string's ship branch waits for a person. Node-free:
 // the shim Worker imports this by relative path.
 
-import { DEFAULT_GRANT, GRANT_RENEWALS_MAX, IDLE_DAYS_MAX, type Grant, type GrantSource } from "../budgets.js";
+import { DAY_MS, DEFAULT_GRANT, GRANT_RENEWALS_MAX, IDLE_DAYS_MAX, type Grant, type GrantSource } from "../budgets.js";
 import { DEFAULT_VERBOSITY, isVerbosity, type Verbosity } from "../verbosity.js";
 import {
   applyReturn,
@@ -68,8 +74,11 @@ import {
   childInterruptedEventType,
   childResumedEventType,
   isCoordinatorUnit,
+  isUnitWakeAnswer,
   runFinishedEventType,
+  unitNudgeEventType,
   type CoordinatorUnit,
+  type UnitWakeAnswer,
 } from "./contract.js";
 
 const MIN = 60_000;
@@ -102,6 +111,7 @@ export type CoordinatorStepRoute =
   | "pr-check"
   | "round"
   | "unit-end"
+  | "unit-wake"
   | "checks"
   | "merge"
   | "finish";
@@ -279,6 +289,11 @@ function readUnitStart(a: BotAnswer): { at: number } {
   return { at: a.body.at };
 }
 
+function readWakeAnswer(a: BotAnswer): { answer: UnitWakeAnswer; at: number } {
+  if (a.body.ok !== true || !isUnitWakeAnswer(a.body.answer)) throw new UnreadableAnswer("unit-wake", a, "wake answer");
+  return { answer: a.body.answer, at: a.body.at };
+}
+
 function branchReturn(step: string, a: BotAnswer): StepReturn {
   const { ok, reason, at } = a.body;
   if (ok === true) return { type: "branch", step, ok: true, at };
@@ -428,6 +443,9 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
         ...(Array.isArray(a.body.fixupCommits) && a.body.fixupCommits.every((s: unknown) => typeof s === "string")
           ? { fixupCommits: a.body.fixupCommits as string[] }
           : {}),
+        // The base's merge-queue rule beside the checks (issue 2011): the
+        // merge:person report says the person's merge is queued.
+        ...(typeof a.body.baseHasMergeQueue === "boolean" ? { baseHasMergeQueue: a.body.baseHasMergeQueue } : {}),
       },
       at,
     };
@@ -451,7 +469,7 @@ function prCheckReturn(step: string, a: BotAnswer): StepReturn {
  *  ask's answer carries `retried` instead: whether the re-run was dispatched,
  *  so the machine never waits on a head an undispatched re-run left unchanged. */
 function checksReturn(step: string, a: BotAnswer): StepReturn {
-  const { ok, checks, draft, retried, at } = a.body;
+  const { ok, checks, draft, retried, refired, at } = a.body;
   if (ok !== true) throw new UnreadableAnswer("checks", a, "ok");
   return {
     type: "checks",
@@ -461,6 +479,7 @@ function checksReturn(step: string, a: BotAnswer): StepReturn {
     // unit for the ready event instead of merging or ending without a cause.
     ...(draft === true ? { draft: true } : {}),
     ...(typeof retried === "boolean" ? { retried } : {}),
+    ...(typeof refired === "boolean" ? { refired } : {}),
     at,
   };
 }
@@ -471,7 +490,10 @@ const isRoundChecks = (v: unknown): v is RoundChecks =>
   Array.isArray(v.pending) &&
   v.pending.every((n: unknown) => typeof n === "string") &&
   Array.isArray(v.failed) &&
-  v.failed.every((f: unknown) => isRecord(f) && typeof f.name === "string" && typeof f.conclusion === "string");
+  v.failed.every((f: unknown) => isRecord(f) && typeof f.name === "string" && typeof f.conclusion === "string") &&
+  (v.required === undefined ||
+    (Array.isArray(v.required) && v.required.every((n: unknown) => typeof n === "string"))) &&
+  (v.expected === undefined || (Array.isArray(v.expected) && v.expected.every((n: unknown) => typeof n === "string")));
 
 function mergeReturn(step: string, a: BotAnswer): StepReturn {
   const { ok, outcome, by, sha, mergedAt, reason, at } = a.body;
@@ -652,8 +674,8 @@ async function perform(
     }
     case "checks":
       // The round's checks step (record 0055): the bot reads the check runs at
-      // the reviewed head with the merge door's own reading — or, on a retry
-      // ask, re-runs the named failed checks' jobs first.
+      // the reviewed head with the merge door's own reading — or performs one
+      // of the step's bounded recovery effects first.
       return checksReturn(
         action.step,
         answerOf(
@@ -664,6 +686,7 @@ async function perform(
               prNumber: action.prNumber,
               headSha: action.headSha,
               ...(action.retry !== undefined ? { retry: action.retry } : {}),
+              ...(action.refire === true ? { refire: true } : {}),
             }),
           ),
         ),
@@ -686,8 +709,70 @@ async function perform(
   }
 }
 
+/** The throw's one line, for the step-threw ending's report (issue 2100). */
+function oneLineOf(err: unknown): string {
+  const line = (err instanceof Error ? err.message : String(err)).split("\n")[0]!.trim();
+  if (line.length === 0) return "an error with no message";
+  return line.length > REASON_MAX ? `${line.slice(0, REASON_MAX)}…` : line;
+}
+
+/** Where the machine was when a step threw: the step's own name and, inside a
+ *  round, the round it belonged to. */
+interface StepAt {
+  step: string;
+  round?: { index: number; kind: string };
+}
+
+/** A step that throws inside the walk becomes the unit's ending (issue 2100):
+ *  kind `failed`, cause `step_threw`, the step and round it was in and the
+ *  throw's one line, posted in the user's words — best effort, before the
+ *  throw is rethrown to fail the instance — so the unit's row carries a cause
+ *  a person can read instead of the bare "no ending was recorded" seal (the
+ *  walk-dies-before-unit-end path behind issues 2063 and 2100: run 21c50656
+ *  died between round 2's review verdict and its outcome write). */
+async function tellStepThrew(
+  step: StepRunner,
+  bot: CoordinatorBot,
+  prefix: string,
+  tag: { parentInstanceId: string; unit: string },
+  pr: { number: number; url: string } | undefined,
+  at: StepAt,
+  err: unknown,
+): Promise<void> {
+  const line = oneLineOf(err);
+  const where =
+    at.round === undefined
+      ? `at \`${at.step}\``
+      : at.round.kind === "review" && /\/review\/(read|checks)\b/.test(at.step)
+        ? `after round ${at.round.index}'s review verdict (\`${at.step}\`)`
+        : `in round ${at.round.index} (\`${at.step}\`)`;
+  const report =
+    `⚠️ The runner failed ${where}: ${line}\n\n` +
+    "Re-issue `agent:ship` in this thread to continue — a pull request already approved with green checks resumes at the checks step, never at a fresh coding round.";
+  const body = {
+    ...tag,
+    ending: {
+      kind: "failed",
+      cause: "step_threw",
+      step: at.step,
+      ...(at.round !== undefined ? { round: at.round.index } : {}),
+      report,
+      threadReport: report,
+    },
+    ...(pr !== undefined ? { pr } : {}),
+  };
+  try {
+    await step.do(`${prefix}/end/threw`, STEP_CONFIG, () => call(bot, "unit-end", body));
+  } catch {
+    // Best effort: the rethrow still fails the instance, and a bot that could
+    // not record the ending leaves the seal's line as before.
+  }
+}
+
 /** One unit's pipeline: its start, then the machine's steps until it ends;
  *  every round boundary and the ending told to the bot as they happen. */
+type DrivenEnding = UnitEnding & { endedAt?: number };
+
 async function runUnit(
   step: StepRunner,
   bot: CoordinatorBot,
@@ -695,16 +780,28 @@ async function runUnit(
   node: PlanUnitNode,
   plan: PlanFacts,
   session?: LeaseSegmentProgress,
-): Promise<UnitEnding> {
+): Promise<DrivenEnding> {
   const unit = node.id;
   // A renewal's segment names its steps under the segment (`U10/s2/…`), so
   // the Workflow's durable step cache never answers segment two with segment
   // one's results (decision 0046).
   const prefix = stepPrefixOf(unit, session);
   const tag = { parentInstanceId: instanceId, unit };
-  const start = readUnitStart(
-    answerOf("unit-start", await step.do(`${prefix}/start`, STEP_CONFIG, () => call(bot, "unit-start", tag))),
-  );
+  // Where the machine is, tracked for the step-threw ending (issue 2100). The
+  // start belongs in the same net as the rest of the unit even though no
+  // pipeline state (and therefore no round) exists yet.
+  let last: StepAt = { step: `${prefix}/start` };
+  let start: ReturnType<typeof readUnitStart>;
+  try {
+    const startStep = `${prefix}/start`;
+    last = { step: startStep };
+    start = readUnitStart(
+      answerOf("unit-start", await step.do(startStep, STEP_CONFIG, () => call(bot, "unit-start", tag))),
+    );
+  } catch (err) {
+    await tellStepThrew(step, bot, prefix, tag, undefined, last, err);
+    throw err;
+  }
   // A resume at review (agent-ship item 10) rides the unit's row: the pull
   // request of ship's own the requester named opens the pipeline at its first
   // review round, with no pre-check, no branch and no round 0.
@@ -739,108 +836,139 @@ async function runUnit(
     start.at,
   );
   let notes = 0;
-  for (;;) {
-    const action = nextAction(state);
-    if (action.type === "end") return action.ending;
-    const transition = applyReturn(state, await perform(step, bot, instanceId, unit, action));
-    state = transition.state;
-    for (const note of transition.notes) {
-      if (note.type === "round") {
-        const body = {
-          ...tag,
-          index: note.index,
-          agent: note.agent,
-          outcome: note.outcome,
-          ...(note.gate !== undefined ? { gate: note.gate } : {}),
-        };
-        await step.do(`${prefix}/note/${++notes}`, STEP_CONFIG, () => call(bot, "round", body));
-      } else {
-        // A merge_ready ending names the pull request as it is at the APPROVED
-        // head (agent-ship item 9): one more pr-check reads the facts fresh —
-        // auto-merge may have been switched on since the round's check, or it
-        // may already have fired, in which case the answer is `merged` and the
-        // report says so rather than naming a gate that has passed. An
-        // unreadable answer just leaves the facts out.
-        let endFacts: MergeReadyFacts | undefined;
-        if (note.ending.kind === "merge_ready") {
-          try {
-            const check = prCheckReturn(
-              `${prefix}/end/pr-facts`,
-              answerOf(
-                "pr-check",
-                await step.do(`${prefix}/end/pr-facts`, STEP_CONFIG, () =>
-                  call(bot, "pr-check", { ...tag, checks: true }),
+  let endedAt: number | undefined;
+  try {
+    for (;;) {
+      const action = nextAction(state);
+      if (action.type === "end") return { ...action.ending, ...(endedAt !== undefined ? { endedAt } : {}) };
+      // Keep the current round across its non-round phases (for example merge)
+      // while replacing it whenever the pipeline names a new one.
+      last = {
+        step: action.step,
+        ...("round" in state.phase
+          ? { round: state.phase.round }
+          : last.round !== undefined
+            ? { round: last.round }
+            : {}),
+      };
+      const transition = applyReturn(state, await perform(step, bot, instanceId, unit, action));
+      state = transition.state;
+      for (const note of transition.notes) {
+        if (note.type === "round") {
+          const body = {
+            ...tag,
+            index: note.index,
+            agent: note.agent,
+            outcome: note.outcome,
+            ...(note.gate !== undefined ? { gate: note.gate } : {}),
+          };
+          const noteStep = `${prefix}/note/${++notes}`;
+          last = { step: noteStep, round: { index: note.index, kind: note.agent } };
+          await step.do(noteStep, STEP_CONFIG, () => call(bot, "round", body));
+        } else {
+          // A merge_ready ending names the pull request as it is at the APPROVED
+          // head (agent-ship item 9): one more pr-check reads the facts fresh —
+          // auto-merge may have been switched on since the round's check, or it
+          // may already have fired, in which case the answer is `merged` and the
+          // report says so rather than naming a gate that has passed. An
+          // unreadable answer just leaves the facts out.
+          let endFacts: MergeReadyFacts | undefined;
+          if (note.ending.kind === "merge_ready") {
+            try {
+              const factsStep = `${prefix}/end/pr-facts`;
+              last = { step: factsStep, ...(last.round !== undefined ? { round: last.round } : {}) };
+              const check = prCheckReturn(
+                factsStep,
+                answerOf(
+                  "pr-check",
+                  await step.do(factsStep, STEP_CONFIG, () => call(bot, "pr-check", { ...tag, checks: true })),
                 ),
-              ),
-            );
-            if (check.type === "pr-check" && check.pr.state === "merged")
-              endFacts = { merged: { sha: check.pr.sha, mergedAt: check.pr.mergedAt } };
-            else if (check.type === "pr-check" && check.pr.state === "open")
-              endFacts = {
-                ...(check.pr.autoMergeEnabled !== undefined ? { autoMergeEnabled: check.pr.autoMergeEnabled } : {}),
-                // The checks at the approved head (record 0055): the report's
-                // headline is a claim about them, never "merge-ready" over a red one.
-                ...(check.pr.checks !== undefined ? { checks: check.pr.checks } : {}),
-                // The ready state beside them (agent-ship item 9): a conflicting
-                // head, or one carrying an unsquashed fix-up commit, is reported
-                // approved-but-not-merge-ready, never "merge-ready".
-                ...(check.pr.mergeableState !== undefined ? { mergeableState: check.pr.mergeableState } : {}),
-                ...(check.pr.fixupCommits !== undefined ? { fixupCommits: check.pr.fixupCommits } : {}),
-              };
-          } catch {
-            // the report simply omits the fact
+              );
+              if (check.type === "pr-check" && check.pr.state === "merged")
+                endFacts = { merged: { sha: check.pr.sha, mergedAt: check.pr.mergedAt } };
+              else if (check.type === "pr-check" && check.pr.state === "open")
+                endFacts = {
+                  ...(check.pr.autoMergeEnabled !== undefined ? { autoMergeEnabled: check.pr.autoMergeEnabled } : {}),
+                  // The checks at the approved head (record 0055): the report's
+                  // headline is a claim about them, never "merge-ready" over a red one.
+                  ...(check.pr.checks !== undefined ? { checks: check.pr.checks } : {}),
+                  // The ready state beside them (agent-ship item 9): a conflicting
+                  // head, or one carrying an unsquashed fix-up commit, is reported
+                  // approved-but-not-merge-ready, never "merge-ready".
+                  ...(check.pr.mergeableState !== undefined ? { mergeableState: check.pr.mergeableState } : {}),
+                  ...(check.pr.fixupCommits !== undefined ? { fixupCommits: check.pr.fixupCommits } : {}),
+                  // The base's merge-queue rule (issue 2011): the merge:person
+                  // path names "queued" in its remaining-gate line.
+                  ...(check.pr.baseHasMergeQueue !== undefined
+                    ? { baseHasMergeQueue: check.pr.baseHasMergeQueue }
+                    : {}),
+                };
+            } catch {
+              // the report simply omits the fact
+            }
           }
-        }
-        // The last coding child's run is named so the bot can put its handoff
-        // — the deviations it recorded — on the unit's board issue beside the
-        // ending (agent-ship item 14).
-        const body = {
-          ...tag,
-          // Two copies (routing-and-config item 28): the full report for the
-          // row and the board, and the thread's at the request's verbosity.
-          ending: {
-            kind: note.ending.kind,
-            report: renderUnitReport(state, endFacts),
-            threadReport: renderUnitReport(state, endFacts, state.input.verbosity ?? DEFAULT_VERBOSITY),
-            // An idle ending carries its continuation facts (record 0051): the
-            // bot writes them on the row's `idle` in place of an ending, with
-            // the coding run id it already receives below.
-            ...(note.ending.kind === "idle"
+          // The last coding child's run is named so the bot can put its handoff
+          // — the deviations it recorded — on the unit's board issue beside the
+          // ending (agent-ship item 14).
+          const body = {
+            ...tag,
+            // Two copies (routing-and-config item 28): the full report for the
+            // row and the board, and the thread's at the request's verbosity.
+            ending: {
+              kind: note.ending.kind,
+              report: renderUnitReport(state, endFacts),
+              threadReport: renderUnitReport(state, endFacts, state.input.verbosity ?? DEFAULT_VERBOSITY),
+              // An idle ending carries its continuation facts (record 0051): the
+              // bot writes them on the row's `idle` in place of an ending, with
+              // the coding run id it already receives below.
+              ...(note.ending.kind === "idle"
+                ? {
+                    why: note.ending.why,
+                    renewalsLeft: note.ending.renewalsLeft,
+                    ...(note.ending.from !== undefined ? { from: note.ending.from } : {}),
+                    spendUsd: note.ending.spendUsd,
+                    ...(note.ending.handoff !== undefined ? { handoff: note.ending.handoff } : {}),
+                  }
+                : {}),
+            },
+            ...(state.pr !== undefined ? { pr: state.pr } : {}),
+            // A review_pending ending names the child's own last push so the next
+            // attempt's pre-check can start at the review round (the row's lastPush)
+            // — an idled one the same, off the idle's `from` (record 0051).
+            ...(note.ending.kind === "review_pending" && note.ending.headSha !== undefined
+              ? { headSha: note.ending.headSha }
+              : note.ending.kind === "idle" && note.ending.why === "review_pending" && note.ending.from !== undefined
+                ? { headSha: note.ending.from }
+                : {}),
+            ...(state.lastCodingRunId !== undefined ? { codingRunId: state.lastCodingRunId } : {}),
+            // A continued ending is a segment's end, not the unit's: the bot
+            // writes the renewal as a row keyed by the next segment's index
+            // (decision 0046), so a runner reclaimed here never renews twice.
+            ...(note.ending.kind === "continued"
               ? {
-                  why: note.ending.why,
-                  renewalsLeft: note.ending.renewalsLeft,
-                  ...(note.ending.from !== undefined ? { from: note.ending.from } : {}),
-                  spendUsd: note.ending.spendUsd,
-                  ...(note.ending.handoff !== undefined ? { handoff: note.ending.handoff } : {}),
+                  segment: {
+                    index: note.ending.segment,
+                    ...(note.ending.from !== undefined ? { from: note.ending.from } : {}),
+                    runId: note.ending.runId,
+                  },
                 }
               : {}),
-          },
-          ...(state.pr !== undefined ? { pr: state.pr } : {}),
-          // A review_pending ending names the child's own last push so the next
-          // attempt's pre-check can start at the review round (the row's lastPush)
-          // — an idled one the same, off the idle's `from` (record 0051).
-          ...(note.ending.kind === "review_pending" && note.ending.headSha !== undefined
-            ? { headSha: note.ending.headSha }
-            : note.ending.kind === "idle" && note.ending.why === "review_pending" && note.ending.from !== undefined
-              ? { headSha: note.ending.from }
-              : {}),
-          ...(state.lastCodingRunId !== undefined ? { codingRunId: state.lastCodingRunId } : {}),
-          // A continued ending is a segment's end, not the unit's: the bot
-          // writes the renewal as a row keyed by the next segment's index
-          // (decision 0046), so a runner reclaimed here never renews twice.
-          ...(note.ending.kind === "continued"
-            ? {
-                segment: {
-                  index: note.ending.segment,
-                  ...(note.ending.from !== undefined ? { from: note.ending.from } : {}),
-                  runId: note.ending.runId,
-                },
-              }
-            : {}),
-        };
-        await step.do(`${prefix}/end`, STEP_CONFIG, () => call(bot, "unit-end", body));
+          };
+          const endStep = `${prefix}/end`;
+          last = { step: endStep, ...(last.round !== undefined ? { round: last.round } : {}) };
+          const endAnswer = answerOf(
+            "unit-end",
+            await step.do(endStep, STEP_CONFIG, () => call(bot, "unit-end", body)),
+          );
+          endedAt = endAnswer.body.at;
+        }
       }
     }
+  } catch (err) {
+    // The walk-dies-before-unit-end path (issue 2100): the throw becomes the
+    // unit's ending before it fails the instance, never the bare seal.
+    await tellStepThrew(step, bot, prefix, tag, state.pr, last, err);
+    throw err;
   }
 }
 
@@ -856,6 +984,24 @@ function blockedReport(unit: string, dep: string, depEnding: string): string {
   return `⛔ Blocked: ${unit} waits on ${dep}, which ended ${depEnding}${person ? " — a person's merge" : ""}. Re-issue the plan naming the remaining units once it is ${person ? "merged" : "resolved"}.`;
 }
 
+/** End a unit that never entered `runUnit` under the same failure net. */
+async function endUnrunUnit(
+  step: StepRunner,
+  bot: CoordinatorBot,
+  instanceId: string,
+  unit: string,
+  ending: { kind: "stopped" | "blocked"; report: string },
+): Promise<void> {
+  const tag = { parentInstanceId: instanceId, unit };
+  const endStep = `${unit}/end`;
+  try {
+    await step.do(endStep, STEP_CONFIG, () => call(bot, "unit-end", { ...tag, ending }));
+  } catch (err) {
+    await tellStepThrew(step, bot, unit, tag, undefined, { step: endStep }, err);
+    throw err;
+  }
+}
+
 /** The graph as one plan answer carries it: the instance's unit rows, in the plan's order. */
 function graphOf(plan: PlanFacts, instanceId: string): PlanGraph {
   return {
@@ -900,6 +1046,106 @@ function rereadCursor(cursor: PlanCursor, fresh: PlanGraph): { cursor: PlanCurso
   return { cursor: { order, status }, gone };
 }
 
+type IdleResult =
+  | { kind: "segment"; session: LeaseSegmentProgress }
+  | { kind: "ending"; ending: Extract<UnitEnding, { kind: "idle_expired" }> | { kind: "stopped" } };
+
+/** Park one unit behind its indexed wait. A timeout closes the idle; a wake
+ * answer is durable at the bot, so this loop may safely move to the next index
+ * after a transport failure without deciding the same event twice. */
+async function waitOnIdle(
+  step: StepRunner,
+  bot: CoordinatorBot,
+  instanceId: string,
+  unit: string,
+  prefix: string,
+  idle: Extract<DrivenEnding, { kind: "idle" }>,
+  idleDays: number,
+  currentSession: LeaseSegmentProgress | undefined,
+): Promise<IdleResult> {
+  const deadline = (idle.endedAt ?? 0) + idleDays * DAY_MS;
+  let now = idle.endedAt ?? 0;
+  for (let index = 1; ; index += 1) {
+    const waitId = `${prefix}/idle/${index}`;
+    const timeout = Math.max(1, deadline - now);
+    try {
+      await step.waitForEvent(waitId, { type: unitNudgeEventType({ instanceId, unit }), timeout });
+    } catch {
+      const ending = { kind: "idle_expired" as const, reviewRounds: idle.reviewRounds };
+      const endStep = `${waitId}/end`;
+      await step.do(endStep, STEP_CONFIG, () =>
+        call(bot, "unit-end", {
+          parentInstanceId: instanceId,
+          unit,
+          ending: {
+            kind: ending.kind,
+            report: "⌛ Idle expired: no reply continued this unit before its idle window closed.",
+          },
+        }),
+      );
+      return { kind: "ending", ending };
+    }
+    let wake: { answer: UnitWakeAnswer; at: number };
+    try {
+      wake = readWakeAnswer(
+        answerOf(
+          "unit-wake",
+          await step.do(`${waitId}/wake`, STEP_CONFIG, () =>
+            call(bot, "unit-wake", { parentInstanceId: instanceId, unit, waitId }),
+          ),
+        ),
+      );
+    } catch {
+      // The event remains unconsumed when the wake could not store an answer.
+      // A stored answer is replayed by the next identity, so either way the
+      // next indexed wait is the safe place to listen again.
+      continue;
+    }
+    now = wake.at;
+    const answer = wake.answer;
+    if (answer.kind === "answered") continue;
+    if (answer.kind === "expired") {
+      const ending = { kind: "idle_expired" as const, reviewRounds: idle.reviewRounds };
+      await step.do(`${waitId}/end`, STEP_CONFIG, () =>
+        call(bot, "unit-end", {
+          parentInstanceId: instanceId,
+          unit,
+          ending: {
+            kind: ending.kind,
+            report: "⌛ Idle expired: the unit reached its indexed wake limit.",
+          },
+        }),
+      );
+      return { kind: "ending", ending };
+    }
+    if (answer.kind === "stopped") {
+      await step.do(`${waitId}/end`, STEP_CONFIG, () =>
+        call(bot, "unit-end", {
+          parentInstanceId: instanceId,
+          unit,
+          ending: { kind: "stopped", report: "⏹ Stopped: the idle unit was ended by an operator." },
+        }),
+      );
+      return { kind: "ending", ending: { kind: "stopped" } };
+    }
+    return {
+      kind: "segment",
+      session: {
+        segment: answer.index,
+        renewalsSpent: answer.leaseMs !== undefined ? (currentSession?.renewalsSpent ?? 0) : answer.index - 1,
+        spendUsd: answer.spendUsd,
+        ...(answer.from !== undefined ? { continueFrom: answer.from } : {}),
+        ...(answer.runId !== undefined ? { previousRunId: answer.runId } : {}),
+        ...(answer.handoff !== undefined ? { previousHandoff: answer.handoff } : {}),
+        ...(answer.texts.length > 0 ? { texts: answer.texts } : {}),
+        ...(answer.leaseMs !== undefined
+          ? { resume: { leaseMs: answer.leaseMs, attempt: (currentSession?.resume?.attempt ?? 0) + 1 } }
+          : {}),
+      },
+    };
+  }
+}
+
 /** The plan: its units one at a time in dependency order, then the endings of the units it never reached. */
 async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string): Promise<PlanRunSummary> {
   // The selection is read at every unit boundary (the orchestration-plane plan): the first read opens
@@ -926,8 +1172,7 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
     if (plan.stopped) {
       for (const id of cursor.order.filter((u) => endings[u] === undefined)) {
         endings[id] = "stopped";
-        const body = { parentInstanceId: instanceId, unit: id, ending: { kind: "stopped", report: stoppedReport(id) } };
-        await step.do(`${id}/end`, STEP_CONFIG, () => call(bot, "unit-end", body));
+        await endUnrunUnit(step, bot, instanceId, id, { kind: "stopped", report: stoppedReport(id) });
       }
       break;
     }
@@ -935,21 +1180,45 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
     if (next === undefined) break;
     cursor = startUnit(graph, cursor, next);
     const node = graph.units.find((u) => u.id === next)!;
-    let ending = await runUnit(step, bot, instanceId, node, plan);
-    // The lease continues while the grant renews (decision 0046): each
-    // `continued` ending opens the next segment of the same unit — a fresh
-    // pipeline under a fresh lease, from the recorded sha, briefed with the
-    // previous segment's write-up — until the unit ends some other way.
-    while (ending.kind === "continued") {
-      const c = ending;
-      ending = await runUnit(step, bot, instanceId, node, plan, {
-        segment: c.segment,
-        renewalsSpent: c.segment - 1,
-        spendUsd: c.spendUsd,
-        ...(c.from !== undefined ? { continueFrom: c.from } : {}),
-        previousRunId: c.runId,
-        ...(c.handoff !== undefined ? { previousHandoff: c.handoff } : {}),
-      });
+    let session: LeaseSegmentProgress | undefined;
+    let ending: DrivenEnding | { kind: "stopped" } = await runUnit(step, bot, instanceId, node, plan);
+    // A machine-renewed continuation opens at once. An idle continuation parks
+    // the whole walk and opens only when the durable wake answer names the
+    // segment (or settles as stopped/expired).
+    for (;;) {
+      if (ending.kind === "continued") {
+        const c = ending;
+        session = {
+          segment: c.segment,
+          renewalsSpent: c.segment - 1,
+          spendUsd: c.spendUsd,
+          ...(c.from !== undefined ? { continueFrom: c.from } : {}),
+          previousRunId: c.runId,
+          ...(c.handoff !== undefined ? { previousHandoff: c.handoff } : {}),
+        };
+        ending = await runUnit(step, bot, instanceId, node, plan, session);
+        continue;
+      }
+      if (ending.kind === "idle") {
+        const parked = await waitOnIdle(
+          step,
+          bot,
+          instanceId,
+          next,
+          stepPrefixOf(next, session),
+          ending,
+          plan.idleDays,
+          session,
+        );
+        if (parked.kind === "ending") {
+          ending = parked.ending;
+          break;
+        }
+        session = parked.session;
+        ending = await runUnit(step, bot, instanceId, node, plan, session);
+        continue;
+      }
+      break;
     }
     endings[next] = ending.kind;
     // A unit is done for its dependents when the base carries its scope: the
@@ -975,12 +1244,10 @@ async function walk(step: StepRunner, bot: CoordinatorBot, instanceId: string):
   for (const id of blocked) {
     const node = graph.units.find((u) => u.id === id)!;
     const dep = node.dependsOn.find((d) => cursor.status[d] === "failed" || cursor.status[d] === "blocked")!;
-    const body = {
-      parentInstanceId: instanceId,
-      unit: id,
-      ending: { kind: "blocked", report: blockedReport(id, dep, endings[dep]!) },
-    };
-    await step.do(`${id}/end`, STEP_CONFIG, () => call(bot, "unit-end", body));
+    await endUnrunUnit(step, bot, instanceId, id, {
+      kind: "blocked",
+      report: blockedReport(id, dep, endings[dep]!),
+    });
   }
   if (!plan.stopped && !cursorFinished(cursor))
     throw new Error(`the plan's cursor did not finish: ${JSON.stringify(cursor.status)}`);