Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
95.5 KB
Raw Blame
/**
 * hook.ts — `gbrain hook <event>`: the harness-side hook command
 * (agent-bootstrap plan: D5, A3, A9, G3, G4, G15, B3, B4, ENG-1, S3#2,
 * S3#7, S3#8).
 *
 * ENGINE-FREE BY CONSTRUCTION (plan D5): `gbrain serve` holds the PGLite
 * single-writer lock for its lifetime, so this command NEVER imports an
 * engine or connectEngine — config comes from `loadConfig()` only, per-turn
 * context comes from serve's resolve-IPC unix socket (requestTurnContext),
 * and everything else is plain file reads/writes. Registered in cli.ts's
 * no-engine dispatch branch (CLI_ONLY + handleCliOnly, before the
 * connectEngine terminator) and must never enter THIN_CLIENT_REFUSED
 * [ENG-2].
 *
 * FAIL-OPEN CONTRACT: a hook failure must never break the user's session.
 * Every event exits 0 (empty stdout on failure) and records a heartbeat
 * line; only a CLI usage error (unknown event) exits non-zero. The
 * `GBRAIN_HOOKS=0` env kill switch short-circuits every event.
 *
 * HEARTBEAT [S3#7, B3]: append-JSONL at
 * `<gbrain home>/integrations/hooks/heartbeat.jsonl` — counters, durations,
 * and error CODES only, never prompt/fact/slug text. Dir 0700, file capped
 * at HEARTBEAT_MAX_LINES (tail-rewrite). `readHeartbeatTail` is the
 * doctor/status read surface.
 *
 * Events:
 *   session-start  digest to stdout from FILE reads only (≤1.5s; ≤4s while a
 *                  setup-wired harness's serve starts) [A3,G4,B3,B4]
 *   user-prompt    stdin hook JSON → IPC turn_context → additionalContext
 *                  JSON on stdout (≤800ms, ≤10000 chars) [ENG-1,S3#8,A9]
 *   stop           append to the per-session live buffer + 7-day GC [G15]
 *   session-end    transcript → secret-scanned corpus file, retention prune,
 *                  parser-drift detection, detached background workspace push
 *                  [S3#2,G3,G15]
 */

import {
  chmodSync,
  existsSync,
  mkdirSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  statSync,
  writeFileSync,
} from 'node:fs';
import { isAbsolute, join } from 'node:path';
import { execFile, spawn } from '../core/spawn.ts';
import { gitChildEnv } from '../core/git-env.ts';
import { ensureGbrainHome, resolveGbrainHome } from '../core/gbrain-home.ts';
import { loadConfig, type GBrainConfig } from '../core/config.ts';
import {
  IPC_UNAVAILABLE,
  readIpcSecretForConfig,
  requestTurnContext,
  requestContextPack,
  hookResolveSocketForConfig,
  type TurnContextResponse,
  type ContextPackResponse,
} from '../core/context/resolve-ipc.ts';
import { contextSourceId, requestSessionStartPack, sessionStartAwaitsServe } from '../core/context/session-start-pack.ts';
import type { WindowTurn } from '../core/context/entity-salience.ts';
import {
  confineTranscriptPath,
  parseTranscript,
  toCorpusText,
} from '../core/transcripts/claude-code-jsonl.ts';
import {
  bankCompactSegment,
  bankWritebackTurn,
  decideCorpusMode,
  gcCorpusArtifacts,
  gcCorpusTurnFiles,
  CORPUS_FAILURE_SUFFIX, CORPUS_PROGRESS_SUFFIX,
  CORPUS_PROGRESS_LOCK_SUFFIX,
  HARVEST_RECEIPT_SUFFIX,
  segmentHash,
  sessionCorpusFileName,
} from '../core/context/corpus-segments.ts';
import { openSessionCorpus } from '../core/context/corpus-source.ts';
import { hookLaneLabel, resolveSeat, seatReasonHint, writeSeatSidecar } from '../core/context/seat.ts';
import { hookSpeakerDecision, type AncestorProcess } from '../core/context/session-speaker.ts';
import { gateWritebackTurn, WRITEBACK_SKIP_REASONS } from '../core/facts/writeback-gate.ts';
import { resolveWritebackConfigFromFile } from '../core/facts/writeback-config.ts';
import { recordCaptureIfOff } from '../core/context/capture-consent.ts';
import { memorableGateAllowed, recordAndRelayReceipt, redactedToolCallsJson } from '../core/context/hook-heartbeat.ts';
import { captureSpecFor } from '../core/transcripts/capture-spec.ts';
import {
  heartbeatPath,
  hookStatusPath,
  readHeartbeatTail,
  writeHeartbeat as writeHeartbeatShared,
  type HookHeartbeatEntry,
} from '../core/context/hook-heartbeat.ts';
import { CLAUDE_HOOK_OUTPUT_CAP_CHARS } from '../core/bootstrap/host-specs.ts';
import { pluginHookYields } from '../core/bootstrap/plugin-lanes.ts';
import { composeSessionStartOutput } from '../core/context/session-start-output.ts';
import { claudeCodePressure } from '../core/context/pressure.ts';
import { readManifest, readReceipt, type InstallReceipt } from '../core/bootstrap/format.ts';
import { githubOwnerRepoString } from '../core/repo-visibility.ts';
import { detectExecutionEnvironment } from '../core/execution-env.ts';
import {
  livePushStatuses,
  readPushStatuses,
  readPushStatusForRoot,
  sanitizePushReason,
  summarizePushStatuses,
  workspaceRootHash,
} from '../core/workspace-push.ts';
import {
  backupCheckDisabled,
  backupNagGate,
  backupNoticeText,
  backupSpawnDue,
  isBackupStatusStale,
  loadBackupStatus,
  recordBackupSpawn,
} from '../core/backup/status-file.ts';
import { realpathOrResolve } from '../core/path-confine.ts';
import { isClaudeCliSelfTranscriptPath } from '../core/ai/providers/claude-cli-scratch.ts';
import { withoutPhysicalRootMetadata } from '../core/persistence/root-metadata.ts';
import { HOOK_SUBCOMMANDS as HOOK_EVENTS, ROUTERS, subcommandHelpRequested } from '../cli/subcommands.ts';
import { isManagedFilesystemPath } from '../core/persistence/filesystem-guard.ts';
import { brainFirstTurnRule } from '../core/setup/brain-first.ts';
import { TURN_RULE_LANE, turnRuleHookYields } from '../core/setup/turn-hook.ts';
import { captureHookSessionCwd, hookSessionCwd } from '../core/setup/hook-launcher.ts';

// ── Tunables ────────────────────────────────────────────────────────────────

/** session-start self-deadline (plan D5). */
export const SESSION_START_DEADLINE_MS = 1500;
/** session-start self-deadline while the harness's serve starts (session-start-pack.ts); under the 5s harness timeout. */
export const SESSION_START_SERVE_WAIT_DEADLINE_MS = 4000;
/** user-prompt hard self-deadline (plan D5/ENG-1). */
export const USER_PROMPT_DEADLINE_MS = 800;
/** MEMORY.md digest budget [A3]. */
export const DIGEST_MEMORY_CAP_BYTES = 3072;
/** Digest-eligible MEMORY.md sections [A3] — matched case-insensitively. */
export const DIGEST_SECTIONS = ['standing rules', 'open commitments', 'active context'];
/** Stop-buffer retention [G15]. */
export const STOP_BUFFER_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
/** Ambient-writeback Stop step's own deadline (WP4): well inside Stop's 10s
 * harness cap, alongside (not inside) the push step's 3s. Fail-open always. */
export const WRITEBACK_STOP_DEADLINE_MS = 2000;
/** Newest-tail read for locating the last user turn — one turn never needs
 * the 2MB user-prompt window, and this lane pays the parse EVERY Stop. */
export const WRITEBACK_TRANSCRIPT_TAIL_BYTES = 128 * 1024;
/** Default corpus retention when `dream.synthesize.corpus_retention_days` is unset [G15]. */
export const CORPUS_RETENTION_DAYS_DEFAULT = 30;
/**
 * Sweep sidecar suffixes — DUPLICATED from sweep.ts on purpose: hook.ts is
 * engine-free by construction (module header D5), and sweep.ts eagerly imports
 * capability.ts, so a value-import here would drag that in. A corpus (re)write
 * MUST invalidate any prior completion/claim marker so the serve sweep
 * re-ingests the appended transcript of a resumed session (otherwise the new
 * turns are skipped forever). Keep these in sync with sweep.ts's
 * CORPUS_INGESTED_SUFFIX / CORPUS_CLAIM_SUFFIX.
 */
export const CORPUS_INGESTED_SUFFIX = '.ingested';
export const CORPUS_CLAIM_SUFFIX = '.in-progress';
/** Trailing-window size for the B3 failure-rate notice. */
export const HEARTBEAT_FAILURE_WINDOW = 20;
/**
 * Trailing-window hard-error rate that trips the B3 digest notice AND the
 * doctor `bootstrap_hooks_heartbeat` fail (doctor imports this — one source).
 */
export const HEARTBEAT_FAILURE_RATE_THRESHOLD = 0.5;
/** Push-staleness threshold [B4] — shared with doctor's bootstrap_push_health. */
export const PUSH_STALE_MS = 48 * 60 * 60 * 1000;
/** user-prompt window: transcript turns fed to turn_context (plan D5: last 4). */
const USER_PROMPT_WINDOW_TURNS = 4;
/** Dedupe-input budget: newest injected blocks kept under this cap so the
 * IPC request can never blow the 256KB message cap on priorContextText. */
export const PRIOR_CONTEXT_MAX_BYTES = 32 * 1024;
/** user-prompt transcript parse budget (tail bytes — the window only needs the newest turns). */
const USER_PROMPT_TRANSCRIPT_MAX_BYTES = 2 * 1024 * 1024;
/** stop-hook push [D3]: hard budget for the debounce decision + detached spawn
 * (the spawn itself is instant; the budget bounds the two 1s git probes). */
const STOP_PUSH_DEADLINE_MS = 3000;
/** stop-hook push debounce default (minutes) for local + ephemeral-container
 * environments; cloud-sandbox defaults to 0 (every turn) — a reclaimed VM's
 * tail loss is permanent, everywhere else SessionStart recovery covers it [D17]. */
export const STOP_PUSH_DEBOUNCE_MIN_DEFAULT = 5;
/** failure banner [D19]: re-announce floor while the same failure persists. */
export const PUSH_ANNOUNCE_REFIRE_MS = 30 * 60 * 1000;
/** failure banner budget (well under ENG-1's whole-payload cap). */
const PUSH_BANNER_MAX_CHARS = 300;

// ── Test seam ───────────────────────────────────────────────────────────────

/**
 * In-process I/O seam. The CLI wiring calls `runHook(args)` with none of
 * these set; tests inject stdin/stdout/cwd (and a transcript confinement
 * root) so the full stdin→stdout contract runs without subprocesses.
 * `transcriptRoot` is intentionally NOT env-configurable — the S3#8
 * confinement root must not be widenable by whatever spawned the hook.
 */
