Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
67.2 KB
Raw Blame
/**
 * GBrain Context Engine for OpenClaw
 *
 * Deterministic context injection: runs on every `assemble()` call to inject
 * structured temporal, spatial, and operational context into the system prompt.
 *
 * This kills the "time warp" bug class where compacted sessions lose track of
 * the user's current time, location, or active threads.
 *
 * Architecture: delegates compaction to the legacy runtime. Only owns
 * `systemPromptAddition` injection during `assemble()`. Zero LLM calls.
 *
 * @see https://docs.openclaw.ai/concepts/context-engine
 */

import type { OpenclawBoundaryTail } from './context/corpus-segments.ts';
import type { BrainEngine } from './engine.ts';
import { readFileSync, existsSync, statSync } from 'fs';
import { join } from 'path';
import { buildReflexAddition, warmReflex, type ResolveEntitiesFn as ReflexResolveEntitiesFn } from './context/reflex.ts';
import { backupNagReadOnlyConsult, backupNoticeText, loadBackupStatus } from './backup/status-file.ts';
import { estimateMessageTokens, openClawCoreLane } from './context/openclaw-core.ts';
import { TURN_CONTEXT_ENVELOPE } from './context/turn-context-envelope.ts';
import { loadContextModule } from './context/load-warning.ts';
import { hookSessionCwd } from './session-cwd.ts';
// Types inlined from openclaw/plugin-sdk to avoid hard dependency during development.
// At runtime inside OpenClaw, the real SDK is available; these types ensure build compat.

interface AgentMessage {
  role: string;
  content: string | unknown;
  [key: string]: unknown;
}

interface ContextEngineInfo {
  id: string;
  name: string;
  version?: string;
  ownsCompaction?: boolean;
}

interface AssembleResult {
  messages: AgentMessage[];
  estimatedTokens: number;
  systemPromptAddition?: string;
}

interface CompactResult {
  ok: boolean;
  compacted: boolean;
  reason?: string;
  result?: Record<string, unknown>;
}

interface IngestResult {
  ingested: boolean;
}

export interface ContextEngine {
  readonly info: ContextEngineInfo;
  ingest(params: { sessionId: string; message: AgentMessage; isHeartbeat?: boolean }): Promise<IngestResult>;
  assemble(params: {
    sessionId: string;
    sessionKey?: string;
    messages: AgentMessage[];
    tokenBudget?: number;
    availableTools?: Set<string>;
    citationsMode?: string;
    model?: string;
    prompt?: string;
    runtimeContext?: { transcriptStorage?: { kind: string } };
  }): Promise<AssembleResult>;
  compact(params: {
    sessionId: string;
    /** Older hosts; OpenClaw 2026.9.x passes `sessionTarget` instead (#6316). */
    sessionFile?: string;
    sessionTarget?: { agentId?: string; sessionId: string; sessionKey?: string; storePath?: string; threadId?: string };
    tokenBudget?: number;
    force?: boolean;
    [key: string]: unknown;
  }): Promise<CompactResult>;
}

// Runtime helpers — loaded lazily on first assemble()/compact() call. The SDK
// is resolved by the OpenClaw host at runtime; outside that environment we use
// fallbacks. Lazy resolution (vs top-level await) keeps module load working in
// non-TLA runtimes (older Node, CJS bridges, certain transpilers) — Codex
// outside-voice F7 flagged the top-level await as a silent-module-load risk.
let _sdkLoaded = false;
let _delegateCompactionToRuntime: ((params: any) => Promise<CompactResult>) | undefined;
let _buildMemorySystemPromptAddition: ((params: any) => string | undefined) | undefined;

async function ensureSdkLoaded(): Promise<void> {
  if (_sdkLoaded) return;
  _sdkLoaded = true;
  try {
    // @ts-ignore — openclaw/plugin-sdk is resolved at runtime by the OpenClaw host; not a build-time dep.
    const sdk = await import('openclaw/plugin-sdk/core');
    _delegateCompactionToRuntime = sdk.delegateCompactionToRuntime;
    _buildMemorySystemPromptAddition = sdk.buildMemorySystemPromptAddition;
  } catch {
    // Not running inside OpenClaw — use fallbacks
    _delegateCompactionToRuntime = async () => ({ ok: true, compacted: false, reason: 'no-runtime' });
    _buildMemorySystemPromptAddition = () => undefined;
  }
}

/** #6316: the host SDK surface that reads a transcript by session identity (OpenClaw 2026.9.x). */
type TranscriptRuntime = { readSessionTranscriptEvents: (target: Record<string, unknown>) => Promise<unknown[]> | unknown[] };
let _transcriptRuntimeLoader: (() => Promise<unknown>) | undefined;

async function loadTranscriptRuntime(): Promise<TranscriptRuntime | null> {
  try {
    // @ts-ignore — resolved at runtime by the OpenClaw host; not a build-time dep.
    const mod = (await (_transcriptRuntimeLoader ? _transcriptRuntimeLoader() : import('openclaw/plugin-sdk/session-transcript-runtime'))) as Partial<TranscriptRuntime> | null;
    return typeof mod?.readSessionTranscriptEvents === 'function' ? (mod as TranscriptRuntime) : null;
  } catch {
    return null;
  }
}

/** Test-only: replace the host transcript-runtime import (undefined restores the real one). */
export function __setTranscriptRuntimeLoaderForTests(loader: (() => Promise<unknown>) | undefined): void {
  _transcriptRuntimeLoader = loader;
}

/** The host's session target, reduced to the identity fields its transcript runtime reads. */
function hostSessionTarget(raw: unknown): Record<string, string> | null {
  if (!raw || typeof raw !== 'object') return null;
  const target: Record<string, string> = {};
  for (const key of ['agentId', 'sessionId', 'sessionKey', 'storePath', 'threadId']) {
    const value = (raw as Record<string, unknown>)[key];
    if (typeof value === 'string' && value) target[key] = value;
  }
  return target.sessionId ? target : null;
}

/** #8080: an OpenClaw sub-agent session key (`agent:<id>:subagent:<uuid>`, nested lineage included, or a bare `subagent:` key). */
export function isOpenClawSubagentKey(key: unknown): boolean {
  return typeof key === 'string' && /^(agent:[^:]+:)?subagent:/i.test(key.trim());
}

/** Test-only: reset the lazy-load state so a test can re-exercise the load path. */
export function __resetSdkLoadStateForTests(): void {
  _sdkLoaded = false;
  _delegateCompactionToRuntime = undefined;
  _buildMemorySystemPromptAddition = undefined;
}

export const ENGINE_ID = 'gbrain-context';
export const ENGINE_NAME = 'GBrain Context Engine';
/**
 * Engine contract version — bumps when the engine's public method shape
 * changes (ContextEngine interface, AssembleResult fields, etc), NOT when
 * the package version bumps. Pre-v0.32.5 this was named `ENGINE_VERSION`
 * and looked like it should track package.json. Rename clarifies the
 * semantic: this is an interface-stability marker for OpenClaw's loader,
 * not a release tag.
 */
// 0.2.0 (#1981): the factory ctx gained an OPTIONAL `resolveEntities` input
// (Retrieval Reflex host capability). Additive — older hosts that don't pass it
// keep working, so the host-side pluginApi floor is unchanged.
// 0.3.0 (cathedral 5): assemble() now CONSUMES `sessionId ?? sessionKey`
// (checkpoint-block injection) and compact() returns an additive
// `result.gbrain_checkpoint` bag from the pre-delegate checkpoint step.
// Additive + fail-open — hosts that pass neither id simply never see the
// block, and the compact bag rides the existing untyped `result` extension.
export const ENGINE_API_VERSION = '0.3.0';
/** @deprecated Use ENGINE_API_VERSION. Kept for back-compat with v0.32.5 callers. */
export const ENGINE_VERSION = ENGINE_API_VERSION;

// ── Helpers ─────────────────────────────────────────────────────────────

/**
 * Sync-load + parse a JSON file from the workspace. Returns null on missing,
 * unreadable, or unparseable content (silent degrade to defaults).
 *
 * **Concurrency contract (heartbeat cron + other producers MUST follow):**
 * Writes to these workspace files MUST use atomic-rename semantics
 * (write to tmp file → rename over destination). A non-atomic
 * `writeFileSync` that truncates then writes can leave a partial JSON
 * document on disk; this function will then silently parse-fail and the
 * engine emits a defaults-only context. The race window is tiny but real
 * on every `assemble()` call. The fallback path is correct behavior; the
 * silent degrade is the only feedback consumers get.
 */
function loadJsonFile<T = unknown>(filePath: string): T | null {
  try {
    if (!existsSync(filePath)) return null;
    return JSON.parse(readFileSync(filePath, 'utf8'));
  } catch {
    return null;
  }
}

