Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

26.2 KB
Raw Blame
/**
 * Pure persistent-CoS-mind state helpers.
 *
 * The supervisor service owns I/O and timers. This module owns the durable
 * shape and clock-driven decisions so restart recovery can replay the same
 * rules without depending on module-level process state.
 */

import { createHash } from 'crypto';
import { PERSISTENT_MIND_ID } from './persistentMindTrajectory.js';
import { MAX_SCREENSHOT_BYTES } from './uploadLimits.js';
import { sanitizeFilename } from './mimeTypes.js';
import { isSafeFilename } from './pathSafety.js';
import {
  asPersistentMindThinkingPresetId,
  normalizePersistentMindThinkingRequest,
  normalizePersistentMindThinkingRequests,
  normalizePersistentMindThinkingSelection,
} from './persistentMindThinkingPresets.js';
import {
  createDefaultPersistentMindToolActivation,
  normalizePersistentMindToolActivation,
} from './persistentMindToolActivation.js';
import { trimTo } from './textUtils.js';

export const PERSISTENT_MIND_SCHEMA_VERSION = 8;

export const PERSISTENT_MIND_IMAGE_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
export const PERSISTENT_MIND_IMAGE_MIME_TYPES = Object.freeze({
  png: 'image/png',
  jpg: 'image/jpeg',
  jpeg: 'image/jpeg',
  gif: 'image/gif',
  webp: 'image/webp',
});

export const PERSISTENT_MIND_STATUSES = [
  'disabled',
  'idle',
  'thinking',
  'waiting',
  'paused',
  'degraded',
  'interrupted',
  'stopping',
];

export const PERSISTENT_MIND_WAKE_KINDS = ['message', 'self'];
export const PERSISTENT_MIND_SELF_WAKE_SCHEDULE_KINDS = ['quiet', 'requested'];

// How often a running turn pulses its heartbeat. Hoisted so the stale-warning
// threshold below can be DERIVED from it rather than restating the number:
// slowing the pulse would otherwise make every healthy turn read as stalled.
const HEARTBEAT_INTERVAL_MS = 60_000;

export const PERSISTENT_MIND_LIMITS = Object.freeze({
  MAX_QUEUED_MESSAGES: 100,
  MAX_RECENT_MESSAGE_IDS: 200,
  MAX_MESSAGE_IMAGES: 8,
  MAX_MESSAGE_CHARS: 8_000,
  MAX_REASON_CHARS: 500,
  MAX_CALL_HISTORY: 20,
  MAX_CALL_REASON_CHARS: 200,
  MAX_CALL_SOURCE_CHARS: 60,
  MAX_ATTACHMENT_ID_CHARS: 128,
  MAX_ATTACHMENT_FILENAME_CHARS: 255,
  MAX_ATTACHMENT_NAME_CHARS: 200,
  MAX_PENDING_ATTACHMENTS: 800,
  MAX_ATTACHMENT_CLEANUP_PER_PASS: 50,
  MAX_ATTACHMENT_BYTES: MAX_SCREENSHOT_BYTES,
  PENDING_ATTACHMENT_TTL_MS: 24 * 60 * 60 * 1000,
  BACKOFF_BASE_MS: 5_000,
  BACKOFF_MAX_MS: 15 * 60_000,
  WATCHDOG_STALE_MS: 5 * 60_000,
  // The adapter owns the pulse timer and imports this back, so one edit moves
  // the cadence and the threshold derived from it together.
  HEARTBEAT_INTERVAL_MS,
  // UI warning threshold: two missed pulses, well before the watchdog kills the
  // turn at WATCHDOG_STALE_MS, so "stalled" is visible while the turn can still
  // recover on its own.
  HEARTBEAT_STALE_WARNING_MS: 2 * HEARTBEAT_INTERVAL_MS,
  MAX_QUIET_MS: 30 * 60_000,
});

const asIso = (value) => {
  if (typeof value !== 'string' || !Number.isFinite(Date.parse(value))) return null;
  return new Date(value).toISOString();
};

const asId = (value) => trimTo(value, 200);
const asMindId = (value) => trimTo(value, 128);

const asCount = (value) => (
  Number.isSafeInteger(value) && value >= 0 ? value : 0
);

