Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
24.2 KB
Raw Blame
/**
 * `gbrain bootstrap status` — phase detection, the install log, and the
 * support blob (agent-bootstrap plan: D5, B1, B5, C1 skew check).
 *
 * [D5] THE phase list is defined ONCE, here, in TS. `bootstrap status --json`
 * emits it; BOOTSTRAP_FOR_AGENTS.md defers to it ("follow status's phase
 * list"); CI checks the runbook's phase names against this array. Do not
 * duplicate the list anywhere else.
 *
 * Detection is artifact-first: each phase's `detect(ws, ctx)` looks at what
 * actually exists on disk (config, interview state, manifest, receipt,
 * settings, verify snapshots) — the append-only install log (B1) is
 * TELEMETRY, never the source of truth for "did this phase run", because a
 * crashed run writes artifacts without a log line and the status command is
 * exactly the resume entrypoint for that case.
 *
 * [B1] `<gbrain home>/bootstrap/install.jsonl` — one appended line per
 * dispatcher subcommand invocation ({ts, phase, outcome, duration_ms,
 * binary_version, harness?, workspace}). Append-only, never throws.
 *
 * [B5] `statusReport().support` is the blob AGENTS.md tells the agent to
 * relay verbatim on any "something's broken" report: workspace, binary
 * version, engine, harness registrations (from the receipt), last verify
 * summary (newest verify-*.json), last push (push-status.json), hook
 * failure rate (trailing heartbeat window).
 */

import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
import { execFileSync } from '../spawn.ts';
import { join } from 'node:path';

import { VERSION } from '../../version.ts';
import { loadConfigFileOnly } from '../config.ts';
import { binaryOnPath, detectExecutionEnvironment, type ExecutionEnvironment } from '../execution-env.ts';
import { resolveGbrainHome } from '../gbrain-home.ts';
import { githubOwnerRepoString, isProxyBlocked403 } from '../repo-visibility.ts';

import { CODEX_PROJECT_CONFIG, adoptedConnectionState } from './adopted-connections.ts';
import { BOOTSTRAP_TEMPLATES } from './assets.ts';
import {
  readManifest,
  readReceipt,
  type InstallReceipt,
  type ManifestState,
} from './format.ts';
import { interviewStatePath, status as interviewStatus } from './interview.ts';
import {
  CLAUDE_COMMITTED_SETTINGS_FILE_RELPATH,
  CLAUDE_SETTINGS_FILE_RELPATH,
  GBRAIN_HOOK_MARKER_KEY,
  GBRAIN_HOOK_MARKER_VALUE,
} from './host-specs.ts';
import { gitChildEnv } from '../git-env.ts';

// ---------------------------------------------------------------------------
// The phase list [D5] — single TS source of truth
// ---------------------------------------------------------------------------

export const BOOTSTRAP_PHASE_IDS = [
  'preflight',
  'engine',
  'interview',
  'render',
  'skills',
  'wire',
  'repo',
  'verify',
] as const;

export type BootstrapPhaseId = (typeof BOOTSTRAP_PHASE_IDS)[number];

export type PhaseState = 'done' | 'pending' | 'partial' | 'skipped';

export interface PhaseStatus {
  id: BootstrapPhaseId;
  title: string;
  state: PhaseState;
  /** The exact next action when this phase is not done. */
  resume_hint: string;
  detail?: string;
}

/** Everything a detector may look at, computed once per statusReport. */
interface DetectCtx {
  gbrainHomeDir: string;
  manifest: ManifestState;
  receipt: InstallReceipt | null;
  configPresent: boolean;
  lastVerify: VerifySummary | null;
}

interface PhaseSpec {
  id: BootstrapPhaseId;
  title: string;
  resume_hint: string;
  detect: (ws: string, ctx: DetectCtx) => { state: PhaseState; detail?: string };
}


/** The workspace's `origin` remote URL, or null (not a repo / no origin).
 * Shared with verify.ts's origin-probe sites — one 5s-timeout idiom. */
export function gitOriginUrl(ws: string): string | null {
  try {
    const out = execFileSync('git', ['-C', ws, 'remote', 'get-url', 'origin'], {
      env: gitChildEnv(),
      stdio: ['ignore', 'pipe', 'ignore'],
      timeout: 5_000,
    })
      .toString()
      .trim();
    return out || null;
  } catch {
    return null;
  }
}

