dsh-autorestart 0.2.0 → 0.3.0

package/lib/checkpoint.js

@@ -13,6 +13,16 @@
  *  - every mutating helper below mutates `state` in place **and** returns it,
  *    so callers may treat the helpers as expressions.
  *
+ * Goal records come in TWO shapes on purpose:
+ *  - `state.disarmedGoals[sessionId] = { goalId, disarmedAt, resumedAt }` is the
+ *    current shape: this plugin called `ctx.goals.disarm(agent)` before a
+ *    restart, which keeps the durable goal `active` and can be re-armed with
+ *    `ctx.goals.resume(...)` after the boot.
+ *  - `state.parkedGoals[sessionId] = { goalId, parkedAt, resumedAt }` is the
+ *    LEGACY shape written by the previous pause-based build. It is still read
+ *    (and can still be cleared) so a goal that build paused is resumed once
+ *    instead of being stranded in `paused` where only a human could undo it.
+ *
  * ESM only, Node builtins only. No DSH / npm imports (profile-installed
  * bundles may not resolve them).
  */
@@ -30,6 +40,12 @@ export const ENTRY_REASONS_LIMIT = 16;
 /** Hard cap on `restart.requesters` (one entry per requesting session). */
 export const REQUESTERS_LIMIT = 16;
 