const asFingerprint = (value) => (
  typeof value === 'string' && /^[a-f0-9]{64}$/.test(value) ? value : null
);

const asAttachmentId = (value) => {
  if (typeof value !== 'string') return null;
  const id = value.trim();
  return id.length <= PERSISTENT_MIND_LIMITS.MAX_ATTACHMENT_ID_CHARS
    && /^[A-Za-z0-9_-]+$/.test(id) ? id : null;
};

const asAttachmentFilename = (value) => {
  if (typeof value !== 'string') return null;
  const filename = value.trim();
  return filename.length <= PERSISTENT_MIND_LIMITS.MAX_ATTACHMENT_FILENAME_CHARS
    && isSafeFilename(filename, PERSISTENT_MIND_IMAGE_EXTENSIONS)
    && /^[A-Za-z0-9][A-Za-z0-9._-]*\.(?:png|jpg|jpeg|gif|webp)$/i.test(filename)
    ? filename
    : null;
};

const asAttachmentMimeType = (value) => (
  typeof value === 'string' && Object.values(PERSISTENT_MIND_IMAGE_MIME_TYPES).includes(value)
    ? value
    : null
);

const asAttachmentSize = (value) => (
  Number.isSafeInteger(value) && value > 0 && value <= PERSISTENT_MIND_LIMITS.MAX_ATTACHMENT_BYTES
    ? value
    : null
);

const attachmentPath = (filename) => {
  const safeFilename = asAttachmentFilename(filename);
  return safeFilename ? `/api/screenshots/${encodeURIComponent(safeFilename)}` : null;
};

/** True when a value is a safe server-issued Mind attachment id. */
export function isPersistentMindAttachmentId(value) {
  return asAttachmentId(value) !== null;
}

/** Convert a stored screenshot filename into the only client-visible reference. */
export function persistentMindAttachmentPath(filename) {
  return attachmentPath(filename);
}

/** Normalize the bounded, machine-local pending attachment record. */
export function normalizePersistentMindAttachment(value) {
  const attachmentId = asAttachmentId(value?.attachmentId);
  const filename = asAttachmentFilename(value?.filename);
  const originalName = typeof value?.originalName === 'string'
    ? sanitizeFilename(value.originalName).slice(0, PERSISTENT_MIND_LIMITS.MAX_ATTACHMENT_NAME_CHARS) || filename
    : filename;
  const mimeType = asAttachmentMimeType(value?.mimeType);
  const size = asAttachmentSize(value?.size);
  const uploadedAt = asIso(value?.uploadedAt || value?.createdAt);
  const claimedBy = value?.claimedBy == null ? null : asId(value.claimedBy);
  if (!attachmentId || !filename || !mimeType || size === null || !uploadedAt) return null;
  if (value?.claimedBy != null && !claimedBy) return null;
  const expiresAt = claimedBy
    ? null
    : asIso(value?.expiresAt)
      || new Date(Date.parse(uploadedAt) + PERSISTENT_MIND_LIMITS.PENDING_ATTACHMENT_TTL_MS).toISOString();
  return {
    attachmentId,
    filename,
    originalName,
    mimeType,
    size,
    uploadedAt,
    expiresAt,
    claimedBy,
    claimedAt: asIso(value?.claimedAt),
    claimIndex: Number.isSafeInteger(value?.claimIndex)
      && value.claimIndex >= 0
      && value.claimIndex < PERSISTENT_MIND_LIMITS.MAX_MESSAGE_IMAGES
      ? value.claimIndex
      : null,
  };
}

/** Build the durable image reference stored on a queued or active message. */
export function normalizePersistentMindMessageImage(value) {
  const attachment = normalizePersistentMindAttachment(value);
  if (!attachment) return null;
  return {
    attachmentId: attachment.attachmentId,
    filename: attachment.filename,
    path: attachmentPath(attachment.filename),
    originalName: attachment.originalName,
    mimeType: attachment.mimeType,
    size: attachment.size,
    uploadedAt: attachment.uploadedAt,
  };
}

/**
 * Hash the bounded message content used to validate retries after completion.
 *
 * A temporary thinking-session selection is part of the content: retrying the
 * same text on a different (possibly account-billed) model is a different
 * request, not the same one. The key is omitted entirely when no override was
 * chosen so fingerprints recorded before temporary sessions existed still match
 * byte-for-byte, and an in-flight idempotent retry survives the upgrade.
 */