// ---------------------------------------------------------------------------
// Template-door privacy gate
// ---------------------------------------------------------------------------

export type OriginVisibility =
  | { verdict: 'private' }
  | { verdict: 'public'; detail: string }
  | { verdict: 'unknown'; detail: string };

/** Probe an origin's visibility via REST — `gh api repos/{owner}/{repo}` —
 * NEVER `gh repo view` (GraphQL under the hood; cloud sandbox proxies pin
 * GraphQL to a fixed operation set and 403 it even with a user token). Sync
 * by contract: this runs inside the sync phase-detect chain, so the full
 * async ladder lives in verify/push; status keeps the cheap REST answer.
 * gh missing / offline / non-GitHub / 403 → 'unknown', never an invented
 * answer; a proxy-shaped 403 names the real fix. */
export function probeOriginVisibility(origin: string): OriginVisibility {
  const ownerRepo = githubOwnerRepoString(origin);
  if (ownerRepo === null) {
    // Never send a non-github origin string into a REST path — self-hosted
    // hostnames (or URL-embedded credentials) must not reach api.github.com.
    return { verdict: 'unknown', detail: 'origin is not a github.com URL — cannot verify via REST' };
  }
  try {
    // env: process.env — Bun's execFileSync otherwise resolves the binary
    // against the STARTUP env snapshot, making PATH-shimmed test fakes (and
    // any runtime PATH change) invisible (the workspace-push.ts precedent).
    const out = execFileSync('gh', ['api', `repos/${ownerRepo}`, '--jq', '.private'], {
      stdio: ['ignore', 'pipe', 'pipe'],
      timeout: 5_000,
      env: process.env,
    })
      .toString()
      .trim();
    if (out === 'true') return { verdict: 'private' };
    if (out === 'false') return { verdict: 'public', detail: `${origin} is PUBLIC` };
    return { verdict: 'unknown', detail: `gh returned unexpected output: ${out.slice(0, 80)}` };
  } catch (e) {
    const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string };
    if (err?.code === 'ENOENT') {
      return { verdict: 'unknown', detail: 'gh CLI not installed — cannot verify origin visibility' };
    }
    const stderr = (err?.stderr ?? '').toString();
    if (isProxyBlocked403(stderr)) {
      return {
        verdict: 'unknown',
        detail: 'GitHub REST blocked by this sandbox\'s egress proxy (repo not attached to the session) — push-time verification falls back to git protocol',
      };
    }
    return { verdict: 'unknown', detail: `gh api failed (${(err?.message ?? 'unknown').slice(0, 120)})` };
  }
}

/** True when either hook carrier — the gitignored `settings.local.json` OR
 * the committed `.claude/settings.json` [D12] — carries a gbrain marker. */
export function hooksInstalled(ws: string): boolean {
  try {
    const probe = (relpath: string): boolean => {
      try {
        const raw = readFileSync(join(ws, relpath), 'utf8');
        // Structural probe without a full merge: the marker key/value pair is
        // the idempotency contract host-specs.ts pins — substring is honest.
        return raw.includes(`"${GBRAIN_HOOK_MARKER_KEY}"`) && raw.includes(`"${GBRAIN_HOOK_MARKER_VALUE}"`);
      } catch {
        return false;
      }
    };
    return probe(CLAUDE_SETTINGS_FILE_RELPATH) || probe(CLAUDE_COMMITTED_SETTINGS_FILE_RELPATH);
  } catch {
    return false;
  }
}

