Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
64.0 KB
Raw Blame
/**
 * `gbrain bootstrap verify` — the whole-install contract check
 * (agent-bootstrap plan: D8 + G1, G6, G13, CX2-5, CX-P0.5, ENG-tests, B2,
 * D3.6/A4 first-run tour).
 *
 * Every check is FAIL-SOFT and COLLECTED: a thrown probe becomes a failed
 * check with the error in `detail`, never an unhandled exception — the
 * runbook pastes the whole report to the human.
 *
 * Determinism [CX2-5]: verify never talks to a host's live serve. The caller
 * (the bootstrap dispatcher, or a test) holds the engine, so the graph-floor
 * seam is: write via the REAL put_page op handler (ctx.remote:false) →
 * `runMaintenanceSweep` directly (the `gbrain sweep --once` equivalent) →
 * edge query via the engine link tables. No timing nondeterminism, works
 * pre-registration AND as the weekly re-run (verify's caller holds the
 * engine either way).
 *
 * Keyless first-class [CX-P0.5]: the magic-moment fact is written through a
 * `## Facts` fence on the probe page and reconciled by the sweep's ZERO-LLM
 * fence pass, then read back at visibility='world' (the visibility the
 * harness can read, S3#1) — the check passes with zero API keys.
 *
 * [G13] Fixed probe slugs; prior leftovers are swept before writing; probe
 * deletion failure is a WARNING, not a verify failure.
 *
 * [B2] Every run persists to `<gbrain home>/bootstrap/verify-<ts>.json`,
 * keeping the last 5 snapshots. `bootstrap status` + doctor read them.
 */

import { managedPersistenceEnabled } from '../persistence/ownership.ts';
import { managedFilesystemRootFor } from '../persistence/filesystem-guard.ts';
import { submitPageMutation } from '../persistence/page-mutations.ts';
import { unpurgePage } from '../persistence/page-purge.ts';
import { withCoordinatedWrite } from '../persistence/context.ts';
import { pendingReceiptOf, pollCommand, resolveCliWriteWaitMs, WRITE_WAIT_ENV } from '../persistence/write-wait.ts';
import { maintenanceAttribution } from '../persistence/attribution.ts';
import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { createHash, randomUUID } from 'node:crypto';
import { execFileSync } from '../spawn.ts';
import { join, relative, resolve } from 'node:path';

import type { BrainEngine } from '../engine.ts';
import { operations, type Operation, type OperationContext } from '../operations.ts';
import { loadConfigFileOnly, type GBrainConfig } from '../config.ts';
import { detectExecutionEnvironment } from '../execution-env.ts';
import { resolveGbrainHome } from '../gbrain-home.ts';
import { realpathOrResolve } from '../path-confine.ts';
import { runMaintenanceSweep } from '../sweep.ts';
import { detectCapabilities, renderCapabilityReport, type CapabilityReport } from '../capability.ts';
import { loadWorkspaceAllowlist, matchesGlob, SCAN_ALLOW_FILENAME, scanFiles, type SecretFinding } from '../secret-scan.ts';
import { scanAllowProblems } from '../git/range-secret-scan.ts';
import {
  PUSH_DENY_GLOBS, SECRET_SCAN_REFUSAL_DOCS, verifyRemotePrivacy, readPushStatuses, summarizePushStatuses,
} from '../workspace-push.ts';
import { shellQuote } from '../mcp-registration.ts';
import { OWNERSHIP_MARKER_GLOBS } from '../persistence/root-metadata.ts';
import { FACTS_DEFAULT_VISIBILITY_KEY } from '../facts/visibility.ts';
import { byteFloors } from './render.ts';
import { CLAUDE_HOOK_EVENTS, claudeUserSettingsPath } from './host-specs.ts';
import { groupsCarryGbrainHook } from './hooks.ts';
import { BOOTSTRAP_TEMPLATES, loadQuestionBank } from './assets.ts';
import { readManifest, writeManifest } from './format.ts';
import { status as interviewStatus } from './interview.ts';
import { gitOriginUrl, hooksInstalled } from './status.ts';
import { resolveSourceId } from '../source-resolver.ts';
import { auditWritebackContract } from './contract.ts';
import {
  ensureIpcSecret,
  resolveSocketPath,
  socketHasLiveListener,
  startResolveIpcServer,
} from '../context/resolve-ipc.ts';
import { assembleTurnContext } from '../context/turn-context.ts';
import { gitChildEnv } from '../git-env.ts';

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

export interface VerifyCheck {
  id: string;
  ok: boolean;
  /** Set when a non-ok state is advisory (does not fail the run). */
  warn?: boolean;
  detail: string;
}

export interface VerifyReport {
  ok: boolean;
  checks: VerifyCheck[];
  /** Human-readable report, capability block + first-run tour included. */
  report: string;
  capability: CapabilityReport;
  /** The three scripted first-run prompts [D3.6/A4]. */
  tour: string[];
  /** The OOBE hand-off lines (ownership + the cold-start next action) —
   *  unconditional in the shape like `tour`; printed in the report on PASS. */
  handoff: string[];
}

export interface VerifyOpts {
  /** Source the workspace brain/ dir registered as. Default 'workspace'. */
  sourceId?: string;
  /** Gbrain home for snapshot persistence. Default resolveGbrainHome(). */
  gbrainHomeDir?: string;
  /** Capability report override (test seam — mirrors SweepOpts). */
  capabilities?: CapabilityReport;
  /** Sweep wall-clock budget. Default 20s (fence + links passes are cheap). */
  sweepBudgetMs?: number;
  /** Skip the hooks IPC smoke (tests that don't stage a settings file). */
  skipHooksSmoke?: boolean;
  log?: (line: string) => void;
}

/** Fixed probe slugs [G13]. */
export const VERIFY_PROBE_SLUG = 'wiki/bootstrap-verify-probe';
export const VERIFY_PROBE_ENTITY_SLUG = 'wiki/bootstrap-verify-probe-entity';
/** Deterministic magic-moment token the fence fact carries [CX-P0.5]. */
export const VERIFY_MAGIC_TOKEN = 'verify-lighthouse-passphrase';

/** The three scripted first-run prompts [D3.6] — pinned by the A4 snapshot test.
 *  Exactly three (the count is copy-pinned here, in BOOTSTRAP_FOR_AGENTS.md,
 *  and the A4 plan). Prompt 3 must be TRUE on day one — the brain is empty at
 *  install, so "everything ingested so far" would be an anticlimax; the
 *  round-trip fact from prompt 2 is the honest day-one payoff. */
export const FIRST_RUN_TOUR: readonly string[] = [
  '"Who am I to you?" — identity from SOUL.md/USER.md, no lookup needed.',
  '"Remember that <one small true fact>." — it lands in the brain, not this chat.',
  '"What do you remember about me?" — asked in the NEW session: on day one that is the fact from prompt 2, recalled from the brain. Every session after this adds more. That round-trip is the whole product.',
];

// ---------------------------------------------------------------------------
// Op plumbing (trusted local ctx)
// ---------------------------------------------------------------------------

function findOp(name: string): Operation {
  const op = operations.find((o) => o.name === name);
  if (!op) throw new Error(`operation not found: ${name}`);
  return op;
}

export function localCtx(engine: BrainEngine, sourceId: string, log?: (l: string) => void): OperationContext {
  const sink = log ?? (() => {});
  const config = (loadConfigFileOnly() ?? { engine: 'pglite' }) as GBrainConfig;
  return {
    engine,
    config,
    logger: { info: sink, warn: sink, error: sink },
    dryRun: false,
    remote: false,
    sourceId,
    writeWaitMs: resolveCliWriteWaitMs({ config }),
  };
}

/** The roundtrip detail for a failed probe write: an admitted, still-pending write names its request and the next step. */
export function putPageFailureDetail(error: unknown, waitMs: number | undefined): string {
  const receipt = pendingReceiptOf(error);
  if (!receipt) return `put_page failed: ${(error as Error).message}`;
  return `put_page was admitted but is still pending after ${Math.round((waitMs ?? 0) / 1000)}s (request ${receipt.request_id}); `
    + `check it with \`${pollCommand(receipt.request_id)}\`, or raise ${WRITE_WAIT_ENV} and rerun gbrain bootstrap verify`;
}