export function persistentMindMessageFingerprint(value) {
  const images = Array.isArray(value?.images)
    ? value.images.map((image) => (typeof image === 'string' ? image : image?.attachmentId))
      .map(asAttachmentId)
      .filter(Boolean)
    : [];
  const thinkingPresetId = asPersistentMindThinkingPresetId(value?.thinkingPresetId);
  const selection = normalizePersistentMindThinkingSelection(value?.thinkingPreset);
  return createHash('sha256')
    .update(JSON.stringify({
      text: trimTo(value?.text, PERSISTENT_MIND_LIMITS.MAX_MESSAGE_CHARS),
      images,
      ...(thinkingPresetId ? { thinkingPresetId } : {}),
      ...(thinkingPresetId && selection ? {
        thinkingPreset: { id: selection.id, providerId: selection.providerId, model: selection.model, effort: selection.effort },
      } : {}),
    }))
    .digest('hex');
}

/** Retain the accepted selection so id-only clients can retry after revocation. */
export function persistentMindMessageReceipt(message) {
  const selection = normalizePersistentMindThinkingSelection(message?.thinkingPreset);
  return {
    id: message.id,
    fingerprint: persistentMindMessageFingerprint(message),
    ...(selection ? { thinkingPreset: selection } : {}),
  };
}

/** Build the safe upload response without exposing claim bookkeeping. */
export function publicPersistentMindAttachment(value) {
  const attachment = normalizePersistentMindAttachment(value);
  if (!attachment) return null;
  return {
    attachmentId: attachment.attachmentId,
    filename: attachment.filename,
    path: attachmentPath(attachment.filename),
    originalName: attachment.originalName,
    mimeType: attachment.mimeType,
    size: attachment.size,
    uploadedAt: attachment.uploadedAt,
    expiresAt: attachment.expiresAt,
  };
}

const sanitizeMessage = (value) => {
  const id = asId(value?.id);
  const text = trimTo(value?.text, PERSISTENT_MIND_LIMITS.MAX_MESSAGE_CHARS);
  const images = [];
  const seenImageIds = new Set();
  for (const candidate of Array.isArray(value?.images) ? value.images : []) {
    const image = normalizePersistentMindMessageImage(candidate);
    if (!image || seenImageIds.has(image.attachmentId)) continue;
    seenImageIds.add(image.attachmentId);
    images.push(image);
    if (images.length >= PERSISTENT_MIND_LIMITS.MAX_MESSAGE_IMAGES) break;
  }
  if (!id || (!text && images.length === 0)) return null;
  const thinkingPresetId = asPersistentMindThinkingPresetId(value?.thinkingPresetId);
  return {
    id,
    text,
    ...(images.length > 0 ? { images } : {}),
    // Absent on every ordinary message. Kept on the durable queued/active record
    // so a requeue or a restart replays the route the user actually chose,
    // instead of quietly answering on the home profile.
    ...(thinkingPresetId || value?.thinkingPresetId || value?.thinkingPreset ? {
      thinkingPresetId: thinkingPresetId || 'invalid-preset',
      thinkingPreset: thinkingPresetId
        ? normalizePersistentMindThinkingSelection(value?.thinkingPreset)
        : null,
    } : {}),
    createdAt: asIso(value?.createdAt) || new Date(0).toISOString(),
  };
};

// One placed outbound call. Only the timestamp, the mind's own reason, and
// which subsystem asked are kept — never the handle that was dialed, which is
// the user's phone number or email and has no business in a durable ledger.
const sanitizeCallRecord = (value) => {
  const at = asIso(value?.at);
  if (!at) return null;
  return {
    at,
    reason: trimTo(value?.reason, PERSISTENT_MIND_LIMITS.MAX_CALL_REASON_CHARS),
    source: trimTo(value?.source, PERSISTENT_MIND_LIMITS.MAX_CALL_SOURCE_CHARS) || 'mind',
  };
};