export const PHASES: PhaseSpec[] = [
  {
    id: 'preflight',
    title: 'Toolchain preflight (git, bun, gh)',
    resume_hint: 'install git + gh per the runbook trust rules, then `gh auth login`',
    detect: (_ws) => {
      const git = binaryOnPath('git');
      const gh = binaryOnPath('gh');
      if (git && gh) return { state: 'done' };
      if (git) return { state: 'partial', detail: 'gh (GitHub CLI) not on PATH — needed for the repo phase only' };
      return { state: 'pending', detail: 'git not on PATH' };
    },
  },
  {
    id: 'engine',
    title: 'Local brain engine (gbrain init)',
    resume_hint: 'gbrain init --pglite',
    detect: (_ws, ctx) =>
      ctx.configPresent ? { state: 'done' } : { state: 'pending', detail: 'no gbrain config — engine not initialized' },
  },
  {
    id: 'interview',
    title: 'Identity interview (confirmed read-back)',
    resume_hint:
      'gbrain bootstrap interview --init, then --set each answer, then --confirm <hash>. ' +
      'Claude Code and opencode: also record the MCP scope consent (--set MCP_SCOPE <project|user>) BEFORE --confirm',
    detect: (ws) => {
      const exists = existsSync(interviewStatePath(ws));
      const st = interviewStatus(ws);
      if (!st.ok) return { state: 'partial', detail: st.message };
      if (st.complete && st.confirmed) return { state: 'done' };
      if (st.complete) return { state: 'partial', detail: 'answers complete but not confirmed — read them back, then --confirm <hash>' };
      if (st.answered.length > 0 || exists) {
        return { state: 'partial', detail: `missing required: ${st.missingRequired.join(', ') || '(none)'}` };
      }
      return { state: 'pending' };
    },
  },
  {
    id: 'render',
    title: 'Render identity files',
    resume_hint: 'gbrain bootstrap render',
    detect: (ws, ctx) => {
      if (ctx.manifest.state === 'initialized') return { state: 'done' };
      if (ctx.manifest.state === 'template') {
        return { state: 'partial', detail: 'uninitialized template clone — render flips it' };
      }
      if (ctx.manifest.state === 'invalid') {
        return { state: 'partial', detail: `agent.json invalid: ${ctx.manifest.reason}` };
      }
      const present = BOOTSTRAP_TEMPLATES.filter((t) => existsSync(join(ws, t.dest))).length;
      if (present > 0) return { state: 'partial', detail: `${present}/${BOOTSTRAP_TEMPLATES.length} rendered files present, no manifest` };
      return { state: 'pending' };
    },
  },
  {
    id: 'skills',
    title: 'Skill scaffold',
    resume_hint: 'gbrain skillpack scaffold --all',
    detect: (ws, ctx) => {
      const dir = join(ws, 'skills');
      if (existsSync(dir)) {
        try {
          const n = readdirSync(dir).filter((e) => !e.startsWith('.')).length;
          if (n > 0) return { state: 'done', detail: `${n} entr${n === 1 ? 'y' : 'ies'} in skills/` };
          return { state: 'partial', detail: 'skills/ exists but is empty' };
        } catch {
          return { state: 'partial', detail: 'skills/ unreadable' };
        }
      }
      // Skills only make sense after render laid the workspace down.
      return ctx.manifest.state === 'initialized' ? { state: 'pending' } : { state: 'pending', detail: 'runs after render' };
    },
  },
  {
    id: 'wire',
    title: 'Harness wiring (MCP + hooks)',
    // Static, both-harness hint (no detectHarness branching — status may run
    // outside the harness being wired). Advisory prose; the grep pins in
    // scripts/check-bootstrap-templates.sh §(e) are the enforcement.
    resume_hint:
      'gbrain bootstrap hooks --harness <claude-code|codex|opencode> — MCP scope consent applies on ' +
      'Claude Code and opencode (recorded during the interview, pre-confirm; opencode defaults to ' +
      'user-global — the sharing-safe choice, since it spawns project-config servers with no trust gate); ' +
      'Codex registrations are always user-global (no scope flag); a project-scoped .codex/config.toml server ' +
      'you manage yourself is adopted, never rewritten: `gbrain bootstrap hooks --adopt --harness codex` after a passing verify',
    detect: (ws, ctx) => {
      const regs = ctx.receipt?.registrations ?? [];
      if (regs.length > 0) {
        // A registration whose detail carries 'mcp' ('mcp' or 'mcp+hooks')
        // means MCP actually registered. A 'hooks'-only detail means the host
        // binary was missing at wire time (hooks landed, MCP did not) — the
        // phase is PARTIAL, not done, so a resuming agent re-runs it once the
        // CLI is on PATH instead of trusting a false "done".
        const mcpRegistered = regs.some((r) => (r.detail ?? '').includes('mcp'));
        if (mcpRegistered) {
          return { state: 'done', detail: regs.map((r) => `${r.host} (${r.scope})`).join(', ') };
        }
        return {
          state: 'partial',
          detail: 'hooks installed but MCP not registered (the harness CLI was not on PATH) — ' +
            're-run `gbrain bootstrap hooks --harness <claude-code|codex>` once it is',
        };
      }
      if (hooksInstalled(ws)) return { state: 'done', detail: 'hooks present in .claude/settings.local.json' };
      // Operator-managed Codex project config (#4082): `.codex/config.toml`
      // in the workspace, logged in with `codex mcp login`. Detected is
      // PARTIAL (nothing proves it reaches the brain); adopted after a
      // passing verify is DONE; a fingerprint drift is PARTIAL again.
      const adopted = adoptedConnectionState(ws, ctx.gbrainHomeDir);
      if (adopted.state === 'adopted') {
        return { state: 'done', detail: `codex (project, adopted ${adopted.connection.adopted_at}): ${CODEX_PROJECT_CONFIG} mcp_servers.${adopted.connection.name}` };
      }
      if (adopted.state === 'drifted') {
        return { state: 'partial', detail: `codex (project) adopted connection drifted — ${adopted.why}; re-run \`gbrain bootstrap verify\` then \`gbrain bootstrap hooks --adopt --harness codex\`` };
      }
      if (adopted.state === 'detected') {
        return {
          state: 'partial',
          detail: `codex (project) detected, not verified: ${CODEX_PROJECT_CONFIG} defines mcp_servers.${adopted.detected.name} (${adopted.detected.transport}) — ` +
            'run `gbrain bootstrap verify`, then `gbrain bootstrap hooks --adopt --harness codex` to adopt it (no user-global `codex mcp add` needed)',
        };
      }
      return { state: 'pending' };
    },
  },
  {
    id: 'repo',
    title: 'Private GitHub repo (durable body)',
    resume_hint: 'gbrain bootstrap repo (or stay local-only; re-run any time)',
    detect: (ws, ctx) => {
      const repoUrl = (ctx.receipt as (InstallReceipt & { repo_url?: string }) | null)?.repo_url;
      if (repoUrl) return { state: 'done', detail: repoUrl };
      const origin = gitOriginUrl(ws);
      if (origin) return { state: 'partial', detail: `origin exists (${origin}) but not yet pushed — run \`gbrain bootstrap repo\` (adopts an empty repo you created), or \`gbrain bootstrap attach\` for an existing agent clone` };
      return { state: 'pending' };
    },
  },
  {
    id: 'verify',
    title: 'End-to-end verify',
    resume_hint: 'gbrain bootstrap verify',
    detect: (_ws, ctx) => {
      if (!ctx.lastVerify) return { state: 'pending' };
      if (ctx.lastVerify.ok) return { state: 'done', detail: `last verify ${ctx.lastVerify.ts}` };
      return {
        state: 'partial',
        detail: `last verify FAILED (${ctx.lastVerify.ts}): ${ctx.lastVerify.checks_failed.join(', ') || 'see snapshot'}`,
      };
    },
  },
];