// ---------------------------------------------------------------------------
// Probe content
// ---------------------------------------------------------------------------

const PROBE_ENTITY_CONTENT = `---
title: Bootstrap Verify Probe Entity
type: concept
---

# Bootstrap Verify Probe Entity

Anchor page for the \`gbrain bootstrap verify\` graph-floor probe. Written and
deleted by verify; not user content.
`;

const PROBE_CONTENT = `---
title: Bootstrap Verify Probe
type: concept
---

# Bootstrap Verify Probe

Written and deleted by \`gbrain bootstrap verify\` (fixed slug, swept on every
run). It links to [[${VERIFY_PROBE_ENTITY_SLUG}]] so the graph floor has a
deterministic edge to extract.

## Facts

<!--- gbrain:facts:begin -->
| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |
|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|
| 1 | The bootstrap verify magic-moment token is ${VERIFY_MAGIC_TOKEN} | fact | 1.0 | world | low | | | bootstrap-verify | |
<!--- gbrain:facts:end -->
`;

/** Remove any prior probe state [G13]: page rows (hard — verify is a trusted
 * local caller and the probe is not user content), reconciled probe facts,
 * and write-through files under brain/. Best-effort, never throws. */
async function sweepProbeLeftovers(engine: BrainEngine, ws: string, sourceId: string): Promise<void> {
  await removeProbes(engine, ws, sourceId);
}

/**
 * Hard-delete both probe pages, their files and their fence facts; returns one
 * warning per page that could not be removed. An unmanaged brain uses the
 * engine primitives. A managed brain (#5280) purges each probe through the
 * coordinator (`delete_page --purge`, bound to its revision, which also removes
 * its canonical file) and removes the probe facts in a coordinated transaction.
 * #6634: the probe bodies are constant, so a purge tombstone would refuse the
 * next run's put_page as `purged_content`; each probe's tombstones (page, and
 * the fact/take purges of the same request) are cleared through the host-only
 * unpurge path after its purge, and on every sweep, which also clears leftovers
 * of earlier runs. Probe pages are not user content.
 */
async function removeProbes(engine: BrainEngine, ws: string, sourceId: string): Promise<string[]> {
  const warnings: string[] = [];
  const managed = await managedPersistenceEnabled(engine);
  for (const slug of [VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG]) {
    try {
      if (managed) {
        const snapshot = await engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
        if (snapshot) await submitPageMutation(localCtx(engine, sourceId), { operation: 'delete_page', params: {
          slug, source_id: sourceId, purge: true, expected_revision: snapshot.revision, request_id: randomUUID() } });
      } else {
        await engine.deletePage(slug, { sourceId });
      }
    } catch (e) {
      warnings.push(`${slug}: ${(e as Error).message}`);
    }
    try {
      await unpurgePage(localCtx(engine, sourceId), { slug, source_id: sourceId });
    } catch {
      /* page_purges may not exist on a pre-migration brain — doctor_green names that */
    }
    if (managed) continue;
    try {
      rmSync(join(ws, 'brain', `${slug}.md`), { force: true });
    } catch {
      /* best effort */
    }
  }
  try {
    // Scope the delete to the EXACT probe page(s) this run wrote (via the
    // v51 fence column source_markdown_slug), NEVER a `fact LIKE %token%`
    // substring match — a user fact that merely mentions the token string
    // must survive verify's cleanup [G13].
    const sql = `DELETE FROM facts WHERE source_id = $1 AND source_markdown_slug IN ($2, $3)`;
    const params = [sourceId, VERIFY_PROBE_SLUG, VERIFY_PROBE_ENTITY_SLUG];
    if (managed) {
      const attribution = await maintenanceAttribution(engine);
      await engine.transaction(tx => withCoordinatedWrite(tx, [sourceId], () => tx.executeRaw(sql, params), attribution));
    }
    else await engine.executeRaw(sql, params);
  } catch {
    /* facts table may not exist on a pre-migration brain — doctor_green names that */
  }
  return warnings;
}

// ---------------------------------------------------------------------------
// Individual checks (each returns a VerifyCheck; never throws)
// ---------------------------------------------------------------------------

async function checkDoctorGreen(engine: BrainEngine): Promise<VerifyCheck> {
  const id = 'doctor_green';
  try {
    // The cheapest existing health probe: config round-trip + schema probe.
    // Deliberately NOT a shell-out to `gbrain doctor` (a second engine open
    // would contend for the PGLite lock verify's caller already holds).
    const version = await engine.getConfig('version');
    await engine.executeRaw(`SELECT 1 FROM pages LIMIT 1`, []);
    return { id, ok: true, detail: `engine healthy (schema version ${version ?? 'unrecorded'})` };
  } catch (e) {
    return { id, ok: false, detail: `engine probe failed: ${(e as Error).message}` };
  }
}

const TOKEN_RE = /\{\{([A-Z0-9_]+)\}\}/g;

function checkTokenSweep(ws: string): VerifyCheck {
  const id = 'token_sweep';
  try {
    const manifest = readManifest(ws);
    if (manifest.state === 'template') {
      // Minimal-mode template trees legitimately keep the six required-key
      // markers — the sweep would be a false alarm on a template clone.
      return { id, ok: true, warn: true, detail: 'template clone (initialized:false) — placeholder tokens are expected; render before verifying for real' };
    }
    const offenders: string[] = [];
    for (const dest of BOOTSTRAP_TEMPLATES.flatMap((t) => (t.openclawDest ? [t.dest, t.openclawDest] : [t.dest]))) {
      const p = join(ws, dest);
      if (!existsSync(p)) continue;
      const raw = readFileSync(p, 'utf8');
      const tokens = [...raw.matchAll(TOKEN_RE)].map((m) => m[1]);
      if (tokens.length > 0) offenders.push(`${dest} (${[...new Set(tokens)].join(', ')})`);
    }
    if (offenders.length > 0) {
      return { id, ok: false, detail: `unresolved {{TOKEN}}s in rendered files: ${offenders.join('; ')} — finish the interview and re-run render` };
    }
    return { id, ok: true, detail: 'no unresolved template tokens in rendered identity files' };
  } catch (e) {
    return { id, ok: false, detail: `token sweep failed: ${(e as Error).message}` };
  }
}

function checkByteFloors(ws: string): VerifyCheck {
  const id = 'byte_floors';
  try {
    const bank = loadQuestionBank();
    const st = interviewStatus(ws);
    const answeredCount = st.ok ? st.answered.filter((k) => bank.interviewKeys.includes(k)).length : 0;
    const floors = byteFloors(answeredCount);
    const problems: string[] = [];
    for (const [file, floor] of Object.entries(floors)) {
      const p = join(ws, file);
      if (!existsSync(p)) {
        problems.push(`${file} missing`);
        continue;
      }
      const size = statSync(p).size;
      if (size < floor) problems.push(`${file} is ${size}B < floor ${floor}B (@${answeredCount} answered)`);
    }
    if (problems.length > 0) {
      return { id, ok: false, detail: `byte floors: ${problems.join('; ')} — floors catch skipped interviews, never pad; re-run the interview + render` };
    }
    return { id, ok: true, detail: `SOUL.md/USER.md above floors for ${answeredCount} answered question(s)` };
  } catch (e) {
    return { id, ok: false, detail: `byte-floor check failed: ${(e as Error).message}` };
  }
}

/** A healthy retrieval surface without a same-turn write-back contract is a
 * one-way memory: useful now, stale later. Fresh bootstrap renders this gate;
 * the check catches pre-bootstrap/custom workspaces and points at the
 * additive repair command rather than overwriting their AGENTS.md. */
export function checkWritebackContract(ws: string): VerifyCheck {
  const audit = auditWritebackContract(ws);
  return audit.ok
    ? { id: 'writeback_contract', ok: true, detail: audit.detail }
    : {
        id: 'writeback_contract',
        ok: false,
        detail: `${audit.detail}. Fix: run \`gbrain bootstrap contract --repair\` from the workspace (or pass --workspace explicitly).`,
      };
}

/** Tracked files via git; falls back to the rendered file set + state/ when
 * the workspace is not (yet) a git repo. */