export interface HookIo {
  /** Injected stdin body; undefined → read process.stdin (non-TTY only). */
  stdin?: string;
  /** Injected stdout sink; default process.stdout.write. */
  write?: (s: string) => void;
  /** Workspace dir override; default stdin JSON `cwd` → the session directory (GBRAIN_HOOK_CWD from the hook launcher, else process.cwd()). */
  cwd?: string;
  /** TEST SEAM: transcript confinement root (default ~/.claude/projects). */
  transcriptRoot?: string;
  /**
   * TEST SEAM: detached-push spawner (default spawnDetachedPush). Receives the
   * gated bootstrap workspace root; throwing marks the push unavailable.
   */
  spawnPush?: (root: string) => void;
  /** TEST SEAM: detached backup-check spawner (default spawnDetachedBackupCheck). */
  spawnBackupCheck?: () => void;
  /** TEST SEAM: user-prompt deadline override (wall-clock flake control). */
  userPromptDeadlineMs?: number;
  /** TEST SEAM: compact deadline override (drives the per-step degrade paths). */
  compactDeadlineMs?: number;
  /**
   * TEST SEAM (v0.46.15, BrainBench production seam): config override for
   * hookUserPrompt — `undefined` = load the real file-plane config;
   * `null`/object = use as-is. Lets the bench point the hook at a throwaway
   * brain WITHOUT mutating process-global GBRAIN_HOME (parallel-test safe).
   */
  configOverride?: GBrainConfig | null;
  /**
   * TEST SEAM (v0.46.15): suppress the pending-push failure banner. The
   * banner reads the OPERATOR's real push-status files — on a bench run
   * that's environmental contamination (a locally-failing push would inject
   * a banner on stay-silent turns and read as a false fire).
   */
  disablePushBanner?: boolean;
  /**
   * TEST SEAM: the per-turn brain-first rule user-prompt leads every turn
   * with. `undefined` = read it from the brain-first ledger; `null` = none
   * (BrainBench and bootstrap verify measure the context block alone).
   */
  turnRule?: string | null;
  /**
   * TEST SEAM (v0.46.15, codex ship-review): suppress hook telemetry WRITES
   * (heartbeat JSONL). Telemetry paths resolve from GBRAIN_HOME/homedir —
   * NOT from configOverride — so a hermetic bench replay would otherwise
   * append every fixture turn to the operator's real hook-health history.
   */
  disableTelemetry?: boolean;
  /**
   * Feedback-loop attribution channel (`--harness <claude-code|codex|opencode>`).
   * Default 'claude-code' — the only harness bootstrap registers hooks for
   * today; a codex/opencode hook registration passes the flag explicitly.
   */
  harness?: 'claude-code' | 'codex' | 'opencode';
  /** TEST SEAMS (#8064): the launcher env and process ancestry the session speaker is resolved from. */
  env?: Record<string, string | undefined>;
  processAncestry?: () => readonly AncestorProcess[];
}

// ── Entry point ─────────────────────────────────────────────────────────────

export { HOOK_EVENTS, HOOK_EVENTS as SUBCOMMANDS };
export const printUsage = (): void => { process.stdout.write(`${USAGE}\n`); };

const USAGE = `Usage: gbrain hook <event>

Events (wired into .claude/settings.local.json by gbrain bootstrap):
  session-start   print the greeting digest (MEMORY.md sections, push status,
                  hook health) to stdout
  user-prompt     read hook JSON on stdin, request per-turn context from a
                  running 'gbrain serve' over IPC, print additionalContext JSON
                  (--harness <claude-code|codex|opencode> sets the feedback-loop
                  channel; default claude-code, unknown values fall back to the default)
  stop            bank the writeback backstop and spawn the workspace push
  session-end     ingest the session transcript into the dream corpus
                  (secret-scanned), prune old corpus files, push the workspace
  compact         (PreCompact) bank the window's standing entities into the
                  session cursor so the post-compaction session-start serves
                  a warm context pack; emits nothing

Env: GBRAIN_HOOKS=0 disables all events (immediate exit 0).
     GBRAIN_SESSION_AGENT=<label>|off|owner names who wrote the session's user
     turns (an agent's are never saved as yours; off saves nothing).
All events fail open: errors exit 0 with empty stdout and a heartbeat entry at
<gbrain home>/integrations/hooks/heartbeat.jsonl.`;

/** Dispatch a hook event. Returns the process exit code (0 for every runtime path). */
export async function runHook(args: string[], io: HookIo = {}): Promise<number> {
  captureHookSessionCwd();
  const event = args[0];
  if (subcommandHelpRequested(args, ROUTERS.hook)) {
    write(io, USAGE + '\n');
    return 0;
  }
  // `--harness <claude-code|codex|opencode>` — feedback-loop channel
  // attribution for user-prompt. Unknown values fall back to the default
  // (fail-open: a bad registration must never break the hook contract).
  const harnessIdx = args.indexOf('--harness');
  if (harnessIdx >= 0 && !io.harness) {
    const v = args[harnessIdx + 1];
    if (v === 'claude-code' || v === 'codex' || v === 'opencode') io = { ...io, harness: v };
  }
  if (!event || !(HOOK_EVENTS as readonly string[]).includes(event)) {
    process.stderr.write(USAGE + '\n');
    return 1;
  }
  // Kill switch — before any file/socket touch, no heartbeat (the user asked
  // for silence, and a disabled hook writing telemetry would be a lie).
  if (process.env.GBRAIN_HOOKS === '0') return 0;

  if (process.env.GBRAIN_HOOK_LANE === 'skill-resolver') return (await import('../core/skills/resolver/hook-lane.ts')).runSkillResolverLane(event, harnessIdx >= 0 && args[harnessIdx + 1] === 'hermes' ? 'hermes' : io.harness === 'codex' ? 'codex' : 'claude-code', io.cwd ? { cwd: io.cwd } : {});
  // #4043 harness-lane defer guard: Claude Code MERGES user- and
  // project-scope hook settings, so a machine wired by `bootstrap harness`
  // (user scope) plus a real workspace bootstrap install (settings.local.json,
  // bootstrap-v1 marker) would fire the same event twice. The workspace
  // install wins; the harness lane yields silently (exit 0, no output, no
  // heartbeat). Same cwd resolution as the handlers (io.cwd is the test
  // seam; the harness runs hooks in the session's working dir). Fail-open:
  // any read hiccup means run normally.
  if (process.env.GBRAIN_HOOK_LANE === 'harness') {
    try {
      // BOTH workspace carriers count: settings.local.json (local installs)
      // and the committed .claude/settings.json ([D12] — an event owned by
      // the committed carrier is stripped from local, so checking only local
      // would double-fire it against the user-scope harness wiring). The
      // check PARSES the settings and requires a live bootstrap-v1 hook entry
      // wiring THIS event — a raw substring match would let any repo disable
      // the machine-wide capture lane by committing the two marker strings in
      // an unrelated field (ship-review P1), and would over-yield events the
      // workspace does not actually wire.
      const eventKey = {
        'session-start': 'SessionStart',
        'user-prompt': 'UserPromptSubmit',
        stop: 'Stop',
        'session-end': 'SessionEnd',
        compact: 'PreCompact',
      }[event];
      const dotClaude = join(io.cwd ?? hookSessionCwd(), '.claude');
      for (const file of ['settings.local.json', 'settings.json']) {
        const p = join(dotClaude, file);
        if (!existsSync(p)) continue;
        const settings = JSON.parse(readFileSync(p, 'utf8')) as {
          hooks?: Record<string, Array<{ hooks?: Array<Record<string, unknown>> }>>;
        };
        const groups = settings.hooks?.[eventKey ?? ''];
        if (!Array.isArray(groups)) continue;
        for (const g of groups) {
          if (!Array.isArray(g?.hooks)) continue;
          if (g.hooks.some((e) => e?._gbrain === 'bootstrap-v1')) return 0;
        }
      }
    } catch {
      /* fail-open */
    }
  }
  // Plugin lane (the Claude Code and Codex plugin manifests): yields to any other gbrain lane wiring this event.
  if (process.env.GBRAIN_HOOK_LANE === 'plugin' && pluginHookYields(io.harness ?? 'claude-code', event, io.cwd ?? hookSessionCwd())) return 0;
  // Turn-rule lane (src/core/setup/turn-hook.ts): rule only, and only when no other gbrain lane wires this event.
  if (process.env.GBRAIN_HOOK_LANE === TURN_RULE_LANE && event === 'user-prompt' && turnRuleHookYields(io.harness ?? 'claude-code', io.cwd ?? hookSessionCwd())) return 0;

  switch (event) {
    case 'session-start':
      return hookSessionStart(io);
    case 'user-prompt':
      return hookUserPrompt(io);
    case 'stop':
      return hookStop(io);
    case 'session-end':
      return hookSessionEnd(io);
    case 'compact':
      return hookCompact(io);
    default:
      return 1; // unreachable
  }
}

// ── Shared plumbing ─────────────────────────────────────────────────────────

function write(io: HookIo, s: string): void {
  if (io.write) io.write(s);
  else process.stdout.write(s);
}

const DEADLINE: unique symbol = Symbol('deadline');

function withDeadline<T>(ms: number, work: Promise<T>): Promise<T | typeof DEADLINE> {
  return new Promise((resolve) => {
    const t = setTimeout(() => resolve(DEADLINE), ms);
    (t as { unref?: () => void }).unref?.();
    work.then(
      (v) => {
        clearTimeout(t);
        resolve(v);
      },
      () => {
        clearTimeout(t);
        resolve(DEADLINE); // caller treats a rejection like a timeout: fail-open
      },
    );
  });
}

/** Read stdin (or the injected seam) and JSON-parse; null on anything else. */
async function readStdinJson(io: HookIo, timeoutMs: number): Promise<Record<string, unknown> | null> {
  let raw: string;
  if (io.stdin !== undefined) {
    raw = io.stdin;
  } else {
    raw = await readProcessStdin(timeoutMs);
  }
  if (!raw.trim()) return null;
  try {
    const parsed = JSON.parse(raw) as unknown;
    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
      ? (parsed as Record<string, unknown>)
      : null;
  } catch {
    return null;
  }
}

function readProcessStdin(timeoutMs: number): Promise<string> {
  return new Promise((resolve) => {
    if (process.stdin.isTTY) return resolve('');
    let buf = '';
    let done = false;
    const finish = () => {
      if (done) return;
      done = true;
      clearTimeout(t);
      resolve(buf);
    };
    const t = setTimeout(finish, timeoutMs);
    (t as { unref?: () => void }).unref?.();
    process.stdin.setEncoding('utf8');
    process.stdin.on('data', (c: string) => {
      buf += c;
      if (buf.length > 4 * 1024 * 1024) finish(); // hook payloads are small — cap defensively
    });
    process.stdin.on('end', finish);
    process.stdin.on('error', finish);
  });
}

/**
 * Gbrain home resolver: the S3#10 choke point, statically imported [CX2-8].
 * Only the CALL is guarded — ensureGbrainHome throws solely when the create
 * fails, and resolveGbrainHome (pure path resolution, same semantics) is the
 * fail-open fallback; downstream writers under an uncreatable home fail into
 * their own swallow-and-heartbeat paths.
 */
async function resolveHome(): Promise<string> {
  try {
    return ensureGbrainHome();
  } catch {
    return resolveGbrainHome();
  }
}

function ensureDir0700(dir: string): string {
  mkdirSync(dir, { recursive: true, mode: 0o700 });
  try {
    chmodSync(dir, 0o700);
  } catch {
    /* best effort */
  }
  return dir;
}

export function sanitizeSessionId(id: unknown): string {
  // Leading dashes are stripped so the id can never be parsed as a FLAG by a
  // downstream argv consumer (the detached memorable spawn passes it as a
  // positional value) — hook stdin is untrusted input.
  const s =
    typeof id === 'string' ? id.replace(/[^A-Za-z0-9._-]/g, '-').replace(/^-+/, '').slice(0, 120) : '';
  return s && !/^\.+$/.test(s) ? s : 'unknown';
}

/** Reason strings must be CODES [S3#7] — clamp anything message-shaped. */
function reasonCode(reason: string): string {
  return /^[A-Za-z0-9_.:-]{1,48}$/.test(reason) ? reason : 'server_error';
}

function errorCode(e: unknown): string {
  const name = e instanceof Error ? e.constructor.name : typeof e;
  return reasonCode(`exception:${name}`);
}

// ── Heartbeat [S3#7, B3] ────────────────────────────────────────────────────
// Extracted to src/core/context/hook-heartbeat.ts (cathedral 5) so the
// serve-side checkpoint harvest appends outcome events without importing this
// command module. Re-exported here so every existing import site
// (doctor/status/verify/tests) keeps working unchanged.

export {
  HEARTBEAT_ALLOWED_KEYS,
  HEARTBEAT_MAX_LINES,
} from '../core/context/hook-heartbeat.ts';
export { heartbeatPath, hookStatusPath, readHeartbeatTail };
export type { HookHeartbeatEntry };

/**
 * Hook-side heartbeat writer: delegates to the shared module (cathedral 5 —
 * the serve harvest appends its own events there), honoring the BrainBench
 * telemetry seam (v0.46.15): a hermetic bench replay drives the REAL hook
 * in-process, and without this gate every fixture turn would append to the
 * operator's real hook-health history and skew doctor/failure-notice reads.
 */
async function writeHeartbeat(io: HookIo, entry: HookHeartbeatEntry): Promise<void> {
  if (io.disableTelemetry) return;
  await writeHeartbeatShared(entry);
}

// ── session-start [A3, G4, B3, B4] ──────────────────────────────────────────

