@signalridge/pi-goal 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @signalridge/pi-goal
 
+## 1.3.1
+### Patch Changes
+
+- f714ea0: Publish the package versions already prepared by the previous release transition after its first publish attempt was blocked before npm publication.
+
+## 1.3.0
+### Minor Changes
+
+- b6cf242: New `goal_wait` tool: a goal that depends on something outside the session — CI finishing, a review landing, a reply arriving — can now say so. Without it the model either burns continuation turns re-checking or reports a blocker that is not one; `goal_wait` records *why* it is waiting, pauses the goal, and either waits for the next real message or wakes itself on a deadline.
+  
+  It reuses the existing `paused` state rather than adding a fourth one, so every resume path, restore path, and status surface already handles it, and the deadline resumes through the same code as `/goal resume` (tool-policy preparation, recovery clearing, prompt delivery) rather than a second, lesser resume. Requests below 10s are clamped rather than refused — the model's intent ("wait, then check") is right even when its number makes a polling loop — and the reply says when a number was raised. The wake-up re-checks at fire time that the goal is still the paused, active one, and a generation counter keeps an already-in-flight callback from waking a goal that was cleared microseconds earlier.
+  
+  `toolVisibility` now defaults to `"after-first-goal"` instead of `"always"`.
+  
+  `goal_complete` and `goal_blocked` are meaningless without an active goal, so in a session that never runs `/goal` — the overwhelming majority — their definitions and prompt guidelines were pure context cost paid on every request. They are now withheld until the first accepted `/goal` activation, and a session that restores an unfinished goal reveals them at startup as before.
+  
+  Nothing else changes: the `"after-first-goal"` machinery is unchanged, missing and invalid settings both land on the new default (an unreadable settings file must not be a way to get the always-on behaviour), and `"always"` remains available for anyone who wants a tool schema that is identical from session startup.
+  
+  Reload Pi after changing the setting, as before.
+
+### Patch Changes
+
+- b6cf242: Peer dependency ranges now name the versions actually validated against, so an untested host combination fails at install time instead of silently at runtime: `@earendil-works/pi-coding-agent`, `pi-ai`, `pi-tui`, and `pi-agent-core` move from `"*"` to `^0.84.0`, and `typebox` from `"*"` to `^1.3.11`.
+  
+  Shared dependencies now carry ONE declared range across every package that uses them, and `bun run check:shared-deps` keeps it that way.
+  
+  `@narumitw/pi-tui-kit` was declared at three disjoint floors — `^0.54.0`, `^0.51.0`, and `^0.49.1` across nine packages — and the lockfile duly resolved three copies (0.54.0, 0.51.0, 0.49.3) installed side by side. For a shared rendering surface drawing into one terminal inside one host process, that means a theme rendering one way in one extension and another way in the next, with nothing failing at install to say so. All nine now declare `^0.54.0` and the install resolves a single copy. `@sinclair/typebox` likewise converges on `^0.34.50`.
+  
+  The new check covers `dependencies` and `peerDependencies` and compares range strings rather than their semantics: two ranges that merely overlap are still a finding, because the goal is one intentional answer per dependency rather than an accidental intersection. `devDependencies` are deliberately out of scope — a build tool is not a shared surface, and `pi-subagents` intentionally carries its own toolchain. `docs/package-boundaries.md` documents the Kit as a shared surface for the first time.
+
 ## 1.0.0
 ### Major Changes
 

package/README.md

@@ -22,7 +22,8 @@ Goal mode uses Codex-like persistence instructions and sends guarded continuatio
 - Stores goal state in the current Pi session, following Codex's thread-owned goal model instead of using a global per-directory goal. Experimental queues keep independent budget, usage, elapsed-time, iteration, status, and stale-id accounting for every item.
 - Registers a `goal_complete({ goal_id, summary })` tool for explicit completion, requiring the current goal id and rejecting missing/stale ids plus plainly contradictory summaries such as “not complete” or “tests still fail”.
 - Registers `goal_blocked({ goal_id, reason, evidence, repeated_turns })` for true impasses only; it requires the current goal id, concrete evidence, and the same blocker recurring for at least three consecutive goal turns.