function trackedWorkspaceFiles(ws: string): { files: string[]; via: 'git' | 'fallback' } {
  try {
    const out = execFileSync('git', ['-C', ws, 'ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
      env: gitChildEnv(),
      stdio: ['ignore', 'pipe', 'ignore'],
      timeout: 15_000,
      maxBuffer: 16 * 1024 * 1024,
    }).toString();
    const rel = out.split('\0').filter((s) => s.length > 0);
    if (rel.length > 0) return { files: rel, via: 'git' };
  } catch {
    /* not a repo — fallback below */
  }
  const files: string[] = [];
  for (const dest of BOOTSTRAP_TEMPLATES.flatMap((t) => (t.openclawDest ? [t.dest, t.openclawDest] : [t.dest]))) {
    if (existsSync(join(ws, dest))) files.push(dest);
  }
  if (existsSync(join(ws, 'state', 'interview.json'))) files.push(join('state', 'interview.json'));
  return { files, via: 'fallback' };
}

function checkSecretScan(ws: string): VerifyCheck {
  const id = 'secret_scan';
  try {
    const { files, via } = trackedWorkspaceFiles(ws);
    const allowlist = loadWorkspaceAllowlist(ws);
    const allowed: string[] = [];
    const findings: SecretFinding[] = scanFiles(files.map((f) => join(ws, f)), {
      allowlist,
      workspaceRoot: ws,
      onAllowed: (hit) => allowed.push(`${relative(ws, hit.file)}:${hit.line} [${hit.pattern}] by ${hit.entry}`),
    });
    const allowedNote = allowed.length ? `; ${allowed.length} hit(s) allowed by ${SCAN_ALLOW_FILENAME} rule lines: ${allowed.slice(0, 5).join('; ')}${allowed.length > 5 ? '; …' : ''}` : '';
    if (findings.length > 0) {
      const sample = findings.slice(0, 5).map((f) => {
        const { since } = f as SecretFinding & { since?: string };
        return `${f.file}:${f.line} [${f.pattern}${since ? ` since gbrain v${since.replace(/^v/, '')}` : ''}] ${f.fingerprint}`;
      }).join('; ');
      return {
        id, ok: false,
        detail: `${findings.length} secret-scan finding(s): ${sample}${findings.length > 5 ? '; …' : ''} — ` +
          'remove a real credential first; allowlist only a reviewed false positive by appending its fingerprint to ' +
          `${shellQuote(resolve(ws, SCAN_ALLOW_FILENAME))} (${SECRET_SCAN_REFUSAL_DOCS})` +
          scanAllowProblems(allowlist).map((p) => `; ${SCAN_ALLOW_FILENAME} line ${p.entry}: ${p.problem}`).join(''),
      };
    }
    return { id, ok: true, detail: `no secrets in ${files.length} ${via === 'git' ? 'tracked' : 'workspace'} file(s)${allowedNote}` };
  } catch (e) {
    return { id, ok: false, detail: `secret scan failed: ${(e as Error).message}` };
  }
}

const OWNERSHIP_DENY_GLOBS: readonly string[] = [...OWNERSHIP_MARKER_GLOBS, '.gbrain-bootstrap.lock/**'];

export function checkDenyGlobs(ws: string): VerifyCheck {
  const id = 'deny_globs';
  try {
    const { files, via } = trackedWorkspaceFiles(ws);
    const matches = files.filter((f) => PUSH_DENY_GLOBS.some((g) => matchesGlob(g, f)));
    if (via === 'git' && matches.length > 0) {
      // #5186: an ownership marker or bootstrap lock that is merely on disk (a root
      // stamped before the exclude rule, a concurrent run's lock) is not a finding:
      // `sources push` excludes it. One in the INDEX is, with `git rm --cached` as the fix.
      const indexed = new Set(execFileSync('git', ['-C', ws, 'ls-files', '--cached', '-z'], {
        stdio: ['ignore', 'pipe', 'ignore'], timeout: 15_000, maxBuffer: 16 * 1024 * 1024, env: gitChildEnv(),
      }).toString().split('\0').filter((f) => f.length > 0));
      const findings = matches.filter((f) => indexed.has(f) || !OWNERSHIP_DENY_GLOBS.some((g) => matchesGlob(g, f)));
      if (findings.length > 0) {
        return { id, ok: false, detail: `deny-glob matches among candidate files: ${findings.slice(0, 10).join(', ')} — remove from the index (git rm --cached) before any push` };
      }
      return { id, ok: true, detail: `no tracked files match the push deny list; ${matches.length} untracked ownership marker/lock file(s) stay out of every push (${matches.slice(0, 5).join(', ')})` };
    }
    return { id, ok: true, detail: via === 'git' ? 'no tracked files match the push deny list' : 'not a git repo yet — deny-glob backstop applies at push time' };
  } catch (e) {
    return { id, ok: false, detail: `deny-glob check failed: ${(e as Error).message}` };
  }
}

/** Self-repair channel for existing installs [B8]: a git-TRACKED .mcp.json
 * carries an absolute machine-specific binary path into the private repo.
 * Fresh renders gitignore it; this warn heals pre-fix installs. Never gates. */
function checkMcpJsonHygiene(ws: string): VerifyCheck {
  const id = 'mcp_json_hygiene';
  try {
    if (!existsSync(join(ws, '.mcp.json'))) return { id, ok: true, detail: 'no .mcp.json in the workspace' };
    try {
      execFileSync('git', ['-C', ws, 'ls-files', '--error-unmatch', '.mcp.json'], {
        env: gitChildEnv(),
        stdio: 'ignore', timeout: 5_000,
      });
    } catch {
      return { id, ok: true, detail: '.mcp.json present but untracked (gitignored) — correct' };
    }
    return {
      id,
      ok: true, // warn-only: informational, never gating
      detail:
        'WARN: machine-specific .mcp.json is COMMITTED to the repo — run `git rm --cached .mcp.json` ' +
        '(bootstrap now gitignores it; it regenerates via `claude mcp add` / `bootstrap hooks --repair`)',
    };
  } catch (e) {
    return { id, ok: true, detail: `mcp.json hygiene probe failed (${(e as Error).message})` };
  }
}

/** [D12 upgrade-path guard, #4585]: an event carried by MORE THAN ONE hook
 * carrier double-fires every turn — Claude Code merges hook scopes, so the
 * carriers compared are ALL the files that can inject a gbrain hook for this
 * workspace: user-scope settings.json (what `bootstrap harness` writes) plus
 * workspace-scope .claude/settings.json and .claude/settings.local.json
 * (what `bootstrap hooks` writes). Same-scope overlap arises when the
 * committed carrier arrives via git pull onto a machine whose local file
 * predates the dedupe-aware writers; cross-scope overlap arises when both
 * installers ran on the same box. Warn-only. Exported for tests
 * (userSettingsPath injectable). */
export function checkHookCarrierOverlap(
  ws: string,
  userSettingsPath = claudeUserSettingsPath(),
): VerifyCheck {
  const id = 'hook_carrier_overlap';
  try {
    const carriers: Array<{ label: string; path: string }> = [
      { label: 'user-scope settings.json', path: userSettingsPath },
      { label: '.claude/settings.json', path: join(ws, '.claude', 'settings.json') },
      { label: '.claude/settings.local.json', path: join(ws, '.claude', 'settings.local.json') },
    ];
    const overlaps: string[] = [];
    for (const event of CLAUDE_HOOK_EVENTS) {
      const hits = carriers.filter(({ path }) => {
        try {
          const parsed = JSON.parse(readFileSync(path, 'utf8')) as { hooks?: Record<string, unknown> };
          const groups = parsed?.hooks?.[event];
          return groupsCarryGbrainHook(groups, event);
        } catch {
          return false;
        }
      });
      if (hits.length >= 2) overlaps.push(`${event} (${hits.map((h) => h.label).join(' + ')})`);
    }
    if (overlaps.length === 0) return { id, ok: true, detail: 'no event fires from more than one hook carrier' };
    return {
      id,
      ok: true, // warn-only self-repair channel
      detail:
        `WARN: double-fire — ${overlaps.join('; ')} carry a gbrain hook in more than one carrier. ` +
        'Workspace-scope duplication: run `gbrain bootstrap hooks --repair`. ' +
        'User-scope + workspace overlap: remove one installer\'s wiring (`gbrain bootstrap harness --remove` or `gbrain bootstrap uninstall`), then re-run the one you keep.',
    };
  } catch (e) {
    return { id, ok: true, detail: `carrier overlap probe failed (${(e as Error).message})` };
  }
}