const sanitizeSelfWake = (value) => {
  const id = asId(value?.id);
  const reason = trimTo(value?.reason, PERSISTENT_MIND_LIMITS.MAX_REASON_CHARS);
  const sourceTurnId = asId(value?.sourceTurnId);
  if (!id || !reason || !sourceTurnId) return null;
  return {
    id,
    kind: 'self',
    scheduleKind: PERSISTENT_MIND_SELF_WAKE_SCHEDULE_KINDS.includes(value?.scheduleKind)
      ? value.scheduleKind
      : 'requested',
    reason,
    sourceTurnId,
    ...(value?.thinkingRequest ? { thinkingRequest: normalizePersistentMindThinkingRequest(value.thinkingRequest) } : {}),
    createdAt: asIso(value?.createdAt) || new Date(0).toISOString(),
    notBefore: asIso(value?.notBefore),
  };
};

const sanitizeWake = (value) => {
  if (value?.kind === 'message') {
    const message = sanitizeMessage(value.message);
    return message ? { kind: 'message', message } : null;
  }
  return sanitizeSelfWake(value);
};

const sanitizeActiveTurn = (value) => {
  const id = asId(value?.id);
  const wake = sanitizeWake(value?.wake);
  if (!id || !wake) return null;
  return {
    id,
    wake,
    startedAt: asIso(value?.startedAt) || new Date(0).toISOString(),
    heartbeatAt: asIso(value?.heartbeatAt) || asIso(value?.startedAt) || new Date(0).toISOString(),
    providerId: asId(value?.providerId) || null,
    model: trimTo(value?.model, 500) || null,
    effort: trimTo(value?.effort, 100) || null,
  };
};

export function createDefaultPersistentMindState() {
  return {
    schemaVersion: PERSISTENT_MIND_SCHEMA_VERSION,
    mindId: PERSISTENT_MIND_ID,
    enabled: false,
    started: false,
    status: 'disabled',
    pauseReason: null,
    queuedMessages: [],
    pendingAttachments: [],
    selfWake: null,
    activeTurn: null,
    recentMessageIds: [],
    recentMessageFingerprints: [],
    callHistory: [],
    thinkingRequests: normalizePersistentMindThinkingRequests(),
    // Progressive tool exposure (#7624): which families' full schemas are
    // still on lease from a prior turn's tools.activate/renewal, plus the
    // turn id the lease was last aged against so a within-turn tool-round
    // loop never ages it twice. A selection hint only — see
    // persistentMindToolActivation.js for the "never authority" invariant.
    toolActivation: createDefaultPersistentMindToolActivation(),
    lastCompletedTurnId: null,
    lastCompletedAt: null,
    nextEligibleWakeAt: null,
    failureCount: 0,
    lastError: null,
  };
}