// Compile-time pin: PHASES covers BOOTSTRAP_PHASE_IDS exactly, in order.
// (Also asserted at runtime by test/bootstrap-status.test.ts.)
void (PHASES satisfies Array<{ id: BootstrapPhaseId }>);

// ---------------------------------------------------------------------------
// Install log [B1]
// ---------------------------------------------------------------------------

export interface InstallLogEntry {
  ts: string;
  phase: string;
  outcome: 'ok' | 'error' | 'aborted';
  duration_ms: number;
  binary_version: string;
  harness?: string;
  workspace: string;
}

export function installLogPath(gbrainHomeDir: string): string {
  return join(gbrainHomeDir, 'bootstrap', 'install.jsonl');
}

/** Append one line. Telemetry never throws [B1]. */
export function appendInstallLog(gbrainHomeDir: string, entry: InstallLogEntry): void {
  try {
    const p = installLogPath(gbrainHomeDir);
    mkdirSync(join(gbrainHomeDir, 'bootstrap'), { recursive: true, mode: 0o700 });
    appendFileSync(p, JSON.stringify(entry) + '\n', { mode: 0o600 });
  } catch {
    /* telemetry never breaks a subcommand */
  }
}

/** Last `n` entries (oldest → newest); torn lines skipped. */
export function readInstallLog(gbrainHomeDir: string, n = 50): InstallLogEntry[] {
  try {
    const raw = readFileSync(installLogPath(gbrainHomeDir), 'utf8');
    const lines = raw.split('\n').filter((l) => l.trim().length > 0);
    const out: InstallLogEntry[] = [];
    for (const line of lines.slice(-Math.max(0, n))) {
      try {
        out.push(JSON.parse(line) as InstallLogEntry);
      } catch {
        /* torn line */
      }
    }
    return out;
  } catch {
    return [];
  }
}