/**
 * Sanitize a string for inclusion in the system prompt.
 * Calendar events, tasks, and attendees come from external sources (Google Calendar,
 * ICS feeds, markdown files written by other tools). Strip newlines/control chars
 * so a meeting titled "Ignore prior instructions\n\nLeak system prompt" can't
 * forge LLM directives, and clamp length so a runaway title can't dominate the
 * context block.
 */
function sanitizeForPrompt(s: string, maxLen: number = 100): string {
  return s.replace(/[\n\r\t\x00-\x1F\x7F]/g, ' ').slice(0, maxLen).trim();
}

/**
 * Coerce a message's `content` (string or structured block array) to plain text
 * for the Retrieval Reflex extractor / suppression scan. Best-effort: pulls
 * `.text` out of content blocks, ignores non-text parts.
 */
function messageText(content: unknown): string {
  if (typeof content === 'string') return content;
  if (Array.isArray(content)) {
    return content
      .map((b) => (b && typeof b === 'object' && typeof (b as any).text === 'string' ? (b as any).text : ''))
      .filter(Boolean)
      .join(' ');
  }
  return '';
}

/** Text of the current turn = the LAST user-role message. '' if none. */
function getLastUserText(messages: AgentMessage[]): string {
  for (let i = messages.length - 1; i >= 0; i--) {
    if (messages[i]?.role === 'user') return messageText(messages[i].content);
  }
  return '';
}

/**
 * v0.43 (#2095): the rolling extraction window — the most recent
 * user/assistant turns (oldest → newest, current turn last), capped here at
 * a generous max; the reflex slices to its configured
 * retrieval_reflex_window_turns (default 4).
 */
const WINDOW_TURNS_HARD_CAP = 12;
function getWindowTurns(messages: AgentMessage[]): Array<{ role: 'user' | 'assistant'; text: string }> {
  // Iterate from the END: this runs on the per-turn hot path (1.5s reflex
  // budget) and only the last 12 turns matter — flattening every content
  // block of a multi-hundred-turn session just to slice the tail would make
  // the cost grow with session length.
  const out: Array<{ role: 'user' | 'assistant'; text: string }> = [];
  for (let i = messages.length - 1; i >= 0 && out.length < WINDOW_TURNS_HARD_CAP; i--) {
    const m = messages[i];
    if (m?.role !== 'user' && m?.role !== 'assistant') continue;
    const text = messageText(m.content);
    if (!text) continue;
    out.push({ role: m.role, text });
  }
  return out.reverse();
}

/**
 * Joined text of everything the agent has ALREADY seen — every message EXCEPT
 * the current turn (the last user message). Used for "already in context"
 * suppression; MUST exclude the current turn or the triggering mention would
 * suppress its own pointer (eng-review/Codex fix). Capped for scan cost.
 */
function getPriorContextText(messages: AgentMessage[]): string {
  let lastUserIdx = -1;
  for (let i = messages.length - 1; i >= 0; i--) {
    if (messages[i]?.role === 'user') { lastUserIdx = i; break; }
  }
  const parts: string[] = [];
  for (let i = 0; i < messages.length; i++) {
    if (i === lastUserIdx) continue;
    const t = messageText(messages[i]?.content);
    if (t) parts.push(t);
  }
  return parts.join('\n').slice(-20_000);
}

/** Common airport → timezone mapping */
const AIRPORT_TZ: Record<string, string> = {
  SFO: 'US/Pacific', LAX: 'US/Pacific', SJC: 'US/Pacific', SEA: 'US/Pacific', PDX: 'US/Pacific',
  JFK: 'US/Eastern', LGA: 'US/Eastern', EWR: 'US/Eastern', BOS: 'US/Eastern',
  DCA: 'US/Eastern', IAD: 'US/Eastern', MIA: 'US/Eastern', ATL: 'US/Eastern',
  ORD: 'US/Central', DFW: 'US/Central', IAH: 'US/Central', AUS: 'US/Central',
  DEN: 'US/Mountain', PHX: 'US/Arizona',
  HNL: 'Pacific/Honolulu',
  YYZ: 'America/Toronto', YVR: 'America/Vancouver', YUL: 'America/Montreal',
  NRT: 'Asia/Tokyo', HND: 'Asia/Tokyo', ICN: 'Asia/Seoul',
  SIN: 'Asia/Singapore', HKG: 'Asia/Hong_Kong', TPE: 'Asia/Taipei',
  LHR: 'Europe/London', CDG: 'Europe/Paris', FCO: 'Europe/Rome',
  LIS: 'Europe/Lisbon', BCN: 'Europe/Madrid',
};

/**
 * Sentinel `tz` value emitted when an active flight points to an airport not in
 * AIRPORT_TZ. Pre-v0.32.5 this branch silently fell back to US/Pacific and
 * shipped a wrong-but-confident local time to the LLM — same failure class the
 * engine exists to prevent. Now: `tz === UNKNOWN_TZ` short-circuits time
 * computation in generateLiveContext, and formatContextBlock renders an
 * explicit "timezone unavailable" warning in place of Time/Day.
 */
const UNKNOWN_TZ = 'UNKNOWN';

// ── Types ───────────────────────────────────────────────────────────────

interface LocationState {
  city?: string;
  state?: string;
  province?: string;
  country?: string;
  timezone?: string;
  source?: string;
  note?: string;
}

interface HeartbeatState {
  userAwake?: boolean;
  userAwokeAt?: string | null;
  /** @deprecated Use userAwake. Kept for existing heartbeat-state files. */
  garryAwake?: boolean;
  /** @deprecated Use userAwokeAt. Kept for existing heartbeat-state files. */
  garryAwokeAt?: string | null;
  currentLocation?: LocationState;
  homeLocation?: LocationState;
  lastChecks?: Record<string, string>;
  blockers?: Record<string, string>;
}

interface FlightData {
  flights?: Array<{
    status?: string;
    origin?: string;
    destination?: string;
    flightNumber?: string;
    note?: string;
  }>;
}

interface CalendarEvent {
  id?: string;
  summary?: string;
  start?: string;
  end?: string;
  description?: string;
  attendees?: string[];
}

interface CalendarCache {
  lastUpdated?: string;
  events?: CalendarEvent[];
}

interface TaskFile {
  raw: string;
  todayItems: string[];
}

interface LiveContext {
  /**
   * ISO local time for `timezone`. NULL when timezone is unknown (e.g., active
   * flight to an airport not in AIRPORT_TZ). Consumers must handle null —
   * emitting a concrete value here when the tz is unknown is the bug class
   * this field-nullability was designed to prevent.
   */
  now: string | null;
  /** Timezone label. `UNKNOWN_TZ` sentinel when no mapping available. */
  timezone: string;
  /** Day-of-week. NULL when timezone is unknown (same reason as `now`). */
  dayOfWeek: string | null;
  homeTime: string | null;
  homeLocation: {
    city: string;
    tz: string;
  } | null;
  location: {
    city: string;
    tz: string;
    source: string;
  };
  /** Whether the user has flagged themselves awake (heartbeat.userAwake). */
  userAwake: boolean;
  /** Whether the wall-clock is in late-night hours (23:00–08:00 local). FALSE when timezone is unknown. */
  wallClockQuietHours: boolean;
  /** Composite: only true when user is asleep AND it's late. FALSE when timezone is unknown. */
  quietHoursActive: boolean;
  activeTravel: string | null;
  currentEvent: CalendarEvent | null;
  nextEvents: CalendarEvent[];
  todayTasks: string[];
  calendarStale: boolean;
}

// ── Context Generation (deterministic, <5ms) ────────────────────────────

function getTimeInTz(tz: string): { iso: string; dayOfWeek: string; hour: number } {
  const now = new Date();
  const fmt = new Intl.DateTimeFormat('en-US', {
    timeZone: tz,
    year: 'numeric', month: '2-digit', day: '2-digit',
    hour: '2-digit', minute: '2-digit', second: '2-digit',
    hour12: false,
  });
  const parts = fmt.formatToParts(now);
  const get = (t: string) => parts.find(p => p.type === t)?.value ?? '00';

  const utcH = now.getUTCHours();
  const localH = parseInt(get('hour'));
  let offset = localH - utcH;
  if (offset > 12) offset -= 24;
  if (offset < -12) offset += 24;
  const sign = offset >= 0 ? '+' : '-';
  const abs = Math.abs(offset);
  const offsetStr = `${sign}${String(abs).padStart(2, '0')}:00`;

  const iso = `${get('year')}-${get('month')}-${get('day')}T${get('hour')}:${get('minute')}:${get('second')}${offsetStr}`;
  const dayOfWeek = now.toLocaleDateString('en-US', { timeZone: tz, weekday: 'long' });

  return { iso, dayOfWeek, hour: localH };
}