async function hookSessionStart(io: HookIo): Promise<number> {
  const t0 = Date.now();
  let outcome: HookHeartbeatEntry['outcome'] = 'ok';
  let reason: string | undefined;
  const out: string[] = [];
  const coreBox: { core: { text: string; revision: string; chars_used: number } | null; reason?: string } = { core: null };
  // Deferred nag records: fire ONLY after the digest actually reached stdout
  // (record-after-write — a deadline-suppressed note must re-fire next time).
  const deferredRecords: Array<() => void> = [];

  try {
    const j = await readStdinJson(io, 250);
    const ws = io.cwd ?? (typeof j?.cwd === 'string' ? (j.cwd as string) : hookSessionCwd());
    const awaitServe = sessionStartAwaitsServe(j?.source, io.harness ?? 'claude-code', ws);
    const deadlineMs = awaitServe ? SESSION_START_SERVE_WAIT_DEADLINE_MS : SESSION_START_DEADLINE_MS;
    let serveNotReady = false;

    const work = (async () => {
      // 1. MEMORY.md digest — allowlisted sections only, ≤3KB [A3].
      const digest = memoryDigest(join(ws, 'MEMORY.md'));
      if (digest) out.push(digest);

      // 3. Push staleness [B4].
      const pushNote = await pushStatusNote();
      if (pushNote) out.push(pushNote);

      // 3b. Monthly backup-coverage note (cache read; bounded by the shared
      //     nag gate — dampener + per-channel ceiling + global monthly cap).
      const backupNote = backupSessionStartNote();
      if (backupNote) {
        out.push(backupNote.text);
        deferredRecords.push(backupNote.record);
      }

      // 4. Visible degradation [B3] + parser-drift status file [G3].
      const failNote = await hookFailureNotice();
      if (failNote) out.push(failNote);
      const statusNote = await statusFileNotice();
      if (statusNote) out.push(statusNote);

      // 5. Dirty-tree recovery push [G4] — bootstrap workspaces ONLY (the
      //    initialized agent.json manifest is the gate; `gbrain hook
      //    session-start` run in an arbitrary repo must never commit it).
      //    The push itself runs as a detached child; the hook only spawns.
      const dirty = await dirtyTreePush(ws, io);
      if (dirty) {
        if (dirty.note) out.push(dirty.note);
        if (dirty.reason && outcome === 'ok') {
          if (dirty.degraded) outcome = 'degraded';
          reason = reasonCode(dirty.reason);
        }
      }

      // 6. v0.45.7 ambient recall — boundary context pack over IPC. SessionStart
      //    is Claude Code's cold-start AND post-compaction re-entry point
      //    (source=compact/resume), so this one arm covers both. The server
      //    owns the intelligence (banked entities + since-cursor + advance);
      //    world-only always. Every failure is a silent skip — the file-only
      //    digest above must never be hostage to the brain being down.
      try {
        const cfg = loadConfig();
        if (sanitizeSessionId(j?.session_id) !== 'unknown') await sessionCorpus(io, cfg, sanitizeSessionId(j?.session_id), ws); // #6268: freeze at start
        // Engine-uniform (#4245): same config-keyed socket/secret resolution as the
        // user-prompt and compact arms; IPC timeout clamped to the remaining deadline.
        // Same session-id sanitizer as compact banking (a raw id splits the cursor key).
        serveNotReady = awaitServe; // still true if the deadline fires mid-wait
        const sourceId = await contextSource(io, cfg, j?.session_id, ws);
        const res = await requestSessionStartPack(cfg, {
          sourceId,
          sessionId: sanitizeSessionId(j?.session_id),
          trigger: typeof j?.source === 'string' ? `session-start:${j.source as string}` : 'session-start',
          deadlineAt: t0 + deadlineMs,
          awaitServe,
        });
        serveNotReady = res.serveNotReady;
        if (res.ipcUnavailable && outcome === 'ok') { outcome = 'degraded'; reason = 'ipc_unavailable'; }
        const pack = res.pack;
        if (pack && !pack.ok && pack.error === 'source_mismatch' && outcome === 'ok') { outcome = 'degraded'; reason = 'source_mismatch'; } // #5941
        if (pack?.ok && pack.degradedReason === 'server_budget' && outcome === 'ok') { outcome = 'degraded'; reason = 'server_budget'; }
        if (pack?.ok && pack.block?.text) out.push(pack.block.text);
        if (pack?.ok && pack.block?.core && process.env.GBRAIN_CORE !== '0') coreBox.core = pack.block.core;
        else if (pack?.ok && !pack.block?.core) coreBox.reason = 'stale_serve_no_core';
      } catch { /* fail-open: no pack, digest stands alone */ }
    })();

    const res = await withDeadline(deadlineMs, work);
    if ((res === DEADLINE || serveNotReady) && outcome === 'ok') {
      outcome = 'degraded';
      reason = serveNotReady ? 'serve_not_ready' : 'deadline';
    }
    // Print whatever accumulated before the deadline — a partial digest
    // beats an empty one (the deadline bounds latency, not usefulness).
    // Always-loaded core first; digest/pack trimmed to the cap (session-start-output.ts).
    const text = composeSessionStartOutput(coreBox.core?.text ?? '', out.filter(Boolean));
    if (text) {
      write(io, text + '\n');
      for (const record of deferredRecords) {
        try {
          record();
        } catch {
          /* fail-open — worst case the note re-fires */
        }
      }
    }
  } catch (e) {
    outcome = 'error';
    reason = errorCode(e); // fail-open: empty stdout, exit 0
  }
  await writeHeartbeat(io, {
    ts: new Date().toISOString(),
    event: 'session-start',
    outcome,
    ...(reason ? { reason } : coreBox.reason ? { reason: coreBox.reason } : {}),
    duration_ms: Date.now() - t0,
    ...(coreBox.core ? { core_chars: coreBox.core.chars_used, core_revision: coreBox.core.revision } : {}),
  });
  return 0;
}

/**
 * Extract the digest-eligible sections from MEMORY.md [A3]. Only headings in
 * DIGEST_SECTIONS qualify — the template's security-boundary note and every
 * other section stay out of injected context. Capped at
 * DIGEST_MEMORY_CAP_BYTES.
 */