-- Keeps both goal tools active by default for a stable tool schema; optional `"after-first-goal"` visibility hides them until the first accepted `/goal` activation or an unfinished goal is restored, then keeps them desired for the rest of that extension runtime without overriding a restrictive restore policy.
+- Registers `goal_wait({ goal_id, reason, resume_after_ms? })` for a goal that is waiting on something outside the session rather than unfinished or blocked. The goal pauses with the reason recorded and either waits for the next real message or wakes on the deadline; requests under 10s are clamped, since a shorter "wait" is a polling loop. Resuming a deadline uses the same path as `/goal resume`.
+- Hides all three goal tools by default until the first goal exists (`"after-first-goal"`), keeping their definitions and prompt guidelines out of a session that never runs `/goal`; optional `"always"` visibility keeps them resident for a stable tool schema. Hidden means hidden until the first accepted `/goal` activation or an unfinished goal is restored, then keeps them desired for the rest of that extension runtime without overriding a restrictive restore policy.
 - Records continuation and queue-transition intent, then triggers exactly one next turn only after Pi reports the agent fully settled, idle, and free of pending messages; if terminal tools disappear during a tool loop or before the next queued goal starts, pauses before another model turn.
 - Lets retry, compaction, steering, follow-up, and other queued work settle before automatic goal continuation.
 - Separates user interruption (`paused`), true impasse or terminal non-usage error (`blocked`), provider/account quota exhaustion (`usage_limited`), and user token budget exhaustion (`budget_limited`).