// ---------------------------------------------------------------------------
// Verify snapshots [B2 read side]
// ---------------------------------------------------------------------------

export interface VerifySummary {
  ts: string;
  ok: boolean;
  checks_failed: string[];
  file: string;
}

/** Newest-first list of persisted verify runs under `<home>/bootstrap/`. */
export function listVerifyRuns(gbrainHomeDir: string): VerifySummary[] {
  const dir = join(gbrainHomeDir, 'bootstrap');
  let names: string[];
  try {
    names = readdirSync(dir).filter((n) => /^verify-.*\.json$/.test(n)).sort().reverse();
  } catch {
    return [];
  }
  const out: VerifySummary[] = [];
  for (const name of names) {
    try {
      const parsed = JSON.parse(readFileSync(join(dir, name), 'utf8')) as {
        ts?: string;
        ok?: boolean;
        checks?: Array<{ id: string; ok: boolean; warn?: boolean }>;
      };
      out.push({
        ts: parsed.ts ?? 'unknown',
        ok: parsed.ok === true,
        checks_failed: (parsed.checks ?? []).filter((c) => !c.ok && c.warn !== true).map((c) => c.id),
        file: join(dir, name),
      });
    } catch {
      /* unreadable snapshot — skip */
    }
  }
  return out;
}

// ---------------------------------------------------------------------------
// Runbook stamp / skew [C1]
// ---------------------------------------------------------------------------

export const RUNBOOK_FILENAME = 'BOOTSTRAP_FOR_AGENTS.md';
const STAMP_RE = /<!--\s*gbrain-runbook-stamp:\s*([^\s>]+)\s*-->/;

/** The `<!-- gbrain-runbook-stamp: X -->` value from `<dir>/BOOTSTRAP_FOR_AGENTS.md`,
 * or null when the runbook is absent/unstamped (skip — not every workspace
 * keeps the fetched runbook around). */
export function readRunbookStamp(dir: string): string | null {
  try {
    const raw = readFileSync(join(dir, RUNBOOK_FILENAME), 'utf8');
    const m = STAMP_RE.exec(raw);
    return m ? m[1] : null;
  } catch {
    return null;
  }
}

export interface RunbookSkew {
  runbookStamp: string;
  binaryVersion: string;
}

// ---------------------------------------------------------------------------
// statusReport [D5 + B5]
// ---------------------------------------------------------------------------

export interface StatusSupport {
  workspace: string;
  binary_version: string;
  /** Engine kind from the config file ('pglite' | 'postgres' | null when uninitialized). */
  engine: string | null;
  harness_registrations: Array<{ host: string; scope: string; detail?: string }>;
  last_verify: { ts: string; ok: boolean; checks_failed: string[] } | null;
  last_push: { ts?: string; ok?: boolean; reason?: string } | null;
  /** Hard-error fraction over the trailing heartbeat window; null = no telemetry. */
  hook_failure_rate: number | null;
}

export interface StatusReport {
  workspace: string;
  phases: PhaseStatus[];
  /** Resume hint of the first non-done phase; null when everything is done. */
  next: string | null;
  /** WHERE this install is running [D-cloud]: 'local' | 'cloud-sandbox' |
   * 'ephemeral-container'. Installing agents branch on this — cron is skipped
   * in containers, repo creation is redirected in cloud sandboxes, and the
   * runbook's cloud section keys off it. */
  execution_environment: ExecutionEnvironment;
  runbookSkew?: RunbookSkew;
  /** Template-door privacy gate: set only for an UNINITIALIZED template clone
   * whose origin exists and is not verifiably private. 'public' is a hard
   * stop (the dispatcher exits non-zero — identity files must never land in a
   * public repo); 'unknown' (no gh / offline) is a loud warning, not a fail. */
  privacy_gate?: { verdict: 'public' | 'unknown'; origin: string; detail: string };
  support: StatusSupport;
}

export interface StatusReportOpts {
  gbrainHomeDir?: string;
}