export function memoryDigest(memoryPath: string): string | null {
  let raw: string;
  try {
    const st = statSync(memoryPath);
    if (!st.isFile() || st.size > 512 * 1024) return null; // malformed/huge — skip
    raw = readFileSync(memoryPath, 'utf8');
  } catch {
    return null;
  }
  const picked: string[] = [];
  let inSection = false;
  for (const line of raw.split('\n')) {
    const h = /^(#{1,3})\s+(.+?)\s*$/.exec(line);
    if (h) {
      inSection = DIGEST_SECTIONS.includes(h[2].trim().toLowerCase());
      if (inSection) picked.push(line);
      continue;
    }
    if (inSection) picked.push(line);
  }
  const body = picked.join('\n').trim();
  if (!body) return null;
  let text = `From MEMORY.md:\n${body}`;
  if (Buffer.byteLength(text, 'utf8') > DIGEST_MEMORY_CAP_BYTES) {
    const cut = Buffer.from(text, 'utf8').subarray(0, DIGEST_MEMORY_CAP_BYTES - 2).toString('utf8');
    text = cut.replace(/�+$/, '') + '…';
  }
  return text;
}

async function liveBufferDir(): Promise<string> {
  const home = await resolveHome();
  ensureDir0700(join(home, 'transcripts'));
  return ensureDir0700(join(home, 'transcripts', 'live'));
}

async function pushStatusNote(): Promise<string | null> {
  try {
    // One reader + one aggregation for every status surface [D8]; per-root
    // files [D13] so one workspace's success can't mask another's failure.
    // #5799: a managed root's records are the fenced legacy push, not this note's subject.
    const entries = livePushStatuses(readPushStatuses());
    if (entries.length === 0) return null;
    const { failing, stalestTs } = summarizePushStatuses(entries);
    if (failing.length > 0) {
      const e = failing[0]!;
      const which = e.repoRoot ? ` for ${e.repoRoot}` : '';
      const rest = failing.length > 1 ? ` [+${failing.length - 1} more workspace(s)]` : '';
      return `Workspace push${which} is FAILING (since ${e.ts ?? 'unknown'}): ${sanitizePushReason(e.reason)}${rest} — run gbrain doctor`;
    }
    if (stalestTs !== null && Date.now() - stalestTs > PUSH_STALE_MS) {
      return `Workspace push: last success ${new Date(stalestTs).toISOString()} (>48h ago) — recent work may be unpushed [B4]`;
    }
    return null;
  } catch {
    return null;
  }
}

/**
 * [B3] Visible degradation: when >50% of the trailing-20 heartbeat entries
 * are hard errors, say so in the digest. Degraded entries (pull-mode
 * no_serve, stale_serve, …) are DESIGNED fallbacks and don't count — the
 * notice is for broken, not for absent.
 */
async function hookFailureNotice(): Promise<string | null> {
  const tail = await readHeartbeatTail(HEARTBEAT_FAILURE_WINDOW);
  if (tail.length === 0) return null;
  const failures = tail.filter((e) => e.outcome === 'error').length;
  if (failures / tail.length > HEARTBEAT_FAILURE_RATE_THRESHOLD) {
    return 'brain context unavailable for recent turns — run gbrain doctor';
  }
  return null;
}

const STATUS_NOTICE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;

async function statusFileNotice(): Promise<string | null> {
  try {
    const p = await hookStatusPath();
    if (!existsSync(p)) return null;
    const s = JSON.parse(readFileSync(p, 'utf8')) as { ts?: string; error?: string };
    const t = s.ts ? Date.parse(s.ts) : NaN;
    if (!Number.isFinite(t) || Date.now() - t > STATUS_NOTICE_MAX_AGE_MS) return null;
    return `Hook alert: ${s.error ?? 'unknown'} (${s.ts}) — transcript ingestion may be broken; run gbrain doctor`;
  } catch {
    return null;
  }
}

/** Per-git-command timeout for hook quick checks (bounds the child; the event loop stays free). */
const HOOK_GIT_TIMEOUT_MS = 1000;

/**
 * Async execFile wrapper: hook push paths must NEVER block the event loop with
 * execFileSync (a slow repo/network would stall withDeadline's timer for minutes).
 * null on any failure (missing binary, non-zero exit, timeout). Explicit `env`:
 * git must see the cwd-.env quarantine (env-trust.ts), not Bun's startup snapshot.
 */
function tryExecAsync(bin: string, args: string[], timeoutMs = HOOK_GIT_TIMEOUT_MS): Promise<string | null> {
  return new Promise((resolve) => {
    try {
      execFile(
        bin,
        // #8427: a checkout's .git/config core.fsmonitor names a command that `git status` runs; a hook probe never runs it.
        bin === 'git' ? ['-c', 'core.fsmonitor=false', ...args] : args,
        { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, env: gitChildEnv() },
        (err, stdout) => resolve(err ? null : stdout.toString().trim()),
      );
    } catch {
      resolve(null);
    }
  });
}

/**
 * Resolve the bootstrap workspace root for a hook event: the git toplevel of
 * `ws`, which must be the install receipt's workspace_dir (checked before any
 * git runs, #8427) and hold an `initialized` agent.json manifest. The gate
 * is the security boundary — `gbrain hook <event>` run in an arbitrary repo
 * must never commit or push it. Shared by session-start and session-end.
 */
async function resolveBootstrapWorkspaceRoot(ws: string): Promise<string | null> {
  // #8427: only the receipt's workspace runs git; a checkout can supply its own initialized agent.json and .git/config.
  const workspace = (() => { try { const w = readReceipt(resolveGbrainHome())?.workspace_dir; return w ? realpathOrResolve(w) : null; } catch { return null; } })();
  if (!workspace) return null;
  const at = realpathOrResolve(ws);
  if (at !== workspace && !at.startsWith(workspace.endsWith('/') ? workspace : `${workspace}/`)) return null;
  const root = await tryExecAsync('git', ['-C', ws, 'rev-parse', '--show-toplevel']);
  if (!root || realpathOrResolve(root) !== workspace) return null;
  const manifest = readManifest(root);
  if (manifest.state !== 'initialized') return null; // not a bootstrap workspace
  return root;
}

/** owner/name from a github https/ssh remote URL, or null. Canonical parser
 * (repo-visibility.ts is engine-free, so the hook contract holds). */
function githubOwnerName(url: string): string | null {
  return githubOwnerRepoString(url);
}

/**
 * The no-daemon workspace push must NOT fire until the repo phase has verified
 * the origin's privacy and recorded `repo_url`. In a create-repo-first install
 * the origin exists (the clone) BEFORE the repo phase, and hooks are wired one
 * phase earlier — so an ungated session-end/recovery push could publish
 * workspace content to an as-yet-unverified (possibly public) remote. A recorded
 * `repo_url` means the repo phase completed against a verified-private remote.
 *
 * Bound to the recorded repo: the current origin — BOTH the fetch URL and the
 * push URL (`git push` uses the push URL when set) — must still resolve to the
 * same owner/name as `repo_url`, so a later `git remote set-url` can't redirect
 * the push to another (possibly public) repo. No receipt / no repo_url / a
 * changed origin → defer (fail-closed).
 */
async function repoPhaseComplete(root: string): Promise<boolean> {
  try {
    const receipt = readReceipt(resolveGbrainHome()) as (InstallReceipt & { repo_url?: string }) | null;
    if (!receipt || typeof receipt.repo_url !== 'string' || receipt.repo_url.length === 0) return false;
    if (realpathOrResolve(receipt.workspace_dir) !== realpathOrResolve(root)) return false;
    const want = githubOwnerName(receipt.repo_url);
    const fetchUrl = await tryExecAsync('git', ['-C', root, 'remote', 'get-url', 'origin']);
    // Push URL (remote.origin.pushurl) via the config key directly (no dash-flag):
    // unset → `git push` uses the fetch URL (already matched). Only a configured
    // push URL that points elsewhere blocks the push.
    const pushUrl = await tryExecAsync('git', ['-C', root, 'config', 'remote.origin.pushurl']);
    if (want) {
      if (githubOwnerName(fetchUrl ?? '') !== want) return false;
      return !pushUrl || githubOwnerName(pushUrl) === want;
    }
    // Non-github repo_url (self-hosted / explicitly-trusted transports): bind
    // by EXACT URL equality — the recorded url is what the repo phase (or the
    // operator) verified, and a later remote redirect must still block the
    // push. Without this branch, every non-github install's no-daemon push
    // deferred forever (post-#4024 regression).
    if ((fetchUrl ?? '').trim() !== receipt.repo_url) return false;
    return !pushUrl || pushUrl.trim() === receipt.repo_url;
  } catch {
    return false;
  }
}

/**
 * Fire-and-forget `gbrain sources push --path <root>` as a DETACHED child.
 * workspacePush must never run inline in a hook — its git chain is fully
 * synchronous (execFileSync) and would block the event loop past every
 * deadline. The child owns the push lock/status plumbing; the hook only
 * announces it. Throws when the child can't be spawned (caller degrades).
 */
function spawnDetachedPush(root: string): void {
  const exec = process.execPath ?? '';
  const pushArgs = ['sources', 'push', '--path', root];
  // Compiled binary: execPath IS gbrain. Dev (bun src/cli.ts): re-exec the
  // entrypoint — the jobs.ts --detach precedent.
  const argv = /[/\\]gbrain(\.exe)?$/.test(exec) ? pushArgs : [process.argv[1], ...pushArgs];
  // Explicit env: a child spawned without one does not see the parent's
  // cwd-.env quarantine deletions (core/env-trust.ts).
  const child = spawn(exec, argv, { detached: true, stdio: 'ignore', env: process.env });
  child.unref();
}

/**
 * [G4] Crashed-session recovery: dirty tree or unpushed commits at session
 * start → spawn the workspace push in the background (never inline). GATED
 * on the initialized-manifest bootstrap workspace root (the security
 * boundary — see resolveBootstrapWorkspaceRoot).
 */
async function dirtyTreePush(
  ws: string,
  io: HookIo,
): Promise<{ note?: string; reason?: string; degraded?: boolean } | null> {
  try {
    const root = await resolveBootstrapWorkspaceRoot(ws);
    if (!root) return null;
    if (!(await treeNeedsPush(root))) return null; // clean + up to date → nothing to recover
    if (isManagedFilesystemPath(root)) return { reason: 'push_managed_coordinator' };
    // There IS unpushed work. Defer until the repo phase verified privacy +
    // recorded repo_url — never recover-push to an unverified origin
    // (create-repo-first race). Only fires when work actually exists (P2-1).
    if (!(await repoPhaseComplete(root))) {
      return {
        note: 'Unpushed work detected; will push after the repo phase completes (`gbrain bootstrap repo`).',
        reason: 'push_deferred_repo_pending',
      };
    }
    try {
      (io.spawnPush ?? spawnDetachedPush)(root);
      return {
        note: 'Unpushed work from a previous session detected — recovering unpushed work in background (gbrain sources push).',
        reason: 'push_spawned',
      };
    } catch {
      return {
        note: 'Unpushed work from a previous session detected; automatic push unavailable — run gbrain doctor',
        reason: 'push_unavailable',
        degraded: true,
      };
    }
  } catch {
    return null;
  }
}

/** True when the workspace has uncommitted changes or commits ahead of
 * upstream — shared by the SessionStart recovery push and the stop-hook
 * per-turn push. Two 1s-capped git probes; never throws. */
async function treeNeedsPush(root: string): Promise<boolean> {
  // Dirty tree → always needs a push. For "ahead", measure against the SAME
  // ref workspacePush targets (origin/<default-branch>), NOT @{u}: a branch
  // with no upstream makes `@{u}..HEAD` error → 0, which would report a clean
  // + committed-but-unpushed tree as push_clean and silently strand it (the
  // exact tail-loss the per-turn push exists to prevent). When the origin ref
  // doesn't resolve yet (never pushed), any commit past the empty tree counts
  // as needs-push.
  const status = await tryExecAsync('git', ['-C', root, 'status', '--porcelain']);
  if (withoutPhysicalRootMetadata(status ?? '') !== '') return true;
  const branch = await tryExecAsync('git', ['-C', root, 'branch', '--show-current']);
  const b = (branch ?? '').trim();
  if (b) {
    const ahead = await tryExecAsync('git', ['-C', root, 'rev-list', '--count', `origin/${b}..HEAD`]);
    if (ahead !== null) return (parseInt(ahead, 10) || 0) > 0;
    // origin/<b> doesn't exist (never pushed) → any local commit needs pushing.
    const have = await tryExecAsync('git', ['-C', root, 'rev-list', '--count', 'HEAD']);
    return (parseInt(have ?? '0', 10) || 0) > 0;
  }
  // Detached HEAD / no branch name — fall back to the upstream measure.
  const ahead = await tryExecAsync('git', ['-C', root, 'rev-list', '--count', '@{u}..HEAD']);
  return ahead !== null && (parseInt(ahead, 10) || 0) > 0;
}

// ── stop-hook per-turn push [D3/D17/D20] ────────────────────────────────────
//
// SessionEnd never fires on /exit (upstream: closed not-planned), can't fire
// on crash, and a cloud sandbox VM may simply be reclaimed between turns —
// so the Stop boundary (fires after EVERY assistant turn) is the only cadence
// that always runs while work exists. Debounced per workspace root, detached
// spawn (instant), fail-open everywhere.

function stopPushStatePath(root: string): string {
  return join(resolveGbrainHome(), 'bootstrap', `stop-push-${workspaceRootHash(root)}.json`);
}

/** Debounce resolution: env GBRAIN_STOP_PUSH_DEBOUNCE_MIN (minutes; 0 = every
 * turn) → file-plane config hooks.stop_push_debounce_min → environment-kind
 * default (cloud-sandbox: 0, everything else: 5). */
function stopPushDebounceMs(): number {
  const env = process.env.GBRAIN_STOP_PUSH_DEBOUNCE_MIN;
  if (env !== undefined) {
    const n = Number.parseInt(env, 10);
    if (Number.isFinite(n) && n >= 0) return n * 60_000;
  }
  try {
    const cfg = loadConfig();
    const v = cfg?.hooks?.stop_push_debounce_min;
    const n = typeof v === 'number' ? v : typeof v === 'string' ? Number.parseInt(v, 10) : NaN;
    if (Number.isFinite(n) && n >= 0) return n * 60_000;
  } catch {
    /* tolerant read — fall through to the default */
  }
  return detectExecutionEnvironment() === 'cloud-sandbox' ? 0 : STOP_PUSH_DEBOUNCE_MIN_DEFAULT * 60_000;
}

/** Floor for the [D20] failing-status retry cadence: a stuck push (e.g. gh
 * unauthenticated for a day) must not re-run the full network ladder on every
 * single turn — one retry a minute keeps recovery fast without the storm. */
export const STOP_PUSH_FAILING_RETRY_FLOOR_MS = 60_000;

/** Decide + (maybe) spawn the per-turn push. Returns the heartbeat reason.
 * Ordered cheapest-first: the debounce (two file reads) answers the common
 * case before any git subprocess runs — repoPhaseComplete's git probes only
 * execute on turns that might actually spawn a push. */
async function stopPushIfDue(ws: string, io: HookIo): Promise<string> {
  if (process.env.GBRAIN_STOP_PUSH === '0') return 'push_disabled';
  const root = await resolveBootstrapWorkspaceRoot(ws);
  if (!root) return 'push_skipped_not_bootstrap';

  const stateP = stopPushStatePath(root);
  let lastTs: number | null = null;
  try {
    const s = JSON.parse(readFileSync(stateP, 'utf8')) as { ts?: string };
    const t = Date.parse(s.ts ?? '');
    if (Number.isFinite(t)) lastTs = t;
  } catch {
    /* missing/corrupt state → due (fail-open) */
  }
  // [D20] a failing push bypasses the normal debounce so recovery is fast —
  // but with a 60s floor so a persistently failing push can't re-run the
  // network verification ladder on every turn (the push lock bounds
  // concurrency, not cadence; the banner is already showing the failure).
  const failing = readPushStatusForRoot(root)?.ok === false;
  const now = Date.now();
  // Healthy: the normal debounce (0 = every turn in cloud). Failing: a fixed
  // 60s retry floor — faster than a long local debounce so a transient failure
  // recovers within a turn or two, but NEVER every-turn (a Math.min against the
  // cloud debounce of 0 was a re-run-the-ladder-every-turn storm; adversarial
  // review caught it).
  const windowMs = failing ? STOP_PUSH_FAILING_RETRY_FLOOR_MS : stopPushDebounceMs();
  if (lastTs !== null && now - lastTs < windowMs) return 'push_debounced';
  // Same privacy gate as SessionEnd: never push before the repo phase has
  // verified the origin and recorded repo_url (create-repo-first race).
  if (!(await repoPhaseComplete(root))) return 'push_deferred_repo_pending';
  if (!(await treeNeedsPush(root))) return 'push_clean';
  if (isManagedFilesystemPath(root)) return 'push_managed_coordinator';
  try {
    // Written BEFORE the spawn so repeated fail-fast children stay debounced
    // on the healthy path; the [D20] failing-status bypass handles retries.
    mkdirSync(join(resolveGbrainHome(), 'bootstrap'), { recursive: true, mode: 0o700 });
    const tmp = `${stateP}.tmp-${process.pid}`;
    writeFileSync(tmp, JSON.stringify({ ts: new Date(now).toISOString(), root }) + '\n', { mode: 0o600 });
    renameSync(tmp, stateP);
  } catch {
    /* state-write failure must not block the push itself */
  }
  try {
    (io.spawnPush ?? spawnDetachedPush)(root);
    return 'push_spawned';
  } catch {
    return 'push_unavailable';
  }
}

// ── push-failure banner [D5/D13/D19] ────────────────────────────────────────

interface PushAnnounceState {
  announced_ts?: string;
  last_announce_at?: string;
}

/**
 * The pending ≤300-char failure banner, or null. `record()` marks the due
 * failures announced and is called ONLY after the banner actually reached
 * stdout — a deadline-suppressed banner must re-fire next turn. Announce
 * state is a sidecar next to each per-root status file (`<file>.announced`):
 * each new failure `ts` announces once, then re-announces at most every
 * PUSH_ANNOUNCE_REFIRE_MS while the failure persists [D19].
 */
function pendingPushFailureBanner(): { text: string; record: () => void } | null {
  try {
    // #5799: a refusal recorded on a managed root is not a failing push; the outbox publishes there.
    const failing = livePushStatuses(readPushStatuses()).filter((e) => e.ok === false);
    if (failing.length === 0) return null;
    const now = Date.now();
    const due = failing.filter((e) => {
      try {
        const s = JSON.parse(readFileSync(`${e.file}.announced`, 'utf8')) as PushAnnounceState;
        if (s.announced_ts !== e.ts) return true;
        const last = Date.parse(s.last_announce_at ?? '');
        return !Number.isFinite(last) || now - last > PUSH_ANNOUNCE_REFIRE_MS;
      } catch {
        return true; // never announced (or unreadable state) → due
      }
    });
    if (due.length === 0) return null;
    const first = due[0]!;
    const which = first.repoRoot ?? 'the workspace';
    const more = due.length > 1 ? ` (+${due.length - 1} more workspace(s))` : '';
    const text = (
      `NOTICE: the background workspace push for ${which} is FAILING ` +
      `(${sanitizePushReason(first.reason)})${more} — work is committed locally ` +
      'but NOT on GitHub. Run gbrain doctor.'
    ).slice(0, PUSH_BANNER_MAX_CHARS);
    const record = () => {
      for (const e of due) {
        try {
          writeFileSync(
            `${e.file}.announced`,
            JSON.stringify({ announced_ts: e.ts, last_announce_at: new Date(now).toISOString() }) + '\n',
            { mode: 0o600 },
          );
        } catch {
          /* fail-open — worst case the banner re-fires */
        }
      }
    };
    return { text, record };
  } catch {
    return null;
  }
}

// ── monthly backup-coverage notices (cache readers; engine-free) ────────────

/**
 * Shared body for the two hook-borne backup notices: cache read + the shared
 * nag gate on the given channel; the returned record() is deferred until the
 * text actually reached stdout (record-after-write). backupNoticeText already
 * caps the body at its 300-char budget — the short prefix on top stays far
 * inside the payload cap, so no second slice (a slice here chopped the
 * trailing call-to-action).
 */
function backupHookNotice(channel: string, prefix: string): { text: string; record: () => void } | null {
  try {
    if (backupCheckDisabled()) return null;
    const s = loadBackupStatus();
    if (!s || s.overall !== 'warn') return null;
    const gate = backupNagGate(channel, s);
    if (!gate.show) return null;
    const t = backupNoticeText(s, 'human');
    if (!t) return null;
    return { text: `${prefix}${t}`, record: gate.record };
  } catch {
    return null;
  }
}

/** Session-start digest note ('hook-note' channel). */
function backupSessionStartNote(): { text: string; record: () => void } | null {
  return backupHookNotice('hook-note', 'Backup check: ');
}

/**
 * The backup banner for the user-prompt payload ('hook-banner' channel). Same
 * delivery rail as the push-failure banner (systemMessage + additionalContext);
 * the push failure wins the single banner slot — this one only fires when no
 * push failure is pending.
 */
function pendingBackupBanner(): { text: string; record: () => void } | null {
  return backupHookNotice('hook-banner', 'NOTICE: ');
}

/**
 * Fire-and-forget `gbrain backup check --quiet` as a DETACHED child (the
 * spawnDetachedPush pattern). The child re-resolves everything itself and
 * exits 0 silently when the PGLite lock is held by a live serve — that
 * install is covered by the serve-side refresher instead.
 */
function spawnDetachedBackupCheck(): void {
  const exec = process.execPath ?? '';
  const checkArgs = ['backup', 'check', '--quiet'];
  const argv = /[/\\]gbrain(\.exe)?$/.test(exec) ? checkArgs : [process.argv[1], ...checkArgs];
  const child = spawn(exec, argv, {
    detached: true,
    stdio: 'ignore',
    env: { ...process.env, GBRAIN_SKIP_STARTUP_HOOKS: '1' },
  });
  child.on('error', () => {});
  child.unref();
}

// ── user-prompt [ENG-1, S3#8, A9] ───────────────────────────────────────────

interface UserPromptOutcome {
  outcome: HookHeartbeatEntry['outcome'];
  reason?: string;
  turns?: number;
  pressure_pct?: number;
}

async function hookUserPrompt(io: HookIo): Promise<number> {
  const t0 = Date.now();
  let expired = false;
  const guardedWrite = (s: string) => {
    if (!expired) write(io, s);
  };

  // [D5/D19] Same-session failure surfacing: a refused/failed background push
  // becomes visible on the NEXT turn — to the model via additionalContext AND
  // to the human via systemMessage ("never silent" must not depend on the
  // model choosing to relay its own tooling's failure). Embedded in the main
  // payload when one is written; emitted alone on every degraded path.
  // Computed INSIDE the deadline-raced closure: its sync file reads must be
  // budgeted by the 800ms deadline, not free-ride before the race starts.
  let banner: ReturnType<typeof pendingPushFailureBanner> = null;
  let wrotePayload = false;
  // Per-turn brain-first rule (brain-first.ts): every turn, with or without a block.
  let turnRule: string | null = null;

  const work = (async (): Promise<UserPromptOutcome> => {
    // Push failure wins the single banner slot; the monthly backup notice
    // rides the same rail (systemMessage + additionalContext) when no push
    // failure is pending. Both are cache/file readers, budgeted by the race.
    turnRule = io.turnRule !== undefined ? io.turnRule : brainFirstTurnRule(io.harness ?? 'claude-code', io.cwd ?? hookSessionCwd());
    const j = await readStdinJson(io, 300);
    // #8028, #9163: a task notification or agent-team message arrives as a prompt but is no human turn: no context, no rule.
    if (typeof j?.prompt === 'string' && /^\s*<(task-notification|teammate-message)[\s>]/.test(j.prompt)) { turnRule = null; return { outcome: 'ok', reason: 'harness_prompt' }; }
    // The turn-rule lane's connection may reach another brain, so it never reads this machine's context or banners.
    if (process.env.GBRAIN_HOOK_LANE === TURN_RULE_LANE) return { outcome: 'ok', reason: 'rule_only' };
    banner = io.disablePushBanner ? null : (pendingPushFailureBanner() ?? pendingBackupBanner());
    if (!j) return { outcome: 'degraded', reason: 'no_stdin' };

    // S3#8: transcript_path is untrusted input. A present-but-unconfined
    // path aborts the event (heartbeat + empty stdout), never "best effort".
    let turns: WindowTurn[] = [];
    let priorContextText: string | undefined;
    let transcriptPath: string | undefined;
    if (j.transcript_path !== undefined && j.transcript_path !== null) {
      const conf = captureSpecFor(io.harness).confine(j.transcript_path, { // #5941: codex rollouts live under CODEX_HOME/sessions
        ...(io.transcriptRoot ? { root: io.transcriptRoot } : {}),
        // #5701: bounded tail read below — the 50MiB whole-file gate must not
        // reject a long session before it runs (full rationale in
        // claude-code-jsonl.ts's confinement).
        allowOversize: true,
      });
      if (!conf.ok) return { outcome: 'degraded', reason: `transcript_${conf.reason}` };
      transcriptPath = conf.path;
      try {
        const parsed = captureSpecFor(io.harness).parse(conf.path, { maxBytes: USER_PROMPT_TRANSCRIPT_MAX_BYTES });
        turns = parsed.turns.slice(-USER_PROMPT_WINDOW_TURNS);
        // Cross-turn dedupe: feed the blocks WE previously injected this
        // session back as priorContextText (slug-only suppression + volunteer
        // dedupe inside assembleTurnContext) — a page is volunteered once per
        // session, not once per mention. Structured extraction only (the
        // gbrain-marked hook_additional_context attachments), never raw turn
        // text, so a short slug in a tool payload can't over-suppress.
        // Bounded before send: identical blocks dedupe (the same pointer
        // re-recorded each turn is pure redundancy) and the newest blocks are
        // kept under a byte cap — an unbounded join would eventually exceed
        // the 256KB IPC message cap and permanently silence the channel.
        // Horizon note: the tail read bounds dedupe to the newest
        // USER_PROMPT_TRANSCRIPT_MAX_BYTES of transcript — in very long
        // sessions the oldest injections roll out and their pages become
        // volunteerable again (documented, preferable to a state file).
        if (parsed.injectedContextBlocks.length) {
          const unique = [...new Set(parsed.injectedContextBlocks)];
          const kept: string[] = [];
          let bytes = 0;
          for (const block of unique.reverse()) { // newest first
            const b = Buffer.byteLength(block, 'utf8') + 2;
            // Skip (not break): one oversized block must not evict every
            // older, smaller block — that would disable ALL dedupe at once.
            if (bytes + b > PRIOR_CONTEXT_MAX_BYTES) continue;
            kept.unshift(block); // restore oldest → newest order
            bytes += b;
          }
          if (kept.length) priorContextText = kept.join('\n\n');
        }
      } catch {
        turns = []; // unreadable-mid-flight — the prompt alone still works
      }
    }
    const prompt = typeof j.prompt === 'string' ? j.prompt : '';
    if (prompt.trim()) turns = [...turns, { role: 'user', text: prompt }];
    if (turns.length === 0) return { outcome: 'ok', reason: 'empty_window' };

    const cfg = io.configOverride !== undefined ? io.configOverride : loadConfig();
    // Engine-uniform (#4245): PGLite keys the socket off the data dir,
    // Postgres off hash12(database_url) under ~/.gbrain/run. Null = no
    // keying material at all (no config, thin-client remote) — ENGINE-FREE
    // means no direct-engine fallback here; pull-mode covers it.
    const sessionId = typeof j.session_id === 'string' ? j.session_id : undefined;
    const sourceId = await contextSource(io, cfg, sessionId, io.cwd ?? (typeof j.cwd === 'string' ? j.cwd : hookSessionCwd()));
    const socketPath = await hookResolveSocketForConfig(cfg, sourceId);
    if (!socketPath) {
      return { outcome: 'degraded', reason: 'no_pglite_path' };
    }
    const secret = readIpcSecretForConfig(cfg);
    if (!secret) return { outcome: 'degraded', reason: 'no_serve' };

    const res = await requestTurnContext(socketPath, {
      secret,
      window: turns,
      ...(priorContextText ? { priorContextText } : {}),
      ...(sessionId ? { sessionId } : {}),
      ...(sourceId ? { sourceId } : {}),
      // Feedback-loop attribution: the serve logs the delivered block's
      // volunteered pages/pointers under this channel. Bootstrap registers
      // hooks for Claude Code only today; a future codex registration passes
      // `--harness codex` on the hook command.
      channel: io.harness ?? 'claude-code',
    });
    if (res === IPC_UNAVAILABLE) {
      return { outcome: 'degraded', reason: 'ipc_unavailable', turns: turns.length };
    }
    if ('degraded' in res && res.degraded === 'stale_serve') {
      // [A9] Protocol echo missing → v1 serve answered; degrade LOUDLY.
      return { outcome: 'degraded', reason: 'stale_serve', turns: turns.length };
    }
    const resp = res as TurnContextResponse;
    if (!resp.ok) {
      return { outcome: 'degraded', reason: reasonCode(resp.error ?? 'server_error'), turns: turns.length };
    }
    // Context-pressure notice (pressure.ts) leads the block so the cap loop never trims it.
    const pressure = transcriptPath && io.harness !== 'codex' ? claudeCodePressure(resp.block?.pressure, transcriptPath, sessionId) : null;
    const text = [pressure?.notice, resp.block?.text].filter(Boolean).join('\n\n');
    if (!text) return resp.degradedReason === 'server_budget' ? { outcome: 'degraded', reason: 'server_budget', turns: turns.length } : { outcome: 'ok', reason: 'empty_block', turns: turns.length };

    // [ENG-1] The 10000-char harness cap applies to the WHOLE stdout payload;
    // the block is budgeted ≤8KB server-side, but JSON escaping inflates, so
    // trim defensively rather than letting the harness divert-and-drop. The
    // banner (≤300 chars, fixed) rides inside the same payload [D5] — only
    // blockText is trimmed, so the failure notice survives the cap loop.
    const bannerPrefix = [banner?.text, turnRule].filter(Boolean).map((t) => `${t}\n\n`).join('');
    const buildPayload = (block: string) =>
      JSON.stringify({
        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: bannerPrefix + block },
        ...(banner ? { systemMessage: banner.text } : {}),
      });
    let blockText = text;
    let payload = buildPayload(blockText);
    while (payload.length > CLAUDE_HOOK_OUTPUT_CAP_CHARS && blockText.length > 0) {
      blockText = blockText.slice(0, Math.max(0, blockText.length - (payload.length - CLAUDE_HOOK_OUTPUT_CAP_CHARS) - 16));
      payload = buildPayload(blockText);
    }
    if (blockText.length === 0) return { outcome: 'degraded', reason: 'over_cap', turns: turns.length };
    guardedWrite(payload + '\n');
    if (!expired) {
      wrotePayload = true;
      banner?.record();
    }
    // Partial trim is delivery-count drift: the serve already logged the FULL
    // post-budget set at the response write, but pages cut from the tail here
    // were never injected. Record it so the doctor's heartbeat reconciliation
    // (and a future reconciler) can see the divergence — outcome stays ok
    // (context WAS injected), the reason carries the signal.
    const pct = pressure?.notice ? { pressure_pct: pressure.percent } : {};
    if (blockText.length < text.length) return { outcome: 'ok', reason: 'trimmed', turns: turns.length, ...pct };
    return { outcome: 'ok', turns: turns.length, ...pct };
  })();

  let result: UserPromptOutcome;
  try {
    const raced = await withDeadline(io.userPromptDeadlineMs ?? USER_PROMPT_DEADLINE_MS, work);
    if (raced === DEADLINE) {
      expired = true; // late writes are suppressed — a post-deadline block must not appear
      result = { outcome: 'degraded', reason: 'deadline' };
    } else {
      result = raced;
    }
  } catch (e) {
    expired = true;
    result = { outcome: 'error', reason: errorCode(e) };
  }
  // Banner-only emission [D5]: every path that did NOT write the main payload
  // (no_serve, ipc_unavailable, no_pglite_path, empty windows, transcript
  // aborts, …) still surfaces the push failure — unless the deadline expired,
  // in which case record() was never called and the banner re-fires next turn.
  // The per-turn rule rides the same fallback on every path, the deadline included.
  // (Local copies: TS cannot track the closure-side assignments.)
  const pendingBanner = (expired ? null : banner) as { text: string; record: () => void } | null;
  const rule = turnRule as string | null;
  if (!wrotePayload && (pendingBanner || rule)) {
    write(
      io,
      JSON.stringify({
        hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: [pendingBanner?.text, rule].filter(Boolean).join('\n\n') },
        ...(pendingBanner ? { systemMessage: pendingBanner.text } : {}),
      }) + '\n',
    );
    pendingBanner?.record();
  }
  await writeHeartbeat(io, {
    ts: new Date().toISOString(),
    event: 'user-prompt',
    outcome: result.outcome,
    ...(result.reason ? { reason: result.reason } : {}),
    duration_ms: Date.now() - t0,
    ...(result.turns !== undefined ? { turns: result.turns } : {}),
    ...(result.pressure_pct !== undefined ? { pressure_pct: result.pressure_pct } : {}),
  });
  return 0;
}