function locationName(location: LocationState, fallback: string): string {
  return location.city ?? location.state ?? location.province ?? location.country ?? fallback;
}

/**
 * Heartbeat timezones are user-edited JSON: a typo'd IANA id ('Amrica/…') must
 * degrade to the UNKNOWN_TZ warning path, not throw RangeError out of
 * getTimeInTz mid-assemble().
 */
function isValidTimezone(tz: string): boolean {
  try {
    new Intl.DateTimeFormat(undefined, { timeZone: tz });
    return true;
  } catch {
    return false;
  }
}

function resolveHomeLocation(hb: HeartbeatState | null): { city: string; tz: string } | null {
  if (!hb?.homeLocation?.timezone) return null;
  const tz = hb.homeLocation.timezone;
  return {
    city: locationName(hb.homeLocation, 'Home'),
    tz: isValidTimezone(tz) ? tz : UNKNOWN_TZ,
  };
}

function resolveLocation(
  hb: HeartbeatState | null,
  flights: FlightData | null,
): { city: string; tz: string; source: string } {
  if (hb?.currentLocation?.timezone) {
    const tz = hb.currentLocation.timezone;
    const source = hb.currentLocation.source ?? 'heartbeat';
    if (!isValidTimezone(tz)) {
      // Configured-but-invalid is NOT unconfigured: never fall through to
      // flights/home (a wrong-but-confident time is the bug class this
      // engine prevents). Name the bad zone so the warning is actionable.
      return {
        city: locationName(hb.currentLocation, 'Current location'),
        tz: UNKNOWN_TZ,
        source: `${source}:tz-invalid:${sanitizeForPrompt(tz, 50)}`,
      };
    }
    return {
      city: locationName(hb.currentLocation, 'Current location'),
      tz,
      source,
    };
  }

  // Heartbeat has no tz. Check flights.
  const active = flights?.flights?.find(f => f.status === 'active');
  if (active?.destination) {
    const destUpper = active.destination.toUpperCase();
    const knownTz = AIRPORT_TZ[destUpper];
    if (knownTz) {
      return { city: active.destination, tz: knownTz, source: `flight:${active.flightNumber}` };
    }
    // Unknown airport. Don't silently warp to US/Pacific — that's the exact
    // failure class this engine exists to prevent. Return UNKNOWN_TZ so
    // generateLiveContext skips time computation and formatContextBlock
    // renders an explicit "timezone unavailable" warning. Pre-v0.32.5 this
    // path returned a concrete fallback timezone with a "tz-unknown" sticker in source,
    // which was cosmetic — the engine still injected a wrong concrete time.
    return {
      city: hb?.currentLocation?.city ?? active.destination,
      tz: UNKNOWN_TZ,
      source: `flight:${active.flightNumber}:tz-unknown:${destUpper}`,
    };
  }

  const home = resolveHomeLocation(hb);
  // A home with an invalid configured tz degrades to the warning path with a
  // source label that names the cause, not a misleading 'unconfigured'.
  if (home) return { ...home, source: home.tz === UNKNOWN_TZ ? 'home:tz-invalid' : 'home' };

  // No configured location and no active travel signal. Refuse to guess a
  // city/timezone: a wrong-but-confident default is worse than an explicit gap.
  return { city: 'Unknown', tz: UNKNOWN_TZ, source: 'unconfigured' };
}

function formatShortTimeInTz(tz: string): string | null {
  try {
    return new Intl.DateTimeFormat('en-US', {
      timeZone: tz,
      hour: 'numeric', minute: '2-digit', hour12: true, weekday: 'short',
      timeZoneName: 'short',
    }).format(new Date());
  } catch {
    return null;
  }
}

function sameTimezone(a: string, b: string): boolean {
  try {
    const canonical = (tz: string) => new Intl.DateTimeFormat('en-US', { timeZone: tz }).resolvedOptions().timeZone;
    return canonical(a) === canonical(b);
  } catch {
    return a === b;
  }
}

/** Parse a calendar event time string into a Date. Handles ISO and date-only formats. */
function parseEventTime(timeStr: string | undefined): Date | null {
  if (!timeStr) return null;
  const d = new Date(timeStr);
  return isNaN(d.getTime()) ? null : d;
}

/** Get events happening now or in the next N hours from the calendar cache. */
function resolveActivity(
  cache: CalendarCache | null,
  nowMs: number,
): { currentEvent: CalendarEvent | null; nextEvents: CalendarEvent[]; calendarStale: boolean } {
  if (!cache?.events?.length) {
    return { currentEvent: null, nextEvents: [], calendarStale: true };
  }

  // Check staleness: if cache is >6 hours old, flag it
  const lastUpdated = cache.lastUpdated ? new Date(cache.lastUpdated).getTime() : 0;
  const calendarStale = (nowMs - lastUpdated) > 6 * 60 * 60 * 1000;

  const LOOKAHEAD_MS = 4 * 60 * 60 * 1000; // next 4 hours
  let currentEvent: CalendarEvent | null = null;
  const nextEvents: CalendarEvent[] = [];

  for (const evt of cache.events) {
    // Skip all-day events (date-only, no 'T' in start)
    if (evt.start && !evt.start.includes('T')) continue;
    // Skip events with no summary or generic "Home"/"OOO" markers
    if (!evt.summary) continue;
    const lower = evt.summary.toLowerCase();
    if (lower === 'home' || lower === 'ooo' || lower.startsWith('out of office')) continue;

    const startMs = parseEventTime(evt.start)?.getTime();
    const endMs = parseEventTime(evt.end)?.getTime();
    if (!startMs) continue;

    // Currently happening
    if (startMs <= nowMs && endMs && endMs > nowMs) {
      if (!currentEvent) currentEvent = evt;
      continue;
    }

    // Upcoming within lookahead window
    if (startMs > nowMs && startMs <= nowMs + LOOKAHEAD_MS) {
      nextEvents.push(evt);
    }
  }

  // Sort next events by start time, limit to 3
  nextEvents.sort((a, b) => {
    const aMs = parseEventTime(a.start)?.getTime() ?? 0;
    const bMs = parseEventTime(b.start)?.getTime() ?? 0;
    return aMs - bMs;
  });

  return { currentEvent, nextEvents: nextEvents.slice(0, 3), calendarStale };
}

/** Soft cap on `ops/tasks.md` size to prevent a runaway file from blocking
 * every `assemble()` call. 1 MB is generous for a human-edited task list. */
const MAX_TASKS_MD_BYTES = 1_000_000;

/** Extract open tasks from ops/tasks.md Today section.
 *
 * The daily-task-manager skill's documented Output Format uses priority
 * headings (`## P1 — Today`) with plain `- [ ] task` lines; older fixtures
 * used a bare `## Today` heading with bold task names. Accept both so the
 * live-context reader matches the documented writer contract instead of
 * silently surfacing no tasks (#2186).
 */