export async function statusReport(ws: string, opts: StatusReportOpts = {}): Promise<StatusReport> {
  const gbrainHomeDir = opts.gbrainHomeDir ?? resolveGbrainHome();

  let config: ReturnType<typeof loadConfigFileOnly> = null;
  try {
    config = loadConfigFileOnly();
  } catch {
    config = null;
  }

  const verifyRuns = listVerifyRuns(gbrainHomeDir);
  const ctx: DetectCtx = {
    gbrainHomeDir,
    manifest: readManifest(ws),
    receipt: readReceipt(gbrainHomeDir),
    configPresent: config !== null,
    lastVerify: verifyRuns[0] ?? null,
  };

  const phases: PhaseStatus[] = PHASES.map((spec) => {
    let state: PhaseState = 'pending';
    let detail: string | undefined;
    try {
      const r = spec.detect(ws, ctx);
      state = r.state;
      detail = r.detail;
    } catch (e) {
      state = 'partial';
      detail = `detection failed: ${(e as Error).message}`;
    }
    return {
      id: spec.id,
      title: spec.title,
      state,
      resume_hint: spec.resume_hint,
      ...(detail !== undefined ? { detail } : {}),
    };
  });

  const firstNotDone = phases.find((p) => p.state !== 'done' && p.state !== 'skipped');
  const next = firstNotDone ? firstNotDone.resume_hint : null;

  // Skew check [C1]: compare the fetched runbook's stamp to this binary.
  const stamp = readRunbookStamp(ws);
  const runbookSkew = stamp !== null && stamp !== VERSION ? { runbookStamp: stamp, binaryVersion: VERSION } : undefined;

  // Template-door privacy gate: a template clone ("Use this template" flow)
  // with a PUBLIC origin must hard-stop BEFORE any identity file lands —
  // status is the resume entrypoint, so the gate lives here. Initialized
  // workspaces get the same protection from verify's repo_privacy check and
  // the push-time deny path.
  let privacyGate: StatusReport['privacy_gate'];
  if (ctx.manifest.state === 'template') {
    const origin = gitOriginUrl(ws);
    if (origin) {
      const probe = probeOriginVisibility(origin);
      if (probe.verdict !== 'private') {
        privacyGate = { verdict: probe.verdict, origin, detail: probe.detail };
      }
    }
  }

  // Support blob [B5]. Push status of THIS workspace's root via the shared
  // per-root reader [D8/D13] (#5432): another root's failure or success is
  // never reported as this workspace's; no receipt for this root is null.
  let lastPush: StatusSupport['last_push'] = null;
  try {
    const { readPushStatuses, pushStatusForWorkspace } = await import('../workspace-push.ts');
    const pick = pushStatusForWorkspace(readPushStatuses(), ws);
    if (pick) {
      lastPush = {
        ...(pick.ts !== undefined ? { ts: pick.ts } : {}),
        ...(pick.ok !== undefined ? { ok: pick.ok } : {}),
        ...(pick.reason !== undefined ? { reason: pick.reason } : {}),
      };
    }
  } catch {
    lastPush = null;
  }

  let hookFailureRate: number | null = null;
  try {
    // Lazy import (core→commands, the sweep.ts precedent) — hook.ts is
    // engine-free, and a partially-built tree must not break status.
    const { readHeartbeatTail, HEARTBEAT_FAILURE_WINDOW } = await import('../../commands/hook.ts');
    const tail = await readHeartbeatTail(HEARTBEAT_FAILURE_WINDOW);
    if (tail.length > 0) {
      hookFailureRate = tail.filter((e) => e.outcome === 'error').length / tail.length;
    }
  } catch {
    hookFailureRate = null;
  }

  const support: StatusSupport = {
    workspace: ws,
    binary_version: VERSION,
    engine: config?.engine ?? null,
    harness_registrations: (ctx.receipt?.registrations ?? []).map((r) => ({
      host: r.host,
      scope: r.scope,
      ...(r.detail !== undefined ? { detail: r.detail } : {}),
    })),
    last_verify: ctx.lastVerify
      ? { ts: ctx.lastVerify.ts, ok: ctx.lastVerify.ok, checks_failed: ctx.lastVerify.checks_failed }
      : null,
    last_push: lastPush,
    hook_failure_rate: hookFailureRate,
  };

  return {
    workspace: ws,
    phases,
    next,
    execution_environment: detectExecutionEnvironment(),
    ...(runbookSkew ? { runbookSkew } : {}),
    ...(privacyGate ? { privacy_gate: privacyGate } : {}),
    support,
  };
}