// ── compact (PreCompact banking, v0.45.7 ambient recall) ─────────────────────

/** Self-deadline for the compact event (harness timeout is 5s). */
export const COMPACT_DEADLINE_MS = 3000;
/** Banking wants breadth, not the 4-turn prompt window. */
const COMPACT_WINDOW_TURNS = 20;
/** Minimum remaining budget to START the segment scan+write (cathedral 5). */
const SEGMENT_MIN_BUDGET_MS = 600;
/** Minimum remaining budget for the durability WRITE itself (segment file +
 * ledger). Named separately from the IPC threshold on purpose (pre-landing
 * review): tuning one must not silently retune the other. */
const SEGMENT_WRITE_MIN_BUDGET_MS = 300;
/** Minimum remaining budget to fire the banking IPC call (cathedral 5). */
const COMPACT_IPC_MIN_BUDGET_MS = 300;

/**
 * PreCompact fires BEFORE Claude Code compacts the transcript. Its stdout is
 * NOT context-injected — the useful work is the WRITEs (cathedral 5 order,
 * durability first):
 *   1. bank the since-last-boundary window DURABLY as a content-addressed
 *      corpus segment + ledger entry (secret-scanned; never written unscanned;
 *      per-step deadline degrades with typed codes) — the serve sweep is the
 *      extraction backstop even if everything after this fails;
 *   2. ONE IPC round trip that banks the window's standing entities into the
 *      session cursor (and, when a segment was banked, asks serve to harvest
 *      it promptly) so the post-compaction SessionStart (source=compact)
 *      serves a warm rehydration pack.
 * Engine-free: transcript parse + fs + one IPC round trip. Fail-open always.
 */
