crewhaus 0.1.8 → 0.2.1

package/dist/compile-check.js

@@ -0,0 +1,285 @@
+/**
+ * Item 33 — `crewhaus compile --check` core (shape assertion → dep install →
+ * liveness boot), in a side-effect-free module so it is unit-testable (the
+ * CLI entry file runs an argv switch on import). The compile path calls
+ * `runCompileCheck()` after writing the bundle; every subprocess goes
+ * through the injectable `CheckStepRunner` so tests never hit the network.
+ *
+ * The three steps, in degradation order:
+ *   1. assertion — the target shape's `ShapeAssertion` from
+ *      @crewhaus/smoke-harness applied generically (fixture-only anchors
+ *      skipped). Offline + deterministic; skipped only when the target
+ *      ships no assertion.
+ *   2. install — `bun install` in the out-dir (bounded by a 120s timeout so
+ *      a hung registry cannot hang the compile forever). When the emitter
+ *      didn't produce a package.json (only the cf-worker shapes do), a
+ *      minimal one is synthesized from the bundle's @crewhaus imports,
+ *      pinned to this CLI's own version (the packages publish in lockstep,
+ *      so that is exactly the contract this CLI's bundles run against).
+ *   3. boot — spawn the bundle's entrypoint once, CREDENTIAL-FREE (env
+ *      scrubbed to PATH/HOME + the credential-free proxy/CA vars), with
+ *      `doctor --liveness` semantics: booting far enough to reach the
+ *      shape's own credential/input gate IS the signal (see
+ *      BOOT_GATE_PATTERNS — derived empirically by booting every fixture
+ *      bundle key-less). Scrubbing is deliberate: with real credentials in
+ *      the env, autonomous shapes (workflow, batch, …) would EXECUTE their
+ *      agent on boot — paid model calls from a compile flag. Bun would
+ *      quietly defeat that scrub by auto-loading a `.env` colocated with
+ *      the bundle, so the boot passes `--env-file=<empty file>` to disable
+ *      the auto-load (see bootArgvFor). Shapes whose boot needs live
+ *      credentials/servers therefore degrade to "gated" (green) and the
+ *      verdict reports which step ran; a structural break (SyntaxError,
+ *      unresolved import) matches no gate and stays red.
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SHAPE_ASSERTIONS, assertBundleAgainstShape, assertionForTarget, } from "@crewhaus/smoke-harness";
+import { cliVersion } from "./version";
+const DEFAULT_BOOT_TIMEOUT_MS = 10_000;
+// A hung registry must not hang `compile --check` forever — the install step
+// is bounded (override via CompileCheckOptions.installTimeoutMs).
+const DEFAULT_INSTALL_TIMEOUT_MS = 120_000;
+/**
+ * Env vars copied through the credential scrub. PATH/HOME are needed to find
+ * bun and its caches; the proxy/CA vars carry no credentials but are required
+ * for `bun install` (and any gated boot probe) to reach the network at all in
+ * proxied/corporate environments.
+ */
+const SCRUB_PASSTHROUGH_VARS = [
+    "PATH",
+    "HOME",
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "NO_PROXY",
+    "SSL_CERT_FILE",
+    "NODE_EXTRA_CA_CERTS",
+];
+/** Credential-free child env: only {@link SCRUB_PASSTHROUGH_VARS} survive. */
+export function scrubbedEnv(baseEnv) {
+    const env = {};
+    for (const name of SCRUB_PASSTHROUGH_VARS) {
+        const value = baseEnv[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
+/**
+ * Lazily-created empty env file for `bun --env-file=…`. Without the flag Bun
+ * AUTO-LOADS `.env` from the child's cwd — the out-dir — so a colocated .env
+ * with real keys would silently defeat the credential scrub and let an
+ * autonomous shape execute paid agent runs from a verification flag. An
+ * explicit `--env-file` replaces the auto-load entirely (verified on Bun
+ * 1.3.14: the child sees none of the .env's vars). An empty temp file is
+ * used rather than /dev/null so the flag also works on Windows.
+ */
+let cachedEmptyEnvFile;
+export function emptyEnvFile() {
+    if (cachedEmptyEnvFile === undefined) {
+        const path = join(mkdtempSync(join(tmpdir(), "crewhaus-check-env-")), "empty.env");
+        writeFileSync(path, "");
+        cachedEmptyEnvFile = path;
+    }
+    return cachedEmptyEnvFile;
+}
+/**
+ * The exact argv `compile --check` boots a bundle entrypoint with. Exported
+ * so the F4 regression tests exercise the REAL construction (flag presence
+ * with an injected runner, and .env invisibility with a live subprocess).
+ */
+export function bootArgvFor(entry) {
+    return ["bun", `--env-file=${emptyEnvFile()}`, entry];
+}
+/** Collect the @crewhaus/* packages the emitted bundle imports (sorted, deduped). */
+export function collectCrewhausDeps(files) {
+    const deps = new Set();
+    const re = /["'](@crewhaus\/[a-z0-9-]+)["']/g;
+    for (const file of files) {
+        if (!file.path.endsWith(".ts") && !file.path.endsWith(".js"))
+            continue;
+        for (const m of file.content.matchAll(re)) {
+            const dep = m[1];
+            if (dep !== undefined)
+                deps.add(dep);
+        }
+    }
+    return [...deps].sort();
+}
+/**
+ * Minimal manifest for bundles whose emitter ships no package.json.
+ * Versions pin to the CLI's OWN version: the @crewhaus/* packages publish in
+ * lockstep (scripts/publish-workspace.ts stamps them all with one version),
+ * so `<cliVersion>` is exactly the published contract this CLI's emitters
+ * were released against — where "latest" would silently verify against
+ * whatever shipped since, making the check's verdict depend on the day it
+ * runs. "latest" remains only as the fallback when no version is resolvable
+ * (a broken installation). (In a dev checkout the pinned publish can lag
+ * unreleased emitter features; the boot step then reports the mismatch,
+ * which is a real signal, not a false positive.)
+ */
+export function buildBundlePackageJson(deps, version) {
+    const pin = version ?? "latest";
+    const dependencies = {};
+    for (const dep of deps)
+        dependencies[dep] = pin;
+    return `${JSON.stringify({ name: "crewhaus-compiled-bundle", private: true, type: "module", dependencies }, null, 2)}\n`;
+}
+/** daemon.ts (daemon shapes) beats agent.ts; undefined = nothing bootable here. */
+export function resolveBootEntry(files) {
+    const paths = new Set(files.map((f) => f.path));
+    if (paths.has("daemon.ts"))
+        return "daemon.ts";
+    if (paths.has("agent.ts"))
+        return "agent.ts";
+    return undefined;
+}
+/**
+ * Known first-boot gates: the message a shape prints when it boots far
+ * enough to demand its live inputs. Reaching a gate is the liveness signal
+ * (`doctor --liveness` semantics — "booting far enough to parse argv IS the
+ * signal"). Derived empirically from booting every fixture bundle with a
+ * scrubbed env; keep patterns narrow so structural breakage stays red.
+ */
+export const BOOT_GATE_PATTERNS = [
+    // runtime-core resolveAuth / provider adapters (cli, workflow, graph, …).
+    { pattern: /no Anthropic credentials found|ProviderAuthError/, gate: "provider credentials" },
+    // Env-ref rewriting: `process.env["X"] ?? throw` (channel secrets, onchain RPC).
+    { pattern: /missing required env var/, gate: "spec env refs" },
+    // crew daemon reads its kickoff input from stdin.
+    { pattern: /no input on stdin/, gate: "stdin input" },
+    // voice daemon's v0 headless smoke path.
+    { pattern: /no --smoke/, gate: "a --smoke pcm fixture" },
+    // browser driver needs a prompt to open a session.
+    { pattern: /no prompt \(pass --prompt/, gate: "an initial --prompt" },
+    // eval bundle resolves its dataset from the local registry.
+    { pattern: /dataset "[^"]*" not found/, gate: "a registered eval dataset" },
+];
+export function classifyBootOutcome(result) {
+    if (result.timedOut) {
+        return { status: "ok", detail: "daemon stayed alive for the liveness window" };
+    }
+    if (result.exitCode === 0) {
+        return { status: "ok", detail: "booted and exited cleanly" };
+    }
+    // Gates are matched against BOTH streams: most shapes print their gate to
+    // stderr, but nothing guarantees it — a stdout-printed gate must not be
+    // misclassified as a structural failure.
+    const output = `${result.stdout}\n${result.stderr}`;
+    for (const { pattern, gate } of BOOT_GATE_PATTERNS) {
+        if (pattern.test(output)) {
+            return {
+                status: "gated",
+                detail: `boot reached its ${gate} gate — full boot needs live ${gate}`,
+            };
+        }
+    }
+    const tail = result.stderr.trim().split("\n").slice(-3).join(" | ").slice(0, 400);
+    return { status: "failed", detail: `boot exited ${result.exitCode}: ${tail}` };
+}
+/** Fold the steps into the single green/red verdict line. Only "failed" is red. */
+export function buildVerdict(steps) {
+    const green = steps.every((s) => s.status !== "failed");
+    const parts = steps.map((s) => `${s.step} ${s.status}${s.detail !== undefined ? ` (${s.detail})` : ""}`);
+    return { green, line: `compile --check: ${green ? "GREEN" : "RED"} — ${parts.join("; ")}` };
+}
+export const defaultCheckRunner = async ({ argv, cwd, env, timeoutMs }) => {
+    const head = argv[0] ?? "bun";
+    const proc = Bun.spawn([head, ...argv.slice(1)], {
+        cwd,
+        env: env ?? { PATH: process.env["PATH"] ?? "", HOME: process.env["HOME"] ?? "" },
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+    });
+    let timedOut = false;
+    const timer = timeoutMs !== undefined
+        ? setTimeout(() => {
+            timedOut = true;
+            proc.kill("SIGKILL");
+        }, timeoutMs)
+        : undefined;
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    if (timer !== undefined)
+        clearTimeout(timer);
+    return { exitCode, timedOut, stdout, stderr };
+};
+export async function runCompileCheck(opts) {
+    const runner = opts.runner ?? defaultCheckRunner;
+    const steps = [];
+    // 1 — shape assertion (offline, deterministic).
+    const assertion = assertionForTarget(opts.target, opts.assertions ?? SHAPE_ASSERTIONS);
+    if (assertion === undefined) {
+        steps.push({
+            step: "assertion",
+            status: "skipped",
+            detail: `no smoke assertion for target "${opts.target}"`,
+        });
+    }
+    else {
+        const failures = assertBundleAgainstShape(assertion, opts.bundle);
+        const applied = assertion.anchors.filter((a) => a.fixtureOnly !== true).length;
+        steps.push(failures.length === 0
+            ? { step: "assertion", status: "ok", detail: `${applied} anchors` }
+            : { step: "assertion", status: "failed", detail: failures.join("; ") });
+    }
+    // 2 — install the bundle's deps in the out-dir. Scrubbed env (proxy/CA
+    // vars pass through — bun needs them to reach the registry) + a timeout so
+    // a hung registry cannot hang the compile forever.
+    const baseEnv = opts.env ?? process.env;
+    const childEnv = scrubbedEnv(baseEnv);
+    if (!opts.bundle.files.some((f) => f.path === "package.json")) {
+        writeFileSync(join(opts.outDir, "package.json"), buildBundlePackageJson(collectCrewhausDeps(opts.bundle.files), cliVersion()));
+    }
+    const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+    const install = await runner({
+        argv: ["bun", "install"],
+        cwd: opts.outDir,
+        env: childEnv,
+        timeoutMs: installTimeoutMs,
+    });
+    const installOk = !install.timedOut && install.exitCode === 0;
+    steps.push(installOk
+        ? { step: "install", status: "ok" }
+        : {
+            step: "install",
+            status: "failed",
+            detail: install.timedOut
+                ? `bun install timed out after ${installTimeoutMs}ms (registry unreachable/hung?)`
+                : `bun install exited ${install.exitCode}: ${install.stderr
+                    .trim()
+                    .split("\n")
+                    .slice(-2)
+                    .join(" | ")
+                    .slice(0, 300)}`,
+        });
+    // 3 — liveness boot (credential-free by design; see module doc). The
+    // --env-file flag in bootArgvFor keeps Bun from auto-loading a `.env`
+    // colocated with the bundle, which would defeat the scrub.
+    const entry = resolveBootEntry(opts.bundle.files);
+    if (entry === undefined) {
+        steps.push({
+            step: "boot",
+            status: "skipped",
+            detail: "no agent.ts/daemon.ts entrypoint (bundle boots via its own tooling)",
+        });
+    }
+    else if (!installOk) {
+        steps.push({ step: "boot", status: "skipped", detail: "install failed" });
+    }
+    else {
+        const boot = await runner({
+            argv: bootArgvFor(entry),
+            cwd: opts.outDir,
+            env: childEnv,
+            timeoutMs: opts.bootTimeoutMs ?? DEFAULT_BOOT_TIMEOUT_MS,
+        });
+        const outcome = classifyBootOutcome(boot);
+        steps.push({ step: "boot", status: outcome.status, detail: outcome.detail });
+    }
+    return { ...buildVerdict(steps), steps };
+}

package/dist/compliance-schedule.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Item 34 — scheduling ergonomics for `crewhaus compliance evidence`,
+ * factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Side-effect-free and directly unit-testable, mirroring `scope-audit.ts` /
+ * `audit-verify.ts`.
+ *
+ * A cron job cannot hardcode `--period 2026-Q3` — it would silently collect
+ * the wrong quarter after a boundary. `--period current` resolves the
+ * current quarter from the clock in the same `YYYY-QN` label format the
+ * command already accepts (see `runCompliance`'s usage example), using UTC
+ * to match the audit log's UTC day rotation.
+ */
+/** `YYYY-QN` label for the quarter containing `date`, in UTC. */
+export declare function currentQuarterPeriod(date: Date): string;
+/**
+ * Resolve the raw `--period` flag value: the literal `current` becomes the
+ * clock's current quarter; any other label passes through verbatim (the
+ * collector's `writeBundle` still path-validates it downstream).
+ */
+export declare function resolvePeriodFlag(value: string, now?: () => Date): string;
+/** The slice of an EvidenceBundle the empty-evidence gate needs. */
+export type BundleCount = {
+    readonly frameworkId: string;
+    readonly controlId: string;
+    readonly recordCount: number;
+};
+/**
+ * `framework/control` ids of every collected bundle with zero records — the
+ * evidence gaps that fail a scheduled run (a control that collected nothing
+ * is a control an auditor cannot be shown; exiting 0 would hide that until
+ * audit time). Order-preserving so the failure message mirrors collection
+ * order.
+ */
+export declare function findEmptyControls(bundles: ReadonlyArray<BundleCount>): ReadonlyArray<string>;

package/dist/compliance-schedule.js

@@ -0,0 +1,36 @@
+/**
+ * Item 34 — scheduling ergonomics for `crewhaus compliance evidence`,
+ * factored out of the entry file `index.ts` (which runs a top-level argv
+ * switch and so cannot be imported by a test without executing the CLI).
+ * Side-effect-free and directly unit-testable, mirroring `scope-audit.ts` /
+ * `audit-verify.ts`.
+ *
+ * A cron job cannot hardcode `--period 2026-Q3` — it would silently collect
+ * the wrong quarter after a boundary. `--period current` resolves the
+ * current quarter from the clock in the same `YYYY-QN` label format the
+ * command already accepts (see `runCompliance`'s usage example), using UTC
+ * to match the audit log's UTC day rotation.
+ */
+/** `YYYY-QN` label for the quarter containing `date`, in UTC. */
+export function currentQuarterPeriod(date) {
+    const quarter = Math.floor(date.getUTCMonth() / 3) + 1;
+    return `${date.getUTCFullYear()}-Q${quarter}`;
+}
+/**
+ * Resolve the raw `--period` flag value: the literal `current` becomes the
+ * clock's current quarter; any other label passes through verbatim (the
+ * collector's `writeBundle` still path-validates it downstream).
+ */
+export function resolvePeriodFlag(value, now = () => new Date()) {
+    return value === "current" ? currentQuarterPeriod(now()) : value;
+}
+/**
+ * `framework/control` ids of every collected bundle with zero records — the
+ * evidence gaps that fail a scheduled run (a control that collected nothing
+ * is a control an auditor cannot be shown; exiting 0 would hide that until
+ * audit time). Order-preserving so the failure message mirrors collection
+ * order.
+ */
+export function findEmptyControls(bundles) {
+    return bundles.filter((b) => b.recordCount === 0).map((b) => `${b.frameworkId}/${b.controlId}`);
+}

package/dist/context-pressure.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Item 17 (completion) — `crewhaus doctor --context-pressure`: the
+ * telemetry-driven tuning loop's report face. The advise rules already
+ * turn recovery/compaction telemetry into SpecPatches (the detection
+ * half); this module reads the same persisted session events and prints
+ * WHERE the pressure is — truncation recoveries, compaction fires per
+ * session, the snip-vs-autocompact split — next to the spec's current
+ * knobs, and, when the advise thresholds trip, the exact advise/optimize
+ * commands that close the loop. A report, not a gate: doctor exits 0.
+ *
+ * Event vocabulary (runtime-core's `logEvent` kinds):
+ *   - `recovery` with `action: "continue"` — emitted exclusively for
+ *     max_output_tokens truncations (recovery-engine's taxonomy), so the
+ *     continue count IS the truncation-pressure count;
+ *   - `compaction` with `kind: "snip" | "autocompact" | "reactive"` —
+ *     snips are free (head/tail trim), autocompact + reactive summarize
+ *     via a model call. The ratio is only derivable when kind-tagged
+ *     events exist (the kind field ships with the events themselves, so
+ *     any persisted compaction carries it; "unknown" tolerates foreign
+ *     or hand-edited logs).
+ *
+ * Kept in a side-effect-free module (the CLI entry file runs an argv
+ * switch on import) following the doctor-checks.ts pattern: pure builders
+ * over caller-supplied `SessionEvents`, directly unit-testable.
+ */
+import type { Spec } from "@crewhaus/spec";
+import { type AdviceThresholds, type SessionEvents } from "./advise-rules";
+/** Default number of most-recent sessions the doctor report scans. */
+export declare const DEFAULT_CONTEXT_PRESSURE_SESSIONS = 20;
+export type CompactionKindCounts = {
+    readonly snip: number;
+    readonly autocompact: number;
+    readonly reactive: number;
+    /** Compaction events without a recognized `kind` (foreign logs). */
+    readonly unknown: number;
+};
+export type ContextPressureReport = {
+    readonly sessionCount: number;
+    /** `recovery` events with `action: "continue"` — max_output_tokens
+     *  truncations by construction. */
+    readonly truncationContinues: number;
+    readonly compactionTotal: number;
+    readonly sessionsWithCompaction: number;
+    /** Mean over ALL scanned sessions (a quiet session counts as 0). */
+    readonly avgCompactionsPerSession: number;
+    readonly maxCompactionsPerSession: number;
+    readonly maxCompactionSessionId?: string;
+    readonly compactionKinds: CompactionKindCounts;
+    /** snip / (snip + model-backed fires); undefined when no kind-tagged
+     *  compaction event was seen (ratio not derivable). */
+    readonly snipRatio?: number;
+    readonly spec: {
+        /** False when no parseable crewhaus.yaml was supplied. */
+        readonly present: boolean;
+        readonly maxTokens?: number;
+        readonly compactionCurate?: boolean;
+        readonly compactionDedupeThreshold?: number;
+        readonly compactionRelevanceTopK?: number;
+    };
+    /** Advise-threshold trips: "truncation-pressure" / "compaction-thrash". */
+    readonly tripped: ReadonlyArray<string>;
+    /** The exact commands to run when any threshold tripped (empty otherwise). */
+    readonly commands: ReadonlyArray<string>;
+};
+/** The commands the report prints when pressure trips — the nightly
+ *  advisor composition (advise emits the patches, optimize --from-advice
+ *  eval-gates and applies them). */
+export declare const CONTEXT_PRESSURE_COMMANDS: ReadonlyArray<string>;
+/**
+ * Fold the persisted session events into the context-pressure report.
+ * Every field access is defensive (missing payloads, wrong-typed fields,
+ * old-vintage logs all pass through cleanly), matching
+ * `buildAdviceContext`'s posture.
+ */
+export declare function buildContextPressureReport(sessions: ReadonlyArray<SessionEvents>, opts?: {
+    readonly spec?: Spec;
+    readonly thresholds?: Partial<AdviceThresholds>;
+}): ContextPressureReport;
+/** One-screen report, printed by `doctor --context-pressure`. */
+export declare function formatContextPressureLines(report: ContextPressureReport): string[];

package/dist/context-pressure.js

@@ -0,0 +1,166 @@
+import { DEFAULT_ADVICE_THRESHOLDS, payloadOf, } from "./advise-rules";
+/** Default number of most-recent sessions the doctor report scans. */
+export const DEFAULT_CONTEXT_PRESSURE_SESSIONS = 20;
+/** The commands the report prints when pressure trips — the nightly
+ *  advisor composition (advise emits the patches, optimize --from-advice
+ *  eval-gates and applies them). */
+export const CONTEXT_PRESSURE_COMMANDS = Object.freeze([
+    "crewhaus advise --all -o .",
+    "crewhaus optimize crewhaus.yaml --from-advice suggestions.json --write-back --dataset eval/dataset.jsonl --graders eval/graders.yaml",
+]);
+// Narrow accessors over the Spec union (mirrors advise-rules): the fields
+// exist on most (not all) targets, so read through an index signature.
+function specField(spec, key) {
+    if (spec === undefined)
+        return undefined;
+    return spec[key];
+}
+/**
+ * Fold the persisted session events into the context-pressure report.
+ * Every field access is defensive (missing payloads, wrong-typed fields,
+ * old-vintage logs all pass through cleanly), matching
+ * `buildAdviceContext`'s posture.
+ */
+export function buildContextPressureReport(sessions, opts = {}) {
+    const thresholds = { ...DEFAULT_ADVICE_THRESHOLDS, ...(opts.thresholds ?? {}) };
+    let truncationContinues = 0;
+    let snip = 0;
+    let autocompact = 0;
+    let reactive = 0;
+    let unknown = 0;
+    const compactionsBySession = new Map();
+    for (const session of sessions) {
+        for (const obj of session.objects) {
+            const recovery = payloadOf(obj, "recovery");
+            if (recovery !== undefined) {
+                if (recovery["action"] === "continue")
+                    truncationContinues += 1;
+                continue;
+            }
+            const compaction = payloadOf(obj, "compaction");
+            if (compaction !== undefined) {
+                compactionsBySession.set(session.sessionId, (compactionsBySession.get(session.sessionId) ?? 0) + 1);
+                switch (compaction["kind"]) {
+                    case "snip":
+                        snip += 1;
+                        break;
+                    case "autocompact":
+                        autocompact += 1;
+                        break;
+                    case "reactive":
+                        reactive += 1;
+                        break;
+                    default:
+                        unknown += 1;
+                }
+            }
+        }
+    }
+    let compactionTotal = 0;
+    let maxCompactionsPerSession = 0;
+    let maxCompactionSessionId;
+    for (const [sessionId, count] of compactionsBySession) {
+        compactionTotal += count;
+        if (count > maxCompactionsPerSession) {
+            maxCompactionsPerSession = count;
+            maxCompactionSessionId = sessionId;
+        }
+    }
+    const avgCompactionsPerSession = sessions.length === 0 ? 0 : compactionTotal / sessions.length;
+    // Ratio of free snips to ALL kind-tagged fires (autocompact + reactive
+    // both summarize via a model call). Underivable without tagged events.
+    const tagged = snip + autocompact + reactive;
+    const snipRatio = tagged > 0 ? snip / tagged : undefined;
+    const spec = opts.spec;
+    const agent = specField(spec, "agent");
+    const maxTokens = typeof agent?.["max_tokens"] === "number" ? agent["max_tokens"] : undefined;
+    const compactionBlock = specField(spec, "compaction");
+    const curate = typeof compactionBlock?.["curate"] === "boolean" ? compactionBlock["curate"] : undefined;
+    const dedupe = typeof compactionBlock?.["dedupeThreshold"] === "number"
+        ? compactionBlock["dedupeThreshold"]
+        : undefined;
+    const topK = typeof compactionBlock?.["relevanceTopK"] === "number"
+        ? compactionBlock["relevanceTopK"]
+        : undefined;
+    // The SAME thresholds the advise rules fire on — when the report says
+    // "tripped", `crewhaus advise` will emit a patch for it.
+    const tripped = [];
+    if (truncationContinues >= thresholds.truncationContinues)
+        tripped.push("truncation-pressure");
+    if (maxCompactionsPerSession >= thresholds.compactionsPerSession) {
+        tripped.push("compaction-thrash");
+    }
+    return {
+        sessionCount: sessions.length,
+        truncationContinues,
+        compactionTotal,
+        sessionsWithCompaction: compactionsBySession.size,
+        avgCompactionsPerSession,
+        maxCompactionsPerSession,
+        ...(maxCompactionSessionId !== undefined ? { maxCompactionSessionId } : {}),
+        compactionKinds: { snip, autocompact, reactive, unknown },
+        ...(snipRatio !== undefined ? { snipRatio } : {}),
+        spec: {
+            present: spec !== undefined,
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(curate !== undefined ? { compactionCurate: curate } : {}),
+            ...(dedupe !== undefined ? { compactionDedupeThreshold: dedupe } : {}),
+            ...(topK !== undefined ? { compactionRelevanceTopK: topK } : {}),
+        },
+        tripped,
+        commands: tripped.length > 0 ? [...CONTEXT_PRESSURE_COMMANDS] : [],
+    };
+}
+/** One-screen report, printed by `doctor --context-pressure`. */
+export function formatContextPressureLines(report) {
+    const lines = ["── context-pressure report ──────────────────────"];
+    lines.push(`sessions scanned:      ${report.sessionCount} (most recent)`);
+    lines.push(`truncation recoveries: ${report.truncationContinues} max_output_tokens continue(s)`);
+    const maxNote = report.maxCompactionSessionId !== undefined
+        ? `, max ${report.maxCompactionsPerSession} in ${report.maxCompactionSessionId}`
+        : "";
+    lines.push(`compaction fires:      ${report.compactionTotal} across ${report.sessionsWithCompaction} session(s) ` +
+        `(avg ${report.avgCompactionsPerSession.toFixed(1)}/session${maxNote})`);
+    if (report.snipRatio !== undefined) {
+        const k = report.compactionKinds;
+        lines.push(`snip vs autocompact:   ${k.snip} snip / ${k.autocompact} autocompact / ${k.reactive} reactive ` +
+            `(${(report.snipRatio * 100).toFixed(0)}% free snips)`);
+    }
+    else {
+        lines.push("snip vs autocompact:   not derivable (no kind-tagged compaction events)");
+    }
+    if (!report.spec.present) {
+        lines.push("spec:                  no parseable crewhaus.yaml in cwd");
+    }
+    else {
+        lines.push(`spec agent.max_tokens: ${report.spec.maxTokens !== undefined
+            ? report.spec.maxTokens
+            : "not set (runtime default 8192)"}`);
+        const curate = report.spec.compactionCurate === true
+            ? "on"
+            : report.spec.compactionCurate === false
+                ? "off (explicit)"
+                : "off (default)";
+        const curatorKnobs = [
+            ...(report.spec.compactionDedupeThreshold !== undefined
+                ? [`dedupeThreshold ${report.spec.compactionDedupeThreshold}`]
+                : []),
+            ...(report.spec.compactionRelevanceTopK !== undefined
+                ? [`relevanceTopK ${report.spec.compactionRelevanceTopK}`]
+                : []),
+        ];
+        lines.push(`spec compaction.curate: ${curate}${curatorKnobs.length > 0 ? ` (${curatorKnobs.join(", ")})` : ""}`);
+    }
+    if (report.tripped.length === 0) {
+        lines.push("pressure:              healthy — no advise thresholds tripped");
+    }
+    else {
+        lines.push(`pressure:              ${report.tripped.join(", ")} tripped`);
+        lines.push("next:");
+        for (const cmd of report.commands) {
+            lines.push(`  ${cmd}`);
+        }
+    }
+    lines.push("─────────────────────────────────────────────────");
+    return lines;
+}