/** Normalize hand-edited, legacy, or partially migrated state. */
export function normalizePersistentMindState(raw) {
  const defaults = createDefaultPersistentMindState();
  const source = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
  const queuedMessages = [];
  const seenQueued = new Set();
  for (const candidate of Array.isArray(source.queuedMessages) ? source.queuedMessages : []) {
    const message = sanitizeMessage(candidate);
    if (!message || seenQueued.has(message.id)) continue;
    seenQueued.add(message.id);
    queuedMessages.push(message);
    if (queuedMessages.length >= PERSISTENT_MIND_LIMITS.MAX_QUEUED_MESSAGES) break;
  }
  const recentMessageIds = [];
  for (const candidate of Array.isArray(source.recentMessageIds) ? source.recentMessageIds : []) {
    const id = asId(candidate);
    if (!id || recentMessageIds.includes(id)) continue;
    recentMessageIds.push(id);
  }
  const recentMessageFingerprints = [];
  const seenFingerprintIds = new Set();
  for (const candidate of Array.isArray(source.recentMessageFingerprints) ? source.recentMessageFingerprints : []) {
    const id = asId(candidate?.id);
    const fingerprint = asFingerprint(candidate?.fingerprint);
    if (!id || !fingerprint || seenFingerprintIds.has(id)) continue;
    seenFingerprintIds.add(id);
    const selection = normalizePersistentMindThinkingSelection(candidate?.thinkingPreset);
    recentMessageFingerprints.push({ id, fingerprint, ...(selection ? { thinkingPreset: selection } : {}) });
  }
  const callHistory = [];
  for (const candidate of Array.isArray(source.callHistory) ? source.callHistory : []) {
    const record = sanitizeCallRecord(candidate);
    if (record) callHistory.push(record);
  }
  const pendingAttachments = [];
  const seenAttachmentIds = new Set();
  for (const candidate of Array.isArray(source.pendingAttachments) ? source.pendingAttachments : []) {
    const attachment = normalizePersistentMindAttachment(candidate);
    if (!attachment || seenAttachmentIds.has(attachment.attachmentId)) continue;
    seenAttachmentIds.add(attachment.attachmentId);
    pendingAttachments.push(attachment);
    if (pendingAttachments.length >= PERSISTENT_MIND_LIMITS.MAX_PENDING_ATTACHMENTS) break;
  }

  const enabled = source.enabled === true;
  const started = enabled && source.started === true;
  let status = PERSISTENT_MIND_STATUSES.includes(source.status)
    ? source.status
    : started ? 'idle' : enabled ? 'idle' : 'disabled';
  if (!enabled) status = 'disabled';
  else if (!started || status === 'disabled') status = 'idle';

  let selfWake = sanitizeSelfWake(source.selfWake);
  let activeTurn = sanitizeActiveTurn(source.activeTurn);
  if (!started && activeTurn) {
    if (activeTurn.wake.kind === 'message') {
      const message = activeTurn.wake.message;
      if (!recentMessageIds.includes(message.id)) {
        if (message.thinkingPresetId) {
          // A temporary session may already have spent a billed call before the
          // process stopped, and nothing on disk can say whether it did.
          // Recovering it as queued work would silently repeat that spend on the
          // next boot, so it is recorded as consumed and left for the user to
          // resend deliberately.
          const queuedIndex = queuedMessages.findIndex((queued) => queued.id === message.id);
          if (queuedIndex >= 0) queuedMessages.splice(queuedIndex, 1);
          recentMessageIds.push(message.id);
          recentMessageFingerprints.push(persistentMindMessageReceipt(message));
        } else if (!seenQueued.has(message.id)) {
          queuedMessages.unshift(message);
          if (queuedMessages.length > PERSISTENT_MIND_LIMITS.MAX_QUEUED_MESSAGES) queuedMessages.pop();
        }
      }
    } else if (!selfWake && !activeTurn.wake.thinkingRequest) {
      selfWake = activeTurn.wake;
    }
    activeTurn = null;
  }

  const thinkingRequests = normalizePersistentMindThinkingRequests(source.thinkingRequests);
  if (!started) {
    thinkingRequests.history = thinkingRequests.history.map((entry) => entry.outcome === 'admitted'
      ? { ...entry, outcome: 'interrupted' } : entry);
  }

  return {
    ...defaults,
    schemaVersion: PERSISTENT_MIND_SCHEMA_VERSION,
    mindId: asMindId(source.mindId) || PERSISTENT_MIND_ID,
    enabled,
    started,
    status,
    pauseReason: trimTo(source.pauseReason, PERSISTENT_MIND_LIMITS.MAX_REASON_CHARS) || null,
    queuedMessages,
    pendingAttachments,
    selfWake,
    activeTurn,
    recentMessageIds: recentMessageIds.slice(-PERSISTENT_MIND_LIMITS.MAX_RECENT_MESSAGE_IDS),
    recentMessageFingerprints: recentMessageFingerprints.slice(-PERSISTENT_MIND_LIMITS.MAX_RECENT_MESSAGE_IDS),
    thinkingRequests,
    toolActivation: normalizePersistentMindToolActivation(source.toolActivation),
    callHistory: callHistory.slice(-PERSISTENT_MIND_LIMITS.MAX_CALL_HISTORY),
    lastCompletedTurnId: asId(source.lastCompletedTurnId) || null,
    lastCompletedAt: asIso(source.lastCompletedAt),
    nextEligibleWakeAt: asIso(source.nextEligibleWakeAt),
    failureCount: asCount(source.failureCount),
    lastError: trimTo(source.lastError, PERSISTENT_MIND_LIMITS.MAX_REASON_CHARS) || null,
  };
}

/**
 * May the mind ring the user's phone right now?
 *
 * Two independent caps, both read from durable state so a restart, a crash, or
 * a supervisor rewire cannot hand back a fresh allowance:
 *
 * - a minimum gap, so a burst of urgent-feeling wakes cannot dial repeatedly;
 * - a rolling-window ceiling, so a persistently agitated mind still stops.
 *
 * A timestamp in the future (a clock rollback, a hand-edited state file) reads
 * as "too soon" rather than as "no recent calls" — the fail-closed reading,
 * which self-heals once the clock passes it.
 */