async function checkRepoPrivacy(ws: string): Promise<VerifyCheck> {
  const id = 'repo_privacy';
  try {
    const origin = gitOriginUrl(ws);
    if (!origin) {
      return { id, ok: true, detail: 'local-only (no origin remote) — run `gbrain bootstrap repo` any time to add the private body' };
    }
    const verdict = await verifyRemotePrivacy(ws);
    if (verdict.verdict === 'private') return { id, ok: true, detail: `origin verified private (${origin})` };
    if (verdict.verdict === 'not_private') return { id, ok: false, detail: `origin is NOT private: ${verdict.detail} — make it private before pushing workspace contents` };
    return { id, ok: false, detail: `origin visibility unverifiable (${verdict.detail}) — refusing to bless an unverified remote [G8]; re-run once gh works` };
  } catch (e) {
    return { id, ok: false, detail: `repo privacy check failed: ${(e as Error).message}` };
  }
}

/** Informational, NEVER gating [D-cloud]: name the detected execution
 * environment and its expected degradations so an installing agent (and the
 * pasted verify report) states them as facts instead of rediscovering them
 * as mystery failures. */
function checkExecutionEnvironment(): VerifyCheck {
  const id = 'execution_env';
  try {
    const env = detectExecutionEnvironment();
    if (env === 'cloud-sandbox') {
      return {
        id,
        ok: true,
        detail:
          'cloud sandbox detected — expected degradations: no crontab (scheduled pull skipped; per-turn/session-end pushes cover it); ' +
          'GitHub GraphQL always blocked and REST scoped to session-attached repos (privacy verification falls back to git protocol); ' +
          'pushes restricted to the session\'s working branch; only repo-committed files carry into the next session',
      };
    }
    if (env === 'ephemeral-container') {
      return {
        id,
        ok: true,
        detail: 'container detected — no reliable scheduler (scheduled pull skipped); event-driven pushes cover persistence',
      };
    }
    return { id, ok: true, detail: 'local machine — full persistence surface available' };
  } catch (e) {
    return { id, ok: true, detail: `environment detection failed (${(e as Error).message}) — treated as local` };
  }
}

/** [CX-P1.1] Single-principal posture: facts written without an explicit
 * visibility must be recallable by the owner's own sessions (the harness
 * reads at visibility='world'). Set-IF-UNSET only, through the engine config
 * plane — an operator's explicit value (e.g. 'private' for a brain exposed to
 * other surfaces) is NEVER overridden. The report line names the posture and
 * where to flip it. */
async function ensureDefaultVisibilityPosture(engine: BrainEngine): Promise<VerifyCheck> {
  const id = 'facts_visibility';
  try {
    const existing = await engine.getConfig(FACTS_DEFAULT_VISIBILITY_KEY);
    if (existing == null || existing.trim() === '') {
      await engine.setConfig(FACTS_DEFAULT_VISIBILITY_KEY, 'world');
      return {
        id,
        ok: true,
        detail:
          `facts default visibility: world (set by bootstrap verify — was unset). ` +
          `Governs extraction-path writes only — \`remember\` defaults to world either way, except from a member-bound credential, whose saves stay private on its member page; pass \`visibility\` per call to keep a remembered fact private. ` +
          `Flip with \`gbrain config set ${FACTS_DEFAULT_VISIBILITY_KEY} private\` if less-trusted surfaces will read this brain.`,
      };
    }
    return {
      id,
      ok: true,
      detail:
        `facts default visibility: ${existing.trim()} (explicit operator value — untouched). ` +
        `Governs extraction-path writes only — \`remember\` defaults to world either way, except from a member-bound credential, whose saves stay private on its member page; pass \`visibility\` per call to keep a remembered fact private. ` +
        `Flip with \`gbrain config set ${FACTS_DEFAULT_VISIBILITY_KEY} <world|private>\`.`,
    };
  } catch (e) {
    return { id, ok: true, warn: true, detail: `could not read/set ${FACTS_DEFAULT_VISIBILITY_KEY}: ${(e as Error).message}` };
  }
}

/**
 * #4287 — ACTIVE embedding-plane probe. A verify that passes its roundtrip
 * keyless-style while the configured embedder and the schema column disagree
 * certifies a brain on which every keyed write fails ("expected N dimensions,
 * not M"). Config numbers can lie about what the runtime emits (the observed
 * split emitted the compiled-in default, a width no config plane named), so
 * in keyed mode this embeds ONE short probe string through the same
 * document-side path put_page uses and compares the RETURNED width to the
 * actual `content_chunks.embedding` column width. Keyless installs pass (no
 * active plane exists — writes store no vectors by design); a transient probe
 * failure WARNs (the roundtrip owns hard put failures); a confirmed width
 * mismatch is a named FAIL with the recovery command.
 */
export async function checkEmbeddingPlane(
  engine: BrainEngine,
  caps: CapabilityReport,
): Promise<VerifyCheck> {
  const id = 'embedding_plane';
  // S2: resolve the registry-ACTIVE write column FIRST — comparing the
  // embedder to the literal legacy `embedding` column false-FAILs a healthy
  // brain whose registry routes writes elsewhere (e.g. a 1024d Voyage
  // column). An unresolvable registry row is itself a genuine FAIL: every
  // chunk write throws the resolver error until the config row is fixed.
  let activeColName: string;
  try {
    const { resolveActiveEmbeddingColumnFromEngine } = await import('../search/embedding-column.ts');
    activeColName = (await resolveActiveEmbeddingColumnFromEngine(engine)).name;
  } catch (e) {
    return {
      id,
      ok: false,
      detail:
        `the configured embedding column cannot be resolved (${(e as Error).message}) — every chunk ` +
        `write fails until the registry row is fixed. Inspect \`gbrain config get search_embedding_column\` ` +
        `and \`gbrain config get embedding_columns\`.`,
    };
  }
  const colLabel = `content_chunks.${activeColName}`;
  let colDims: number | null = null;
  let colExists = false;
  try {
    const { readContentChunksColumnDim } = await import('../embedding-dim-check.ts');
    const col = await readContentChunksColumnDim(engine, activeColName);
    colDims = col.dims;
    colExists = col.exists;
  } catch (e) {
    return { id, ok: true, warn: true, detail: `embedding column width probe failed (${colLabel}): ${(e as Error).message}` };
  }
  if (!caps.embeddings.available) {
    return {
      id,
      ok: true,
      detail: `keyless — no embedding provider configured; writes store no vectors (active column ${colLabel}: ${colExists ? `${colDims ?? '?'}d` : 'absent'})`,
    };
  }
  if (!colExists) {
    return {
      id,
      ok: false,
      detail: `embeddings are configured but the active ${colLabel} column is ABSENT — every embedding write fails. Run \`gbrain migrate embeddings --status\` to diagnose, then \`gbrain migrate embeddings --to <provider:model>\` to (re)build it.`,
    };
  }
  try {
    // Same document-side embed path put_page uses (import-file.ts embedBatch),
    // lazy so keyless verifies never load the gateway.
    const { embedBatch, getEmbeddingModelName } = await import('../embedding.ts');
    const vecs = await embedBatch(['gbrain bootstrap verify embedding-plane probe']);
    const got = vecs[0]?.length ?? 0;
    let model = 'unknown';
    try { model = getEmbeddingModelName(); } catch { /* label only */ }
    if (colDims !== null && got !== colDims) {
      return {
        id,
        ok: false,
        detail:
          `EMBEDDING PLANE SPLIT: the runtime embedder (${model}) returns ${got}d vectors but ` +
          `${colLabel} is ${colDims}d — every embedding write fails ("expected ${colDims} ` +
          `dimensions, not ${got}") and nothing is stored. Fix: gbrain migrate embeddings --to <provider:model> ` +
          `--dim ${got} (or correct embedding_model/embedding_dimensions to match the column).`,
      };
    }
    return {
      id,
      ok: true,
      detail: `active plane verified end-to-end: ${model} emits ${got}d = ${colLabel} ${colDims ?? got}d`,
    };
  } catch (e) {
    // A dead/misconfigured provider surfaces in the roundtrip put; this check
    // only certifies plane AGREEMENT, so degrade to a warning here.
    return { id, ok: true, warn: true, detail: `live embed probe failed (${(e as Error).message}) — cannot verify the active embedding plane end-to-end` };
  }
}