async function hookCompact(io: HookIo): Promise<number> {
  const t0 = Date.now();
  const deadlineMs = io.compactDeadlineMs ?? COMPACT_DEADLINE_MS;
  const remaining = () => deadlineMs - (Date.now() - t0);
  let outcome: HookHeartbeatEntry['outcome'] = 'ok';
  let reason: string | undefined;
  let segment: string | undefined;
  let flushAck: string | undefined;
  let seatReasons: string[] = [];

  const work = (async () => {
    const j = await readStdinJson(io, 300);
    if (!j) { outcome = 'degraded'; reason = 'no_stdin'; return; }

    // S3#8 posture matches user-prompt: an unconfined transcript path aborts.
    let turns: WindowTurn[] = [];
    let boundaryTurnIndexes: number[] = [];
    let allTurns: WindowTurn[] = [];
    let transcriptPath: string | undefined;
    if (j.transcript_path !== undefined && j.transcript_path !== null) {
      const conf = confineTranscriptPath(j.transcript_path, {
        ...(io.transcriptRoot ? { root: io.transcriptRoot } : {}),
        // #5701: bounded tail read below — the 50MiB whole-file gate must not
        // reject a long session before it runs (full rationale in
        // claude-code-jsonl.ts's confinement).
        allowOversize: true,
      });
      if (!conf.ok) { outcome = 'degraded'; reason = `transcript_${conf.reason}`; return; }
      transcriptPath = conf.path;
      try {
        const parsed = parseTranscript(conf.path, { maxBytes: USER_PROMPT_TRANSCRIPT_MAX_BYTES });
        allTurns = parsed.turns;
        boundaryTurnIndexes = parsed.boundaryTurnIndexes;
        turns = parsed.turns.slice(-COMPACT_WINDOW_TURNS);
      } catch {
        turns = [];
      }
    }
    // sanitizeSessionId maps a MISSING id to the 'unknown' sentinel (fine for
    // the stop buffer's filenames, wrong for cursor banking — a shared
    // 'unknown' bucket would cross-pollinate sessions). Treat it as absent.
    const sid = sanitizeSessionId(j?.session_id);
    const sessionId = sid === 'unknown' ? null : sid;
    if (!sessionId || turns.length === 0) {
      // Nothing to bank against — not an error, just nothing to do.
      if (outcome === 'ok') reason = sessionId ? 'empty_window' : 'no_session';
      return;
    }

    const cfg = loadConfig();

    // Cathedral 5, durability FIRST: content-addressed segment + ledger before
    // any IPC. Written for EVERY engine config (the sweep backstop harvests it
    // when serve/IPC is unavailable). Per-step deadline degrades — a scan that
    // can't finish skips the segment ENTIRELY (never write unscanned content).
    const { dir, stamp, source } = await sessionCorpus(io, cfg, sessionId, io.cwd ?? (typeof j.cwd === 'string' ? j.cwd : hookSessionCwd()));
    const speaker = hookSpeaker(io, dir, sessionId);
    if (speaker.bank !== true) { if (speaker.bank === 'failed') outcome = 'degraded'; reason = speaker.reason; return; }
    seatReasons = [...speaker.reasons, ...captureSeat(io, dir, sessionId, transcriptPath)];
    const banked = await bankCompactSegment(dir, sessionId, allTurns, boundaryTurnIndexes, {
      remainingMs: remaining,
      minScanMs: SEGMENT_MIN_BUDGET_MS,
      minWriteMs: SEGMENT_WRITE_MIN_BUDGET_MS,
      beforeWrite: (file, text) => { recordCaptureIfOff(cfg, file, text, source); },
      stamp,
    });
    segment = banked.segment;
    const flushCorpusFile = banked.flushCorpusFile;

    // Same engine-uniform resolution as the session-start pack arm (v0.45.7
    // symmetry, engine-uniform since #4245): a Postgres config carrying a
    // leftover database_path must not probe the PGLite socket (the resolver
    // checks engine first); a Postgres brain probes its hash12(database_url)
    // run-dir socket instead. Null = no keying material → degrade.
    const compactSocket = await hookResolveSocketForConfig(cfg, source);
    if (!compactSocket) { outcome = 'degraded'; reason = 'no_pglite_path'; return; }
    const secret = readIpcSecretForConfig(cfg);
    if (!secret) { outcome = 'degraded'; reason = 'no_serve'; return; }
    if (remaining() < COMPACT_IPC_MIN_BUDGET_MS) { outcome = 'degraded'; reason = 'deadline'; return; }

    const res = await requestContextPack(compactSocket, {
      secret,
      sessionId,
      window: turns,
      bankOnly: true,
      trigger: 'compact-bank',
      ...(flushCorpusFile ? { flushCorpusFile } : {}),
      ...(source ? { sourceId: source } : {}),
    });
    if (res === IPC_UNAVAILABLE) { outcome = 'degraded'; reason = 'ipc_unavailable'; return; }
    if ('degraded' in res && res.degraded === 'stale_serve') { outcome = 'degraded'; reason = 'stale_serve'; return; }
    const resp = res as ContextPackResponse;
    if (!resp.ok) { outcome = 'degraded'; reason = reasonCode(resp.error ?? 'server_error'); return; }
    // Fold the harvest-schedule ack into the heartbeat (adversarial review):
    // a persistently full queue, bad basename, or split-corpus-dir not_found
    // was previously observable NOWHERE — the ack was dropped on the floor
    // and serve only heartbeats pump outcomes. Codes only, never content.
    const cf = (resp.block as { checkpointFlush?: { status?: string; reason?: string } } | null | undefined)
      ?.checkpointFlush;
    if (cf?.status === 'scheduled') flushAck = 'scheduled';
    else if (cf) flushAck = `skip_${cf.reason ?? 'unknown'}`;
  })();

  try {
    const raced = await withDeadline(deadlineMs, work);
    if (raced === DEADLINE && outcome === 'ok') { outcome = 'degraded'; reason = 'deadline'; }
  } catch (e) {
    outcome = 'error';
    reason = errorCode(e); // fail-open: exit 0
  }
  if (outcome === 'ok' && seatReasons.length) { outcome = 'degraded'; reason = seatReasons[0]; }
  const hint = seatReasonHint(reason);
  await writeHeartbeat(io, {
    ts: new Date().toISOString(),
    event: 'compact',
    outcome,
    ...(reason ? { reason } : {}),
    ...(hint ? { hint } : {}),
    duration_ms: Date.now() - t0,
    ...(segment ? { segment } : {}),
    ...(flushAck ? { flush: flushAck } : {}),
  });
  return 0;
}

// ── stop [G15] ──────────────────────────────────────────────────────────────