export function persistentMindCallRateVerdict(raw, now = Date.now(), limits = {}) {
  const {
    maxPerRollingDay = 3,
    rollingWindowMs = 24 * 60 * 60 * 1000,
    minGapMs = 30 * 60 * 1000,
  } = limits;
  const placedAt = normalizePersistentMindState(raw).callHistory
    .map((entry) => Date.parse(entry.at))
    .filter((value) => Number.isFinite(value));
  const withinWindow = placedAt.filter((at) => now - at < rollingWindowMs);
  const mostRecent = placedAt.length > 0 ? Math.max(...placedAt) : null;
  if (mostRecent !== null && now - mostRecent < minGapMs) {
    return { ok: false, reason: 'too-soon', retryAt: mostRecent + minGapMs, callsInWindow: withinWindow.length };
  }
  if (withinWindow.length >= maxPerRollingDay) {
    return {
      ok: false,
      reason: 'rate-capped',
      retryAt: Math.min(...withinWindow) + rollingWindowMs,
      callsInWindow: withinWindow.length,
    };
  }
  return { ok: true, reason: null, retryAt: null, callsInWindow: withinWindow.length };
}

/** Append one placed call to the durable, bounded call ledger. */
export function recordPersistentMindCall(raw, { at = new Date().toISOString(), reason = '', source = 'mind' } = {}) {
  const state = normalizePersistentMindState(raw);
  return normalizePersistentMindState({
    ...state,
    callHistory: [...state.callHistory, { at, reason, source }]
      .slice(-PERSISTENT_MIND_LIMITS.MAX_CALL_HISTORY),
  });
}

export function persistentMindBackoffMs(failureCount) {
  const exponent = Math.max(0, Math.min(20, asCount(failureCount) - 1));
  return Math.min(
    PERSISTENT_MIND_LIMITS.BACKOFF_MAX_MS,
    PERSISTENT_MIND_LIMITS.BACKOFF_BASE_MS * (2 ** exponent)
  );
}

/** User messages always outrank a due self-wake. */
export function takeNextPersistentMindWake(raw, now = Date.now()) {
  const state = normalizePersistentMindState(raw);
  const gateAt = state.nextEligibleWakeAt ? Date.parse(state.nextEligibleWakeAt) : 0;
  if (Number.isFinite(gateAt) && gateAt > now) return { state, wake: null, dueAt: gateAt };

  if (state.queuedMessages.length > 0) {
    const [message, ...queuedMessages] = state.queuedMessages;
    return { state: { ...state, queuedMessages }, wake: { kind: 'message', message }, dueAt: now };
  }

  if (!state.selfWake) return { state, wake: null, dueAt: null };
  const dueAt = state.selfWake.notBefore ? Date.parse(state.selfWake.notBefore) : now;
  if (Number.isFinite(dueAt) && dueAt > now) return { state, wake: null, dueAt };
  return { state: { ...state, selfWake: null }, wake: state.selfWake, dueAt: now };
}

/**
 * Does abandoning this wake risk repeating work the user may already be billed for?
 *
 * Human-selected temporary sessions and approved self-selected wakes consume
 * an attempt. A human-selected session is the one
 * route the user opted into per-message, and it may sit on an account-backed
 * provider. The home profile is the mind's ordinary heartbeat, so a self-wake
 * or an ordinary message still requeues and retries as before.
 */
export function persistentMindWakeConsumesAttempt(wake) {
  return Boolean(wake?.thinkingRequest) || (wake?.kind === 'message' && Boolean(wake.message?.thinkingPresetId));
}

/**
 * Retire a wake WITHOUT requeueing it, recording its id and fingerprint so an
 * idempotent client retry reads as a completed duplicate rather than as new
 * work. Resuming a temporary session is then an explicit user decision (a fresh
 * message id), never an automatic replay.
 */