/** Effective MCP-surface posture: bootstrap registrations pin `--surface
 * full`, but a REGISTRATION THAT PREDATES that pin resolves the config key —
 * `mcp_surface: 'verbs'` would silently narrow the bootstrap contract
 * (put_page/get_page/timeline are not memory verbs). Loud WARN naming the fix. */
function checkMcpSurface(): VerifyCheck {
  const id = 'mcp_surface';
  try {
    const surface = loadConfigFileOnly()?.mcp_surface;
    if (surface === 'verbs') {
      return {
        id,
        ok: true,
        warn: true,
        detail:
          `config mcp_surface='verbs' narrows a bare \`gbrain serve\` to the five memory verbs — the bootstrap ` +
          `contract needs the full surface. Fix: re-run \`gbrain bootstrap hooks --repair\` (registrations now pin ` +
          `--surface full) or \`gbrain config set mcp_surface full\`.`,
      };
    }
    return { id, ok: true, detail: `mcp_surface: ${surface ?? 'full (default)'} — full op surface for registrations` };
  } catch (e) {
    return { id, ok: true, warn: true, detail: `mcp_surface config unreadable: ${(e as Error).message}` };
  }
}

/**
 * Pure, engine-free derivation of the collision-fallback source_id for a
 * workspace — a deterministic hash of the workspace's real path, no DB
 * lookup involved. `resolveSourceIdCollision` (below) is the only thing that
 * decides WHETHER this id is actually needed (that half requires the engine,
 * since the sources registry lives only in the DB) — but the id itself is
 * safe to preview from an engine-free phase. `bootstrap hooks` does exactly
 * that, so a human has the fallback id in hand before they ever hand-register
 * a source, instead of discovering it only after an FK error + a corrective
 * `verify` run.
 */
export function deriveWorkspaceSourceId(ws: string): string {
  const hash = createHash('sha256').update(realpathOrResolve(ws)).digest('hex').slice(0, 8);
  return `workspace-${hash}`;
}

/**
 * Resolve the source id a verify run should exercise (#4328). An initialized
 * manifest is authoritative (that's the id hooks/attach/status all follow).
 * An UNINITIALIZED workspace has no manifest to consult — the old hardcoded
 * 'workspace' fallback pointed the probe writes at a source no one ever
 * registered, so put_page died on its sources FK. Instead, run the standard
 * source-resolution chain rooted at the workspace (registered local_path →
 * brain default → seeded 'default'), which always lands on a real source.
 * Any resolver surprise degrades to 'default' (seeded by migration) rather
 * than failing verify before it can print a report.
 */
export async function resolveVerifySourceId(engine: BrainEngine, ws: string): Promise<string> {
  const state = readManifest(ws);
  if (state.state === 'initialized') return state.manifest.source_id;
  try {
    return await resolveSourceId(engine, null, ws);
  } catch {
    return 'default';
  }
}

/**
 * source_id collision resolution [engine seam]. Render is ENGINE-FREE and the
 * sources registry lives ONLY in the DB (no registry file exists), so verify —
 * the one bootstrap subcommand holding an engine — is where a manifest
 * source_id already registered to a DIFFERENT checkout is detected. On
 * collision it derives a stable `workspace-<8char-path-hash>` id (via
 * `deriveWorkspaceSourceId`), persists it to agent.json (render preserves it
 * on re-render), and names the re-register steps; every consumer (hooks
 * GBRAIN_SOURCE env, verify, status hints, attach, repo persistence) reads
 * manifest.source_id, so the derived id propagates. Returns a sourceId ONLY
 * when it derived one.
 */
async function resolveSourceIdCollision(
  engine: BrainEngine,
  ws: string,
): Promise<{ sourceId: string | null; check: VerifyCheck | null }> {
  const state = readManifest(ws);
  if (state.state !== 'initialized') return { sourceId: null, check: null };
  const current = state.manifest.source_id;
  const brainDir = join(ws, 'brain');
  try {
    const rows = await engine.executeRaw<{ local_path: string | null }>(
      `SELECT local_path FROM sources WHERE id = $1`,
      [current],
    );
    const registered = rows[0]?.local_path ?? null;
    if (rows.length === 0 || registered === null) return { sourceId: null, check: null };
    if (realpathOrResolve(registered) === realpathOrResolve(brainDir)) {
      return { sourceId: null, check: null }; // same checkout — no collision
    }
    const derived = deriveWorkspaceSourceId(ws);
    writeManifest(ws, { ...state.manifest, source_id: derived });
    return {
      sourceId: derived,
      check: {
        id: 'source_id',
        ok: true,
        warn: true,
        detail:
          `source '${current}' is already registered to a different checkout (${registered}) — derived ` +
          `'${derived}' and persisted it to agent.json. Register it (gbrain sources add ${derived} --path ${brainDir}) ` +
          `and re-run \`gbrain bootstrap hooks --repair\` so GBRAIN_SOURCE follows.`,
      },
    };
  } catch (e) {
    return {
      sourceId: null,
      check: { id: 'source_id', ok: true, warn: true, detail: `source-id collision probe failed: ${(e as Error).message}` },
    };
  }
}

interface RoundtripOutcome {
  checks: VerifyCheck[];
}

/** The G1/CX2-5 core: put_page (real op, remote:false) → committed file under
 * brain/ → sweep → graph floor via link tables → get_page → search → magic
 * moment (keyless fence fact) → delete probes. */