async function hookStop(io: HookIo): Promise<number> {
  const t0 = Date.now();
  let outcome: HookHeartbeatEntry['outcome'] = 'ok';
  let reason: string | undefined;
  let j: Record<string, unknown> | null = null;
  try {
    j = await readStdinJson(io, 300);
    // #5558: stop no longer buffers assistant text; GC drains any buffers
    // older binaries left behind.
    gcOldFiles(await liveBufferDir(), STOP_BUFFER_RETENTION_MS);
  } catch (e) {
    outcome = 'error';
    reason = errorCode(e);
  }
  // Ambient-writeback backstop (WP4) — its own try/deadline, fail-open, and
  // FILE-plane gated (this child never opens the engine; the serve-side
  // harvest re-checks the AUTHORITATIVE DB-plane gate before extracting).
  // Every outcome is a typed heartbeat reason on its own `writeback-bank`
  // event; IPC down = degraded (the sweep's corpus pass extracts the banked
  // file later). Zero LLM here — the gate is deterministic and "Thanks"
  // never even produces a file.
  let wbReason: string | undefined;
  const wbT0 = Date.now();
  try {
    const wbWork = (async (): Promise<string> => {
      // ONE uncached loadConfig for the whole step (it re-reads disk every
      // call) — gate, corpus dir, and IPC discovery all share it.
      const cfg = loadConfig();
      const wb = resolveWritebackConfigFromFile(cfg);
      if (!wb.enabled) return 'wb_off';
      const sid = sanitizeSessionId(j?.session_id);
      if (sid === 'unknown') return 'no_session';
      const tp = j?.transcript_path;
      if (tp === undefined || tp === null) return 'no_transcript';
      const conf = confineTranscriptPath(tp as string, {
        ...(io.transcriptRoot ? { root: io.transcriptRoot } : {}),
        // #5701: bounded tail reads (128KB probe, then the 2MB cap).
        allowOversize: true,
      });
      if (!conf.ok) return `transcript_${conf.reason}`;
      // #5820: the SessionEnd guard's fingerprint (#5413) — a turn from
      // gbrain's own claude-cli subprocess is never banked, or extracting it
      // spawns another claude-cli call that banks again.
      const ws = io.cwd ?? (typeof j?.cwd === 'string' ? j.cwd : hookSessionCwd());
      if (isClaudeCliSelfTranscriptPath(conf.path) || isClaudeCliSelfTranscriptPath(ws)) return 'self_capture';
      const findLastUser = (parsed: ReturnType<typeof parseTranscript>): WindowTurn | undefined => {
        const index = parsed.genuineUserTurnIndexes.at(-1);
        return index === undefined ? undefined : parsed.turns[index];
      };
      let lastUser: WindowTurn | undefined;
      try {
        // Cheap-first tail sizing: a 128KB newest-tail finds the most-recent
        // user turn in the common case, BUT the turn's OFFSET from EOF is the
        // whole assistant response including tool_result JSONL — a single big
        // file-read result can push it out of the window (red-team review,
        // this wave: turn SIZE ≠ turn OFFSET). Missing ⇒ ONE retry at the
        // 2MB user-prompt cap; only then is the turn genuinely absent. The
        // wide parse only ever runs when the cheap one failed, so the common
        // path keeps the 128KB cost inside this lane's 2s budget.
        lastUser = findLastUser(
          parseTranscript(conf.path, { maxBytes: WRITEBACK_TRANSCRIPT_TAIL_BYTES }),
        );
        if (!lastUser) {
          lastUser = findLastUser(
            parseTranscript(conf.path, { maxBytes: USER_PROMPT_TRANSCRIPT_MAX_BYTES }),
          );
        }
      } catch {
        return 'parse_failed';
      }
      if (!lastUser || !lastUser.text) return 'no_user_turn';
      const gated = gateWritebackTurn(lastUser.text);
      if (!gated.ok) return gated.reason;
      const { dir, stamp, source } = await sessionCorpus(io, cfg, sid, ws);
      const speaker = hookSpeaker(io, dir, sid); // #8064: the speaker marker precedes the banked turn file
      if (speaker.bank !== true) return speaker.reason;
      captureSeat(io, dir, sid, conf.path); // #4618: the seat precedes the banked turn file
      // The session's source rides IN THE NAME so the sweep fallback files the turn where the IPC lane below would.
      const banked = await bankWritebackTurn(dir, sid, gated.normalized, gated.hash24, stamp);
      if (banked.status !== 'wb_banked' && banked.status !== 'wb_dup') return banked.status;
      if (banked.status === 'wb_dup') return 'wb_dup';
      // Prompt-harvest ask over the compact-bank IPC lane — sourceId rides
      // exactly like the compact call (OV2-9/OV-A6); every failure below is
      // degraded-not-blocking: the banked file is the durable artifact and
      // the sweep extracts it when serve is away.
      const socket = await hookResolveSocketForConfig(cfg, source);
      if (!socket) return 'no_pglite_path';
      const secret = readIpcSecretForConfig(cfg);
      if (!secret) return 'no_serve';
      const res = await requestContextPack(socket, {
        secret,
        sessionId: sid,
        bankOnly: true,
        trigger: 'writeback-bank',
        ...(banked.flushCorpusFile ? { flushCorpusFile: banked.flushCorpusFile } : {}),
        ...(source ? { sourceId: source } : {}),
      });
      if (res === IPC_UNAVAILABLE) return 'ipc_unavailable';
      if ('degraded' in res && res.degraded === 'stale_serve') return 'stale_serve';
      const resp = res as ContextPackResponse;
      if (!resp.ok) return 'flush_failed';
      const cf = (resp.block as { checkpointFlush?: { status?: string; reason?: string } } | null | undefined)?.checkpointFlush;
      if (cf?.status === 'scheduled') return 'wb_scheduled';
      return cf ? `flush_skip_${cf.reason ?? 'unknown'}` : 'wb_banked';
    })();
    const raced = await withDeadline(WRITEBACK_STOP_DEADLINE_MS, wbWork);
    wbReason = raced === DEADLINE ? 'wb_deadline' : raced;
  } catch (e) {
    wbReason = `wb_${errorCode(e)}`;
  }
  if (wbReason && wbReason !== 'wb_off') {
    // Outcome classes (adversarial review, this wave): 'ok' covers BOTH the
    // banked/scheduled successes AND every BY-DESIGN skip — the deterministic
    // gate filters ("Thanks" → ack_or_greeting), a turn genuinely absent from
    // the transcript, and the flush_skip_* family (the turn IS banked; the
    // enqueue was declined by a designed cap/queue policy and the sweep
    // extracts it later). 'degraded' is reserved for infrastructure faults
    // (IPC down, stale serve, parse/scan failures, deadline) so doctor's
    // skipped-vs-failed counters and any alerting stay honest.
    const wbByDesign =
      wbReason === 'wb_scheduled' || wbReason === 'wb_banked' || wbReason === 'wb_dup' ||
      wbReason === 'no_user_turn' || wbReason === 'self_capture' || wbReason === 'capture_opt_out' || wbReason.startsWith('flush_skip_') ||
      (WRITEBACK_SKIP_REASONS as readonly string[]).includes(wbReason);
    await writeHeartbeat(io, {
      ts: new Date().toISOString(),
      event: 'writeback-bank',
      outcome: wbByDesign ? 'ok' : 'degraded',
      reason: wbReason,
      // Step-local clock: this event's duration must reflect the 2s-budgeted
      // step, not hookStop's whole run (a wb_deadline reason with a
      // duration exceeding the deadline would mislead triage).
      duration_ms: Date.now() - wbT0,
    });
  }

  // Per-turn durability push [D3/D17/D20] — its own try/deadline so the
  // buffer append above and the heartbeat below are never at risk.
  let pushReason: string | undefined;
  try {
    const ws = io.cwd ?? (typeof j?.cwd === 'string' ? (j.cwd as string) : hookSessionCwd());
    const raced = await withDeadline(STOP_PUSH_DEADLINE_MS, stopPushIfDue(ws, io));
    pushReason = raced === DEADLINE ? 'push_unavailable' : raced;
  } catch {
    pushReason = 'push_unavailable';
  }
  await writeHeartbeat(io, {
    ts: new Date().toISOString(),
    event: 'stop',
    outcome,
    ...((reason ?? pushReason) ? { reason: reason ?? pushReason } : {}),
    duration_ms: Date.now() - t0,
  });
  return 0;
}

function gcOldFiles(dir: string, maxAgeMs: number): void {
  try {
    const cutoff = Date.now() - maxAgeMs;
    for (const name of readdirSync(dir)) {
      if (!name.endsWith('.txt')) continue;
      const p = join(dir, name);
      try {
        if (statSync(p).mtimeMs < cutoff) rmSync(p, { force: true });
      } catch {
        /* per-file best effort */
      }
    }
  } catch {
    /* GC never breaks the hook */
  }
}

// ── session-end [S3#2, G3, G15] ─────────────────────────────────────────────

async function corpusDir(cfg: GBrainConfig | null): Promise<string> {
  const configured = cfg?.dream?.synthesize?.session_corpus_dir;
  if (configured && isAbsolute(configured)) return ensureDir0700(configured);
  const home = await resolveHome();
  ensureDir0700(join(home, 'transcripts'));
  return ensureDir0700(join(home, 'transcripts', 'corpus'));
}

/** #6268: the session's spool dir and frozen source stamp (`source` unset while unresolved). */
const sessionCorpus = async (io: HookIo, cfg: GBrainConfig | null, sessionId: string, cwd: string) =>
  openSessionCorpus(await corpusDir(cfg), sessionId, { cwd, harness: io.harness ?? 'claude-code' });

/** #5941: the context arms' source (session-start-pack.ts `contextSourceId`): the session's frozen record when there is a session id. */
const contextSource = (io: HookIo, cfg: GBrainConfig | null, rawSessionId: unknown, cwd: string) => {
  const sid = sanitizeSessionId(rawSessionId);
  return contextSourceId(sid !== 'unknown' ? () => sessionCorpus(io, cfg, sid, cwd) : null, cwd);
};

function corpusRetentionDays(cfg: GBrainConfig | null): number {
  // Key is plan-defined [G15] but not yet in the GBrainConfig type (config.ts
  // is another lane's file) — read tolerantly.
  const synth = cfg?.dream?.synthesize as Record<string, unknown> | undefined;
  const v = synth?.corpus_retention_days;
  return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : CORPUS_RETENTION_DAYS_DEFAULT;
}

/** #4618: record the session's seat sidecar; returns heartbeat reason codes. Never throws. */
/** #8016: drop a parser_drift status file this lane (or a pre-#8016 record naming none) wrote; best effort. */
async function clearDriftStatus(harness: string): Promise<void> {
  try {
    const p = await hookStatusPath();
    const s = JSON.parse(readFileSync(p, 'utf8')) as { error?: string; harness?: string };
    if (s.error === 'parser_drift' && (s.harness === undefined || s.harness === harness)) rmSync(p, { force: true });
  } catch { /* absent or unreadable: nothing to clear */ }
}

/** #8064: whether this session may be banked; an agent speaker is recorded first, and a failed record banks nothing (#8080 notes ride `reasons`). */
function hookSpeaker(io: HookIo, dir: string, sessionId: string) {
  return hookSpeakerDecision(dir, sessionId, { env: io.env ?? process.env, ...(io.processAncestry ? { ancestry: io.processAncestry } : {}) }, io.harness ?? 'claude-code');
}

function captureSeat(io: HookIo, dir: string, sessionId: string, transcriptPath: string | undefined): string[] {
  const harness = io.harness ?? 'claude-code';
  try {
    const seat = resolveSeat({ env: process.env, harness, transcriptPath });
    return seat ? writeSeatSidecar(dir, sessionId, seat, { harness, hookLane: hookLaneLabel(process.env.GBRAIN_HOOK_LANE) }) : [];
  } catch {
    return ['seat_write_failed'];
  }
}