export function holdPersistentMindWake(raw, wake) {
  const state = normalizePersistentMindState(raw);
  const sanitized = sanitizeWake(wake);
  if (sanitized?.kind === 'self' && sanitized.thinkingRequest) {
    const { thinkingRequest: _request, ...ordinary } = sanitized;
    return { ...state, selfWake: state.selfWake || {
      ...ordinary, reason: 'Resume default after local thinking attempt',
      notBefore: new Date(Date.now() + PERSISTENT_MIND_LIMITS.MAX_QUIET_MS).toISOString(),
    } };
  }
  if (sanitized?.kind !== 'message') return state;
  const { id } = sanitized.message;
  return {
    ...state,
    queuedMessages: state.queuedMessages.filter((message) => message.id !== id),
    recentMessageIds: [...state.recentMessageIds.filter((entry) => entry !== id), id]
      .slice(-PERSISTENT_MIND_LIMITS.MAX_RECENT_MESSAGE_IDS),
    recentMessageFingerprints: [
      ...state.recentMessageFingerprints.filter((entry) => entry.id !== id),
      persistentMindMessageReceipt(sanitized.message),
    ].slice(-PERSISTENT_MIND_LIMITS.MAX_RECENT_MESSAGE_IDS),
  };
}

export function requeuePersistentMindWake(raw, wake) {
  const state = normalizePersistentMindState(raw);
  const sanitized = sanitizeWake(wake);
  if (!sanitized) return state;
  if (sanitized.kind === 'message') {
    const alreadyQueued = state.queuedMessages.some((message) => message.id === sanitized.message.id);
    const alreadyCompleted = state.recentMessageIds.includes(sanitized.message.id);
    return alreadyQueued || alreadyCompleted
      ? state
      : { ...state, queuedMessages: [sanitized.message, ...state.queuedMessages] };
  }
  return { ...state, selfWake: sanitized };
}

/**
 * Report whether a source transition can safely cross a reader that predates
 * image-bearing Persistent Mind messages. Counts only durable queued/active
 * work; completed historical assets do not make rollback unsafe.
 */
export function persistentMindImageWorkGuard(raw) {
  const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
  const hasValidImages = (value) => value.images === undefined || Array.isArray(value.images);
  const source = raw == null ? {} : raw;
  const queuedMessages = source?.queuedMessages;
  const activeTurn = source?.activeTurn;
  const activeMessage = activeTurn?.wake?.kind === 'message' ? activeTurn.wake.message : null;
  const trusted = isRecord(source)
    && (queuedMessages === undefined || (
      Array.isArray(queuedMessages)
      && queuedMessages.every((message) => isRecord(message) && hasValidImages(message))
    ))
    && (activeTurn == null || isRecord(activeTurn))
    && (activeMessage == null || (isRecord(activeMessage) && hasValidImages(activeMessage)));
  if (!trusted) {
    return { safe: false, trusted: false, queuedImageMessages: 0, activeImageMessage: false };
  }
  const queuedImageMessages = (Array.isArray(queuedMessages) ? queuedMessages : [])
    .filter((message) => Array.isArray(message?.images) && message.images.length > 0)
    .length;
  const activeImageMessage = Boolean(
    activeMessage && Array.isArray(activeMessage.images) && activeMessage.images.length > 0,
  );
  return {
    safe: queuedImageMessages === 0 && !activeImageMessage,
    trusted: true,
    queuedImageMessages,
    activeImageMessage,
  };
}

export function persistentMindTurnIsStale(raw, now = Date.now(), staleMs = PERSISTENT_MIND_LIMITS.WATCHDOG_STALE_MS) {
  const active = normalizePersistentMindState(raw).activeTurn;
  if (!active) return false;
  const heartbeatAt = Date.parse(active.heartbeatAt);
  return Number.isFinite(heartbeatAt) && now - heartbeatAt >= staleMs;
}

export function nextPersistentMindWakeAt(raw, now = Date.now()) {
  const state = normalizePersistentMindState(raw);
  if (!state.enabled || !state.started || state.activeTurn || state.status === 'paused') return null;
  const gateAt = state.nextEligibleWakeAt ? Date.parse(state.nextEligibleWakeAt) : now;
  if (state.queuedMessages.length > 0) return Math.max(now, gateAt || now);
  if (!state.selfWake) return null;
  const selfAt = state.selfWake.notBefore ? Date.parse(state.selfWake.notBefore) : now;
  return Math.max(now, gateAt || now, selfAt || now);
}