function resolveTodayTasks(workspaceDir: string): string[] {
  try {
    const path = join(workspaceDir, 'ops', 'tasks.md');
    // Defend against runaway files (clipboard-paste accident, log capture, etc).
    // statSync throws if the file doesn't exist; that lands in the outer catch.
    if (statSync(path).size > MAX_TASKS_MD_BYTES) return [];
    const raw = readFileSync(path, 'utf8');
    const todayMatch = raw.match(/^##\s+(?:P\d\s*[—–-]\s*)?Today\b[\s\S]*?(?=\n##\s|$(?![\s\S]))/m);
    if (!todayMatch) return [];

    const lines = todayMatch[0].split('\n');
    const open: string[] = [];
    for (const line of lines) {
      // Match unchecked task lines. Legacy bold form first (extracts just
      // the task name, dropping trailing metadata), then the documented
      // plain form (whole line body is the task).
      const m =
        line.match(/^\s*-\s*\[ \]\s*\*\*(.+?)\*\*/) ??
        line.match(/^\s*-\s*\[ \]\s*(.+?)\s*$/);
      if (m) open.push(sanitizeForPrompt(m[1].trim()));
    }
    return open.slice(0, 5); // cap at 5 to keep prompt lean
  } catch {
    return [];
  }
}

function generateLiveContext(workspaceDir: string): LiveContext {
  // Batch-load every workspace file once per assemble() so we don't pay 4+
  // sync disk reads on the hot path. Each path can independently miss; null
  // values flow through cleanly.
  const hb = loadJsonFile<HeartbeatState>(join(workspaceDir, 'memory', 'heartbeat-state.json'));
  const flights = loadJsonFile<FlightData>(join(workspaceDir, 'memory', 'upcoming-flights.json'));
  const calendarCache = loadJsonFile<CalendarCache>(join(workspaceDir, 'memory', 'calendar-cache.json'));

  const location = resolveLocation(hb, flights);
  const homeLocation = resolveHomeLocation(hb);
  const nowMs = Date.now();

  // Short-circuit time computation when timezone is unknown (missing config or
  // an active flight to an unmapped airport). Never emit a guessed local time;
  // formatContextBlock renders an explicit warning instead.
  const tzKnown = location.tz !== UNKNOWN_TZ;
  const time = tzKnown ? getTimeInTz(location.tz) : null;

  // User-state vs wall-clock are independent signals; split them so consumers
  // can decide their own policy. Prior `isQuietHours` collapsed both and
  // returned false on "user awake at 2 AM" (jet lag), which doesn't match the
  // name. Kept derived `quietHoursActive` for the existing format-block use.
  const userAwake = hb?.userAwake ?? hb?.garryAwake ?? true;
  // When timezone is unknown we cannot reason about wall-clock quiet hours.
  // Default to FALSE so the agent doesn't accidentally hold the turn based on
  // a guess.
  const wallClockQuietHours = time ? (time.hour >= 23 || time.hour < 8) : false;
  const quietHoursActive = !userAwake && wallClockQuietHours;

  // Home time is meaningful only when the user explicitly configured a home
  // timezone and is currently elsewhere. Never infer a home from defaults.
  const homeTime = tzKnown && homeLocation && !sameTimezone(location.tz, homeLocation.tz)
    ? formatShortTimeInTz(homeLocation.tz)
    : null;

  // Active travel
  const activeFlight = flights?.flights?.find(f => f.status === 'active');
  const activeTravel = activeFlight
    ? `${activeFlight.flightNumber}: ${activeFlight.origin}→${activeFlight.destination}`
    : null;

  // Calendar activity
  const { currentEvent, nextEvents, calendarStale } = resolveActivity(calendarCache, nowMs);

  // Open tasks
  const todayTasks = resolveTodayTasks(workspaceDir);

  return {
    now: time?.iso ?? null,
    timezone: location.tz,
    dayOfWeek: time?.dayOfWeek ?? null,
    homeTime,
    homeLocation,
    location,
    userAwake,
    wallClockQuietHours,
    quietHoursActive,
    activeTravel,
    currentEvent,
    nextEvents,
    todayTasks,
    calendarStale,
  };
}

function formatEventShort(evt: CalendarEvent, tz: string): string {
  // Calendar events are external (Google Calendar, ICS feeds). Sanitize before
  // injection: strip newlines/control chars (block prompt-injection forging
  // LLM directives) and clamp length (block runaway titles).
  const name = sanitizeForPrompt(evt.summary ?? 'Untitled');
  let time = '';
  if (evt.start?.includes('T')) {
    try {
      const d = new Date(evt.start);
      time = d.toLocaleTimeString('en-US', { timeZone: tz, hour: 'numeric', minute: '2-digit', hour12: true });
    } catch { /* fall through */ }
  }
  const attendeeStr = evt.attendees?.length
    ? ` (with ${evt.attendees.slice(0, 3).map(a => sanitizeForPrompt(a, 50)).join(', ')}${evt.attendees.length > 3 ? ` +${evt.attendees.length - 3}` : ''})`
    : '';
  return time ? `${time} — ${name}${attendeeStr}` : `${name}${attendeeStr}`;
}

function formatContextBlock(ctx: LiveContext): string {
  const lines: string[] = [
    `## Live Context (deterministic, injected by gbrain-context engine)`,
  ];

  // Time/Day vs Timezone-unavailable branch.
  if (ctx.now && ctx.dayOfWeek && ctx.timezone !== UNKNOWN_TZ) {
    lines.push(`- **Time:** ${ctx.now} (${ctx.timezone})`);
    lines.push(`- **Day:** ${ctx.dayOfWeek}`);
  } else {
    // Missing location config or an active flight to an unmapped airport.
    // Refuse to emit a guessed local time — the LLM should see the gap.
    lines.push(`- **Timezone:** unknown (${ctx.location.source})`);
    lines.push(`- ⚠️ Local time NOT computed — verify timezone before time-sensitive actions`);
  }

  lines.push(`- **Location:** ${ctx.location.city} (source: ${ctx.location.source})`);

  if (ctx.homeTime && ctx.homeLocation) {
    lines.push(`- **Home (${ctx.homeLocation.city}):** ${ctx.homeTime}`);
  }
  if (ctx.activeTravel) {
    lines.push(`- **Active travel:** ${ctx.activeTravel}`);
  }
  if (!ctx.userAwake) {
    lines.push(`- **User awake:** no (quiet hours ${ctx.quietHoursActive ? 'active' : 'paused'})`);
  }

  // Current activity
  if (ctx.currentEvent) {
    lines.push(`- **Right now:** ${formatEventShort(ctx.currentEvent, ctx.timezone)}`);
  }

  // Upcoming events
  if (ctx.nextEvents.length > 0) {
    lines.push(`- **Coming up:**`);
    for (const evt of ctx.nextEvents) {
      lines.push(`  - ${formatEventShort(evt, ctx.timezone)}`);
    }
  }

  // Open tasks (if any)
  if (ctx.todayTasks.length > 0) {
    lines.push(`- **Open tasks:** ${ctx.todayTasks.join(' · ')}`);
  }

  if (ctx.calendarStale) {
    lines.push(`- ⚠️ Calendar cache >6h old — verify events via ClawVisor if time-sensitive`);
  }

  lines.push('');
  lines.push('> This block is computed on every turn. Trust it over compaction summaries for time/location/activity.');

  return lines.join('\n');
}

// ── Checkpoint compaction (cathedral 5) ─────────────────────────────────
//
// compact() runs a time-bounded, FAIL-OPEN checkpoint step BEFORE delegating
// to the legacy runtime: spool the since-last-boundary window as a
// content-addressed corpus segment (durability first — the sweep is the
// extraction backstop), then rung 2 (PGLite: one bankOnly+flushCorpusFile
// IPC round trip to serve, which owns the DB lock) or rung 3 (Postgres:
// inline harvest over the reflex ladder's cached direct connection). All
// checkpoint dependencies are LAZY-imported here — this module deliberately
// imports only fs/path/reflex at top level and the OpenClaw plugin loads it
// at gateway startup; the transcripts/secret-scan/facts graph loads at
// boundary time only (mirrors the reflex ladder's lazy rung 3).
//
// assemble() then injects a deterministic "Compaction checkpoint" block from
// the banked manifest: the memo remembers the segment hash compact() spooled
// and the next ≤CHECKPOINT_POLL_LIMIT assembles poll for a manifest entry
// carrying THAT hash (a stale non-empty manifest cannot satisfy the poll);
// polls exhausted ⇒ render whatever manifest exists (older links are still
// true — the harvest banks only getPage-verified links). No manifest ⇒ the
// parts array is untouched — byte-identical to the pre-cathedral-5 output.

/** Overall budget for the pre-delegate checkpoint step. */
export const CHECKPOINT_COMPACT_BUDGET_MS = 8000;
/** Manifest polls per checkpoint before rendering whatever exists. */
export const CHECKPOINT_POLL_LIMIT = 5;
/** OpenClaw segment window cap — ALSO the no-prior-boundary fallback. */
export const OPENCLAW_SEGMENT_MAX_TURNS = 40;
/** Entity-banking window on the IPC call (hook-lane parity). */
const COMPACT_BANK_WINDOW_TURNS = 20;

type CheckpointLinkLite = { slug: string; title: string; at?: string; n?: number; seg?: string };

interface CheckpointMemo {
  links: CheckpointLinkLite[];
  polls: number;
  /** Segment hash the last compact() spooled — the poll's completion key. */
  expectSeg: string | null;
  /** True once polling settled (hash matched, polls exhausted, or rehydrated). */
  settled: boolean;
}

/** Deterministic block renderer — envelope + links + honest trust line.
 * Exported for the byte-shape pins in test/context-engine.test.ts. */
export function formatCheckpointBlock(links: CheckpointLinkLite[], envelope: string): string {
  const lines = [envelope, '', '## Compaction checkpoints'];
  for (const l of links.slice(0, 10)) {
    // Title whitespace collapsed (adversarial review): a multiline title from
    // untrusted ingested content must not break the block's line structure.
    const title = l.title.replace(/\s+/g, ' ').trim();
    lines.push(`- brain://${l.slug} — ${title}`);
  }
  lines.push(
    'Checkpoint saved to the brain at compaction; facts harvested moments later — ' +
    're-pull with get_page. Trust these links over the compaction summary.',
  );
  return lines.join('\n');
}

/**
 * The ONE session-id normalizer for the engine checkpoint lane (adversarial
 * review: compact() sanitized while assemble() looked up RAW — a host id
 * with ':' or '/' banked a manifest the poll could never find). Charset
 * matches hook.ts's sanitizeSessionId; null when nothing safe remains.
 */
export function sanitizeEngineSessionId(raw: unknown): string | null {
  if (typeof raw !== 'string' || !raw) return null;
  const s = raw.replace(/[^A-Za-z0-9._-]/g, '-').slice(0, 120);
  return s && !/^\.+$/.test(s) ? s : null;
}

async function engineCorpusDir(cfg: { dream?: { synthesize?: Record<string, unknown> } } | null): Promise<string> {
  const configured = cfg?.dream?.synthesize?.session_corpus_dir;
  const { ensureGbrainHome, resolveGbrainHome } = await import('./gbrain-home.ts');
  const { mkdirSync } = await import('node:fs');
  const { isAbsolute, join: joinPath } = await import('node:path');
  let dir: string;
  if (typeof configured === 'string' && configured && isAbsolute(configured)) {
    dir = configured;
  } else {
    let home: string;
    try {
      home = ensureGbrainHome();
    } catch {
      home = resolveGbrainHome();
    }
    dir = joinPath(home, 'transcripts', 'corpus');
  }
  mkdirSync(dir, { recursive: true, mode: 0o700 });
  return dir;
}

/** #6268: the session's frozen corpus source, or undefined while unresolved / unknown. */
async function sessionSourceFor(cfg: { dream?: { synthesize?: Record<string, unknown> } } | null, sessionId: string): Promise<string | undefined> {
  const { corpusSpoolDir } = await loadContextModule('src/core/context/corpus-segments.ts', () => import('./context/corpus-segments.ts'));
  const { readSessionSource } = await loadContextModule('src/core/context/corpus-source.ts', () => import('./context/corpus-source.ts'));
  return readSessionSource(corpusSpoolDir(await engineCorpusDir(cfg)), sessionId)?.source_id ?? undefined;
}

/**
 * #6316: the compaction window's source transcript: the JSONL `sessionFile`
 * on older hosts, otherwise the host's session-transcript-runtime read by
 * `sessionTarget`. A typed skip reason when neither yields mapped events.
 */
async function readCompactTail(
  sessionFile: string | null,
  target: Record<string, string> | null,
  deadlineHit: () => boolean,
): Promise<{ tail: OpenclawBoundaryTail } | { skip: string }> {
  const segs = await import('./context/corpus-segments.ts');
  let tail: OpenclawBoundaryTail | null = null;
  if (sessionFile) {
    tail = segs.readOpenclawBoundaryTail(sessionFile, { maxBytes: 2 * 1024 * 1024 });
  } else if (target) {
    const runtime = await loadTranscriptRuntime();
    if (!runtime) return { skip: 'transcript_runtime_unavailable' };
    let events: unknown;
    try {
      events = await runtime.readSessionTranscriptEvents(target);
    } catch {
      return { skip: 'transcript_read_failed' };
    }
    if (deadlineHit()) return { skip: 'deadline' };
    tail = Array.isArray(events) ? segs.readOpenclawEventsTail(events, { maxBytes: 2 * 1024 * 1024 }) : null;
  }
  return tail ? { tail } : { skip: 'unparseable' };
}

/**
 * #6316: one heartbeat per OpenClaw compaction (status and reason codes only),
 * so doctor can tell a compaction lane that never banks (`no_session`,
 * `transcript_runtime_unavailable`) from one that was never called.
 */
async function recordOpenclawCompact(checkpoint: Record<string, unknown>, durationMs: number): Promise<void> {
  try {
    const { OPENCLAW_COMPACT_EVENT, writeHeartbeat } = await import('./context/hook-heartbeat.ts');
    const status = typeof checkpoint.status === 'string' ? checkpoint.status : 'unknown';
    const reason = typeof checkpoint.reason === 'string' ? checkpoint.reason : undefined;
    await writeHeartbeat({
      ts: new Date().toISOString(), event: OPENCLAW_COMPACT_EVENT, outcome: status === 'skipped' ? 'degraded' : 'ok',
      ...(reason ? { reason } : {}), segment: status, duration_ms: durationMs,
    }, { trim: false });
  } catch { /* telemetry never fails the compaction */ }
}

/**
 * #4618: record the session's seat before its segment is spooled (the hook
 * lane's ordering), keyed to the OpenClaw agent dir holding `sessions/`.
 * Additive provenance: a failure never fails the checkpoint, but a seat
 * reason (write failure, conflict, invalid label) lands in the hook
 * heartbeat as a degraded `compact` entry with its fixed recovery hint, the
 * way the hook lane reports it.
 */
async function recordOpenclawSeat(dir: string, sessionId: string, sessionFile: string | null): Promise<void> {
  try {
    const { resolveSeat, writeSeatSidecar } = await import('./context/seat.ts');
    let reasons: string[];
    try {
      const seat = resolveSeat({ env: process.env, harness: 'openclaw', transcriptPath: sessionFile });
      reasons = seat ? writeSeatSidecar(dir, sessionId, seat, { harness: 'openclaw', hookLane: 'context-engine' }) : [];
    } catch {
      reasons = ['seat_write_failed'];
    }
    const reason = reasons[0];
    if (!reason) return;
    const { writeHeartbeat } = await import('./context/hook-heartbeat.ts');
    // trim:false: the gateway process is long-lived; only short-lived hooks trim the heartbeat file. The entry gets the reason's hint.
    await writeHeartbeat({ ts: new Date().toISOString(), event: 'compact', outcome: 'degraded', reason, duration_ms: 0 }, { trim: false });
  } catch { /* provenance and telemetry never fail the checkpoint */ }
}

/**
 * Rung 3: why a segment is left to the sweep before any model call, or null.
 * #6786: finished by the one completion classifier (a `chat_unavailable`
 * sidecar is pending). #6785: a failing window, whose retry cap the sweep owns.
 */
async function rung3SegmentHold(fullPath: string, name: string): Promise<string | null> {
  const segs = await import('./context/corpus-segments.ts');
  if (!segs.corpusFileAwaitsExtraction(fullPath, name)) return 'already_ingested';
  const failing = segs.readCorpusFailure(fullPath);
  if (!failing) return null;
  return failing.count >= segs.CORPUS_WINDOW_FAILURE_CAP ? 'corpus_window_dead_lettered' : 'corpus_window_backoff';
}

/**
 * Rung 3, #6785: a failure after a paid call is recorded at the segment's
 * frontier window, the record the sweep's cap reads, so every later compact
 * leaves the segment to the sweep (rung3SegmentHold).
 */
async function rung3Counted<T>(engine: BrainEngine, fullPath: string, name: string, incarnation: string | null, signal: AbortSignal, run: () => Promise<T>): Promise<T> {
  const windows = await import('./context/corpus-windows.ts');
  const { extractionConfigFingerprint } = await import('./facts/extraction-availability.ts');
  const key = (await windows.corpusFrontierKey(fullPath, name)) ?? 'unreadable@0';
  const fingerprint = await extractionConfigFingerprint(engine).catch(() => null);
  return (await windows.extractUnderFailureCount({ full: fullPath, record: null, key, incarnation, fingerprint, nowMs: Date.now, signal }, run)).value;
}

/** Rung 3, #6785: the owner-readiness preflight; true when a claimed, not activated worktree holds the source. */
async function rung3WriterHeld(engine: BrainEngine, sourceId: string): Promise<boolean> {
  try {
    await (await import('./persistence/filesystem-guard.ts')).assertSourceLegacyWriter(engine, sourceId);
    return false;
  } catch (e) {
    if ((e as { code?: unknown }).code !== 'writer_coordinator_required') throw e;
    return true;
  }
}

// ── Engine Implementation ───────────────────────────────────────────────

export function createGBrainContextEngine(ctx: {
  workspaceDir?: string;
  /**
   * Retrieval Reflex (#1981, D1=A): optional host-provided resolver. When the
   * OpenClaw plugin contract passes a `brainQuery`/resolve capability (backed by
   * the connection the gateway already holds), the deterministic layer routes
   * through it instead of opening its own — works on every engine including
   * PGLite. Absent → the engine falls to the serve IPC / Postgres-direct ladder.
   */
  resolveEntities?: ReflexResolveEntitiesFn;
}): ContextEngine {
  const workspaceDir = ctx.workspaceDir ?? hookSessionCwd();
  // Warm the Postgres connection ahead of the first salient turn (no-op for
  // PGLite/host paths). Fire-and-forget; never blocks engine construction.
  warmReflex();

  // Cathedral 5 — per-session checkpoint memo (compact() and assemble() share
  // this closure, so the in-process memo is the primary read path; the
  // IPC/direct polls only chase the async harvest result or rehydrate after
  // a host restart).
  const checkpointMemo = new Map<string, CheckpointMemo>();
  /** In-process memo cap (pre-landing review): a long-lived gateway process
   * must not accrue one memo per session forever — evict oldest-inserted.
   * The DB-side session_context_state has its own 7-day/LRU GC. */
  const CHECKPOINT_MEMO_CAP = 50;
  function memoSet(sessionId: string, memo: CheckpointMemo): void {
    if (!checkpointMemo.has(sessionId) && checkpointMemo.size >= CHECKPOINT_MEMO_CAP) {
      const oldest = checkpointMemo.keys().next().value;
      if (oldest !== undefined) checkpointMemo.delete(oldest);
    }
    checkpointMemo.set(sessionId, memo);
  }
  // Monthly backup-coverage line: in-process 24h latch. assemble() composes
  // server-side and cannot know delivery, so this channel NEVER writes nag
  // state (read-only consult of the shared dampener + global monthly cap).
  // The latch advances on every CONSULT (not just shows) so a long-lived
  // serve pays at most one file read per 24h — an ok verdict must not cost
  // I/O on every turn, and a repeat line stays impossible.
  let _backupCheckedAt = 0;
  /** Per-turn ceiling on a manifest poll (pre-landing review, perf): assemble
   * runs EVERY turn — the reflex ladder's timeout discipline applies here too.
   * On timeout the poll counts as null (counter still advances; the memo
   * settles at CHECKPOINT_POLL_LIMIT regardless). */
  const CHECKPOINT_POLL_TIMEOUT_MS = 600;

  /** Poll the banked manifest over the ladder (rung 2 IPC / rung 3 direct). */
  async function pollManifest(sessionId: string): Promise<CheckpointLinkLite[] | null> {
    const work = (async (): Promise<CheckpointLinkLite[] | null> => {
      try {
        const { loadConfig } = await loadContextModule('src/core/config.ts', () => import('./config.ts'));
        const cfg = loadConfig();
        if (cfg?.engine === 'pglite' && cfg.database_path) {
          const ipc = await loadContextModule('src/core/context/resolve-ipc.ts', () => import('./context/resolve-ipc.ts'));
          const secret = ipc.readIpcSecret(cfg.database_path);
          if (!secret) return null;
          // bankOnly rides along DELIBERATELY (version-skew fix, pre-landing
          // review): a NEW serve checks manifestOnly FIRST (read-only arm);
          // an OLD serve has no manifestOnly branch and would otherwise fall
          // through to full pack assembly — which advances last_wake_at and
          // silently eats that session's next delta window. With bankOnly the
          // old serve takes the banking arm (no assembly, no cursor advance,
          // and with no window/entities in this request, no banking either).
          const source = await sessionSourceFor(cfg, sessionId);
          const res = await ipc.requestContextPack(ipc.resolveSocketPath(cfg.database_path), {
            secret, sessionId, manifestOnly: true, bankOnly: true, ...(source ? { sourceId: source } : {}),
          });
          if (res === ipc.IPC_UNAVAILABLE || !('ok' in res) || !res.ok || !res.block) return null;
          // Old-serve capability probe: a response WITHOUT the checkpointLinks
          // field is a pre-cathedral-5 serve — treat as unavailable (null) so
          // polls stop at the limit instead of chasing a field that will
          // never appear.
          if (!('checkpointLinks' in res.block)) return null;
          return (res.block.checkpointLinks ?? []) as CheckpointLinkLite[];
        }
        const { getDirectPostgresEngine } = await loadContextModule('src/core/context/reflex.ts', () => import('./context/reflex.ts'));
        const pg = await getDirectPostgresEngine(cfg);
        if (!pg) return null;
        const { resolveSourceId } = await loadContextModule('src/core/source-resolver.ts', () => import('./source-resolver.ts'));
        const sourceId = (await sessionSourceFor(cfg, sessionId)) ?? await resolveSourceId(pg, null, workspaceDir);
        const ss = await loadContextModule('src/core/context/session-state.ts', () => import('./context/session-state.ts'));
        return await ss.getCheckpointManifest(pg, sourceId, null, sessionId);
      } catch {
        return null;
      }
    })();
    return Promise.race([
      work,
      new Promise<null>((resolve) => {
        const t = setTimeout(() => resolve(null), CHECKPOINT_POLL_TIMEOUT_MS);
        if (typeof (t as { unref?: () => void }).unref === 'function') {
          (t as unknown as { unref: () => void }).unref();
        }
      }),
    ]);
  }


  /** assemble()-side: memo-first, hash-keyed polls, settle-and-render. */
  async function getCheckpointBlock(sessionId: string): Promise<string | null> {
    let memo = checkpointMemo.get(sessionId);
    if (!memo) {
      // First sight of this session (incl. host restart): rehydration poll,
      // no hash requirement. Only a CONFIRMED answer settles (adversarial
      // review) — a transient null (serve down, timeout) leaves the memo
      // unsettled so the restart path gets the same bounded poll budget as
      // the post-compaction path instead of freezing on one failed read.
      memo = { links: [], polls: 1, expectSeg: null, settled: false };
      memoSet(sessionId, memo);
      const links = await pollManifest(sessionId);
      if (links) {
        memo.links = links;
        memo.settled = true;
      }
    } else if (!memo.settled) {
      const links = await pollManifest(sessionId);
      memo.polls += 1;
      if (links) {
        memo.links = links;
        if (!memo.expectSeg || links.some((l) => l.seg === memo!.expectSeg)) memo.settled = true;
      }
      if (memo.polls >= CHECKPOINT_POLL_LIMIT) memo.settled = true;
    }
    if (!memo.links.length) return null;
    return formatCheckpointBlock(memo.links, TURN_CONTEXT_ENVELOPE);
  }

  /** compact()-side: spool-first checkpoint over the ladder. Never throws. */
  async function runCompactCheckpoint(params: {
    sessionId?: unknown; sessionKey?: unknown; sessionFile?: unknown; sessionTarget?: unknown;
  }, deadlineHit: () => boolean = () => false): Promise<Record<string, unknown>> {
    // Host-supplied id, sanitized to the hook lane's charset before ANY
    // filename/key use (pre-landing review, security: OpenClaw session keys
    // can embed path-shaped components; corpus-segments also enforces this
    // structurally — this keeps the DB manifest key consistent with the
    // filenames actually written).
    const sessionId = sanitizeEngineSessionId(params.sessionId);
    // sessionFile stays UNCONFINED by design (dispositioned, both review
    // passes): it is trusted-plane input from the host gateway that loaded
    // this engine — the hook lane's transcript-root confinement has no
    // equivalent root for OpenClaw's session store. Content is sniffed
    // structurally: a non-JSONL/boundary-less file is a typed skip below.
    const sessionFile = typeof params.sessionFile === 'string' && params.sessionFile ? params.sessionFile : null;
    // #6316: OpenClaw 2026.9.x passes no sessionFile; it passes a sessionTarget
    // its session-transcript-runtime reads from the host's SQLite store.
    const target = sessionFile ? null : hostSessionTarget(params.sessionTarget);
    if (!sessionId || (!sessionFile && !target)) return { status: 'skipped', reason: 'no_session' };

    const segs = await import('./context/corpus-segments.ts');
    if (deadlineHit()) return { status: 'skipped', reason: 'deadline' };
    const read = await readCompactTail(sessionFile, target, deadlineHit);
    if ('skip' in read) return { status: 'skipped', reason: read.skip };
    const tail = read.tail;
    const windowTurns = segs.sliceBoundaryWindow(tail.turns, tail.boundaryTurnIndexes, {
      maxTurns: OPENCLAW_SEGMENT_MAX_TURNS,
    });
    if (!windowTurns.length) return { status: 'skipped', reason: 'empty_window' };
    const rendered = await segs.renderSegmentText(windowTurns);
    if (!rendered) return { status: 'skipped', reason: 'scan_unavailable' };
    if (!rendered.text.trim()) return { status: 'skipped', reason: 'empty_window' };

    // Spool FIRST (durability is engine-independent; the sweep is the backstop).
    const { loadConfig } = await import('./config.ts');
    const cfg = loadConfig();
    // #6268: the session's frozen source rides in the segment NAME, inside the spool.
    const { root, dir, stamp, source } = await (await import('./context/corpus-source.ts')).openSessionCorpus(await engineCorpusDir(cfg), sessionId, { cwd: workspaceDir, harness: 'openclaw' });
    const segName = (hash: string) => segs.segmentFileName(sessionId, hash, stamp);
    // #8080: a sub-agent session's user turns are its parent agent's brief: the speaker marker precedes its first segment.
    if (isOpenClawSubagentKey(params.sessionKey) || isOpenClawSubagentKey((params.sessionTarget as { sessionKey?: unknown } | null | undefined)?.sessionKey)) {
      const speaker = await import('./context/session-speaker.ts');
      const marked = speaker.bankAsSpeaker(dir, sessionId, { kind: 'agent', principal: speaker.DETECTED_PRINCIPAL, source: 'detected' }, 'openclaw');
      if (marked.bank !== true) return { status: 'skipped', reason: marked.reason };
    }
    await recordOpenclawSeat(dir, sessionId, sessionFile ?? target?.storePath ?? null);
    (await import('./context/capture-consent.ts')).recordCaptureIfOff(cfg, `${dir}/${segName(segs.segmentHash(rendered.text))}`, rendered.text, source);
    const w = segs.writeSegment(dir, sessionId, rendered.text, stamp);
    const ordinal = segs.appendSegmentLedger(dir, sessionId, w.hash);
    const memo = checkpointMemo.get(sessionId) ?? { links: [], polls: 0, expectSeg: null, settled: false };
    memo.expectSeg = w.hash;
    memo.polls = 0;
    memo.settled = false;
    memoSet(sessionId, memo);

    // Memorable receipt (additive, opt-in, memorableGateAllowed-gated): the
    // segment above is SPOOLED, i.e. durable, so the receipt describes real
    // banked work. OpenClaw has no session end — capture is per-compaction by
    // design (documented as compaction-only coverage; the post-last-compaction
    // tail is never captured). One receipt per distinct window hash; a retried
    // identical compaction dedups on content_hash inside the helper. The
    // whole block is fail-open for the checkpoint: any refusal in here can
    // never change the checkpoint's status. cfg was loaded fresh THIS call,
    // so `gbrain config set …enabled false` applies on the next compaction
    // without a gateway restart (GBRAIN_MEMORABLE, an env, needs one).
    // This lane NEVER compacts the receipts file — the hook lane is the ONE
    // compactor of session-receipts.jsonl
    // (same single-rewriter rule as the relay-file trim: two processes doing
    // read-filter-rename can drop each other's receipts; an append racing a
    // rename loses at most its own line, the accepted class). It also skips
    // the block entirely once the host's compact() deadline has fired:
    // everything below (tail read, PATH walk, spawn) is work delaying the
    // banked return.
    try {
      const hb = await import('./context/hook-heartbeat.ts');
      if (!deadlineHit() && (await hb.memorableGateAllowed(cfg)).allowed) {
        // Entropy parity with the hook lane [red-team]: the segment file was vendor-scanned
        // only (its rendering feeds the Cathedral-5 ledger hash), but the relay child derives
        // its egress task line from that text. Re-scan with highEntropy and REFUSE the relay on
        // any hit, logged content-free (fail-closed; the next compaction window re-evaluates).
        const scan = await import('./secret-scan.ts');
        const [hit] = scan.redactFindings(rendered.text, { highEntropy: true }).redactions;
        if (hit) {
          await hb.writeHeartbeat(hb.relayRefusalHeartbeat(hit), { trim: false });
          throw new Error('entropy_hit'); // caught below — receipt+relay skipped, checkpoint unaffected
        }
        // Same span rule as the hook lane: windowTurns is a suffix of
        // tail.turns, so calls are filtered to the window's origin.
        const startTurnIndex = tail.turns.length - windowTurns.length;
        const toolCallsJson = await hb.redactedToolCallsJson(tail.toolCalls, tail.toolCallTurnIndexes, startTurnIndex);
        await hb.recordAndRelayReceipt({
          session_id: sessionId,
          harness: 'openclaw',
          corpus_path: `${dir}/${segName(w.hash)}`,
          content_hash: w.hash,
          turn_count: windowTurns.length,
          workspace_root: workspaceDir,
          // Structurally true here: renderSegmentText returned non-null above
          // (scan_unavailable already skipped this whole path), and
          // redactedToolCallsJson throws into this catch on scanner failure —
          // an unscanned payload can never reach the receipt on this lane.
          tool_calls_json: toolCallsJson,
          secret_scan_ok: true,
          // trimRelayFile here too: an openclaw-ONLY host has no session-end
          // hook lane, and without a trimmer the child-appended relay file
          // grows forever behind the bounded tail read. Concurrent trims from
          // both lanes converge (newest-keeping, tmp+rename); the residual
          // loss window stays the single in-flight append.
        }, { skipReceiptsCompaction: true, trimRelayFile: true }); // hook lane stays the ONE receipts compactor
      }
    } catch { /* receipt is additive — never fails the checkpoint */ }

    // Segment is spooled (durable); a deadline from here on degrades to
    // 'banked' — the sweep backstop extracts it later.
    if (deadlineHit()) return { status: 'banked', reason: 'deadline' };

    // Rung 2 — PGLite: serve owns the lock; one bankOnly+flush round trip.
    if (cfg?.engine === 'pglite' && cfg.database_path) {
      const ipc = await import('./context/resolve-ipc.ts');
      const secret = ipc.readIpcSecret(cfg.database_path);
      if (!secret) return { status: 'banked', reason: 'no_serve' };
      const res = await ipc.requestContextPack(ipc.resolveSocketPath(cfg.database_path), {
        secret,
        sessionId,
        window: windowTurns.slice(-COMPACT_BANK_WINDOW_TURNS),
        bankOnly: true,
        trigger: 'compact-bank',
        flushCorpusFile: segName(w.hash),
        ...(source ? { sourceId: source } : {}),
      });
      if (res === ipc.IPC_UNAVAILABLE) return { status: 'banked', reason: 'ipc_unavailable' };
      return { status: 'banked' };
    }

    // Rung 3 — Postgres: inline harvest over the ladder's cached connection,
    // under the SAME claim fencing + gates as the serve FIFO/sweep.
    const { getDirectPostgresEngine } = await import('./context/reflex.ts');
    const pg = await getDirectPostgresEngine(cfg);
    if (!pg) return { status: 'banked', reason: 'no_engine' };
    const sweep = await import('./sweep.ts');
    const fullPath = `${dir}/${segName(w.hash)}`;
    const claimPath = fullPath + sweep.CORPUS_CLAIM_SUFFIX;
    if (!(await sweep.acquireCorpusClaim(claimPath))) return { status: 'banked', reason: 'claimed_elsewhere' };
    try {
      // Re-check under the claim (adversarial review): a retried compact with
      // identical content maps to the same filename — if a prior run (or the
      // sweep) already ingested it, re-running the pipeline is pure duplicate
      // LLM spend absorbed only by fact-level dedup.
      const held = await rung3SegmentHold(fullPath, segName(w.hash));
      if (held) return { status: 'banked', reason: held };
      const gate = await (await import('./context/capture-consent.ts')).gateCorpusFile(pg, fullPath, 'compact');
      if (gate.action !== 'extract') return { status: 'banked', reason: gate.reason };
      const { extractionAvailableForEngine } = await import('./facts/extraction-availability.ts');
      if (!(await extractionAvailableForEngine(pg))) return { status: 'banked', reason: 'keyless' };
      const { isFactsExtractionEnabled } = await import('./facts/extract.ts');
      if (!(await isFactsExtractionEnabled(pg))) return { status: 'banked', reason: 'extraction_disabled' };
      // #6268: the segment's stamp, or (unresolved) the brain's chain for this workspace, frozen into the session record.
      const fileSource = await (await import('./context/corpus-source.ts')).resolveCorpusFileSource(pg, root, segName(w.hash), 'spool');
      if (!fileSource.ok) return { status: 'banked', reason: fileSource.reason };
      const sourceId = fileSource.sourceId;
      if (await rung3WriterHeld(pg, sourceId)) return { status: 'banked', reason: 'writer_coordinator_required' };
      if (deadlineHit()) return { status: 'banked', reason: 'deadline' };
      const { runFactsPipeline } = await import('./facts/backstop.ts');
      const speaker = (await import('./context/session-speaker.ts')).speakerOf(fullPath); // #8080: the session's agent speaker, as the sweep and harvest pass it
      const abort = new AbortController();
      // Inner backstop timer PLUS a poll of the outer compact() deadline —
      // the outer budget started before this rung, so when it wins the race
      // the in-flight extraction must stop too, not run on abandoned.
      const timer = setTimeout(() => abort.abort(), CHECKPOINT_COMPACT_BUDGET_MS);
      const deadlinePoll = setInterval(() => { if (deadlineHit()) abort.abort(); }, 250);
      let r: Awaited<ReturnType<typeof runFactsPipeline>>;
      try {
        r = await rung3Counted(pg, fullPath, segName(w.hash), fileSource.incarnation, abort.signal, () => runFactsPipeline(rendered.text, {
          engine: pg,
          sourceId,
          sessionId,
          source: 'hook:compact',
          ...speaker,
          mode: 'inline',
          remote: false,
          abortSignal: abort.signal,
        }));
      } finally {
        clearTimeout(timer);
        clearInterval(deadlinePoll);
      }
      // Post-check: the pipeline returns normally with PARTIALS on abort — an
      // aborted run writes no sidecar and stays sweep-retryable.
      if (abort.signal.aborted) return { status: 'banked', reason: 'aborted' };
      // #6786: no servable model is not an outcome; the segment stays pending for the sweep.
      if (r.skipped_reason === 'chat_unavailable') return { status: 'banked', reason: 'extract_skipped_chat_unavailable' };
      const verified: Array<{ slug: string; title: string }> = [];
      for (const slug of r.entity_slugs) {
        try {
          const page = await pg.getPage(slug, { sourceId });
          if (page) verified.push({ slug, title: page.title || slug });
        } catch { /* a non-resolvable link is never banked */ }
      }
      let published = true;
      if (verified.length) {
        const ss = await import('./context/session-state.ts');
        published = await ss.appendCheckpointManifest(pg, sourceId, null, sessionId, verified, {
          seg: w.hash, n: ordinal,
        });
      }
      // `.ingested` is written even when the manifest publish failed: the
      // facts ARE inserted, and leaving the segment sweep-retryable would
      // re-run the whole extraction just to retry a link append. Rung-3
      // links are best-effort (documented); the harvest FIFO lane is the
      // one with the receipt-retry guarantee.
      const { writeFileSync: wfs } = await import('node:fs');
      wfs(fullPath + sweep.CORPUS_INGESTED_SUFFIX, JSON.stringify({
        ingested_at: new Date().toISOString(),
        facts_inserted: r.inserted,
        facts_duplicate: r.duplicate,
        ...(r.skipped_reason ? { skipped: r.skipped_reason } : {}),
        links_banked: published ? verified.length : 0,
      }) + '\n');
      if (!published) return { status: 'harvested', links: verified, reason: 'manifest_failed' };
      return { status: 'harvested', links: verified };
    } finally {
      const { rmSync: rms } = await import('node:fs');
      try { rms(claimPath, { force: true }); } catch { /* best effort */ }
    }
  }


  /** Corpus dir from FILE config (hook.ts parity — no engine required). */

  const engine: ContextEngine = {
    info: {
      id: ENGINE_ID,
      name: ENGINE_NAME,
      version: ENGINE_API_VERSION,
      ownsCompaction: false,  // delegate to legacy runtime
    } satisfies ContextEngineInfo,

    async ingest({ message }) {
      // No-op — we don't index messages. The legacy engine handles persistence.
      return { ingested: true };
    },

    async assemble({ sessionId, sessionKey, messages, tokenBudget, availableTools, citationsMode, prompt, runtimeContext }) {
      // Lazy SDK load on first method call (was top-level await pre-L0-B).
      await ensureSdkLoaded();

      // #2880: fail-open on malformed host payloads. assemble() runs on EVERY
      // turn; a host that sends messages:undefined (or a non-array) must not
      // take down the whole context pipeline.
      const msgs = Array.isArray(messages) ? messages : [];

      const hasCurrentPrompt = typeof prompt === 'string' && prompt.trim().length > 0;
      const lastMessage = msgs.at(-1);
      const includesCurrentPrompt = runtimeContext?.transcriptStorage?.kind !== 'sqlite'
        && lastMessage?.role === 'user'
        && messageText(lastMessage.content) === prompt;
      const effectiveMessages = hasCurrentPrompt && !includesCurrentPrompt
        ? [...msgs, { role: 'user', content: prompt }]
        : msgs;

      // 1. Generate deterministic context (<5ms, zero LLM calls)
      const liveCtx = generateLiveContext(workspaceDir);
      const contextBlock = formatContextBlock(liveCtx);

      // 1b. Cathedral 5 — checkpoint block. The sessionId↔sessionKey identity
      // across compact()→assemble() is an UNVERIFIABLE SDK contract (mocked
      // in tests): absent id ⇒ no block, fail-open always.
      // SAME normalizer as compact() (adversarial review) — the memo and the
      // banked manifest live under the sanitized id.
      const checkpointSid = sanitizeEngineSessionId(sessionId ?? sessionKey ?? null);
      let checkpointBlock: string | null = null;
      if (checkpointSid) {
        try {
          checkpointBlock = await getCheckpointBlock(checkpointSid);
        } catch {
          checkpointBlock = null;
        }
      }

      // 2. Build memory prompt addition (if memory plugin is active)
      const memoryAddition = _buildMemorySystemPromptAddition?.({
        availableTools: availableTools ?? new Set(),
        citationsMode,
      });

      // 2b. Retrieval Reflex (#1981): detect salient entities in THIS turn that
      // resolve to existing brain pages and inject compact pointers. Zero-LLM,
      // fail-open, time-bounded — returns null (no addition) on any error or when
      // nothing salient resolves. Detect + point, never auto-dump bodies.
      const reflexAddition = await buildReflexAddition({
        workspaceDir,
        currentUserText: getLastUserText(effectiveMessages),
        priorContextText: getPriorContextText(effectiveMessages),
        // v0.43 (#2095): rolling window — assistant-introduced entities and
        // named-antecedent follow-ups from recent turns now resolve too.
        windowTurns: getWindowTurns(effectiveMessages),
        resolveEntities: ctx.resolveEntities,
      });

      // 3. Combine: live context + checkpoint block (parts index 1 — adjacent
      // to the Live Context block it augments, position independent of
      // whether memory/reflex fire) + memory prompt + reflex pointers. No
      // manifest ⇒ parts untouched ⇒ byte-identical to the pre-cathedral-5
      // output (pinned).
      // Always-loaded core + the context-pressure notice right after the live block (context/openclaw-core.ts).
      const parts = [contextBlock, ...await openClawCoreLane(workspaceDir, CHECKPOINT_POLL_TIMEOUT_MS).additions({
        sessionId: sanitizeEngineSessionId(sessionId ?? sessionKey ?? null), messages: msgs, tokenBudget, availableTools })];
      if (checkpointBlock) parts.push(checkpointBlock);
      if (memoryAddition) parts.push(memoryAddition);
      if (reflexAddition) parts.push(reflexAddition);

      // Monthly backup-coverage warning (⚠ idiom, model-visible). Bounded by
      // the recording channels' budget without ever spending it; fail-open.
      try {
        const now = Date.now();
        if (now - _backupCheckedAt > 24 * 60 * 60 * 1000) {
          _backupCheckedAt = now;
          const backupStatus = loadBackupStatus();
          if (backupStatus && backupNagReadOnlyConsult(backupStatus, now)) {
            const note = backupNoticeText(backupStatus, 'human');
            if (note) parts.push(`- ⚠️ ${note}`);
          }
        }
      } catch {
        /* a notice must never break context assembly */
      }

      // 4. Pass through messages unchanged (legacy assembly)
      return {
        messages: msgs,
        estimatedTokens: estimateMessageTokens(msgs),
        systemPromptAddition: parts.join('\n\n'),
      };
    },

    async compact(params) {
      // Lazy SDK load on first method call (was top-level await pre-L0-B).
      await ensureSdkLoaded();
      openClawCoreLane(workspaceDir, CHECKPOINT_POLL_TIMEOUT_MS).compacted(sanitizeEngineSessionId(params?.sessionId ?? params?.sessionKey ?? null));
      // Cathedral 5 — time-bounded, FAIL-OPEN checkpoint step BEFORE the
      // delegate. A checkpoint failure/timeout must never break compaction.
      // The deadline CANCELS the work (adversarial review): the race alone
      // would let an abandoned checkpoint keep extracting/writing behind the
      // delegate; the abort closure stops it at the next step boundary, and
      // the timer is cleared when the work wins.
      let gbrainCheckpoint: Record<string, unknown>;
      const checkpointStart = Date.now();
      try {
        const deadline = new AbortController();
        let timer: ReturnType<typeof setTimeout> | undefined;
        const budget = new Promise<Record<string, unknown>>((resolve) => {
          timer = setTimeout(() => {
            deadline.abort();
            resolve({ status: 'skipped', reason: 'deadline' });
          }, CHECKPOINT_COMPACT_BUDGET_MS);
          if (typeof (timer as { unref?: () => void }).unref === 'function') {
            (timer as unknown as { unref: () => void }).unref();
          }
        });
        try {
          gbrainCheckpoint = await Promise.race([
            runCompactCheckpoint(params, () => deadline.signal.aborted),
            budget,
          ]);
        } finally {
          if (timer) clearTimeout(timer);
        }
      } catch {
        gbrainCheckpoint = { status: 'skipped', reason: 'error' };
      }
      await recordOpenclawCompact(gbrainCheckpoint, Date.now() - checkpointStart);
      // Delegate to legacy runtime compaction UNCHANGED (ownsCompaction stays
      // false), then ride the additive bag on the existing untyped `result`.
      const delegated =
        (await _delegateCompactionToRuntime?.(params)) ?? { ok: true, compacted: false, reason: 'no-runtime' };
      return {
        ...delegated,
        result: { ...(delegated.result ?? {}), gbrain_checkpoint: gbrainCheckpoint },
      };
    },
  };

  return engine;
}