@@ -58,7 +59,7 @@ built-in defaults without creating the file:
 
 ```json
 {
-  "toolVisibility": "always",
+  "toolVisibility": "after-first-goal",
   "experimental": {
     "goals": false
   },
@@ -86,8 +87,8 @@ Custom number inputs reject zero, negative numbers, decimals, text, and unsafe i
 
 `toolVisibility` accepts:
 
-- `"always"` (default) — pi-goal does not proactively hide `goal_complete` or `goal_blocked`, keeping the tool schema stable from session startup.
-- `"after-first-goal"` — hides both tools at fresh runtime startup, reveals them for the first accepted Goal activation, and treats an unfinished-goal restore as unlocked for the remainder of that extension runtime. On restore, pi-goal uses the active tools already established by earlier lifecycle handlers; it does not re-add missing terminal tools over a restrictive policy. Failed kickoff, replacement, resume, or reactivating-edit delivery restores the exact pre-activation tool set, including terminal tools exposed by another extension. If revealing the tools would widen an already-running turn, wait for Pi to become idle and retry `/goal`.
+- `"always"` — pi-goal does not proactively hide `goal_complete` or `goal_blocked`, keeping the tool schema stable from session startup.
+- `"after-first-goal"` (default) — hides both tools at fresh runtime startup, reveals them for the first accepted Goal activation, and treats an unfinished-goal restore as unlocked for the remainder of that extension runtime. On restore, pi-goal uses the active tools already established by earlier lifecycle handlers; it does not re-add missing terminal tools over a restrictive policy. Failed kickoff, replacement, resume, or reactivating-edit delivery restores the exact pre-activation tool set, including terminal tools exposed by another extension. If revealing the tools would widen an already-running turn, wait for Pi to become idle and retry `/goal`.
 
 `experimental.goals` accepts a boolean and defaults to `false`. Set it to `true` to enable the ordered-goal subcommands and automatic queue advancement described below. Enabled sessions show one warning because command behavior and persisted queue state remain experimental.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-goal",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Pi extension for autonomous /goal completion with opt-in experimental ordered queues.",
   "type": "module",
   "license": "MIT",
@@ -36,10 +36,10 @@
     "lint": "biome check ."
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
+    "@earendil-works/pi-ai": "^0.84.0",
+    "@earendil-works/pi-coding-agent": "^0.84.0",
+    "@earendil-works/pi-tui": "^0.84.0",
+    "typebox": "^1.3.11"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.7",
@@ -50,7 +50,7 @@
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@narumitw/pi-tui-kit": "^0.49.1"
+    "@narumitw/pi-tui-kit": "^0.54.0"
   },
   "repository": {
     "type": "git",

package/src/goal.ts

@@ -15,6 +15,15 @@ function registerGoalRuntime(pi: ExtensionAPI, options: GoalOptions = {}) {
   const commands = new GoalCommandController(runtime);
   const runController = new GoalRunController(runtime, commands);
 
+  // A `goal_wait` deadline resumes through the SAME path as `/goal resume`:
+  // tool-policy preparation, recovery clearing and prompt delivery all have to
+  // happen, and a shortcut would be a second, worse resume path drifting from
+  // the real one. Wired here because the controller owns it and the runtime,
+  // which arms the timer, deliberately does not depend on the controller.
+  runtime.onGoalWaitElapsed = (ctx) => {
+    void commands.resumeGoal(ctx);
+  };
+
   // Keep registration order explicit: managed-run bus listeners exist before tools,
   // command routing, and session lifecycle bind the per-factory runtime.
   runController.register(pi);

package/src/runtime.ts

@@ -17,8 +17,9 @@ export { queueGoalSafetyReset, resetGoalSafetyEpoch } from "./safety.js";
 
 import { DEFAULT_GOAL_SETTINGS, type GoalSettings, type GoalSettingsLoadIssue } from "./settings.js";
 import { GoalToolPolicy, type GoalToolVisibilitySnapshot } from "./tool-policy.js";
+import { GoalWaitTimer } from "./wait.js";
 
-export { GOAL_BLOCKED_TOOL, GOAL_COMPLETE_TOOL, GOAL_TOOL_NAMES } from "./tool-policy.js";
+export { GOAL_BLOCKED_TOOL, GOAL_COMPLETE_TOOL, GOAL_TOOL_NAMES, GOAL_WAIT_TOOL } from "./tool-policy.js";
 
 export interface ContinuationTicket {
   goalId: string;
@@ -62,6 +63,13 @@ export type GoalStopRequest =
       reason: string;
     }
   | { kind: "retry_exhausted"; expectedGoalId: string; reason: string }
+  /**
+   * `goal_wait`: the goal has no work left until something outside the session
+   * happens. Stops exactly like a reported blocker — same usage accounting,
+   * same stale-call block — but lands on `paused`, which is already the state
+   * every resume path knows how to bring back.
+   */
+  | { kind: "wait"; expectedGoalId: string; reason: string }
   | {
       kind: "tools_unavailable";
       expectedGoalId: string;
@@ -184,6 +192,8 @@ export class GoalRuntime {
   settings: GoalSettings = DEFAULT_GOAL_SETTINGS;
   settingsLoadIssue?: GoalSettingsLoadIssue;
   activeGoal?: ActiveGoal;
+  /** The single `goal_wait` safety wake-up. Cancelled with continuation work. */
+  private readonly goalWaitTimer = new GoalWaitTimer();
   /** Terminal details captured for the matching persisted-state snapshot. */
   private terminalDetails?: GoalTerminalDetails;
   private goalStateSink?: (snapshot: GoalStateSnapshot) => void;
@@ -401,6 +411,15 @@ export class GoalRuntime {
         status = "paused";
         terminalReason = request.reason;
         break;
+      case "wait":
+        this.recordGoalUsage(goal, ctx);
+        this.cancelContinuationWork();
+        this.clearGoalRecoveryForGoal(goal.id);
+        this.clearBudgetWrapUp();
+        this.blockStaleGoalToolCalls();
+        status = "paused";
+        terminalReason = request.reason;
+        break;
       case "retry_exhausted":
         this.clearGoalRecoveryForGoal(goal.id);
         this.cancelContinuationWork();
@@ -706,7 +725,33 @@ export class GoalRuntime {
     return true;
   }
 
+  /**
+   * Arm the `goal_wait` safety wake-up.
+   *
+   * The callback is supplied by the command layer, which owns the only correct
+   * resume: tool-policy preparation, recovery clearing, and prompt delivery all
+   * have to happen, and a shortcut here would be a second, worse resume path.
+   * Unset (a headless or partially-built runtime) simply means a wait keeps
+   * waiting for real input, which is the safe direction.
+   */
+  onGoalWaitElapsed?: (ctx: StatusContext, goalId: string) => void;
+
+  scheduleGoalWaitWake(ctx: StatusContext, goalId: string, resumeAt: number): void {
+    this.goalWaitTimer.schedule(resumeAt, () => {
+      // Re-checked at fire time, not at schedule time: the goal may have been
+      // completed, cleared, or replaced during the wait, and waking a goal that
+      // is no longer the active one would resume the wrong work.
+      if (this.activeGoal?.id !== goalId || this.activeGoal.status !== "paused") return;
+      this.onGoalWaitElapsed?.(ctx, goalId);
+    });
+  }
+
+  clearGoalWaitWake(): void {
+    this.goalWaitTimer.clear();
+  }
+
   cancelContinuationWork() {
+    this.clearGoalWaitWake();
     this.clearContinuationDispatchTimer();
     if (this.continuationDelivery) {
       this.rememberCancelledContinuationMarker(this.continuationDelivery.marker);

package/src/settings.ts

@@ -24,7 +24,14 @@ export interface GoalSettings {
 }
 
 export const DEFAULT_GOAL_SETTINGS: GoalSettings = {
-  toolVisibility: "always",
+  // `after-first-goal`, not `always`: `goal_complete` and `goal_blocked` are
+  // meaningless without an active goal, so in a session that never runs
+  // `/goal` — the overwhelming majority — their definitions and prompt
+  // guidelines are pure context cost paid on every request. They are revealed
+  // the moment the first goal is set, and a session that restores an
+  // unfinished goal reveals them at startup. Set `"always"` to keep them
+  // resident.
+  toolVisibility: "after-first-goal",
   experimental: { goals: false },
   rpc: { enabled: false },
   continuationLimits: { automaticTurns: 25, noProgressTurns: 3 },

package/src/tool-policy.ts

@@ -3,7 +3,8 @@ import type { GoalToolVisibility } from "./settings.js";
 
 export const GOAL_COMPLETE_TOOL = "goal_complete";
 export const GOAL_BLOCKED_TOOL = "goal_blocked";
-export const GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL] as const;
+export const GOAL_WAIT_TOOL = "goal_wait";
+export const GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL, GOAL_WAIT_TOOL] as const;
 
 export interface GoalToolVisibilitySnapshot {
   activeTools: string[];

package/src/tools.ts

@@ -11,6 +11,7 @@ import {
   formatStatus,
   GOAL_BLOCKED_TOOL,
   GOAL_COMPLETE_TOOL,
+  GOAL_WAIT_TOOL,
   type GoalRuntime,
   goalIdRejectionReason,
   isContradictoryCompletionSummary,
@@ -19,6 +20,7 @@ import {
   transitionGoal,
   truncateNotification,
 } from "./runtime.js";
+import { createGoalWait, MAX_GOAL_WAIT_REASON_LENGTH, MIN_GOAL_WAIT_DELAY_MS, resolveGoalWaitDelay } from "./wait.js";
 
 interface GoalCompleteDetails {
   goal: string;
@@ -26,6 +28,15 @@ interface GoalCompleteDetails {
   summary: string;
 }
 
+interface GoalWaitDetails {
+  goal: string;
+  goal_id: string;
+  reason: string;
+  requested_resume_after_ms?: number;
+  effective_resume_after_ms?: number;
+  resume_at?: number;
+}
+
 interface GoalBlockedDetails {
   goal: string;
   goal_id: string;
@@ -285,8 +296,107 @@ export function registerGoalTools(pi: ExtensionAPI, runtime: GoalRuntime) {
     },
   });
 
+  const goalWaitTool = defineTool({
+    name: GOAL_WAIT_TOOL,
+    label: "Goal Wait",
+    description: `Keep the active /goal alive but quiet while something outside this session is expected — CI finishing, a review landing, a reply arriving. The goal pauses, stays resumable, and records why. Call it alone, after arranging whatever will wake it, or pass resume_after_ms as a safety deadline. Requests below ${MIN_GOAL_WAIT_DELAY_MS}ms are clamped to ${MIN_GOAL_WAIT_DELAY_MS}ms. Do not use it for ordinary unfinished work: if there is anything left you can do yourself, do it instead.`,
+    promptSnippet: "Pause the active /goal while waiting on something outside this session",
+    promptGuidelines: [
+      "Use goal_wait only when progress genuinely depends on a later external event — not when work remains that you could do now.",
+      `Prefer deadlines measured in minutes; anything under ${MIN_GOAL_WAIT_DELAY_MS}ms is a polling loop and is clamped.`,
+      "Omit resume_after_ms when a message will wake the goal anyway; pass it only as a bounded safety net.",
+      "Call goal_wait alone: a sibling tool call in the same turn can prevent the turn from ending.",
+    ],
+    parameters: Type.Object({
+      goal_id: Type.String({
+        minLength: 1,
+        maxLength: MAX_GOAL_ID_LENGTH,
+        description: "The exact goal_id shown in the current active /goal prompt.",
+      }),
+      reason: Type.String({
+        minLength: 1,
+        maxLength: MAX_GOAL_WAIT_REASON_LENGTH,
+        description: "What is being waited for, and what will make it done.",
+      }),
+      resume_after_ms: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: `Safety wake-up in milliseconds. Clamped up to ${MIN_GOAL_WAIT_DELAY_MS}ms. Omit to wait for external input only.`,
+        }),
+      ),
+    }),
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const goal = runtime.activeGoal;
+      const requestedGoalId = params.goal_id.trim();
+      const reason = safeTerminalText(params.reason).trim();
+      const requestedResumeAfterMs = params.resume_after_ms;
+
+      const details = (): GoalWaitDetails => {
+        const { requestedMs, effectiveMs } = resolveGoalWaitDelay(requestedResumeAfterMs);
+        return {
+          goal: (goal?.text ?? "").slice(0, MAX_GOAL_TEXT_LENGTH),
+          goal_id: requestedGoalId.slice(0, MAX_GOAL_ID_LENGTH),
+          reason: reason.slice(0, MAX_GOAL_WAIT_REASON_LENGTH),
+          ...(requestedMs === undefined ? {} : { requested_resume_after_ms: requestedMs }),
+          ...(effectiveMs === undefined ? {} : { effective_resume_after_ms: effectiveMs }),
+        };
+      };
+
+      const reject = (why: string, terminate = false) => {
+        const rejection = `goal_wait rejected: ${why}`;
+        notifyTerminal(ctx.ui, rejection, "warning");
+        return {
+          content: toolContent(rejection),
+          details: details(),
+          ...(terminate ? { terminate: true as const } : {}),
+        };
+      };
+
+      if (!goal) return reject("no active goal");
+      if (!runtime.canRecordGoalUsage()) return reject("current run does not own the active goal");
+      if (hasPendingSkipForGoal(runtime, goal.id)) {
+        runtime.recordGoalUsage(goal, ctx);
+        runtime.persistGoal(goal);
+        runtime.updateStatus(ctx, goal);
+        runtime.clearBudgetWrapUp();
+        return reject("goal is queued to be skipped", true);
+      }
+      const staleGoalRejection = goalIdRejectionReason(goal, requestedGoalId);
+      if (staleGoalRejection) return reject(staleGoalRejection);
+      if (goal.status !== "active") return reject(`goal is ${goal.status}, not active`);
+      if (!reason) return reject("reason is empty");
+
+      const wait = createGoalWait(reason, requestedResumeAfterMs);
+      const stoppedGoal = runtime.stopActiveGoal(ctx, {
+        kind: "wait",
+        expectedGoalId: goal.id,
+        reason,
+      });
+      if (!stoppedGoal) return reject("active goal changed before the wait took effect");
+
+      // Armed after the stop, so a wake can never race a goal that is still
+      // being transitioned out of `active`.
+      if (wait.resumeAt !== undefined) runtime.scheduleGoalWaitWake(ctx, stoppedGoal.id, wait.resumeAt);
+
+      const { requestedMs, effectiveMs } = resolveGoalWaitDelay(requestedResumeAfterMs);
+      const clamped = requestedMs !== undefined && effectiveMs !== undefined && effectiveMs !== requestedMs;
+      const deadline =
+        effectiveMs === undefined
+          ? "It will stay paused until you send it something or resume it."
+          : `It will wake in ${Math.round(effectiveMs / 1000)}s${clamped ? ` (raised from ${requestedMs}ms)` : ""}.`;
+      notifyTerminal(ctx.ui, `Goal waiting: ${truncateNotification(reason)}`, "info");
+
+      return {
+        content: toolContent(`Goal waiting: ${reason}. ${deadline}`),
+        details: { ...details(), ...(wait.resumeAt === undefined ? {} : { resume_at: wait.resumeAt }) },
+        terminate: true,
+      };
+    },
+  });
+
   pi.registerTool(goalCompleteTool);
   pi.registerTool(goalBlockedTool);
+  pi.registerTool(goalWaitTool);
 }
 
 function toolContent(text: string) {

package/src/wait.ts

@@ -0,0 +1,112 @@
+/**
+ * wait.ts — `goal_wait`, the difference between "not finished" and "waiting".
+ *
+ * A goal that depends on something outside the session — CI finishing, a review
+ * landing, a colleague replying — has no work left to do right now, but is not
+ * complete and is not blocked. Without a way to say so, the model either keeps
+ * burning continuation turns re-checking, or reports a blocker that is not one.
+ *
+ * `goal_wait` says it: the goal stops, stays resumable, records why, and either
+ * waits for the next real message or wakes itself on a deadline.
+ *
+ * The minimum delay is the load-bearing constant. A model asked to "wait a
+ * moment" will happily pass 100ms, which is a polling loop wearing a wait's
+ * clothing — the same continuation burn the tool exists to prevent. Requests
+ * below the floor are clamped rather than refused, since the model's intent
+ * ("wait, then check") is right even when its number is not.
+ */
+
+export interface GoalWait {
+  reason: string;
+  /** Epoch ms of the safety wake-up. Absent = wait for external input only. */
+  resumeAt?: number;
+}
+
+export const MAX_GOAL_WAIT_REASON_LENGTH = 1_000;
+/** Floor on a requested delay. Below this a "wait" is really a poll. */
+export const MIN_GOAL_WAIT_DELAY_MS = 10_000;
+/** `setTimeout` overflows above this and fires immediately, which is the opposite of waiting. */
+export const MAX_GOAL_WAIT_DELAY_MS = 2_147_483_647;
+/** Largest value `Date` represents; anything beyond is not a timestamp. */
+const MAX_DATE_TIMESTAMP_MS = 8_640_000_000_000_000;
+
+/**
+ * Both the requested delay and the one that will actually apply, so a caller
+ * can tell the model its number was clamped instead of silently substituting.
+ */
+export function resolveGoalWaitDelay(resumeAfterMs: number | undefined): {
+  requestedMs?: number;
+  effectiveMs?: number;
+} {
+  if (resumeAfterMs === undefined) return {};
+  return {
+    requestedMs: resumeAfterMs,
+    effectiveMs: Math.max(MIN_GOAL_WAIT_DELAY_MS, resumeAfterMs),
+  };
+}
+
+/** Build the persisted wait record. `now` is injectable so tests are not timing-dependent. */
+export function createGoalWait(reason: string, resumeAfterMs: number | undefined, now = Date.now()): GoalWait {
+  const { effectiveMs } = resolveGoalWaitDelay(resumeAfterMs);
+  return {
+    reason,
+    ...(effectiveMs === undefined ? {} : { resumeAt: now + effectiveMs }),
+  };
+}
+
+/**
+ * Validate a wait read back from persisted state.
+ *
+ * Rejects rather than repairs: a malformed `resumeAt` would otherwise schedule
+ * a timer at an arbitrary moment, and a goal that wakes at the wrong time is
+ * worse than one that waits for a real message.
+ */
+export function normalizeGoalWait(value: unknown): GoalWait | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const record = value as Record<string, unknown>;
+  const reason = typeof record.reason === "string" ? record.reason.trim() : "";
+  if (!reason || reason.length > MAX_GOAL_WAIT_REASON_LENGTH) return undefined;
+  if (!Object.hasOwn(record, "resumeAt")) return { reason };
+  if (
+    typeof record.resumeAt !== "number" ||
+    !Number.isSafeInteger(record.resumeAt) ||
+    record.resumeAt < 0 ||
+    record.resumeAt > MAX_DATE_TIMESTAMP_MS
+  ) {
+    return undefined;
+  }
+  return { reason, resumeAt: record.resumeAt };
+}
+
+/**
+ * The single wake-up timer.
+ *
+ * Generation-counted rather than merely cleared: a timer already in flight
+ * cannot be un-fired, so a callback that was scheduled before a `clear()` must
+ * recognize that it is stale and do nothing. Without that, a goal cleared or
+ * replaced microseconds before its deadline would still be woken.
+ */
+export class GoalWaitTimer {
+  private generation = 0;
+  private timer?: ReturnType<typeof setTimeout>;
+
+  clear(): void {
+    this.generation += 1;
+    if (!this.timer) return;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+  }
+
+  schedule(resumeAt: number, onDue: () => void): void {
+    this.clear();
+    const generation = this.generation;
+    // A deadline already past fires on the next tick rather than never, and one
+    // beyond the timer range is capped instead of overflowing to immediate.
+    const delay = Math.max(0, Math.min(MAX_GOAL_WAIT_DELAY_MS, resumeAt - Date.now()));
+    this.timer = setTimeout(() => {
+      if (generation !== this.generation) return;
+      this.timer = undefined;
+      onDue();
+    }, delay);
+  }
+}