+/** Hard cap on the disarmed-goal records kept in the checkpoint. */
+export const DISARMED_GOALS_LIMIT = 64;
+
+/** Hard cap on the legacy (pause-based) parked-goal records. */
+export const PARKED_GOALS_LIMIT = 64;
+
 const RESTART_KEYS = new Set([
   'generation',
   'requestedAt',
@@ -41,6 +57,7 @@ const RESTART_KEYS = new Set([
   'failedAttempts',
   'notBefore',
   'requesters',
+  'parkGoals',
 ]);
 
 const ENTRY_KEYS = new Set([
@@ -57,10 +74,26 @@ const ENTRY_KEYS = new Set([
   'resumeAttempts',
   'lastResumeAt',
   'lastResumeError',
+  'lastRecoveryAction',
+  'lastRecoveryDetail',
+  'handoff',
+  'contextOverflow',
 ]);
 
 const GOAL_KEYS = new Set(['goalId', 'goalRevision', 'phase', 'updatedAt']);
 
+/** Record written when a session was handed off to a fresh session. */
+const HANDOFF_KEYS = new Set(['handedOffTo', 'handoffAt', 'carriedChars']);
+
+/** Record written when the context-overflow guard decided a session is over the limit. */
+const CONTEXT_OVERFLOW_KEYS = new Set(['over', 'inputTokens', 'contextWindow', 'detail', 'detectedAt']);
+
+/** LEGACY record shape written by the pause-based build. */
+const PARKED_GOAL_KEYS = new Set(['goalId', 'parkedAt', 'resumedAt']);
+
+/** Current record shape: written after a successful `ctx.goals.disarm()`. */
+const DISARMED_GOAL_KEYS = new Set(['goalId', 'disarmedAt', 'resumedAt']);
+
 const TOP_LEVEL_KEYS = new Set([
   'version',
   'bootId',
@@ -70,6 +103,8 @@ const TOP_LEVEL_KEYS = new Set([
   'phase',
   'restart',
   'sessions',
+  'parkedGoals',
+  'disarmedGoals',
   'updatedAt',
 ]);
 
@@ -118,6 +153,8 @@ function defaultEntry(sessionId, now = Date.now()) {
     resumeAttempts: 0,
     lastResumeAt: null,
     lastResumeError: null,
+    lastRecoveryAction: null,
+    lastRecoveryDetail: null,
   };
 }
 
@@ -167,6 +204,123 @@ function normalizeGoal(raw) {
   return { goal, changed };
 }
 
+/**
+ * Normalize the LEGACY parked-goal records written by the pause-based build:
+ * one entry per session whose goal that build paused. A corrupt record is
+ * dropped, never thrown on.
+ *
+ * @param {unknown} raw
+ * @returns {{ parkedGoals: object|null, changed: boolean }}
+ */
+function normalizeParkedGoals(raw) {
+  if (!isObject(raw)) {
+    return { parkedGoals: null, changed: raw !== null && raw !== undefined };
+  }
+  const parkedGoals = {};
+  let changed = false;
+  for (const [sessionId, value] of Object.entries(raw)) {
+    if (!isObject(value)) {
+      changed = true;
+      continue;
+    }
+    for (const key of Object.keys(value)) if (!PARKED_GOAL_KEYS.has(key)) changed = true;
+    const record = {
+      goalId: nullableString(value.goalId),
+      parkedAt: nullableNumber(value.parkedAt),
+      resumedAt: nullableNumber(value.resumedAt),
+    };
+    if (typeof value.goalId !== 'string' && value.goalId != null) changed = true;
+    if (value.parkedAt != null && !isFiniteNumber(value.parkedAt)) changed = true;
+    if (value.resumedAt != null && !isFiniteNumber(value.resumedAt)) changed = true;
+    if (record.goalId === null && record.parkedAt === null && record.resumedAt === null) {
+      changed = true;
+      continue;
+    }
+    parkedGoals[sessionId] = record;
+  }
+  return { parkedGoals, changed };
+}
+
+/**
+ * Normalize the disarmed-goal records: one entry per session whose goal this
+ * plugin disarmed (and has not resumed yet). A corrupt record is dropped.
+ *
+ * @param {unknown} raw
+ * @returns {{ disarmedGoals: object|null, changed: boolean }}
+ */
+function normalizeDisarmedGoals(raw) {
+  if (!isObject(raw)) {
+    return { disarmedGoals: null, changed: raw !== null && raw !== undefined };
+  }
+  const disarmedGoals = {};
+  let changed = false;
+  for (const [sessionId, value] of Object.entries(raw)) {
+    if (!isObject(value)) {
+      changed = true;
+      continue;
+    }
+    for (const key of Object.keys(value)) if (!DISARMED_GOAL_KEYS.has(key)) changed = true;
+    const record = {
+      goalId: nullableString(value.goalId),
+      disarmedAt: nullableNumber(value.disarmedAt),
+      resumedAt: nullableNumber(value.resumedAt),
+    };
+    if (typeof value.goalId !== 'string' && value.goalId != null) changed = true;
+    if (value.disarmedAt != null && !isFiniteNumber(value.disarmedAt)) changed = true;
+    if (value.resumedAt != null && !isFiniteNumber(value.resumedAt)) changed = true;
+    if (record.goalId === null && record.disarmedAt === null && record.resumedAt === null) {
+      changed = true;
+      continue;
+    }
+    disarmedGoals[sessionId] = record;
+  }
+  return { disarmedGoals, changed };
+}
+
+/**
+ * Normalize the handoff record of a session: `{ handedOffTo, handoffAt, carriedChars }`.
+ * A missing record stays `null`; a corrupt one is dropped instead of being thrown on.
+ *
+ * @param {unknown} raw
+ * @returns {{ handoff: object|null, changed: boolean }}
+ */
+function normalizeHandoff(raw) {
+  if (raw == null) return { handoff: null, changed: false };
+  if (!isObject(raw)) return { handoff: null, changed: true };
+  let changed = false;
+  for (const key of Object.keys(raw)) if (!HANDOFF_KEYS.has(key)) changed = true;
+  const handoff = {
+    handedOffTo: nullableString(raw.handedOffTo),
+    handoffAt: nullableNumber(raw.handoffAt),
+    carriedChars: isFiniteNumber(raw.carriedChars) ? Math.trunc(raw.carriedChars) : null,
+  };
+  if (raw.carriedChars != null && !isFiniteNumber(raw.carriedChars)) changed = true;
+  if (handoff.handedOffTo === null && handoff.handoffAt === null) return { handoff: null, changed: true };
+  return { handoff, changed };
+}
+
+/**
+ * Normalize the recorded context-overflow verdict of a session.
+ *
+ * @param {unknown} raw
+ * @returns {{ contextOverflow: object|null, changed: boolean }}
+ */
+function normalizeContextOverflow(raw) {
+  if (raw == null) return { contextOverflow: null, changed: false };
+  if (!isObject(raw)) return { contextOverflow: null, changed: true };
+  let changed = false;
+  for (const key of Object.keys(raw)) if (!CONTEXT_OVERFLOW_KEYS.has(key)) changed = true;
+  if (raw.over !== true) return { contextOverflow: null, changed: true };
+  const contextOverflow = {
+    over: true,
+    inputTokens: nullableNumber(raw.inputTokens),
+    contextWindow: nullableNumber(raw.contextWindow),
+    detail: nullableString(raw.detail),
+    detectedAt: nullableNumber(raw.detectedAt),
+  };
+  return { contextOverflow, changed };
+}
+
 /**
  * Normalize one persisted session entry.
  * @param {unknown} raw
@@ -209,6 +363,11 @@ function normalizeEntry(raw, sessionId, now) {
     changed = true;
   }
 
+  for (const key of ['lastRecoveryAction', 'lastRecoveryDetail']) {
+    if (typeof raw[key] === 'string' && raw[key].length > 0) entry[key] = raw[key];
+    else if (raw[key] != null) changed = true;
+  }
+
   if (Array.isArray(raw.reasons)) {
     const reasons = raw.reasons.filter((r) => typeof r === 'string' && r.length > 0);
     if (reasons.length !== raw.reasons.length) changed = true;
@@ -221,6 +380,16 @@ function normalizeEntry(raw, sessionId, now) {
   entry.goal = goal.goal;
   if (goal.changed) changed = true;
 
+  // Handoff / overflow records are only present when they were written: the
+  // default entry shape stays as it was, so an older checkpoint reads unchanged.
+  const handoff = normalizeHandoff(raw.handoff);
+  if (handoff.handoff !== null) entry.handoff = handoff.handoff;
+  if (handoff.changed) changed = true;
+
+  const contextOverflow = normalizeContextOverflow(raw.contextOverflow);
+  if (contextOverflow.contextOverflow !== null) entry.contextOverflow = contextOverflow.contextOverflow;
+  if (contextOverflow.changed) changed = true;
+
   return { entry, changed };
 }
 
@@ -285,12 +454,16 @@ function normalizeRestart(raw) {
     failedAttempts: isFiniteNumber(raw.failedAttempts) && raw.failedAttempts >= 0 ? Math.trunc(raw.failedAttempts) : 0,
     notBefore: isFiniteNumber(raw.notBefore) && raw.notBefore >= 0 ? raw.notBefore : 0,
     requesters,
+    // Disarming the goals of goal-driven sessions is the default: a restart must
+    // never deadlock behind a goal that keeps its own agent busy.
+    parkGoals: raw.parkGoals !== false,
   };
   if (!isFiniteNumber(raw.generation) || raw.generation < 0) changed = true;
   if (!isFiniteNumber(raw.requestedAt)) changed = true;
   if (!isFiniteNumber(raw.attempt) || raw.attempt < 0) changed = true;
   if (raw.failedAttempts != null && (!isFiniteNumber(raw.failedAttempts) || raw.failedAttempts < 0)) changed = true;
   if (raw.notBefore != null && !isFiniteNumber(raw.notBefore)) changed = true;
+  if (typeof raw.parkGoals !== 'boolean' && raw.parkGoals != null) changed = true;
   if (typeof raw.resume !== 'boolean' && raw.resume != null) changed = true;
   if (raw.requesters != null && !Array.isArray(raw.requesters)) changed = true;
   if (Array.isArray(raw.requesters) && requesters.length !== raw.requesters.length) changed = true;
@@ -349,6 +522,20 @@ export function normalizeState(raw, now = Date.now()) {
     repaired = true;
   }
 
+  // LEGACY: records written by the pause-based build. Kept verbatim so the
+  // goals that build paused can still be resumed after the next boot.
+  if (raw.parkedGoals != null) {
+    const parked = normalizeParkedGoals(raw.parkedGoals);
+    state.parkedGoals = parked.parkedGoals;
+    if (parked.changed) repaired = true;
+  }
+
+  if (raw.disarmedGoals != null) {
+    const disarmed = normalizeDisarmedGoals(raw.disarmedGoals);
+    state.disarmedGoals = disarmed.disarmedGoals;
+    if (disarmed.changed) repaired = true;
+  }
+
   return { state, repaired };
 }
 
@@ -566,6 +753,9 @@ export function markIdle(state, sessionId, { now = Date.now() } = {}) {
   entry.runningSince = null;
   entry.updatedAt = now;
   state.updatedAt = now;
+  // A handoff record must survive an idle transition: it is what keeps an
+  // over-limit session out of the automatic resume path forever.
+  if (isObject(entry.handoff)) return state;
   if (!entry.pendingResume && !entry.goal) delete state.sessions[sessionId];
   return state;
 }
@@ -652,6 +842,278 @@ export function setGoal(state, sessionId, { goalId, goalRevision = null, phase =
   return state;
 }
 
+/**
+ * Record what the last recovery attempt did for a session. This is the
+ * self-reporting half of the boot recovery: every attempt (including a plain
+ * early return) leaves an action plus a short detail behind, so
+ * `continuum_status` can explain why a session did not continue.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ action?: string|null, detail?: string|null, now?: number }} options
+ * @returns {object} state
+ */
+export function setRecoveryOutcome(state, sessionId, { action = null, detail = null, now = Date.now() } = {}) {
+  if (!sessionId) return state;
+  const entry = entryFor(state, sessionId);
+  entry.lastRecoveryAction = typeof action === 'string' && action.length > 0 ? action : null;
+  entry.lastRecoveryDetail = typeof detail === 'string' && detail.length > 0 ? detail : null;
+  entry.updatedAt = now;
+  state.updatedAt = now;
+  return state;
+}
+
+/**
+ * Record that this plugin DISARMED the goal of a session before a restart.
+ *
+ * A disarmed goal stays durably `active`; the record only exists so the next
+ * boot knows that re-arming it is safe and so `continuum_status` can report
+ * what happened. It is REPORTING ONLY: it never decides whether a goal may be
+ * disarmed (that is decided on the live goal state).
+ *
+ * The record of a session is OVERWRITTEN: a new disarm replaces the previous
+ * one (kind `disarmed`, the new disarm timestamp, `resumedAt: null`), and the
+ * LEGACY parked record of that session is dropped, so a record left over from
+ * the pause-based build can never block a later disarm.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ goalId?: string|null, disarmedAt?: number }} [options]
+ * @returns {object} state
+ */
+export function setDisarmedGoal(state, sessionId, { goalId = null, disarmedAt = Date.now() } = {}) {
+  if (!sessionId) return state;
+  if (!isObject(state.disarmedGoals)) state.disarmedGoals = {};
+  state.disarmedGoals[String(sessionId)] = {
+    goalId: goalId == null ? null : String(goalId),
+    disarmedAt: isFiniteNumber(disarmedAt) ? disarmedAt : Date.now(),
+    resumedAt: null,
+  };
+  // The current shape supersedes the LEGACY one for this session: one session
+  // has ONE goal record, so a stale legacy record can never linger next to it.
+  if (isObject(state.parkedGoals)) delete state.parkedGoals[String(sessionId)];
+  state.updatedAt = Date.now();
+  return state;
+}
+
+/**
+ * Stamp the goal record(s) of a session with the resume timestamp: the goal was
+ * re-armed by this plugin, so the status must show it as resumed.
+ *
+ * Both record shapes are stamped (the current disarmed record and the LEGACY
+ * parked record), because either one can describe the goal that was re-armed.
+ * A session without a record simply has nothing to stamp.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ resumedAt?: number }} [options]
+ * @returns {object} state
+ */
+export function stampResumedGoal(state, sessionId, { resumedAt = Date.now() } = {}) {
+  if (!sessionId) return state;
+  const at = isFiniteNumber(resumedAt) ? resumedAt : Date.now();
+  let changed = false;
+  for (const records of [state.disarmedGoals, state.parkedGoals]) {
+    if (!isObject(records)) continue;
+    const record = records[String(sessionId)];
+    if (!isObject(record)) continue;
+    record.resumedAt = at;
+    changed = true;
+  }
+  if (changed) state.updatedAt = at;
+  return state;
+}
+
+/**
+ * Clear the disarmed record of a session: the goal was re-armed. The record is
+ * kept (with `resumedAt` set) so `continuum_status` can still report whether the
+ * goal came back; a later disarm of the same session overwrites it.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ resumedAt?: number }} [options]
+ * @returns {object} state
+ */
+export function clearDisarmedGoal(state, sessionId, { resumedAt = Date.now() } = {}) {
+  if (!sessionId || !isObject(state.disarmedGoals)) return state;
+  const record = state.disarmedGoals[String(sessionId)];
+  if (!isObject(record)) return state;
+  record.resumedAt = isFiniteNumber(resumedAt) ? resumedAt : Date.now();
+  state.updatedAt = Date.now();
+  return state;
+}
+
+/**
+ * The disarmed-goal record of a session that was not resumed yet, or null.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @returns {{ goalId: string|null, disarmedAt: number|null, resumedAt: number|null }|null}
+ */
+export function disarmedRecord(state, sessionId) {
+  try {
+    if (!isObject(state) || !isObject(state.disarmedGoals)) return null;
+    const record = state.disarmedGoals[String(sessionId)];
+    if (!isObject(record)) return null;
+    if (record.resumedAt !== null && record.resumedAt !== undefined) return null;
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record that the PREVIOUS (pause-based) build parked the goal of a session.
+ * Kept for one purpose: the two goals that build paused must be resumable
+ * after the next boot instead of being stranded in `paused`.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ goalId?: string|null, parkedAt?: number }} [options]
+ * @returns {object} state
+ */
+export function setParkedGoal(state, sessionId, { goalId = null, parkedAt = Date.now() } = {}) {
+  if (!sessionId) return state;
+  if (!isObject(state.parkedGoals)) state.parkedGoals = {};
+  state.parkedGoals[String(sessionId)] = {
+    goalId: goalId == null ? null : String(goalId),
+    parkedAt: isFiniteNumber(parkedAt) ? parkedAt : Date.now(),
+    resumedAt: null,
+  };
+  state.updatedAt = Date.now();
+  return state;
+}
+
+/**
+ * Clear the LEGACY parked state of a session: the paused goal was resumed.
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ resumedAt?: number }} [options]
+ * @returns {object} state
+ */
+export function clearParkedGoal(state, sessionId, { resumedAt = Date.now() } = {}) {
+  if (!sessionId || !isObject(state.parkedGoals)) return state;
+  const record = state.parkedGoals[String(sessionId)];
+  if (!isObject(record)) return state;
+  record.resumedAt = isFiniteNumber(resumedAt) ? resumedAt : Date.now();
+  state.updatedAt = Date.now();
+  return state;
+}
+
+/**
+ * The LEGACY parked-goal record of a session that was not resumed yet, or null.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @returns {{ goalId: string|null, parkedAt: number|null, resumedAt: number|null }|null}
+ */
+export function parkedRecord(state, sessionId) {
+  try {
+    if (!isObject(state) || !isObject(state.parkedGoals)) return null;
+    const record = state.parkedGoals[String(sessionId)];
+    if (!isObject(record)) return null;
+    if (record.resumedAt !== null && record.resumedAt !== undefined) return null;
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record that a session was HANDED OFF to a fresh session.
+ *
+ * The record is the durable marker that this session must never be resumed
+ * automatically again: its conversation is what made every request fail with
+ * "context window exceeds limit", so replaying it can only fail again. Writing
+ * the record therefore also clears the resume flags (the session stops blocking
+ * a restart and stops being picked up by `recoverableSessions`).
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId the OLD (handed-off) session
+ * @param {{ handedOffTo?: string|null, handoffAt?: number, carriedChars?: number|null }} [options]
+ * @returns {object} state
+ */
+export function setHandoff(state, sessionId, { handedOffTo = null, handoffAt = Date.now(), carriedChars = null } = {}) {
+  if (!sessionId) return state;
+  const at = isFiniteNumber(handoffAt) ? handoffAt : Date.now();
+  const entry = entryFor(state, sessionId);
+  entry.handoff = {
+    handedOffTo: handedOffTo == null ? null : String(handedOffTo),
+    handoffAt: at,
+    carriedChars: isFiniteNumber(carriedChars) ? Math.trunc(carriedChars) : null,
+  };
+  entry.pendingResume = false;
+  entry.pendingSince = null;
+  entry.running = false;
+  entry.runningSince = null;
+  entry.interrupted = false;
+  entry.updatedAt = at;
+  state.updatedAt = at;
+  return state;
+}
+
+/**
+ * The handoff record of a session, or null.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @returns {{ handedOffTo: string|null, handoffAt: number|null, carriedChars: number|null }|null}
+ */
+export function handoffRecord(state, sessionId) {
+  try {
+    if (!isObject(state) || !isObject(state.sessions)) return null;
+    const entry = state.sessions[String(sessionId)];
+    if (!isObject(entry) || !isObject(entry.handoff)) return null;
+    return entry.handoff;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record (or clear, with `over: false`) the context-overflow verdict of a
+ * session. Kept on the entry so `continuum_status` can report an over-limit
+ * session even after it is no longer live.
+ *
+ * Mutates `state` in place and returns it.
+ *
+ * @param {object} state
+ * @param {string} sessionId
+ * @param {{ over?: boolean, inputTokens?: number|null, contextWindow?: number|null, detail?: string|null, detectedAt?: number }} [options]
+ * @returns {object} state
+ */
+export function setContextOverflow(state, sessionId, { over = false, inputTokens = null, contextWindow = null, detail = null, detectedAt = Date.now() } = {}) {
+  if (!sessionId) return state;
+  const entry = entryFor(state, sessionId);
+  if (over !== true) {
+    entry.contextOverflow = null;
+  } else {
+    entry.contextOverflow = {
+      over: true,
+      inputTokens: nullableNumber(inputTokens),
+      contextWindow: nullableNumber(contextWindow),
+      detail: nullableString(detail),
+      detectedAt: isFiniteNumber(detectedAt) ? detectedAt : Date.now(),
+    };
+  }
+  state.updatedAt = Date.now();
+  return state;
+}
+
 /**
  * Open a deferred restart cycle (bumps `generation` exactly once per request).
  *
@@ -666,10 +1128,10 @@ export function setGoal(state, sessionId, { goalId, goalRevision = null, phase =
  * Mutates `state` in place and returns it.
  *
  * @param {object} state
- * @param {{ reason?: string, bySessionId?: string|null, resume?: boolean, now?: number }} options
+ * @param {{ reason?: string, bySessionId?: string|null, resume?: boolean, parkGoals?: boolean, now?: number }} options
  * @returns {object} state
  */
-export function requestRestart(state, { reason, bySessionId = null, resume = true, now = Date.now() } = {}) {
+export function requestRestart(state, { reason, bySessionId = null, resume = true, parkGoals = true, now = Date.now() } = {}) {
   const generation = (isFiniteNumber(state.generation) && state.generation >= 0 ? state.generation : 0) + 1;
   state.generation = generation;
   state.phase = 'deferred';
@@ -704,6 +1166,9 @@ export function requestRestart(state, { reason, bySessionId = null, resume = tru
     failedAttempts: 0,
     notBefore: 0,
     requesters,
+    // A goal-driven session must not deadlock the restart: disarming its goal is
+    // on by default and can be turned off per restart request.
+    parkGoals: parkGoals !== false,
   };
   for (const requester of requesters) {
     if (requester.resume === false) continue;
@@ -761,6 +1226,51 @@ export function recoverableSessions(state, { limit } = {}) {
   return selectRecoverableSessions(state, { limit });
 }
 
+/**
+ * Prune one goal-record map: a resumed record is diagnostics only and is
+ * dropped once it is older than `maxAgeMs`; a record that was never resumed is
+ * NEVER dropped, because a later boot still has to resume that goal.
+ *
+ * @param {object} map
+ * @param {{ now: number, maxAgeMs: number, atKey: string, limit: number }} options
+ */
+function pruneGoalRecords(map, { now, maxAgeMs, atKey, limit }) {
+  for (const id of Object.keys(map)) {
+    const record = map[id];
+    if (!isObject(record)) {
+      delete map[id];
+      continue;
+    }
+    const resumedAt = isFiniteNumber(record.resumedAt) ? record.resumedAt : null;
+    if (resumedAt !== null && resumedAt < now - maxAgeMs) delete map[id];
+  }
+  const ids = Object.keys(map);
+  if (ids.length > limit) {
+    const at = (id) => {
+      const record = map[id];
+      return isObject(record) && isFiniteNumber(record[atKey]) ? record[atKey] : 0;
+    };
+    ids.sort((a, b) => at(b) - at(a));
+    for (const id of ids.slice(limit)) delete map[id];
+  }
+}
+
+/**
+ * Keep the goal records small (both shapes). Mutates `state` in place.
+ *
+ * @param {object} state
+ * @param {{ now?: number, maxAgeMs?: number }} [options]
+ */
+function pruneGoalRecordMaps(state, { now = Date.now(), maxAgeMs } = {}) {
+  const age = isFiniteNumber(maxAgeMs) && maxAgeMs > 0 ? maxAgeMs : 7 * 24 * 60 * 60 * 1000;
+  if (isObject(state.disarmedGoals)) {
+    pruneGoalRecords(state.disarmedGoals, { now, maxAgeMs: age, atKey: 'disarmedAt', limit: DISARMED_GOALS_LIMIT });
+  }
+  if (isObject(state.parkedGoals)) {
+    pruneGoalRecords(state.parkedGoals, { now, maxAgeMs: age, atKey: 'parkedAt', limit: PARKED_GOALS_LIMIT });
+  }
+}
+
 /**
  * Keep the checkpoint small: cap the session map by `updatedAt` (newest wins)
  * and optionally drop finished entries older than `maxAgeMs`. Running and
@@ -772,6 +1282,7 @@ export function recoverableSessions(state, { limit } = {}) {
  * @returns {object} state
  */
 export function pruneSessions(state, { maxSessions, now = Date.now(), maxAgeMs } = {}) {
+  pruneGoalRecordMaps(state, { now, maxAgeMs });
   if (!isObject(state.sessions)) return state;
   const sessions = state.sessions;
   const ids = Object.keys(sessions);
@@ -793,6 +1304,9 @@ export function pruneSessions(state, { maxSessions, now = Date.now(), maxAgeMs }
       if (!isObject(entry)) continue;
       if (entry.running === true || entry.pendingResume === true) continue;
       if (entry.goal) continue;
+      // A handoff / overflow record is the durable "never auto-resume this
+      // session again" marker: it is never dropped by age.
+      if (isObject(entry.handoff) || isObject(entry.contextOverflow)) continue;
       if (isFiniteNumber(entry.updatedAt) && entry.updatedAt < cutoff) remove.add(id);
     }
   }