@humwick/server 0.0.0-stage → 0.130.1

package/src/self-resume.ts

@@ -0,0 +1,884 @@
+import { renderSelfCareState } from "./services/self-care-state";
+import { agentPrincipalSink } from "./db/agent-ownership";
+import { isRecord } from "@humwick/sdk";
+import { createCommand, listCommands, listInjectionAttempts, listPendingInjectionAttemptIds } from "./commands-db";
+import type { InjectionAttempt } from "./db/injection-attempts";
+import { emitCommandEvent } from "./command-events";
+import { INJECTION_SWEEP_BACKLOG_INTERVAL_MS, pacedInjectionSweep } from "./injection-sweep-pacing";
+import { MAX_BODY_BYTES, REAP_INTERVAL_MS } from "./config";
+import { getSelfResumeConfig } from "./config-store";
+import {
+  archiveAndAdvanceContinuationAsync,
+  archiveContinuationSegmentAsync,
+  ensureContinuationEnvelope,
+  findMessageByIdempotencyKey,
+  getAgent,
+  getContinuationEnvelope,
+  getMessage,
+  listUncommandedContextResets,
+  markSelfResumeContinuationIngested,
+  selfResumeContinuationIngested,
+  sendMessage,
+  updateContinuationAfterCompact,
+  updateContinuationObjective,
+  ValidationError,
+} from "./db";
+import { emitRelayEvent } from "./events";
+import { emitMessageDeliveryUpdated } from "./sse";
+import { boundaryCaptureClause } from "./memory-boundary-capture";
+import { routeNotification } from "./notification-router";
+import { renderTemplate } from "./prompt-resolver";
+import { augmentContinuationWithIdentity, identityContentForLifecycleCommand, type WhoamiIdentityCache } from "./self-resume-identity";
+import { assertSelfRestartSafePoint, createSelfRestartCommandAsync, type SelfRestartReason } from "./services/restart-spawn";
+import { isContinuationSelfResumeCommand } from "./self-resume-command";
+import { cancelSupersededInjects, supersedingGeneration } from "./self-resume-supersede";
+import { observedResetBoundary } from "./observed-reset-boundary";
+import { attachContextRecoveryCommand, openContextRecovery } from "./self-resume-carry";
+import type { AgentCard, Command, CommandStatus, ContinuationDecisionEntry, ContinuationEnvelope, ContinuationLedgerEntry, Message, SelfResumeMode } from "./types";
+
+interface CompactAndResumeInput {
+  agentId: string;
+  workingState: string;
+  ruledOut?: unknown;
+  mode?: SelfResumeMode;
+  objective?: string;
+  restart?: boolean;
+  reason?: SelfRestartReason;
+}
+
+interface CompactAndResumeResult {
+  ok: boolean;
+  /** #3442 — the command is queued; the runner runs it once the caller's turn ends, so end the turn now. */
+  status: "scheduled";
+  mode: SelfResumeMode | "restart";
+  generation: number;
+  commandId: string;
+  continuationChars?: number;
+  continuationMessageId?: number;
+  ledgerEntries: number;
+  /** #2005 — duplicate working-state blocks the store collapsed. Present only when it collapsed
+   *  some, so the caller learns it is re-sending state it already carried forward. */
+  dedupedWorkingStateBlocks?: number;
+}
+
+const VALID_RESUME_MODES = ["clear-inject", "native"] as const;
+
+export async function compactAndResume(input: CompactAndResumeInput): Promise<CompactAndResumeResult> {
+  const agent = getAgent(input.agentId);
+  if (!agent) throw new ValidationError("agent not found");
+  const config = getSelfResumeConfig();
+  const mode = input.mode ?? config.defaultMode;
+  if (!VALID_RESUME_MODES.includes(mode)) throw new ValidationError(`mode must be one of: ${VALID_RESUME_MODES.join(", ")}`);
+  if (input.restart) await assertSelfRestartSafePoint(agent);
+  else assertResumeSupported(agent, mode);
+
+  const now = Date.now();
+  let envelope = ensureContinuationEnvelope({
+    agentId: agent.id,
+    objective: input.objective,
+    now,
+  });
+  if (input.objective !== undefined && envelope.objective !== input.objective) {
+    envelope = updateContinuationObjective({ agentId: agent.id, objective: input.objective, now });
+  }
+
+  const workingState = input.workingState.trim();
+  if (!workingState) throw new ValidationError("workingState required");
+  // Generation is allocated inside the writer operation; entries are stamped with that reserved
+  // generation there rather than guessing from this stale main-thread snapshot.
+  const ledgerEntries = parseRuledOut(input.ruledOut, 0, now);
+  const compacted = await archiveAndAdvanceContinuationAsync({
+    agentId: agent.id,
+    ledgerEntries,
+    workingState,
+    now,
+  });
+  const { archive, updated, generation } = { archive: compacted.archive, updated: compacted, generation: compacted.generation };
+  if (updated.droppedLedgerEntries.length) await archiveDroppedLedgerEntries(agent.id, generation, updated.droppedLedgerEntries, now);
+  // #1565 P5.2 (design §10.2) — the POST half of the split capture. It is resolved and baked in
+  // HERE, before the clear/compact/restart below, because after that step nothing this function
+  // did not persist survives: the continuation is the payload that crosses the boundary. The PRE
+  // half is elsewhere on purpose (src/context-advisory.ts) — it has to reach the agent while the
+  // generation it asks about still exists, and no line written at this point can do that.
+  const fullContinuation = renderContinuation(updated.envelope, {
+    memoryCapture: boundaryCaptureClause({ seam: "post", agentId: agent.id, now }),
+    liveRuns: renderSelfCareState(agent.id),
+  });
+  // #2836: no core copy here — the startup-context seam re-injects it beside this.
+  const continuationMessage = createContinuationRecoveryMessage(agent.id, generation, fullContinuation, now);
+  const continuation = insertRecoveryPointerAfterIntro(fullContinuation, continuationMessage.id);
+  openContextRecovery(agent.id, generation, now);
+  const command = input.restart
+    ? await createSelfRestartCommandAsync(agent, generation, continuation, continuationMessage.id, input.reason ?? "manual", now)
+    : mode === "native"
+      ? createNativeCompact(agent.id, generation, continuation, continuationMessage.id)
+      : createClearThenInject(agent.id, generation, continuation, continuationMessage.id);
+  attachContextRecoveryCommand(agent.id, generation, command.id);
+  emitCommandEvent(command, "command.requested");
+  return {
+    ok: true,
+    status: "scheduled",
+    mode: input.restart ? "restart" : mode,
+    generation,
+    commandId: command.id,
+    continuationChars: continuation.length,
+    continuationMessageId: continuationMessage.id,
+    ledgerEntries: updated.envelope.ledger.length,
+    ...(updated.dedupedWorkingStateBlocks ? { dedupedWorkingStateBlocks: updated.dedupedWorkingStateBlocks } : {}),
+  };
+}
+
+export interface ForcedResumePlan {
+  commandType: "agent.compact" | "agent.clearContext";
+  /** Extra command params to MERGE onto the forced-compaction command (selfResume, and — for the
+   *  native path — the `/compact <continuation>` instructions). */
+  params: Record<string, unknown>;
+  mode: SelfResumeMode;
+  generation: number;
+}
+
+// #2004 — the FORCED (server-initiated) context-limit boundary has no fresh workingState from the
+// agent (the agent is out of context — it never got to call relay_compact_and_resume). So the
+// resume plan DEGRADES to the LAST-STORED continuation envelope: it re-renders and re-embeds the
+// envelope that was already persisted, rather than capturing/advancing a new generation. That keeps
+// this path synchronous (no archive write) and, crucially, never invents a blank continuation.
+//
+// Provider-shape selection (#2004 review MAJOR-1 / round-3):
+//   * The provider MUST advertise a resume ROUTE (context.resume !== "none"). A resume:"none"
+//     provider — even one that can compact — has NO promised native/clear-inject handshake, so
+//     attaching a self-resume plan would start NativeSelfResumeTracker against a compact that never
+//     emits compacted+idle → the native-self-resume timeout fires → command settles `failed` →
+//     NEITHER the continuation
+//     inject NOR the bare-command identity/startup inject fires: the exact silent post-compact
+//     strand this issue exists to kill. Such a provider returns null here and falls through to a
+//     bare compact, whose identity/startup hooks still reinject the charter. This matches the
+//     assertResumeSupported capability contract.
+//   * With a resume route, a provider that can compact (context.compact) uses an IN-PLACE
+//     agent.compact so its OWN current-thread summary is preserved — critical because the forced
+//     envelope may be STALE (work since the last self-resume lives only in that summary). The stored
+//     envelope + identity are re-injected AFTER the compact by the post-command inject. Claude
+//     (resume "native", compact accepts instructions) additionally passes the continuation as
+//     `/compact <instructions>`; codex (resume "clear-inject" but compact-capable, no instruction
+//     support) compacts in place and relies solely on the post-command inject — we must NOT pretend
+//     it supports instructioned compaction. Both settle through the native self-resume handshake,
+//     which codex's awaited threadCompactStart (emits compacted+idle) resolves.
+//   * A compaction-LESS clear+inject provider uses agent.clearContext with a coupled,
+//     identity-augmented continuation (there is no in-place summary to preserve).
+//
+// The `selfResume` payload matches the self-initiated createNativeCompact / createClearThenInject
+// shapes, so the reactive/sweep reinjection (#1023) plus the #1998 objective-epoch render guarantees
+// apply unchanged. Returns null (→ caller falls back to a bare compact) when the provider has no
+// resume route / no re-injection channel OR the agent has no stored envelope yet.
+export function buildForcedResumePlan(agentId: string, now = Date.now()): ForcedResumePlan | null {
+  const agent = getAgent(agentId);
+  if (!agent) return null;
+  const context = agent.providerCapabilities?.context;
+  if (!context) return null;
+  // No advertised resume route → do NOT attach a self-resume plan (see the strand hazard above).
+  if (context.resume !== "native" && context.resume !== "clear-inject") return null;
+  const canInject = context.inject === true;
+  // In-place compact (preserves the provider's summary) — gated on a promised resume route:
+  //   * resume "native": instruction-capable compact + native handshake (Claude); the continuation
+  //     also rides /compact <instructions>, so it does not additionally require inject.
+  //   * resume "clear-inject" + compact + inject: codex — compacts in place, envelope rides the
+  //     post-command inject, so it DOES require inject.
+  const useNativeCompact = context.resume === "native"
+    ? context.compact === true
+    : context.compact === true && canInject;
+  // A compaction-LESS provider resumes via clear+inject.
+  const useClearInject = !useNativeCompact && context.clear === true && canInject;
+  if (!useNativeCompact && !useClearInject) return null;
+  const envelope = getContinuationEnvelope(agentId);
+  if (!envelope) return null;
+  const generation = envelope.generation;
+  const fullContinuation = renderContinuation(envelope, {
+    memoryCapture: boundaryCaptureClause({ seam: "post", agentId, now }),
+    liveRuns: renderSelfCareState(agentId),
+  });
+  const continuationMessage = createContinuationRecoveryMessage(agentId, generation, fullContinuation, now);
+  const continuation = insertRecoveryPointerAfterIntro(fullContinuation, continuationMessage.id);
+  if (useNativeCompact) {
+    // Preserve the provider's in-place summary; re-inject the (possibly stale) envelope AFTER.
+    return {
+      commandType: "agent.compact",
+      mode: "native",
+      generation,
+      params: {
+        // Only a provider whose compact accepts instructions (resume === "native") gets the
+        // continuation as `/compact <instructions>`; codex compacts in place + post-command inject.
+        ...(context.resume === "native" ? { instructions: continuation } : {}),
+        selfResume: { generation, mode: "native", continuation, fullContextMessageId: continuationMessage.id },
+      },
+    };
+  }
+  // clear-inject: bake identity into the coupled continuation exactly like createClearThenInject, so
+  // a provider whose clearContext couples the inject in-process (#1588) carries the charter with it.
+  const coupledContinuation = augmentContinuationWithIdentity(agentId, continuation);
+  return {
+    commandType: "agent.clearContext",
+    mode: "clear-inject",
+    generation,
+    params: {
+      selfResume: { generation, mode: "clear-inject", continuation: coupledContinuation, fullContextMessageId: continuationMessage.id },
+    },
+  };
+}
+
+function continuationRecoveryPointer(messageId: number): string {
+  return `Recovery pointer: use relay_get_message with message id ${messageId} to read your full prior context.`;
+}
+
+function insertRecoveryPointerAfterIntro(continuation: string, messageId: number): string {
+  const pointer = continuationRecoveryPointer(messageId);
+  const firstNewline = continuation.indexOf("\n");
+  if (firstNewline === -1) return `${continuation.trimEnd()}\n\n${pointer}`;
+  return `${continuation.slice(0, firstNewline).trimEnd()}\n${pointer}${continuation.slice(firstNewline)}`;
+}
+
+function createContinuationRecoveryMessage(agentId: string, generation: number, continuation: string, now: number) {
+  const idempotencyKey = `self-resume-continuation:${agentId}:${generation}`;
+  const existing = findMessageByIdempotencyKey("system", idempotencyKey);
+  if (existing) return existing;
+  return sendMessage({
+    from: "system",
+    to: agentId,
+    kind: "system",
+    subject: `Self-resume continuation generation ${generation}`,
+    body: continuation,
+    replyExpected: false,
+    idempotencyKey,
+    maxAgeSeconds: null,
+    occurredAt: now,
+    payload: {
+      kind: "agent.self_resume_continuation",
+      agentId,
+      generation,
+      fullEnvelope: true,
+      // The durable chat artifact is recoverable immediately, but it is not evidence the fresh
+      // provider session accepted it. The runner promotes this only after turn/start acceptance.
+      delivery: { state: "stored" },
+    },
+  });
+}
+
+// #1023 — the ruledOut ledger bound (see updateContinuationAfterCompact) drops the
+// oldest entries once the persisted ledger grows past its cap instead of letting a
+// long-running agent render a multi-megabyte continuation. Dropped entries are not
+// destroyed: they're archived alongside the workingState segments so relay_recall
+// still finds them. Chunked well under archiveContinuationSegment's MAX_BODY_BYTES
+// limit since a large drop batch could otherwise exceed a single segment's cap.
+const DROPPED_LEDGER_ARCHIVE_CHUNK_BYTES = MAX_BODY_BYTES / 2;
+
+async function archiveDroppedLedgerEntries(agentId: string, generation: number, dropped: ContinuationLedgerEntry[], now: number): Promise<void> {
+  let chunk: string[] = [];
+  let chunkBytes = 0;
+  const flush = async () => {
+    if (!chunk.length) return;
+    await archiveContinuationSegmentAsync({
+      agentId,
+      generation,
+      segment: `Ruled-out ledger entries dropped for size (search via relay_recall):\n${chunk.join("\n")}`,
+      now,
+    });
+    chunk = [];
+    chunkBytes = 0;
+  };
+  for (const entry of dropped) {
+    const line = renderLedgerLine(entry);
+    const lineBytes = new TextEncoder().encode(line).byteLength;
+    if (chunk.length && chunkBytes + lineBytes > DROPPED_LEDGER_ARCHIVE_CHUNK_BYTES) await flush();
+    chunk.push(line);
+    chunkBytes += lineBytes;
+  }
+  await flush();
+}
+
+interface PendingInjection {
+  continuation: string;
+  mode: string;
+  generation?: number;
+  fullContextMessageId?: number;
+}
+
+function extractPendingInjection(command: Command): PendingInjection | null {
+  if (!isContinuationSelfResumeCommand(command)) return null;
+  const resume = isRecord(command.params.selfResume) ? command.params.selfResume : undefined;
+  // isContinuationSelfResumeCommand above proves this shape; retain the
+  // narrow runtime reads here for the payload construction below.
+  const mode = resume!.mode as string;
+  const continuation = resume!.continuation as string;
+  const generation = typeof resume?.generation === "number" ? resume.generation : undefined;
+  const fullContextMessageId = typeof resume?.fullContextMessageId === "number" ? resume.fullContextMessageId : undefined;
+  return { continuation, mode, generation, fullContextMessageId };
+}
+
+// #1588 — the runner now couples the continuation delivery into the clear command itself
+// (deliverCoupledContinuationAfterClear) and records continuationDelivered:true when it lands in
+// the settled fresh context. Skip the now-redundant separate inject on that happy path, but STILL
+// fire the reactive/sweep backstop when the flag is absent (older runner) or false (inline delivery
+// failed) — so none of the #1023 windows regress and a redundant inject is always chosen over a wipe.
+function continuationDeliveredInline(command: Command): boolean {
+  const result = isRecord(command.result) ? command.result : undefined;
+  const provider = result && isRecord(result.providerResult) ? result.providerResult : undefined;
+  return provider?.continuationDelivered === true;
+}
+
+/** Promote the persisted recovery artifact only from delivery evidence emitted by the runner.
+ * A successful clear command or a stored chat row alone is never enough. */
+export function settleSelfResumeContinuationIngestion(command: Command): void {
+  const result = isRecord(command.result) ? command.result : undefined;
+  const provider = result && isRecord(result.providerResult) ? result.providerResult : undefined;
+  let fullContextMessageId: number | undefined;
+  if ((command.type === "agent.clearContext" || command.type === "agent.compact") && continuationDeliveredInline(command)) {
+    const pending = extractPendingInjection(command);
+    fullContextMessageId = pending?.fullContextMessageId;
+  } else if (command.type === "agent.injectContext" && provider?.continuationIngested === true) {
+    const resume = isRecord(command.params.selfResume) ? command.params.selfResume : undefined;
+    fullContextMessageId = typeof resume?.fullContextMessageId === "number" ? resume.fullContextMessageId : undefined;
+  }
+  if (fullContextMessageId === undefined) return;
+  const message = markSelfResumeContinuationIngested(fullContextMessageId);
+  if (message) emitMessageDeliveryUpdated(message);
+}
+
+/** #2619 — a runner parks a continuation the provider refused under a usage/overload hold as a
+ * message to itself (payload.selfResumeFullContextMessageId). Its delivered report is the same
+ * delivery evidence an ingested injectContext result is: promote the recovery artifact. */
+export function settleParkedSelfResumeContinuation(message: Message): void {
+  const fullContextMessageId = message.payload?.selfResumeFullContextMessageId;
+  if (typeof fullContextMessageId !== "number" || message.from !== message.to) return;
+  if (getMessage(fullContextMessageId)?.to !== message.to) return;
+  const promoted = markSelfResumeContinuationIngested(fullContextMessageId);
+  if (promoted) emitMessageDeliveryUpdated(promoted);
+}
+
+// #1565 P4b — three DISTINCT payloads can now correlate to one clear/compact command: the
+// continuation, the identity block, and the memory preamble (§7 — memory and the continuity
+// envelope are re-injected BESIDE each other, never merged). The idempotency lookups below must
+// therefore be scoped by `reason`; an unscoped `correlationId` match would let whichever payload
+// landed first suppress the others, and would make a memory inject count as a continuation
+// delivery attempt in the #1023 sweep.
+const CONTINUATION_INJECTION_REASON = "self-resume-continuation";
+const IDENTITY_INJECTION_REASON = "agent-relay-identity";
+
+// Filtered in SQL, never out of a capped page (#1565 F7): the attempt cap and the idempotency
+// check are only sound if the list is COMPLETE for this (command, reason) pair.
+export function injectionAttemptsFor(command: Command, reason: string): InjectionAttempt[] {
+  return listInjectionAttempts(command.id, reason);
+}
+
+function buildInjectionParams(command: Command, injection: PendingInjection, cache?: WhoamiIdentityCache, replayEpoch?: string): Record<string, unknown> {
+  const content = identityContentForLifecycleCommand(command, injection.continuation, cache) ?? injection.continuation;
+  return {
+    reason: CONTINUATION_INJECTION_REASON,
+    content,
+    ...(replayEpoch ? { continuationReplayEpoch: replayEpoch } : {}),
+    selfResume: {
+      generation: injection.generation,
+      mode: injection.mode,
+      fullContextMessageId: injection.fullContextMessageId,
+      ...(command.type === "agent.clearContext" ? { afterClearCommandId: command.id } : {}),
+      ...(command.type === "agent.compact" ? { afterCompactCommandId: command.id } : {}),
+    },
+  };
+}
+
+function registrationReplayEpoch(agentId: string): string | undefined {
+  const agent = getAgent(agentId);
+  // Agent epoch advances only when a new instance takes over. Unlike lastSeen, it cannot churn on
+  // same-instance registration retries, so it is safe to persist as a replay idempotency key.
+  return agent ? `registration:${agent.epoch}` : undefined;
+}
+
+// #2043 F2 — a clear-inject whose `/clear` commit the runner could not POSITIVELY confirm now
+// settles FAILED (the runner's commit barrier) instead of the pre-#2043 silent success. Treat that
+// FAILED exactly like a succeeded/timed_out clear-inject for continuation RE-INJECTION: we cannot be
+// sure the clear did or did not commit, and — per the #1023 doctrine — a redundant re-inject is
+// always preferable to a silent mind-wipe. Scoped to clear-inject: a FAILED native compact keeps its
+// own exit-recovery (recoverNativeSelfResumeExit) and is deliberately NOT re-injected here.
+export function isFailedClearInjectSelfResume(command: Command): boolean {
+  if (command.status !== "failed" || command.type !== "agent.clearContext") return false;
+  return isContinuationSelfResumeCommand(command);
+}
+
+/** #3662 — an older generation's boundary is retired (its queued injects canceled), never delivered. */
+function retireIfSuperseded(command: Command): boolean {
+  const current = supersedingGeneration(command);
+  if (current === null) return false;
+  cancelSupersededInjects(listPendingInjectionAttemptIds(command.id, CONTINUATION_INJECTION_REASON), current);
+  return true;
+}
+
+export function enqueueContinuationInjectionAfterSelfResume(command: Command): Command | null {
+  if (command.status !== "succeeded" && !isFailedClearInjectSelfResume(command)) return null;
+  const injection = extractPendingInjection(command);
+  if (!injection || retireIfSuperseded(command)) return null;
+  if (continuationDeliveredInline(command)) return null;
+  if (injectionAttemptsFor(command, CONTINUATION_INJECTION_REASON).length) return null;
+  const inject = createCommand({
+    type: "agent.injectContext",
+    source: "system",
+    target: command.target,
+    correlationId: command.id,
+    params: buildInjectionParams(command, injection, undefined, registrationReplayEpoch(command.target)),
+  });
+  emitCommandEvent(inject, "command.requested");
+  return inject;
+}
+
+export function enqueueLifecycleIdentityInjectionAfterContextCommand(command: Command): Command | null {
+  if (command.status !== "succeeded") return null;
+  if (command.type !== "agent.clearContext" && command.type !== "agent.compact") return null;
+  if (extractPendingInjection(command)) return null;
+  const content = identityContentForLifecycleCommand(command);
+  if (!content) return null;
+  if (injectionAttemptsFor(command, IDENTITY_INJECTION_REASON).length) return null;
+  const inject = createCommand({
+    type: "agent.injectContext",
+    source: "system",
+    target: command.target,
+    correlationId: command.id,
+    params: {
+      reason: IDENTITY_INJECTION_REASON,
+      content,
+      agentRelayIdentity: {
+        ...(command.type === "agent.clearContext" ? { afterClearCommandId: command.id } : {}),
+        ...(command.type === "agent.compact" ? { afterCompactCommandId: command.id } : {}),
+      },
+    },
+  });
+  emitCommandEvent(inject, "command.requested");
+  return inject;
+}
+
+export function enqueueContinuationInjectionAfterClear(command: Command): Command | null {
+  return enqueueContinuationInjectionAfterSelfResume(command);
+}
+
+const CLEAR_OR_COMPACT_TYPES = ["agent.clearContext", "agent.compact"] as const;
+const INJECTION_SWEEP_TERMINAL_STATUSES: CommandStatus[] = ["succeeded", "timed_out"];
+const INJECTION_SWEEP_LOOKBACK_MS = 24 * 60 * 60 * 1000;
+/** One page per boundary type per tick. `listCommands` clamps to this anyway; naming it lets the
+ *  enumeration SAY when it truncated instead of silently dropping the oldest candidates. */
+const INJECTION_SWEEP_PAGE_LIMIT = 500;
+export const MAX_INJECTION_ATTEMPTS = 3;
+const IN_FLIGHT_OR_DONE_STATUSES: CommandStatus[] = ["succeeded", "pending", "accepted", "running"];
+
+/**
+ * #2291 — THE ONE definition of "this clear/compact boundary may have committed, so anything the
+ * boundary is supposed to re-deliver must be re-delivered".
+ *
+ * It is deliberately NOT "the command succeeded". A clear/compact command's status answers *did the
+ * runner CONFIRM the destructive step*, which is a different question from *did the destructive step
+ * HAPPEN*:
+ *   • `timed_out` — the runner's `command.update` was lost in transit; the clear/compact itself
+ *     usually ran (the #1023 windows).
+ *   • FAILED clear-inject — the runner's commit barrier could not POSITIVELY confirm the `/clear`
+ *     and fails on purpose (#2043 F2, `runner/src/runner-core.ts` `assertClearInjectCommitted`).
+ *     Pre-#2261 that barrier read tmux scrollback and was unsatisfiable on any pane with history, so
+ *     EVERY self-resume clear on a long-running agent reported `clearConfirmed:false`.
+ *
+ * In both cases relay cannot know, and the #1023 doctrine settles it: a redundant re-delivery is
+ * always preferable to a silent mind-wipe. Every consumer must FAIL TOWARD RE-DELIVERING.
+ *
+ * ONE home, because the set was previously spelled out inline in the sweep below while the memory
+ * seam (`src/memory-injection.ts`) carried its own STRICTER `=== "succeeded"` — and that private
+ * copy silently dropped the memory block on 14 of one coordinator's 17 boundaries (#2291). The
+ * divergence between the two, not either one alone, is the bug. Consumers are idempotent on their
+ * own (`injectionAttemptsFor` keyed by the boundary command id), so a wider set costs at most one
+ * redundant payload, never a duplicate command.
+ *
+ * NOT used by `enqueueContinuationInjectionAfterSelfResume`: its REACTIVE path deliberately leaves
+ * `timed_out` to the sweep below (a timed-out command has no settle event to react to), so widening
+ * it there would be a behaviour change, not a unification.
+ */
+export function boundaryMayHaveCommitted(command: Command): boolean {
+  return INJECTION_SWEEP_TERMINAL_STATUSES.includes(command.status) || isFailedClearInjectSelfResume(command);
+}
+
+/**
+ * #2293 — the CANDIDATE ENUMERATION every missed-boundary sweep shares: each clear/compact in the
+ * lookback that `boundaryMayHaveCommitted` accepts, with the cooperative-cancellation checkpoint at
+ * the per-candidate unit boundary (#1819 — a sweep may stop BETWEEN candidates, never inside one).
+ *
+ * A generator rather than a copied loop because the memory sweep (`src/memory-injection.ts`) must
+ * recover exactly the boundaries this one does. A second hand-rolled list is precisely how the
+ * memory seam drifted into its own stricter status gate and dropped 14 of one coordinator's 17
+ * boundaries (#2291); `boundaryMayHaveCommitted` unified the STATUS SET, and this unifies the
+ * lookback, the page bound and the abort discipline that go with it.
+ *
+ * The import direction is forced, not chosen: `memory-injection.ts` already imports this module, and
+ * the reverse edge would be an import cycle (`src/circular-deps.test.ts`, baseline 0). So the shared
+ * halves live HERE and each sweep keeps only its own payload-specific gating.
+ */
+/** Which boundary types are currently reporting a truncated page — so the warning below fires on
+ *  the way INTO that state and again only after it clears, never once a minute forever. */
+const truncatedSweepPages = new Set<string>();
+
+/** A full newest-first page means the OLDEST boundaries in the lookback (the likeliest misses) were
+ *  cut. Said once per trip into that state, never once per tick (proper paging is #2292's). */
+function noteSweepPage(pageKey: string, rows: number): void {
+  if (rows < INJECTION_SWEEP_PAGE_LIMIT) { truncatedSweepPages.delete(pageKey); return; }
+  if (truncatedSweepPages.size === truncatedSweepPages.add(pageKey).size) return;
+  console.warn(`[relay] injection sweep: ${pageKey} candidates hit the ${INJECTION_SWEEP_PAGE_LIMIT}-row page cap — the oldest boundaries in the ${INJECTION_SWEEP_LOOKBACK_MS / 3_600_000}h lookback are not being swept (#2292)`);
+}
+
+/** `target` scopes the read to one agent's boundaries (idx_commands_target_type_created): a
+ *  per-agent replay must never page the fleet-wide lookback and filter it in JS (#3378). */
+export function* sweepableBoundaryCommands(now: number, signal?: AbortSignal, target?: string): Generator<Command> {
+  const since = now - INJECTION_SWEEP_LOOKBACK_MS;
+  for (const type of CLEAR_OR_COMPACT_TYPES) {
+    if (signal?.aborted) return;
+    const page = listCommands({ type, since, limit: INJECTION_SWEEP_PAGE_LIMIT, ...(target ? { target } : {}) });
+    noteSweepPage(target ? `${target}:${type}` : type, page.length);
+    for (const command of page) {
+      if (signal?.aborted) return;
+      if (!boundaryMayHaveCommitted(command)) continue;
+      yield command;
+    }
+  }
+  // #3698 — resets Relay did not command are boundaries too, so their refresh is retried the same way.
+  const resets = listUncommandedContextResets(since, INJECTION_SWEEP_PAGE_LIMIT, target);
+  noteSweepPage(target ? `${target}:observed-reset` : "observed-reset", resets.length);
+  for (const reset of resets) {
+    if (signal?.aborted) return;
+    yield observedResetBoundary(reset);
+  }
+}
+
+/** What the attempt ledger says should happen to one (boundary, payload) pair. */
+export type InjectionAttemptDecision = "enqueue" | "in-flight" | "exhausted";
+
+/**
+ * #2293 — the ONE retry policy for any payload correlated to a boundary command.
+ *
+ * Three states, and each is load-bearing:
+ *   • `in-flight` — an attempt is pending/accepted/running or already succeeded. This is what makes
+ *     both the reactive settle (which runs twice for one command: bus update + HTTP PATCH) and the
+ *     sweep idempotent, keyed by the boundary command id.
+ *   • `enqueue` — no attempt, or only FAILED ones under the cap. A failed attempt is retried, which
+ *     is #1023 window 3 ("the inject command itself fails once, with no retry").
+ *   • `exhausted` — the cap is spent; the caller reports it ONCE instead of retrying forever against
+ *     an unreachable agent.
+ *
+ * Spelled once so the memory seam cannot answer this differently from the continuation seam — the
+ * same divergence class as #2291's status gate, one level down.
+ */
+export function injectionAttemptDecision(command: Command, reason: string): { decision: InjectionAttemptDecision; attempts: number } {
+  const attempts = injectionAttemptsFor(command, reason);
+  if (attempts.some((item) => IN_FLIGHT_OR_DONE_STATUSES.includes(item.status))) return { decision: "in-flight", attempts: attempts.length };
+  if (attempts.length >= MAX_INJECTION_ATTEMPTS) return { decision: "exhausted", attempts: attempts.length };
+  return { decision: "enqueue", attempts: attempts.length };
+}
+
+/**
+ * A continuation is the recovery artifact for a destructive context boundary.  Unlike optional
+ * memory/startup payloads, it may never be abandoned merely because a provider was briefly busy
+ * or unavailable. Failed commands remain a durable parked ledger and are replayed when the agent
+ * becomes usable again. Invalid payloads are terminal; readiness cannot repair them (#3662).
+ */
+function continuationInjectionAttemptDecision(command: Command, replayEpoch?: string): { decision: "enqueue" | "in-flight" | "parked"; attempts: number } {
+  const attempts = injectionAttemptsFor(command, CONTINUATION_INJECTION_REASON);
+  if (attempts.some((item) => IN_FLIGHT_OR_DONE_STATUSES.includes(item.status))) return { decision: "in-flight", attempts: attempts.length };
+  if (attempts.some((item) => item.status === "failed" && item.error === "content required")) return { decision: "parked", attempts: attempts.length };
+  // #2545 — dedupe on the DELIVERY EVENT, not the attempt ledger. Attempt statuses answer "did the
+  // runner confirm the command" (#2291 doctrine), which is a different question from "did the
+  // envelope reach the provider": an attempt that timed out or settled failed AFTER the runner
+  // accepted the payload leaves a provably-landed artifact behind a failed-looking ledger. Each
+  // new lifecycle epoch (every ready/idle edge, every registration) would otherwise consume
+  // exactly one more replay of that already-processed envelope — a no-op re-confirmation wake per
+  // idle edge for as long as the agent lives. Once the artifact is ingested, this boundary is
+  // DONE, for every epoch.
+  if (selfResumeContinuationIngested(extractPendingInjection(command)?.fullContextMessageId)) return { decision: "parked", attempts: attempts.length };
+  // A failed continuation is a durable parked record, not a reason for the periodic sweep to
+  // create another command every REAP interval. A new eligible lifecycle epoch may consume exactly
+  // one replay; the epoch is persisted on that new attempt so duplicate status frames are inert.
+  if (attempts.length > 0 && (!replayEpoch || attempts.some((item) => item.replayEpoch === replayEpoch))) return { decision: "parked", attempts: attempts.length };
+  return { decision: "enqueue", attempts: attempts.length };
+}
+
+// #1023 — periodic backstop for the three silent mind-wipe windows found in the
+// self-resume audit (relay message #176981):
+//   1. runner->relay `command.update` lost in transit, so the clear/compact command
+//      never reaches "succeeded" and just times out — the reactive inject in
+//      enqueueContinuationInjectionAfterSelfResume never fires.
+//   2. relay crash between persisting "succeeded" and creating the inject command.
+//   3. the inject command itself was never created. A failed inject is durably parked and retried
+//      only on a new eligible lifecycle epoch below, never on every periodic sweep.
+// This re-derives the missing inject directly from the durably persisted command
+// params — the same idempotency key (correlationId = the clear/compact command id)
+// used by the reactive path, so running this concurrently with it is safe. A
+// timed-out clear/compact is treated the same as succeeded: we cannot always tell
+// whether the runner's destructive step actually completed before the update was
+// lost, and a redundant-but-harmless re-injection is preferable to a permanent
+// silent mind-wipe. The sweep creates only a missing initial attempt; it never retries a failed
+// attempt by itself, so an unavailable-but-still-registered provider cannot grow commands forever.
+export function sweepMissedContinuationInjections(now: number = Date.now(), signal?: AbortSignal, targetAgentId?: string, replayEpoch?: string): { enqueuedCommandIds: string[]; aborted?: true } {
+  const enqueuedCommandIds: string[] = [];
+  // #1726 — shared across every candidate this tick: the identity rebuild only depends on the
+  // target agent, and every target must already exist in the (bounded) agent roster, so this
+  // caps the expensive whoami/role rebuild at one per distinct agent instead of one per command.
+  const identityCache: WhoamiIdentityCache = new Map();
+  // #2043 F2 — a FAILED clear-inject (commit-barrier no-op) is swept for re-injection too, same
+  // redundant-beats-wipe rationale as timed_out already carries here. #2291 moved the set itself
+  // into `boundaryMayHaveCommitted`, and #2293 moved the enumeration around it into
+  // `sweepableBoundaryCommands`, so the memory sweep beside this one cannot drift from either.
+  // #1819 — one candidate command is the unit: create-the-inject + emit-the-event must not be
+  // split, and the attempt-ledger read above it is what makes the sweep idempotent, so bailing
+  // between candidates simply leaves the rest for the next tick. SYNCHRONOUS job — inert on one
+  // thread until this grows an await.
+  for (const command of sweepableBoundaryCommands(now, signal, targetAgentId)) {
+    sweepContinuationBoundary(command, identityCache, enqueuedCommandIds, replayEpoch);
+  }
+  return { enqueuedCommandIds, ...(signal?.aborted ? { aborted: true as const } : {}) };
+}
+
+function sweepContinuationBoundary(command: Command, identityCache: WhoamiIdentityCache, enqueuedCommandIds: string[], replayEpoch?: string): void {
+  const injection = extractPendingInjection(command);
+  if (!injection || retireIfSuperseded(command)) return;
+  if (continuationDeliveredInline(command)) return;
+  const agent = getAgent(command.target);
+  if (!agent || agent.status === "offline") return;
+  const attemptEpoch = replayEpoch ?? registrationReplayEpoch(command.target);
+  const { decision } = continuationInjectionAttemptDecision(command, attemptEpoch);
+  if (decision !== "enqueue") return;
+  const inject = createCommand({
+    type: "agent.injectContext",
+    source: "system",
+    target: command.target,
+    correlationId: command.id,
+    params: buildInjectionParams(command, injection, identityCache, attemptEpoch),
+  });
+  emitCommandEvent(inject, "command.requested");
+  enqueuedCommandIds.push(inject.id);
+}
+
+/** #3724 — the job's form of {@link sweepMissedContinuationInjections}: the same units, one macrotask
+ *  each (the sync form held every candidate in one ~1.2s block and was breaker-paused). */
+async function sweepMissedContinuationInjectionsPaced(now: number, signal?: AbortSignal): Promise<{ enqueuedCommandIds: string[]; aborted?: true; moreWork?: true }> {
+  const enqueuedCommandIds: string[] = [];
+  const identityCache: WhoamiIdentityCache = new Map();
+  const { moreWork } = await pacedInjectionSweep(() => sweepableBoundaryCommands(now, signal), (command) => sweepContinuationBoundary(command, identityCache, enqueuedCommandIds), signal);
+  return { enqueuedCommandIds, ...(signal?.aborted ? { aborted: true as const } : {}), ...(moreWork ? { moreWork: true as const } : {}) };
+}
+
+/** Replay one parked continuation attempt for a new ready/idle or registration epoch. The epoch is
+ * persisted on the inject command, making repeated observations of the same lifecycle edge inert. */
+export function replayParkedContinuationInjections(agentId: string, lifecycleEpoch: string, now = Date.now()): { enqueuedCommandIds: string[] } {
+  return sweepMissedContinuationInjections(now, undefined, agentId, lifecycleEpoch);
+}
+
+export const SELF_RESUME_INJECTION_SWEEP_JOB = {
+  id: "self-resume-injection-sweep",
+  critical: false,
+  title: "Self-resume injection sweep",
+  description: "Re-deliver self-resume continuations whose inject was lost to a transport blip, a relay crash between persisting the clear/compact and enqueuing the inject, or a failed inject attempt (#1023).",
+  intervalMs: REAP_INTERVAL_MS,
+  backlogIntervalMs: INJECTION_SWEEP_BACKLOG_INTERVAL_MS,
+  runOnStart: true,
+  handler(context: { signal?: AbortSignal }) {
+    return sweepMissedContinuationInjectionsPaced(Date.now(), context.signal);
+  },
+};
+
+function notifyContinuationInjectionExhausted(command: Command, attempts: number): void {
+  const idempotencyKey = `self-resume-injection-exhausted:${command.target}:${command.id}`;
+  if (findMessageByIdempotencyKey(command.target, idempotencyKey)) return;
+  const agent = getAgent(command.target);
+  const payload = { kind: "agent.resume_injection_failed", agentId: command.target, commandId: command.id, attempts };
+  emitRelayEvent({ type: "agent.resume_injection_failed", source: "server", subject: command.target, data: payload });
+  const recipient = agent?.spawnedBy ?? agentPrincipalSink(command.target);
+  routeNotification({
+    type: "agent.resume_injection_failed",
+    scope: { agentId: command.target, parent: agent?.spawnedBy },
+    recipients: [recipient],
+    message: {
+      subject: "Self-resume continuation failed to inject",
+      body: `Agent \`${command.target}\` completed a self-resume ${command.type === "agent.compact" ? "compact" : "clear"} but its continuation could not be delivered after ${attempts} attempt(s). The agent may be running with an empty or stale context — check it and consider a manual relay_compact_and_resume or restart.`,
+      payload,
+      idempotencyKey,
+      from: command.target,
+      replyExpected: false,
+    },
+  });
+}
+
+// #2043 F4 — observability for a self-compact that did NOT apply. A self-resume clear/compact
+// command that settles FAILED means the agent's context was (probably) NOT compacted — the exact
+// silent no-op that let the #2043 runaway climb to ~750K tokens undetected. Surface it to the spawn
+// parent (and as a durable relay event) instead of swallowing it. Idempotent per command. This is
+// the ALARM; the continuation re-injection backstop (F2) is the separate recovery path.
+export function notifySelfResumeNoOp(command: Command): void {
+  if (command.status !== "failed" && command.status !== "timed_out") return;
+  if (command.type !== "agent.clearContext" && command.type !== "agent.compact") return;
+  const injection = extractPendingInjection(command);
+  if (!injection) return;
+  const idempotencyKey = `self-resume-noop:${command.target}:${command.id}`;
+  if (findMessageByIdempotencyKey(command.target, idempotencyKey)) return;
+  const agent = getAgent(command.target);
+  const kind = command.type === "agent.compact" ? "compact" : "context clear";
+  const payload = {
+    kind: "agent.self_resume_noop",
+    agentId: command.target,
+    commandId: command.id,
+    commandType: command.type,
+    mode: injection.mode,
+    generation: injection.generation,
+    error: command.error,
+  };
+  emitRelayEvent({ type: "agent.self_resume_noop", source: "server", subject: command.target, data: payload });
+  const recipient = agent?.spawnedBy ?? agentPrincipalSink(command.target);
+  const recovery = command.type === "agent.clearContext" || command.status === "timed_out"
+    ? "The relay re-injects the continuation as a backstop, but check the agent and consider a manual relay_compact_and_resume or restart."
+    : "The continuation remains persisted; check the agent and retry relay_compact_and_resume once it is responsive.";
+  routeNotification({
+    type: "agent.self_resume_noop",
+    scope: { agentId: command.target, parent: agent?.spawnedBy },
+    recipients: [recipient],
+    message: {
+      subject: "Self-compact did not apply",
+      body: `Agent \`${command.target}\` attempted a self-resume ${kind} but the command ${command.status.toUpperCase()}${command.error ? ` (${command.error})` : ""}. Its compact boundary was not confirmed — the agent may be running near the context ceiling. ${recovery}`,
+      payload,
+      idempotencyKey,
+      from: command.target,
+      replyExpected: false,
+    },
+  });
+}
+
+/**
+ * Render an envelope.
+ *
+ * `memoryCapture` is #1565 P5.2's POST clause and is OPT-IN per call, not baked in — this renderer
+ * has non-boundary callers (task hydration, the task-memory tool) for which "what survived this
+ * boundary" would simply be false. Only `compactAndResume`, the one path that is about to cross a
+ * boundary, passes it. Empty by default and trimmed off the tail, so every other caller's bytes
+ * are unchanged. `liveRuns` (#2882) is opt-in for the same reason.
+ */
+export function renderContinuation(
+  envelope: ContinuationEnvelope,
+  input: { intro?: string; memoryCapture?: string; liveRuns?: string } = {},
+): string {
+  const decisions = envelope.decisions.length ? envelope.decisions.map(renderDecisionEntry).join("\n") : "- none";
+  const rendered = renderTemplate("continuation.envelope", {
+    intro: input.intro ?? `You have been resumed by Agent Relay — generation ${envelope.generation}.`,
+    generation: String(envelope.generation),
+    objective: envelope.objective,
+    ruledOut: renderLedger(envelope.ledger, envelope.objectiveEpoch ?? 0),
+    decisions,
+    workingState: envelope.workingState,
+    archiveRefs: renderArchiveRefs(envelope.archiveRefs),
+    memoryCapture: input.memoryCapture ?? "",
+  }).trimEnd();
+  return input.liveRuns ? `${rendered}\n\n${input.liveRuns}` : rendered;
+}
+
+function renderArchiveRefs(refs: string[]): string {
+  if (!refs.length) return "- none";
+  const numericRefs = refs.map((ref) => Number(ref)).filter(Number.isSafeInteger);
+  const range = numericRefs.length
+    ? `refs ${Math.min(...numericRefs)}-${Math.max(...numericRefs)}`
+    : `refs ${refs[0]}-${refs[refs.length - 1]}`;
+  return `${refs.length} archived ${refs.length === 1 ? "segment" : "segments"} (${range}); fetch with relay_recall({ query: "<keyword>" }) if you need pre-compaction detail.`;
+}
+
+function renderDecisionEntry(entry: ContinuationDecisionEntry): string {
+  const by = entry.by ? ` · ${entry.by}` : "";
+  return `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}${by}: ${entry.decision}${entry.rationale ? `; rationale: ${entry.rationale}` : ""}`;
+}
+
+function renderLedgerLine(entry: ContinuationLedgerEntry): string {
+  return `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}: ${entry.ruledOut}${entry.why ? `; why: ${entry.why}` : ""}`;
+}
+
+// #1023 — render-time backstop on top of the persisted bound in
+// updateContinuationAfterCompact. Even if that bound is ever bypassed by a future
+// bug, this guarantees the ledger section injected into a fresh context can't blow
+// past a fixed size; it keeps the newest entries and notes what was omitted rather
+// than truncating mid-entry.
+const MAX_RENDERED_LEDGER_CHARS = 300_000;
+// Keep a small tail across objective changes: recent dead ends often describe
+// active constraints even when the caller has just re-pointed its objective.
+const RECENT_LEDGER_FLOOR = 15;
+
+function renderLedger(entries: ContinuationLedgerEntry[], objectiveEpoch: number): string {
+  const floorStart = Math.max(0, entries.length - RECENT_LEDGER_FLOOR);
+  const scoped = entries.filter((entry, index) => index >= floorStart || entry.at >= objectiveEpoch);
+  if (!scoped.length) return "- none";
+  const lines = scoped.map(renderLedgerLine);
+  let start = 0;
+  let totalChars = lines.reduce((sum, line) => sum + line.length + 1, 0);
+  while (totalChars > MAX_RENDERED_LEDGER_CHARS && start < lines.length - 1) {
+    totalChars -= lines[start]!.length + 1;
+    start += 1;
+  }
+  if (start === 0) return lines.join("\n");
+  const omitted = start;
+  return `- (${omitted} older ruled-out ${omitted === 1 ? "entry" : "entries"} omitted for size — see relay_recall for the archived history)\n${lines.slice(start).join("\n")}`;
+}
+
+function assertResumeSupported(agent: AgentCard, mode: SelfResumeMode): void {
+  const context = agent.providerCapabilities?.context;
+  const resume = context?.resume ?? (context?.clear && context?.inject ? "clear-inject" : "none");
+  if (resume === "none") throw new ValidationError("self-resume unsupported, fresh-session handoff only");
+  if (mode === "native" && resume !== "native") throw new ValidationError("native self-resume unsupported for this provider");
+  if (mode === "clear-inject" && !(context?.clear && context?.inject)) {
+    throw new ValidationError("clear-inject self-resume unsupported for this provider");
+  }
+}
+
+function createNativeCompact(agentId: string, generation: number, continuation: string, fullContextMessageId: number): Command {
+  return createCommand({
+    type: "agent.compact",
+    source: "system",
+    target: agentId,
+    params: {
+      reason: "self-resume",
+      instructions: continuation,
+      selfResume: { generation, mode: "native", continuation, fullContextMessageId },
+    },
+  });
+}
+
+function createClearThenInject(agentId: string, generation: number, continuation: string, fullContextMessageId: number): Command {
+  // #1588 — store the fully-built (identity-augmented) continuation in the clear command's params so
+  // the runner can deliver it inline as a coupled unit, race-free, while preserving the #1206 identity
+  // re-injection that the separate reactive inject used to add via buildInjectionParams. The backstop
+  // path re-augments idempotently, so embedding it here causes no drift.
+  const coupledContinuation = augmentContinuationWithIdentity(agentId, continuation);
+  return createCommand({
+    type: "agent.clearContext",
+    source: "system",
+    target: agentId,
+    params: {
+      reason: "self-resume",
+      selfResume: { generation, mode: "clear-inject", continuation: coupledContinuation, fullContextMessageId },
+    },
+  });
+}
+
+function parseRuledOut(value: unknown, generation: number, now: number): ContinuationLedgerEntry[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new ValidationError("ruledOut must be an array");
+  const entries = value.map((item, index) => {
+    if (typeof item === "string") return ledgerEntry(item, "", generation, now);
+    if (!isRecord(item)) throw new ValidationError(`ruledOut[${index}] must be a string or object`);
+    const ruledOut = typeof item.ruledOut === "string" ? item.ruledOut.trim() : "";
+    const why = typeof item.why === "string" ? item.why.trim() : "";
+    if (!ruledOut) throw new ValidationError(`ruledOut[${index}].ruledOut required`);
+    return ledgerEntry(ruledOut, why, generation, now);
+  });
+  // #1023 — ruledOut had no size limit at all (unlike the sibling workingState/objective
+  // fields, both capped at/near MAX_BODY_BYTES): a single legal call could inject a
+  // multi-megabyte continuation straight into the fresh context it was meant to fit
+  // inside. Bound total new content per call to the same ceiling as workingState.
+  const totalBytes = entries.reduce((sum, entry) => sum + new TextEncoder().encode(entry.ruledOut).byteLength + new TextEncoder().encode(entry.why).byteLength, 0);
+  if (totalBytes > MAX_BODY_BYTES) throw new ValidationError(`ruledOut exceeds ${MAX_BODY_BYTES} bytes for a single call — split it across multiple relay_compact_and_resume calls`);
+  return entries;
+}
+
+function ledgerEntry(ruledOut: string, why: string, generation: number, now: number): ContinuationLedgerEntry {
+  const cleaned = ruledOut.trim();
+  if (!cleaned) throw new ValidationError("ruledOut entries cannot be blank");
+  return { gen: generation, ruledOut: cleaned, why, at: now };
+}