async function hookSessionEnd(io: HookIo): Promise<number> {
  const t0 = Date.now();
  let outcome: HookHeartbeatEntry['outcome'] = 'ok';
  let reason: string | undefined;
  let turnsN: number | undefined;
  let bytesN: number | undefined;
  let redactionsN: number | undefined;
  const degrade = (r: string) => {
    if (outcome === 'ok') {
      outcome = 'degraded';
      reason = r;
    }
  };

  let sessionId = 'unknown';
  let ws: string | undefined;
  let segmentMode: string | undefined;
  // Apply-LAST reasons: entries here describe something other than THIS
  // session's own capture health — prior-run relay failures (memorable_relay_*)
  // and a discovery-fallback note — so under first-degrade-wins they must not
  // mask a current-session reason (e.g. push_unavailable, scan_unavailable).
  // Held here and applied just before the heartbeat write.
  const deferredReasons: string[] = [];
  try {
    const j = await readStdinJson(io, 500);
    sessionId = sanitizeSessionId(j?.session_id);
    ws = io.cwd ?? (typeof j?.cwd === 'string' ? (j.cwd as string) : hookSessionCwd());
    const cfg = loadConfig();
    // ONE gate for the whole Memorable integration (memorableGateAllowed —
    // shared with the openclaw lane and doctor). Answered BEFORE the parse so
    // the default gate-off population never pays tool-call collection.
    const memorableAllowed = (await memorableGateAllowed(cfg)).allowed;

    // Per-harness capture seam: claude-code and codex each pin their OWN
    // confinement root + parser; unknown harnesses resolve to the claude spec
    // (today's behavior, pinned by the capture-spec golden test).
    const spec = captureSpecFor(io.harness);
    const rootOpt = io.transcriptRoot ? { root: io.transcriptRoot } : {};
    // #5701: every spec parser reads a bounded window (claude tail, codex head+tail).
    let conf = spec.confine(j?.transcript_path, { ...rootOpt, allowOversize: true });
    // A newest-mtime discovery with NO session-id match is a guess: on a
    // machine with concurrent sessions it can be a different, still-RUNNING
    // rollout. Fine for the local corpus (overwritten on the real session
    // end), never for the relay — a receipt would describe a session that
    // has not ended, and its partial hash would double-pay extraction later.
    let discoveryWasGuess = false;
    if (!conf.ok && conf.reason === 'missing_path' && spec.discover) {
      // A codex SessionEnd payload can carry transcript_path:null (no local
      // rollout); the bounded newest-first discovery keeps the lane useful —
      // LOUDLY (typed deferred reason, never a silent guess).
      const found = spec.discover(sessionId === 'unknown' ? null : sessionId, { ...rootOpt });
      if (found) {
        deferredReasons.push(found.degrade);
        discoveryWasGuess = found.degrade === 'transcript_discovered_newest';
        conf = spec.confine(found.path, { ...rootOpt });
      }
    }
    if (!conf.ok) {
      degrade(`transcript_${conf.reason}`);
    } else if (conf.absent) {
      degrade('transcript_unreadable');
    } else if (
      isClaudeCliSelfTranscriptPath(conf.path) ||
      (ws !== undefined && isClaudeCliSelfTranscriptPath(ws))
    ) {
      // #5413: this session is gbrain's OWN claude-cli subprocess (the
      // scratch cwd fingerprint appears in the transcript path or the
      // payload cwd). Writing it to the dream corpus is a self-ingestion
      // feedback loop — extraction prompts and page content re-enter as
      // "conversations", and synthesize mints duplicate idea pages.
      segmentMode = 'self_transcript';
    } else {
      const parsed = spec.parse(conf.path, { collectToolCalls: memorableAllowed });
      if (sessionId === 'unknown') {
        // Stdin payload carried no session_id (observed on codex): adopt the
        // transcript's own id so successive such sessions don't collapse onto
        // one shared unknown.txt corpus (overwriting each other's dedup key).
        const inline = (parsed as { sessionId?: string | null }).sessionId;
        if (typeof inline === 'string' && inline) sessionId = sanitizeSessionId(inline);
      }
      turnsN = parsed.turns.length;
      bytesN = parsed.bytesRead;
      if (bytesN > 0 && turnsN === 0 && parsed.recognizedOnly) {
        reason = 'empty_session'; // opened and closed with no prompt: nothing to bank, not drift
      } else if (bytesN > 0 && turnsN === 0) {
        // [G3] LOUD: the host format drifted under us — heartbeat error +
        // status file surfaced at the next session-start.
        outcome = 'error';
        reason = 'parser_drift';
        try {
          const p = await hookStatusPath();
          writeFileSync(
            p,
            JSON.stringify({ ts: new Date().toISOString(), error: 'parser_drift', bytes: bytesN, harness: io.harness ?? 'claude-code' }, null, 2) + '\n',
            { mode: 0o600 },
          );
        } catch {
          /* status telemetry best-effort */
        }
      } else if (turnsN > 0) {
        // E-N4: assistant turns with not one user turn is how #5163 (a host
        // renamed its user-turn record) banked half-sessions silently. The
        // corpus is still written; the heartbeat says the human side is gone.
        // Whole-file reads only: a bounded tail of a long agentic run can
        // legitimately hold assistant turns alone.
        if (parsed.genuineUserTurnIndexes.length === 0 && bytesN >= conf.size) degrade('no_user_turns');
        const { root, dir, stamp, source } = await sessionCorpus(io, cfg, sessionId, ws ?? hookSessionCwd());
        const speaker = hookSpeaker(io, dir, sessionId);
        if (speaker.bank !== true) {
          segmentMode = speaker.reason;
          if (speaker.bank === 'failed') degrade(speaker.reason);
        }
        deferredReasons.push(...speaker.reasons);
        // #4618: the seat is recorded BEFORE any corpus file of this session
        // is renamed into place, so a sweep never sees one without its seat.
        if (speaker.bank === true) deferredReasons.push(...captureSeat(io, dir, sessionId, conf.path));
        // Cathedral 5 dedup contract: when EVERY non-empty boundary window's
        // redacted hash is banked in the segment ledger (exact-set), write
        // only the post-last-boundary REMAINDER; any mismatch ⇒ full
        // transcript exactly as before (at-least-once).
        const decided = await decideCorpusMode(dir, sessionId, parsed.turns, parsed.boundaryTurnIndexes);
        const corpusTurns = decided.turns;
        if (decided.mode !== 'full' && speaker.bank === true) segmentMode = decided.mode;
        if (segmentMode !== 'skip_covered' && speaker.bank === true) {
          // (skip_covered: everything already segment-banked; nothing new to
          // write — existing corpus file + sidecars stay untouched.)
          //
          // [S3#2] Secret-scan AT WRITE TIME. Scanner absent → still write
          // (the corpus is 0700-local), but say so in the heartbeat.
          let text = toCorpusText(corpusTurns);
          let toolCallsJson = '[]';
          try {
            const scan = await import('../core/secret-scan.ts');
            // The relay child derives its egress task line from this corpus, so
            // the moment the integration is on, the corpus scan runs with the
            // same highEntropy posture as the tool-calls JSON below — the
            // local-only default keeps the cheaper vendor-prefix-only scan.
            const redacted = scan.redactFindings(text, memorableAllowed ? { highEntropy: true } : {});
            text = redacted.text;
            // COUNT only — the findings themselves never land in telemetry [S3#7].
            redactionsN = redacted.redactions.length;
            if (memorableAllowed) {
              // Same span as the corpus, highEntropy always on — see the
              // shared helper's doc for why.
              toolCallsJson = await redactedToolCallsJson(parsed.toolCalls, parsed.toolCallTurnIndexes, decided.startTurnIndex);
            }
          } catch {
            degrade('scan_unavailable');
          }
          // Session-id-keyed filename: a resumed session OVERWRITES its own
          // corpus file — dedup by construction [A6]. The write is ATOMIC
          // (tmp+rename) so a concurrent sweep never reads a torn half-write,
          // and the stale `.ingested`/`.in-progress` sidecars are dropped AFTER
          // the rename so the sweep re-processes the appended transcript (a
          // resumed session's new turns were being permanently skipped when the
          // completion sidecar survived the overwrite).
          const corpusFile = join(dir, sessionCorpusFileName(sessionId, stamp));
          const tmpCorpus = `${corpusFile}.tmp-${process.pid}`;
          recordCaptureIfOff(cfg, corpusFile, text, source); // #6091, before the rename
          writeFileSync(tmpCorpus, text, { mode: 0o600 });
          renameSync(tmpCorpus, corpusFile);
          await clearDriftStatus(io.harness ?? 'claude-code'); // #8016: a lane that saves turns again is not drifting
          // Additive signal for a local third-party consumer (never gbrain
          // itself): the corpus file above is done, hashed post-redaction so
          // the hash can never fingerprint pre-scrub content. Receipt + relay
          // live in hook-heartbeat.ts's recordAndRelayReceipt (shared with the
          // openclaw context-engine lane): dedup by content hash, prior-run
          // outcome surfacing, detached fire-and-forget spawn.
          if (memorableAllowed && discoveryWasGuess) {
            deferredReasons.push('memorable_relay_skipped_newest_guess');
          } else if (memorableAllowed && redactionsN === undefined) {
            // Scanner unavailable → the corpus above is UNREDACTED. The local
            // 0600 write is fine, but nothing unscanned may reach the relay
            // child (its egress task line derives from this corpus). Fail
            // CLOSED — same posture as the openclaw context-engine lane —
            // instead of delegating the refusal to the closed-source child.
            deferredReasons.push('memorable_relay_skipped_unscanned');
          } else if (memorableAllowed) {
            const relay = await recordAndRelayReceipt({
              session_id: sessionId,
              harness: io.harness ?? 'claude-code',
              corpus_path: corpusFile,
              content_hash: segmentHash(text),
              turn_count: turnsN,
              workspace_root: ws ?? hookSessionCwd(),
              tool_calls_json: toolCallsJson,
              secret_scan_ok: true, // scanner ran — the unscanned case took the branch above
            }, { trimRelayFile: true }); // both capture lanes trim memorable-relay.jsonl (converging newest-keeping trims)
            for (const r of relay.degradeReasons) {
              if (r.startsWith('memorable_relay_')) deferredReasons.push(r);
              else degrade(r);
            }
          }
          try {
            rmSync(corpusFile + CORPUS_INGESTED_SUFFIX, { force: true });
          } catch {
            /* best effort — sidecar invalidation never fails the hook */
          }
          try {
            rmSync(corpusFile + CORPUS_CLAIM_SUFFIX, { force: true });
          } catch {
            /* best effort */
          }
        }
        const retentionMs = corpusRetentionDays(cfg) * 24 * 60 * 60 * 1000;
        for (const gcDir of [dir, root]) { // the spool and the legacy top level
          gcCorpusTurnFiles(gcDir, retentionMs); // [G15]; un-ingested turns kept longer (E-N1)
          gcCorpusArtifacts(gcDir, retentionMs, [CORPUS_INGESTED_SUFFIX, CORPUS_CLAIM_SUFFIX, CORPUS_PROGRESS_SUFFIX, CORPUS_PROGRESS_LOCK_SUFFIX, HARVEST_RECEIPT_SUFFIX, CORPUS_FAILURE_SUFFIX], [dir, root]); // #6611
        }
      }
    }
  } catch (e) {
    outcome = 'error';
    reason = errorCode(e);
  }

  // Best-effort workspace push (the no-daemon persistence backstop, plan D6)
  // — same initialized-manifest gate as session-start [G4]. Spawned DETACHED,
  // never inline: the hook must exit far inside the harness's 60s cap
  // regardless of repo/network state. Fires on clean trees too (a prior
  // failure may have left local ahead; workspacePush handles that + its own
  // in-flight lock in the child).
  try {
    if (ws) {
      const root = await resolveBootstrapWorkspaceRoot(ws);
      if (root && isManagedFilesystemPath(root)) {
        if (outcome === 'ok' && !reason) reason = 'push_managed_coordinator';
      } else if (root && (await repoPhaseComplete(root))) {
        try {
          (io.spawnPush ?? spawnDetachedPush)(root);
          if (outcome === 'ok' && !reason) reason = 'push_spawned';
        } catch {
          degrade('push_unavailable');
        }
      } else if (root && outcome === 'ok' && !reason) {
        // Repo phase not finished (create-repo-first, before `bootstrap repo`):
        // defer the push so we never publish to an unverified-privacy origin.
        reason = 'push_deferred_repo_pending';
      }
    }
  } catch {
    /* best effort */
  }

  // Monthly backup-coverage recompute — detached, 24h-debounced via the nag
  // state file (no sidecar). Covers hooks-without-serve installs; a serve
  // holding the PGLite lock makes the child a benign no-op (exit 0, no cache
  // write) and the serve refresher owns that install instead.
  try {
    if (!backupCheckDisabled() && backupSpawnDue() && isBackupStatusStale(loadBackupStatus())) {
      // Recorded BEFORE the spawn (the stop-push precedent) so repeated
      // fail-fast children stay debounced.
      recordBackupSpawn();
      (io.spawnBackupCheck ?? spawnDetachedBackupCheck)();
    }
  } catch {
    /* best effort */
  }

  // GC this session's stop buffer [G15].
  try {
    const dir = await liveBufferDir();
    rmSync(join(dir, `${sessionId}.txt`), { force: true });
  } catch {
    /* best effort */
  }

  // Deferred reasons apply LAST — visible when nothing about THIS session
  // degraded, never masking a current-session reason.
  for (const r of deferredReasons) degrade(r);
  const hint = seatReasonHint(reason);

  await writeHeartbeat(io, {
    ts: new Date().toISOString(),
    event: 'session-end',
    outcome,
    ...(reason ? { reason } : {}),
    ...(hint ? { hint } : {}),
    duration_ms: Date.now() - t0,
    ...(turnsN !== undefined ? { turns: turnsN } : {}),
    ...(bytesN !== undefined ? { bytes: bytesN } : {}),
    ...(redactionsN !== undefined ? { redactions: redactionsN } : {}),
    ...(segmentMode ? { segment: segmentMode } : {}),
  });
  return 0;
}