async function runRoundtrip(
  engine: BrainEngine,
  ws: string,
  sourceId: string,
  opts: VerifyOpts,
): Promise<RoundtripOutcome> {
  const checks: VerifyCheck[] = [];
  const ctx = localCtx(engine, sourceId, opts.log);
  const putPage = findOp('put_page');
  const getPage = findOp('get_page');
  const queryOp = findOp('query');

  await sweepProbeLeftovers(engine, ws, sourceId);

  // #6001: the probe section runs under one try/finally so the fixed-slug
  // probes are removed on every exit, including the early returns below.
  // `checks` is the same array the early returns hand back, so a cleanup
  // warning pushed in `finally` still reaches the caller.
  try {
    // 1. Write both probe pages through the REAL op handler [G1].
    let writeThroughDetail = '';
    try {
      await putPage.handler(ctx, { slug: VERIFY_PROBE_ENTITY_SLUG, content: PROBE_ENTITY_CONTENT });
      const res = (await putPage.handler(ctx, { slug: VERIFY_PROBE_SLUG, content: PROBE_CONTENT })) as {
        write_through?: { written: boolean; path?: string; skipped?: string; error?: string };
      };
      const wt = res.write_through;
      const expectedFile = join(ws, 'brain', `${VERIFY_PROBE_SLUG}.md`);
      if (wt?.written && wt.path && existsSync(wt.path)) {
        writeThroughDetail = `file materialized at ${wt.path}`;
        checks.push({ id: 'roundtrip', ok: true, detail: `put_page landed in DB and ${writeThroughDetail}` });
      } else if (existsSync(expectedFile)) {
        checks.push({ id: 'roundtrip', ok: true, detail: `put_page landed in DB and file materialized at ${expectedFile}` });
      } else if (wt?.skipped === 'disabled_by_config') {
        // DB-only by operator choice (`sync.write_through=false`), not a broken
        // install: the DB write landed, so WARN and keep the remaining
        // roundtrip-family checks — sweep/graph/search/magic-moment all run off
        // the DB row and still prove the memory loop.
        checks.push({
          id: 'roundtrip',
          ok: true,
          warn: true,
          detail:
            `put_page landed in DB; no file under brain/ because sync.write_through is disabled by config — ` +
            `agent writes stay DB-only (run \`gbrain config set sync.write_through true\` to materialize repo files)`,
        });
      } else {
        // [G1] A green verify with an empty repo is impossible: name the
        // write-through problem explicitly.
        const why = wt?.skipped ?? wt?.error ?? 'write-through reported nothing';
        checks.push({
          id: 'roundtrip',
          ok: false,
          detail:
            `put_page wrote the DB but NO file appeared under brain/ (write-through: ${why}). ` +
            `The workspace source must be registered with its brain/ dir as local_path ` +
            `(gbrain sources add ${sourceId} --path ${join(ws, 'brain')}) or agent writes never reach the repo.`,
        });
        return { checks };
      }
    } catch (e) {
      checks.push({ id: 'roundtrip', ok: false, detail: putPageFailureDetail(e, ctx.writeWaitMs) });
      return { checks };
    }

    // 2. Sweep — the `gbrain sweep --once` equivalent, run in-process because
    // verify's caller holds the engine [CX2-5]. #6786: passes 1 and 2 only.
    // The probes never need the corpus pass, and verify's engine runs without
    // the gateway extraction would use: every pending transcript came back
    // chat_unavailable and was marked ingested with zero facts.
    const caps = opts.capabilities ?? detectCapabilities();
    try {
      const report = await runMaintenanceSweep(engine, {
        sourceId,
        budgetMs: opts.sweepBudgetMs ?? 20_000,
        corpus: false,
        log: opts.log,
      });
      opts.log?.(`[verify] sweep: facts=${report.factsReconciled} links=${report.linksExtracted} timeline=${report.timelineExtracted}`);
    } catch (e) {
      checks.push({ id: 'graph_floor', ok: false, detail: `maintenance sweep failed: ${(e as Error).message}` });
      return { checks };
    }

    // 3. Graph floor: ≥1 extracted edge, answered through the link tables.
    try {
      const links = await engine.getLinks(VERIFY_PROBE_SLUG, { sourceId });
      const edge = links.find((l) => l.to_slug === VERIFY_PROBE_ENTITY_SLUG);
      const backlinks = await engine.getBacklinks(VERIFY_PROBE_ENTITY_SLUG, { sourceId });
      const back = backlinks.find((l) => l.from_slug === VERIFY_PROBE_SLUG);
      if (edge && back) {
        checks.push({ id: 'graph_floor', ok: true, detail: `entity link extracted and the edge-only query answers (probe → entity, ${links.length} outbound / ${backlinks.length} inbound)` });
      } else {
        checks.push({ id: 'graph_floor', ok: false, detail: `expected probe→entity edge missing after sweep (outbound: ${links.length}, inbound: ${backlinks.length}) — link extraction is not compounding the graph` });
      }
    } catch (e) {
      checks.push({ id: 'graph_floor', ok: false, detail: `edge query failed: ${(e as Error).message}` });
    }

    // 4. get_page + search recall.
    try {
      await getPage.handler(ctx, { slug: VERIFY_PROBE_SLUG });
    } catch (e) {
      checks.push({ id: 'roundtrip', ok: false, detail: `get_page read-back failed: ${(e as Error).message}` });
    }
    try {
      const result = await queryOp.handler(ctx, {
        query: 'bootstrap verify probe lighthouse',
        limit: 10,
        expand: false,
      });
      const found = JSON.stringify(result).includes(VERIFY_PROBE_SLUG);
      if (!found) {
        checks.push({ id: 'roundtrip', ok: false, detail: `search did not return the probe page (${caps.search} search) — retrieval round-trip broken` });
      }
    } catch (e) {
      checks.push({ id: 'roundtrip', ok: false, detail: `search failed: ${(e as Error).message}` });
    }

    // 5. Magic moment [CX-P0.5]: the fence fact reconciled by the ZERO-LLM
    // sweep pass, read back at visibility='world' (what the harness can read).
    try {
      const rows = await engine.executeRaw<{ fact: string }>(
        `SELECT fact FROM facts WHERE source_id = $1 AND visibility = 'world' AND fact LIKE $2 LIMIT 1`,
        [sourceId, `%${VERIFY_MAGIC_TOKEN}%`],
      );
      if (rows.length > 0) {
        checks.push({ id: 'magic_moment', ok: true, detail: `fence-written fact recalled at visibility=world (keyless path: ${caps.mode === 'keyless' ? 'yes' : 'keyed install, same zero-LLM pass'})` });
      } else {
        checks.push({ id: 'magic_moment', ok: false, detail: 'the ## Facts fence fact never reached the facts index — keyless memory (agent-authored fences) is broken; check the sweep fence pass' });
      }
    } catch (e) {
      checks.push({ id: 'magic_moment', ok: false, detail: `facts read-back failed: ${(e as Error).message}` });
    }
  } finally {
    // 6. Delete the probes [G13] — failure is a WARNING, never a verify fail.
    // HARD delete via the engine primitive (same as sweepProbeLeftovers): the
    // probe is not user content and verify is a trusted local caller. The
    // delete_page OP is a v0.26.5 SOFT delete (sets deleted_at, row stays in
    // pages until the 72h purge) — using it here left two probe tombstones in
    // the user's brain after every verify run, visible to include_deleted
    // readers and pinned as residue by the Postgres e2e cleanup assertion.
    const deleteWarnings = await removeProbes(engine, ws, sourceId);
    if (deleteWarnings.length > 0) {
      checks.push({ id: 'probe_cleanup', ok: false, warn: true, detail: `probe deletion incomplete: ${deleteWarnings.join('; ')}` });
    }
  }

  return { checks };
}

/** Hooks smoke [D8#8 as amended by CX2-5]: hooks installed → pipe a fixture
 * UserPromptSubmit stdin into runHook('user-prompt') IN-PROCESS against a
 * live in-process IPC server backed by the verify engine (the
 * test/resolve-ipc-v2 pattern). Asserts exit 0 + within the hook's own
 * USER_PROMPT_DEADLINE_MS budget + non-empty block or a documented
 * degradation. */
async function checkHooksSmoke(engine: BrainEngine, ws: string, sourceId: string): Promise<VerifyCheck> {
  const id = 'hooks_smoke';
  if (!hooksInstalled(ws)) {
    return { id, ok: true, detail: 'hooks not installed — smoke not applicable (Codex/pull-mode or declined consent)' };
  }
  if (process.env.GBRAIN_HOOKS === '0') {
    return { id, ok: true, warn: true, detail: 'GBRAIN_HOOKS=0 kill switch is set — hooks are installed but disabled; unset it to re-enable per-turn context' };
  }
  let cfg: GBrainConfig | null = null;
  try {
    cfg = loadConfigFileOnly();
  } catch {
    cfg = null;
  }
  const dataDir = cfg?.database_path;
  if (!dataDir) {
    return { id, ok: true, warn: true, detail: 'no PGLite data dir in config (Postgres brain?) — IPC smoke not applicable' };
  }
  let server: { close: () => void } | null = null;
  const prevSource = process.env.GBRAIN_SOURCE;
  const socketPath = resolveSocketPath(dataDir);
  // #4474: prefer the REAL socket. Pre-fix the smoke ALWAYS started its own
  // in-process IPC server, so it manufactured the exact condition it was
  // testing — a serve posture that never binds IPC (the old `serve --http`)
  // still passed verify while every production hook degraded to no_serve.
  // A LIVE socket now means "a live serve is the provider; exercise IT";
  // only when nothing listens do we self-provide (plumbing-only smoke) and
  // say so honestly in the result. Probed, not existsSync'd: a socket file a
  // dead serve left behind must not read as a live provider (the smoke would
  // "exercise" a listener that isn't there and fail as no_serve).
  const liveSocket = await socketHasLiveListener(socketPath);
  try {
    if (!liveSocket) {
      const secret = ensureIpcSecret(dataDir);
      server = await startResolveIpcServer(
        socketPath,
        {
          resolve: async () => null,
          turn_context: (req) =>
            assembleTurnContext(engine, {
              sourceId,
              window: req.window,
              ...(req.priorContextText !== undefined ? { priorContextText: req.priorContextText } : {}),
              ...(req.sessionId !== undefined ? { sessionId: req.sessionId } : {}),
              ...(req.maxBytes !== undefined ? { maxBytes: req.maxBytes } : {}),
            }),
        },
        { secret, boundSourceId: sourceId },
      );
      if (!server) {
        return { id, ok: true, warn: true, detail: 'could not bind the IPC socket (a live serve owns it?) — smoke skipped; the live serve itself is the IPC provider' };
      }
    }
    // Provenance suffix for every outcome below: which listener answered.
    const via = liveSocket
      ? 'via the live serve’s IPC socket'
      : `via a verify-owned IPC server (no live serve socket at ${socketPath} — hooks stay degraded (no_serve) until a running \`gbrain serve\` binds it)`;
    process.env.GBRAIN_SOURCE = sourceId;
    // USER_PROMPT_DEADLINE_MS is the hook's own budget — the smoke compares
    // against the same constant it enforces (no drifting hardcoded copy).
    const { runHook, readHeartbeatTail, USER_PROMPT_DEADLINE_MS } = await import('../../commands/hook.ts');
    let out = '';
    const t0 = Date.now();
    const code = await runHook(['user-prompt'], {
      stdin: JSON.stringify({ prompt: 'bootstrap verify smoke: who am I to you?', session_id: 'bootstrap-verify' }),
      write: (s: string) => {
        out += s;
      },
      cwd: ws,
      turnRule: null,
    });
    const elapsed = Date.now() - t0;
    if (code !== 0) return { id, ok: false, detail: `hook exited ${code} (must fail open with exit 0)` };
    if (out.trim().length > 0) {
      if (elapsed >= USER_PROMPT_DEADLINE_MS) {
        // [A7] Real latency is a non-gating benchmark — the hard deadline
        // assertion lives in the hook tests against an injected slow-IPC stub.
        return { id, ok: true, warn: true, detail: `context block delivered but in ${elapsed}ms (over the ${USER_PROMPT_DEADLINE_MS}ms budget on this box) ${via} — watch hook latency` };
      }
      // #4474: a self-provided listener is a plumbing-only pass — production
      // hooks still need a live serve to bind the socket, so it WARNS.
      return liveSocket
        ? { id, ok: true, detail: `context block delivered in ${elapsed}ms (${out.trim().length} chars) ${via}` }
        : { id, ok: true, warn: true, detail: `context block delivered in ${elapsed}ms (${out.trim().length} chars) ${via}` };
    }
    // Empty stdout must be a DOCUMENTED degradation — read the heartbeat it wrote.
    const tail = await readHeartbeatTail(1);
    const reason = tail[tail.length - 1]?.reason ?? 'empty_block';
    if (reason === 'empty_block' || reason === 'empty_window') {
      return { id, ok: true, warn: true, detail: `empty context block in ${elapsed}ms (documented degradation: ${reason}) ${via} — plumbing works, brain has nothing to volunteer yet` };
    }
    if (reason === 'deadline' || reason === 'ipc_unavailable' || reason === 'server_budget') {
      // [A7] Latency-shaped degradations don't gate verify (slow CI box ≠
      // broken install); the reason is named so a human can judge.
      return { id, ok: true, warn: true, detail: `hook degraded on latency (${reason}) in ${elapsed}ms ${via} — non-gating; re-run on an idle machine if it persists` };
    }
    return { id, ok: false, detail: `hook degraded (${reason}) in ${elapsed}ms ${via} — stdin→IPC→stdout plumbing is not healthy` };
  } catch (e) {
    return { id, ok: false, detail: `hooks smoke failed: ${(e as Error).message}` };
  } finally {
    if (prevSource === undefined) delete process.env.GBRAIN_SOURCE;
    else process.env.GBRAIN_SOURCE = prevSource;
    try {
      server?.close();
    } catch {
      /* noop */
    }
  }
}

export function checkPushProbe(ws: string): VerifyCheck {
  const id = 'push_probe';
  try {
    // Read through the shared per-root reader [D8/D13] — a v0.45.8+ push
    // writes push-status-<roothash>.json, not the legacy single file, so the
    // old direct read reported "no push recorded" on every fresh install.
    const entries = readPushStatuses();
    const origin = gitOriginUrl(ws);
    // #5606: where a push is expected (an origin or a recorded push), a managed
    // canonical worktree is pushed by the persistence owner's Git effect;
    // sources push is refused there, so never recommend it. A local-only
    // managed workspace stays local-only below.
    const managed = (entries.length > 0 || origin) ? managedFilesystemRootFor(ws) : null;
    if (managed) {
      const source = managed.sourceId ?? '<source>';
      return { id, ok: true, detail: `managed canonical worktree${managed.sourceId ? ` (source ${managed.sourceId})` : ''} — page writes are committed and pushed by the persistence owner's Git effect, not by sources push; `
        + `check \`gbrain sources writer status ${source} --json\` (git_durability) and enable with \`gbrain sources writer git-durability ${source} --enable --dry-run\` if it is off` };
    }
    if (entries.length > 0) {
      const { failing } = summarizePushStatuses(entries);
      if (failing.length > 0) {
        const s = failing[0]!;
        const rest = failing.length > 1 ? ` [+${failing.length - 1} more]` : '';
        return { id, ok: true, warn: true, detail: `last workspace push FAILED (${s.ts ?? 'unknown'}): ${s.reason ?? 'unknown'}${rest} — run \`gbrain sources push --path ${s.repoRoot ?? ws}\`` };
      }
      const ok = entries.find((e) => e.ok === true);
      return { id, ok: true, detail: `last workspace push succeeded (${ok?.ts ?? 'unknown time'})` };
    }
    if (origin) return { id, ok: true, warn: true, detail: 'origin exists but no push recorded yet — run `gbrain sources push` once to prove the persistence path' };
    return { id, ok: true, detail: 'local-only mode — no push expected' };
  } catch (e) {
    return { id, ok: true, warn: true, detail: `push probe unreadable: ${(e as Error).message}` };
  }
}

function checkInertSkills(ws: string, caps: CapabilityReport): VerifyCheck {
  const id = 'inert_skills';
  const dir = join(ws, 'skills');
  if (!existsSync(dir)) return { id, ok: true, detail: 'no skills/ dir — scaffold not run (optional)' };
  try {
    // Best-effort: a SKILL.md that names a provider key is dormant in keyless
    // mode. Deep provider matrices live in `gbrain skillpack check`.
    const skillFiles: string[] = [];
    const walk = (d: string, depth: number): void => {
      if (depth > 3) return;
      for (const name of readdirSync(d)) {
        const p = join(d, name);
        let st;
        try {
          st = statSync(p);
        } catch {
          continue;
        }
        if (st.isDirectory()) walk(p, depth + 1);
        else if (name === 'SKILL.md') skillFiles.push(p);
      }
    };
    walk(dir, 0);
    if (skillFiles.length === 0) return { id, ok: true, detail: 'skills/ present, no SKILL.md files yet' };
    const providerHint = /OPENAI_API_KEY|ANTHROPIC_API_KEY|VOYAGE_API_KEY|api[_ -]?key/i;
    const inert = caps.mode === 'keyless'
      ? skillFiles.filter((p) => {
          try {
            return providerHint.test(readFileSync(p, 'utf8'));
          } catch {
            return false;
          }
        }).length
      : 0;
    if (inert > 0) {
      return { id, ok: true, warn: true, detail: `${inert}/${skillFiles.length} skill(s) reference provider keys and are dormant in keyless mode — one key wakes them (see the capability report)` };
    }
    return { id, ok: true, detail: `${skillFiles.length} skill(s) installed${caps.mode === 'keyless' ? ', none blocked on API keys' : ''}` };
  } catch (e) {
    return { id, ok: true, warn: true, detail: `inert-skill scan failed: ${(e as Error).message}` };
  }
}

// ---------------------------------------------------------------------------
// Persistence [B2]
// ---------------------------------------------------------------------------

export const VERIFY_SNAPSHOTS_KEPT = 5;

function persistVerifyRun(gbrainHomeDir: string, payload: { ts: string; ok: boolean; checks: VerifyCheck[] }): void {
  try {
    const dir = join(gbrainHomeDir, 'bootstrap');
    mkdirSync(dir, { recursive: true, mode: 0o700 });
    const name = `verify-${payload.ts.replace(/[:.]/g, '-')}.json`;
    // tmp+rename (the writeReceipt pattern): a killed verify never leaves a
    // torn snapshot for status/doctor to trip on. The .tmp-* name does not
    // match the retention regex, so a leaked tmp is never counted as a run.
    const dest = join(dir, name);
    const tmp = `${dest}.tmp-${process.pid}`;
    writeFileSync(tmp, JSON.stringify(payload, null, 2) + '\n', { mode: 0o600 });
    renameSync(tmp, dest);
    // Keep the newest VERIFY_SNAPSHOTS_KEPT.
    const runs = readdirSync(dir).filter((n) => /^verify-.*\.json$/.test(n)).sort().reverse();
    for (const stale of runs.slice(VERIFY_SNAPSHOTS_KEPT)) {
      try {
        rmSync(join(dir, stale), { force: true });
      } catch {
        /* best effort */
      }
    }
  } catch {
    /* snapshot telemetry never fails a verify */
  }
}

// ---------------------------------------------------------------------------
// verifyWorkspace
// ---------------------------------------------------------------------------

export async function verifyWorkspace(
  engine: BrainEngine,
  ws: string,
  opts: VerifyOpts = {},
): Promise<VerifyReport> {
  let sourceId = opts.sourceId ?? 'workspace';
  const gbrainHomeDir = opts.gbrainHomeDir ?? resolveGbrainHome();
  const caps = opts.capabilities ?? detectCapabilities();

  const checks: VerifyCheck[] = [];

  checks.push(await checkDoctorGreen(engine));
  const engineHealthy = checks.find((c) => c.id === 'doctor_green')?.ok === true;

  let sourceRegistered = true;
  if (engineHealthy) {
    // Transient-engine work while we hold the engine (before/independent of
    // host registration): the CX-P1.1 visibility posture and the source-id
    // collision resolution both need the config/sources plane.
    checks.push(await ensureDefaultVisibilityPosture(engine));
    const collision = await resolveSourceIdCollision(engine, ws);
    if (collision.sourceId !== null) sourceId = collision.sourceId;
    if (collision.check !== null) checks.push(collision.check);
    // #4328 — registration probe. Probe writes against an UNREGISTERED source
    // die on their sources FK with a raw constraint error that names nothing a
    // user can act on. Detect the gap up front so the roundtrip/hooks-smoke
    // report the one command that fixes it instead. Probe failure fails OPEN
    // (the roundtrip owns surfacing real engine errors).
    try {
      const rows = await engine.executeRaw<{ one: number }>(`SELECT 1 AS one FROM sources WHERE id = $1`, [sourceId]);
      sourceRegistered = rows.length > 0;
    } catch {
      sourceRegistered = true;
    }
  }

  checks.push(checkTokenSweep(ws));
  checks.push(checkByteFloors(ws));
  checks.push(checkWritebackContract(ws));
  checks.push(checkSecretScan(ws));
  checks.push(checkDenyGlobs(ws));
  checks.push(await checkRepoPrivacy(ws));
  checks.push(checkExecutionEnvironment());
  checks.push(checkMcpJsonHygiene(ws));
  checks.push(checkHookCarrierOverlap(ws));

  // Round-trip family only makes sense on a reachable engine. The
  // embedding-plane check (#4287) runs FIRST so a plane split gets its named
  // diagnosis before the roundtrip's put surfaces the raw dimension error —
  // and so a keyless-passing roundtrip can never certify a brain whose keyed
  // writes all fail.
  if (engineHealthy && !sourceRegistered) {
    checks.push(await checkEmbeddingPlane(engine, caps));
    // #4328 — a put against the unregistered source would only surface the
    // raw FK constraint text. Name the actual gap + the one-command fix.
    checks.push({
      id: 'roundtrip',
      ok: false,
      detail:
        `skipped — source '${sourceId}' is not registered in this brain, so probe writes cannot land. ` +
        `Register it (gbrain sources add ${sourceId} --path ${join(ws, 'brain')}) and re-run \`gbrain bootstrap verify\`.`,
    });
  } else if (engineHealthy) {
    checks.push(await checkEmbeddingPlane(engine, caps));
    const rt = await runRoundtrip(engine, ws, sourceId, { ...opts, capabilities: caps });
    checks.push(...rt.checks);
  } else {
    checks.push({ id: 'roundtrip', ok: false, detail: 'skipped — engine probe failed (see doctor_green)' });
  }

  checks.push({ id: 'capability_report', ok: true, detail: `${caps.mode} mode / ${caps.search} search` });
  checks.push(checkMcpSurface());

  if (opts.skipHooksSmoke) {
    checks.push({ id: 'hooks_smoke', ok: true, detail: 'skipped by caller' });
  } else if (!sourceRegistered) {
    // #4328 — the smoke binds GBRAIN_SOURCE to the workspace source; against
    // an unregistered id it can only rediscover the roundtrip's finding.
    checks.push({ id: 'hooks_smoke', ok: true, detail: `skipped — source '${sourceId}' is not registered (see roundtrip)` });
  } else {
    checks.push(await checkHooksSmoke(engine, ws, sourceId));
  }

  checks.push(checkPushProbe(ws));
  checks.push(checkInertSkills(ws, caps));
  const tourCheck = { id: 'first_run_tour', ok: true, detail: 'three scripted prompts appended to the report' };
  checks.push(tourCheck);

  const ok = checks.every((c) => c.ok || c.warn === true);
  if (!ok) tourCheck.detail = 'tour withheld — prints on PASS';

  const ts = new Date().toISOString();
  persistVerifyRun(gbrainHomeDir, { ts, ok, checks });

  const lines: string[] = [];
  lines.push(`gbrain bootstrap verify — ${ok ? 'PASS' : 'FAIL'} (${ts})`);
  for (const c of checks) {
    const mark = c.ok && !c.warn ? 'ok  ' : c.warn ? 'warn' : 'FAIL';
    lines.push(`  [${mark}] ${c.id}: ${c.detail}`);
  }
  lines.push('');
  lines.push(renderCapabilityReport(caps));
  lines.push('');
  // The tour celebrates a WORKING install — under a FAIL banner it reads as
  // a mixed signal ("broken, but go enjoy it"). Gate the report lines on ok;
  // the returned `tour` array (and --json field) stays unconditional so
  // machine consumers keep a stable shape.
  const handoff = buildHandoff(ws);
  if (ok) {
    lines.push('First-run tour — have your human RESTART the session first');
    lines.push('(a fresh session proves the files and the brain, not this chat),');
    lines.push('then try these three prompts in order:');
    FIRST_RUN_TOUR.forEach((p, i) => lines.push(`  ${i + 1}. ${p}`));
    lines.push('');
    for (const h of handoff) lines.push(h);
  } else {
    lines.push('Fix the FAIL checks above and re-run — the first-run tour prints on PASS.');
  }

  return { ok, checks, report: lines.join('\n'), capability: caps, tour: [...FIRST_RUN_TOUR], handoff };
}

/**
 * The post-tour hand-off block [OOBE]: the two things a fresh user must walk
 * away UNDERSTANDING, in priority order —
 *   1. OWNERSHIP: identity files and committed Markdown pages are in a repo
 *      THEY own (or remain local-only). Database-only memory needs a separate
 *      complete backup; deleting the repo does not erase every memory copy.
 *      Say the URL and explain both the ownership and backup boundaries.
 *   2. THE ONE NEXT ACTION: run the cold-start skill. An empty brain is a
 *      database; every flagship skill (book-mirror, briefings, meeting prep)
 *      only becomes magical once the brain holds the user's real life —
 *      cold-start is the designed filler (Gmail/calendar/contacts via
 *      ClawVisor, or offline archives), one consented phase at a time.
 * Returned unconditionally in the machine shape (like `tour`); printed in
 * the report only on PASS. Relay it to the human verbatim.
 */
export function buildHandoff(ws: string): string[] {
  const origin = gitOriginUrl(ws);
  const ownership = origin
    ? [
        `What you own: your agent's identity files and committed Markdown pages are in YOUR private repo — ${origin}.`,
        'Read those files any time, or clone the workspace on another machine and run `gbrain bootstrap attach`.',
      ]
    : [
        'What you own: your agent\'s files and database remain on this machine (no remote yet).',
        'Run `gbrain bootstrap repo` any time to keep the workspace files in your own private GitHub repo.',
      ];
  return [
    ...ownership,
    'Facts, corrections, jobs, and accounting can exist only in the database; a Git clone is not a complete memory backup.',
    'Back up and restore the full database separately. Deleting the repository does not erase database records, history, source material, or backups.',
    '',
    'Fill it next: an empty brain is a database; a filled one is a memory.',
    'Ask your agent to run the cold-start skill — it imports your real life',
    '(Gmail, calendar, contacts via ClawVisor, an OAuth vault so the agent never',
    'holds raw tokens; or offline archives like Google Takeout), one consented',
    'phase at a time. Each phase is independently valuable — stop whenever.',
  ];
}