harnery 0.9.0 → 0.10.0

package/dist/core/context/index.js

@@ -0,0 +1,380 @@
+/**
+ * Context continuity: durable, structured state around native harness
+ * compaction. Harnery does not decide when a harness compacts. It records
+ * context telemetry when the harness exposes it, checkpoints external work
+ * state before compaction, and renders a verified recovery briefing after it.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const CONTEXT_SCHEMA_VERSION = 1;
+export const MAX_CAPSULE_BYTES = 32 * 1024;
+const MAX_SNAPSHOT_PATHS = 15;
+const MAX_SNAPSHOT_PATH_CHARS = 500;
+/** Parse the context-window shapes exposed by current harness hook/status data. */
+export function extractContextSample(payload, options) {
+    const contextValue = payload.context_window;
+    const context = record(contextValue);
+    const usage = record(context?.current_usage) ?? record(payload.usage);
+    const windowTokens = number(context?.context_window_size) ??
+        number(context?.window_tokens) ??
+        number(payload.context_window_size) ??
+        (typeof contextValue === "number" ? finiteNonNegative(contextValue) : undefined);
+    const reportedUsed = number(context?.used_tokens) ?? number(context?.input_tokens) ?? number(payload.used_tokens);
+    const usageParts = usage
+        ? [
+            number(usage.input_tokens),
+            number(usage.cache_read_input_tokens),
+            number(usage.cache_creation_input_tokens),
+        ]
+        : [];
+    const hasUsageParts = usageParts.some((part) => part !== undefined);
+    const usedTokens = reportedUsed ??
+        (hasUsageParts
+            ? usageParts.reduce((total, part) => total + (part ?? 0), 0)
+            : undefined);
+    let usedPercent = number(context?.used_percentage) ?? number(payload.used_percentage);
+    if (usedPercent === undefined && usedTokens !== undefined && windowTokens && windowTokens > 0) {
+        usedPercent = (usedTokens / windowTokens) * 100;
+    }
+    if (usedPercent !== undefined)
+        usedPercent = clamp(usedPercent, 0, 100);
+    if (usedTokens === undefined && windowTokens === undefined && usedPercent === undefined)
+        return null;
+    const model = options.model ??
+        (typeof payload.model === "string" ? payload.model : undefined) ??
+        string(record(payload.model)?.id) ??
+        string(record(payload.model)?.display_name);
+    return {
+        session_id: options.sessionId,
+        harness: options.harness,
+        model,
+        used_tokens: usedTokens,
+        window_tokens: windowTokens,
+        used_percent: usedPercent === undefined ? undefined : round(usedPercent, 2),
+        source: options.source ?? "hook",
+        confidence: options.confidence ?? "reported",
+        observed_at: options.observedAt ?? new Date().toISOString(),
+    };
+}
+/** Persist a latest context sample. Identical measurements are a no-op. */
+export function recordContextSample(coordRoot, instanceId, sample) {
+    const current = readContextState(coordRoot, sample.session_id);
+    const state = current ?? newState({ sessionId: sample.session_id, instanceId, now: sample.observed_at });
+    const changed = !sameMeasurement(state.latest_context, sample);
+    if (!changed)
+        return { state, changed: false };
+    const next = {
+        ...state,
+        instance_id: instanceId,
+        latest_context: sample,
+        updated_at: sample.observed_at,
+    };
+    writeState(coordRoot, next);
+    return { state: next, changed: true };
+}
+/**
+ * Snapshot external work state. Repeated PreCompact events reuse the existing
+ * checkpoint until a matching recovery completes; manual checkpoints always
+ * create a new generation.
+ */
+export function checkpointContext(coordRoot, input) {
+    const now = new Date().toISOString();
+    const current = readContextState(coordRoot, input.sessionId) ??
+        newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    if (input.reason === "pre_compact" && current.phase === "checkpointed") {
+        const existing = readLatestCapsule(coordRoot, input.sessionId);
+        if (existing && current.latest_capsule) {
+            return {
+                capsule: existing,
+                path: join(coordRoot, ".harnery", current.latest_capsule),
+                state: current,
+                reused: true,
+            };
+        }
+    }
+    const heartbeat = readHeartbeat(coordRoot, input.instanceId);
+    const generation = current.generation + 1;
+    const capsule = {
+        schema_version: CONTEXT_SCHEMA_VERSION,
+        capsule_id: randomUUID(),
+        generation,
+        created_at: now,
+        reason: input.reason,
+        session: {
+            session_id: input.sessionId,
+            instance_id: input.instanceId,
+            harness: input.harness,
+            model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
+        },
+        context: current.latest_context,
+        work: buildWorkSnapshot(heartbeat, input.continuationNote),
+        repo: snapshotRepo(input.cwd),
+    };
+    const relativePath = capsuleRelativePath(input.sessionId, generation);
+    const absolutePath = join(coordRoot, ".harnery", relativePath);
+    writeBoundedJson(absolutePath, capsule, MAX_CAPSULE_BYTES);
+    const next = {
+        ...current,
+        instance_id: input.instanceId,
+        phase: "checkpointed",
+        generation,
+        latest_capsule: relativePath,
+        updated_at: now,
+        recovered_at: undefined,
+        compaction_completed_at: undefined,
+        degraded_reason: undefined,
+    };
+    writeState(coordRoot, next);
+    return { capsule, path: absolutePath, state: next, reused: false };
+}
+/** Prepare a briefing without claiming that a harness has accepted it yet. */
+export function prepareContextRecovery(coordRoot, input) {
+    const now = new Date().toISOString();
+    const current = readContextState(coordRoot, input.sessionId) ??
+        newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    const capsule = readLatestCapsule(coordRoot, input.sessionId);
+    if (!capsule) {
+        const degraded = {
+            ...current,
+            instance_id: input.instanceId,
+            phase: "degraded",
+            updated_at: now,
+            degraded_reason: "post-compaction signal arrived without a continuity checkpoint",
+        };
+        writeState(coordRoot, degraded);
+        return null;
+    }
+    const liveRepo = snapshotRepo(input.cwd);
+    const briefing = renderRecoveryBriefing(capsule, liveRepo);
+    return { state: current, capsule, briefing };
+}
+/** Advance continuity only after the harness context channel accepted the briefing. */
+export function completeContextRecovery(coordRoot, input) {
+    const now = new Date().toISOString();
+    const current = readContextState(coordRoot, input.sessionId) ??
+        newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    const recovered = {
+        ...current,
+        instance_id: input.instanceId,
+        phase: "recovered",
+        updated_at: now,
+        recovered_at: now,
+        degraded_reason: undefined,
+    };
+    writeState(coordRoot, recovered);
+    return recovered;
+}
+/** Record that the harness, rather than Harnery, reported compaction complete. */
+export function markContextCompactionCompleted(coordRoot, input) {
+    const now = input.observedAt ?? new Date().toISOString();
+    const current = readContextState(coordRoot, input.sessionId) ??
+        newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    const next = {
+        ...current,
+        instance_id: input.instanceId,
+        phase: current.latest_capsule ? current.phase : "degraded",
+        compaction_completed_at: now,
+        updated_at: now,
+        degraded_reason: current.latest_capsule
+            ? current.degraded_reason
+            : "post-compaction signal arrived without a continuity checkpoint",
+    };
+    writeState(coordRoot, next);
+    return next;
+}
+/** Convenience API for callers whose injection is synchronous and guaranteed. */
+export function recoverContext(coordRoot, input) {
+    const prepared = prepareContextRecovery(coordRoot, input);
+    if (!prepared) {
+        const state = readContextState(coordRoot, input.sessionId);
+        return { state, capsule: null, briefing: "", recovered: false };
+    }
+    const recovered = completeContextRecovery(coordRoot, input);
+    return {
+        state: recovered,
+        capsule: prepared.capsule,
+        briefing: prepared.briefing,
+        recovered: true,
+    };
+}
+export function readContextState(coordRoot, sessionId) {
+    return readJson(statePath(coordRoot, sessionId));
+}
+export function readLatestCapsule(coordRoot, sessionId) {
+    const state = readContextState(coordRoot, sessionId);
+    if (!state?.latest_capsule)
+        return null;
+    return readJson(join(coordRoot, ".harnery", state.latest_capsule));
+}
+export function renderRecoveryBriefing(capsule, liveRepo) {
+    const lines = [
+        `[harnery context continuity] Recovered generation ${capsule.generation} after native context compaction.`,
+    ];
+    if (capsule.work.task)
+        lines.push(`Task: ${capsule.work.task}`);
+    if (capsule.work.turn_summary)
+        lines.push(`Last progress: ${capsule.work.turn_summary}`);
+    if (capsule.work.continuation_note) {
+        lines.push(`Continuation note: ${capsule.work.continuation_note}`);
+    }
+    if (capsule.work.files_held.length > 0) {
+        lines.push(`Files held: ${capsule.work.files_held.join(", ")}`);
+    }
+    if (capsule.work.last_tool) {
+        lines.push(`Last tool: ${capsule.work.last_tool}${capsule.work.last_tool_target ? ` (${capsule.work.last_tool_target})` : ""}`);
+    }
+    const drift = [];
+    if (capsule.repo.branch && liveRepo.branch && capsule.repo.branch !== liveRepo.branch) {
+        drift.push(`branch changed ${capsule.repo.branch} -> ${liveRepo.branch}`);
+    }
+    if (capsule.repo.head && liveRepo.head && capsule.repo.head !== liveRepo.head) {
+        drift.push(`HEAD changed ${capsule.repo.head.slice(0, 8)} -> ${liveRepo.head.slice(0, 8)}`);
+    }
+    const beforeDirty = new Set(capsule.repo.dirty_paths);
+    const afterDirty = new Set(liveRepo.dirty_paths);
+    const added = [...afterDirty].filter((path) => !beforeDirty.has(path));
+    const cleared = [...beforeDirty].filter((path) => !afterDirty.has(path));
+    if (added.length > 0)
+        drift.push(`new dirty paths: ${added.slice(0, 5).join(", ")}`);
+    if (cleared.length > 0)
+        drift.push(`paths no longer dirty: ${cleared.slice(0, 5).join(", ")}`);
+    lines.push(drift.length > 0
+        ? `Repository changed since checkpoint: ${drift.join("; ")}. Re-check before editing.`
+        : "Repository state matches the checkpoint.");
+    return lines.join("\n");
+}
+export function snapshotRepo(cwd) {
+    const root = git(cwd, ["rev-parse", "--show-toplevel"]);
+    if (!root)
+        return { cwd, dirty_paths: [] };
+    const status = git(cwd, ["status", "--porcelain=v1", "--untracked-files=normal"]);
+    const dirty = status
+        ? status
+            .split("\n")
+            .map((line) => line.trimEnd())
+            .filter(Boolean)
+            .map((line) => clampString(line.slice(3).trim(), MAX_SNAPSHOT_PATH_CHARS) ?? "")
+            .filter(Boolean)
+        : [];
+    return {
+        cwd: clampString(cwd, 2_000) ?? cwd,
+        root: clampString(root, 2_000),
+        branch: git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]),
+        head: git(cwd, ["rev-parse", "HEAD"]),
+        dirty_paths: dirty.slice(0, MAX_SNAPSHOT_PATHS),
+        ...(dirty.length > MAX_SNAPSHOT_PATHS ? { dirty_paths_truncated: true } : {}),
+    };
+}
+function buildWorkSnapshot(heartbeat, continuationNote) {
+    const files = Array.isArray(heartbeat?.files_touched)
+        ? heartbeat.files_touched
+            .map((path) => clampString(path, MAX_SNAPSHOT_PATH_CHARS) ?? "")
+            .filter(Boolean)
+        : [];
+    return {
+        task: clampString(heartbeat?.task, 1_000),
+        turn_summary: clampString(heartbeat?.turn_summary, 3_000),
+        continuation_note: clampString(continuationNote, 3_000),
+        files_held: files.slice(0, MAX_SNAPSHOT_PATHS),
+        ...(files.length > MAX_SNAPSHOT_PATHS ? { files_held_truncated: true } : {}),
+        last_tool: clampString(heartbeat?.last_tool, 200),
+        last_tool_target: clampString(heartbeat?.last_tool_target, 1_000),
+    };
+}
+function readHeartbeat(coordRoot, instanceId) {
+    return readJson(join(coordRoot, ".harnery", "active", `${instanceId}.json`));
+}
+function newState(input) {
+    return {
+        schema_version: CONTEXT_SCHEMA_VERSION,
+        session_id: input.sessionId,
+        instance_id: input.instanceId,
+        phase: "observing",
+        generation: 0,
+        updated_at: input.now,
+    };
+}
+function writeState(coordRoot, state) {
+    writeBoundedJson(statePath(coordRoot, state.session_id), state, MAX_CAPSULE_BYTES);
+}
+function statePath(coordRoot, sessionId) {
+    return join(contextDir(coordRoot, sessionId), "state.json");
+}
+function capsuleRelativePath(sessionId, generation) {
+    return join("context", sessionKey(sessionId), "capsules", `${String(generation).padStart(6, "0")}.json`);
+}
+function contextDir(coordRoot, sessionId) {
+    return join(coordRoot, ".harnery", "context", sessionKey(sessionId));
+}
+function sessionKey(sessionId) {
+    return createHash("sha256").update(sessionId).digest("hex").slice(0, 24);
+}
+function writeBoundedJson(path, value, maxBytes) {
+    const text = `${JSON.stringify(value, null, 2)}\n`;
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes > maxBytes) {
+        throw new Error(`context continuity record exceeds ${maxBytes} bytes (${bytes})`);
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.tmp.${process.pid}.${randomUUID()}`;
+    writeFileSync(temp, text, { encoding: "utf8", mode: 0o600 });
+    renameSync(temp, path);
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function git(cwd, args) {
+    try {
+        const result = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 2_000 });
+        return result.status === 0 ? result.stdout.trim() || undefined : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sameMeasurement(a, b) {
+    if (!a)
+        return false;
+    return (a.harness === b.harness &&
+        a.model === b.model &&
+        a.used_tokens === b.used_tokens &&
+        a.window_tokens === b.window_tokens &&
+        a.used_percent === b.used_percent &&
+        a.source === b.source &&
+        a.confidence === b.confidence);
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function string(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function number(value) {
+    return typeof value === "number" ? finiteNonNegative(value) : undefined;
+}
+function finiteNonNegative(value) {
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function round(value, precision) {
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+}
+function clampString(value, max) {
+    if (!value)
+        return undefined;
+    return value.length <= max ? value : value.slice(0, max);
+}

package/dist/core/harnesses/bench.d.ts

@@ -0,0 +1,29 @@
+import type { HarnessRegistry } from "./registry.js";
+import type { CapabilitySupport, HarnessCapabilityDimension, HarnessId } from "./types.js";
+export type BenchVerdict = "supported" | "partial" | "unsupported" | "not_applicable" | "unknown" | "skipped" | "drift";
+export type BenchDimension = "registration" | "binary" | HarnessCapabilityDimension;
+export interface BenchResult {
+    harness: HarnessId;
+    dimension: BenchDimension;
+    declared: CapabilitySupport | "not_applicable";
+    observed: BenchVerdict;
+    verdict: BenchVerdict;
+    note?: string;
+}
+export interface HarnessBenchReport {
+    generatedAt: string;
+    mode: "offline";
+    harnesses: HarnessId[];
+    results: BenchResult[];
+    summary: Record<BenchVerdict, number>;
+    drift: boolean;
+    skipped: boolean;
+}
+export interface HarnessBenchOptions {
+    harnesses?: readonly string[];
+    dimensions?: readonly HarnessCapabilityDimension[];
+    /** Test seam and alternate host probe. A null version means unavailable. */
+    versionProbe?: (binary: string) => string | null;
+}
+export declare function runHarnessBench(registry: HarnessRegistry, opts?: HarnessBenchOptions): HarnessBenchReport;
+//# sourceMappingURL=bench.d.ts.map

package/dist/core/harnesses/bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench.d.ts","sourceRoot":"","sources":["../../../src/core/harnesses/bench.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,iBAAiB,EAEjB,0BAA0B,EAC1B,SAAS,EACV,MAAM,YAAY,CAAC;AAGpB,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,SAAS,GACT,aAAa,GACb,gBAAgB,GAChB,SAAS,GACT,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,QAAQ,GAAG,0BAA0B,CAAC;AAEpF,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IAC/C,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,EAAE,CAAC;IACvB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,SAAS,0BAA0B,EAAE,CAAC;IACnD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAClD;AAYD,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,eAAe,EACzB,IAAI,GAAE,mBAAwB,GAC7B,kBAAkB,CAuDpB"}

package/dist/core/harnesses/bench.js

@@ -0,0 +1,151 @@
+import { spawnSync } from "node:child_process";
+import { HARNESS_SPECS } from "../hooks/harness/events.js";
+import { HARNESS_CAPABILITY_DIMENSIONS } from "./types.js";
+const EMPTY_SUMMARY = {
+    supported: 0,
+    partial: 0,
+    unsupported: 0,
+    not_applicable: 0,
+    unknown: 0,
+    skipped: 0,
+    drift: 0,
+};
+export function runHarnessBench(registry, opts = {}) {
+    const ids = opts.harnesses?.length ? [...opts.harnesses] : registry.ids();
+    const dimensions = opts.dimensions?.length
+        ? [...new Set(opts.dimensions)]
+        : [...HARNESS_CAPABILITY_DIMENSIONS];
+    const versionProbe = opts.versionProbe ?? probeVersion;
+    const results = [];
+    for (const id of ids) {
+        const adapter = registry.require(id);
+        results.push({
+            harness: id,
+            dimension: "registration",
+            declared: "supported",
+            observed: "supported",
+            verdict: "supported",
+            note: `${adapter.profile.integrationMode}; ${adapter.profile.authModel}`,
+        });
+        const version = versionProbe(adapter.profile.binary);
+        results.push({
+            harness: id,
+            dimension: "binary",
+            declared: "supported",
+            observed: version ? "supported" : "skipped",
+            verdict: version ? "supported" : "skipped",
+            note: version ?? `${adapter.profile.binary} not found on PATH`,
+        });
+        const observations = observeAdapter(adapter);
+        for (const dimension of dimensions) {
+            const claim = adapter.profile.capabilities[dimension];
+            const observed = observations[dimension];
+            results.push({
+                harness: id,
+                dimension,
+                declared: claim.support,
+                observed,
+                verdict: reconcile(claim.support, observed),
+                note: claim.note,
+            });
+        }
+    }
+    const summary = { ...EMPTY_SUMMARY };
+    for (const result of results)
+        summary[result.verdict]++;
+    return {
+        generatedAt: new Date().toISOString(),
+        mode: "offline",
+        harnesses: ids,
+        results,
+        summary,
+        drift: summary.drift > 0,
+        skipped: summary.skipped > 0,
+    };
+}
+function observeAdapter(adapter) {
+    const profile = adapter.profile;
+    const effort = profile.effortValues[0];
+    const request = {
+        prompt: "HARNERY_BENCH_PROMPT",
+        model: "harnery-bench-model",
+        effort,
+        timeoutMs: 1_000,
+        maxTurns: 7,
+        cwd: "/harnery-bench",
+    };
+    let argv = [];
+    let planningFailed = false;
+    try {
+        argv = adapter.buildInvocation(request, "/harnery-bench/final.txt").argv;
+    }
+    catch {
+        planningFailed = true;
+    }
+    let normalized = null;
+    try {
+        normalized = adapter.normalizeResult(adapter.fixture.raw);
+    }
+    catch {
+        normalized = null;
+    }
+    const fixture = adapter.fixture.expected;
+    const finalMatches = normalized?.ok === fixture.ok && normalized?.text === fixture.text;
+    const sessionObserved = normalized?.sessionId !== undefined ? "supported" : "unsupported";
+    const costObserved = normalized?.costUsd !== undefined ? "supported" : "unsupported";
+    const hookSpec = adapter.profile.id in HARNESS_SPECS
+        ? HARNESS_SPECS[adapter.profile.id]
+        : undefined;
+    const hookSubcommands = new Set(hookSpec?.events.map((event) => event.subcommand) ?? []);
+    return {
+        invocation: !planningFailed && argv[0] === profile.binary && argv.includes(request.prompt)
+            ? "supported"
+            : "unsupported",
+        modelSelection: !planningFailed && argv.includes(request.model ?? "") ? "supported" : "unsupported",
+        effortSelection: effort === undefined
+            ? "unsupported"
+            : !planningFailed && argv.some((arg) => arg.includes(effort))
+                ? "supported"
+                : "unsupported",
+        maxTurns: !planningFailed && argv.includes(String(request.maxTurns)) ? "supported" : "unsupported",
+        finalResult: finalMatches ? "supported" : "unsupported",
+        sessionId: sessionObserved === "supported" && normalized?.sessionId !== fixture.sessionId
+            ? "unsupported"
+            : sessionObserved,
+        cost: costObserved === "supported" && normalized?.costUsd !== fixture.costUsd
+            ? "unsupported"
+            : costObserved,
+        toolEvidence: normalized && "toolEvidence" in normalized ? "supported" : "unsupported",
+        policyMapping: "unknown",
+        interruption: "unknown",
+        streaming: "unknown",
+        steering: "unknown",
+        resume: "unknown",
+        images: "unknown",
+        contextTelemetry: "unknown",
+        preCompactionSignal: hookSpec
+            ? hookSubcommands.has("pre-compact")
+                ? "supported"
+                : "unsupported"
+            : "unknown",
+        postCompactionSignal: hookSpec
+            ? hookSubcommands.has("post-compact") ||
+                (adapter.profile.id === "claude-code" && hookSubcommands.has("session-start"))
+                ? "supported"
+                : "unsupported"
+            : "unknown",
+        compaction: "unknown",
+    };
+}
+function reconcile(declared, observed) {
+    if (observed === "unknown" || observed === "skipped" || observed === "not_applicable") {
+        return observed;
+    }
+    return declared === observed ? observed : "drift";
+}
+function probeVersion(binary) {
+    const result = spawnSync(binary, ["--version"], { encoding: "utf8", timeout: 5_000 });
+    if (result.error || result.status !== 0)
+        return null;
+    return (result.stdout || result.stderr).trim().split("\n")[0] || "installed";
+}

package/dist/core/harnesses/index.d.ts

@@ -0,0 +1,9 @@
+export type { Spawner, SpawnRequest, SpawnResult } from "../workflow/types.js";
+export type { BenchDimension, BenchResult, BenchVerdict, HarnessBenchOptions, HarnessBenchReport, } from "./bench.js";
+export { runHarnessBench } from "./bench.js";
+export type { BuiltinHarnessId } from "./profiles.js";
+export { BUILTIN_HARNESS_IDS, BUILTIN_HARNESS_PROFILES, builtinHarnessProfile, isBuiltinHarness, validateHarnessEffort, } from "./profiles.js";
+export { createBuiltinHarnessRegistry, HarnessRegistry } from "./registry.js";
+export type { CapabilityClaim, CapabilitySupport, HarnessAdapter, HarnessBenchFixture, HarnessCapabilities, HarnessCapabilityDimension, HarnessId, HarnessInvocation, HarnessProfile, HarnessRawResult, } from "./types.js";
+export { HARNESS_CAPABILITY_DIMENSIONS } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/harnesses/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/harnesses/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC/E,YAAY,EACV,cAAc,EACd,WAAW,EACX,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,4BAA4B,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC9E,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC"}

package/dist/core/harnesses/index.js

@@ -0,0 +1,4 @@
+export { runHarnessBench } from "./bench.js";
+export { BUILTIN_HARNESS_IDS, BUILTIN_HARNESS_PROFILES, builtinHarnessProfile, isBuiltinHarness, validateHarnessEffort, } from "./profiles.js";
+export { createBuiltinHarnessRegistry, HarnessRegistry } from "./registry.js";
+export { HARNESS_CAPABILITY_DIMENSIONS } from "./types.js";

package/dist/core/harnesses/profiles.d.ts

@@ -0,0 +1,62 @@
+import type { HarnessCapabilities, HarnessProfile } from "./types.js";
+/** The one built-in profile catalog. Adding a fourth harness starts here; CLI
+ * choices, doctor metadata, workflow dispatch, and the bench derive from it. */
+export declare const BUILTIN_HARNESS_PROFILES: {
+    readonly "claude-code": {
+        readonly id: "claude-code";
+        readonly displayName: "Claude Code";
+        readonly binary: "claude";
+        readonly installHint: "npm install -g @anthropic-ai/claude-code";
+        readonly loginHint: "run `claude` and use /login";
+        readonly apiKeyEnv: "ANTHROPIC_API_KEY";
+        readonly integrationMode: "cli-subprocess";
+        readonly authModel: "own-auth";
+        readonly modelFamily: "claude";
+        readonly effortValues: readonly ["low", "medium", "high", "xhigh", "max"];
+        readonly verified: {
+            readonly date: "2026-07-20";
+            readonly version: "current CLI contract";
+        };
+        readonly capabilities: HarnessCapabilities;
+    };
+    readonly codex: {
+        readonly id: "codex";
+        readonly displayName: "Codex";
+        readonly binary: "codex";
+        readonly installHint: "npm install -g @openai/codex";
+        readonly loginHint: "codex login";
+        readonly apiKeyEnv: "OPENAI_API_KEY";
+        readonly integrationMode: "cli-subprocess";
+        readonly authModel: "own-auth";
+        readonly modelFamily: "gpt";
+        readonly effortValues: readonly ["none", "minimal", "low", "medium", "high", "xhigh"];
+        readonly verified: {
+            readonly date: "2026-07-21";
+            readonly version: "codex-cli 0.145.0-alpha.18";
+        };
+        readonly capabilities: HarnessCapabilities;
+    };
+    readonly cursor: {
+        readonly id: "cursor";
+        readonly displayName: "Cursor Agent";
+        readonly binary: "cursor-agent";
+        readonly installHint: "curl https://cursor.com/install -fsS | bash";
+        readonly loginHint: "cursor-agent login";
+        readonly apiKeyEnv: "CURSOR_API_KEY";
+        readonly integrationMode: "cli-subprocess";
+        readonly authModel: "own-auth";
+        readonly modelFamily: "multi";
+        readonly effortValues: readonly [];
+        readonly verified: {
+            readonly date: "2026-07-21";
+            readonly version: "2026.07.16-899851b";
+        };
+        readonly capabilities: HarnessCapabilities;
+    };
+};
+export type BuiltinHarnessId = keyof typeof BUILTIN_HARNESS_PROFILES;
+export declare const BUILTIN_HARNESS_IDS: readonly ("cursor" | "claude-code" | "codex")[];
+export declare function isBuiltinHarness(id: string): id is BuiltinHarnessId;
+export declare function builtinHarnessProfile(id: string): HarnessProfile | undefined;
+export declare function validateHarnessEffort(id: string, effort: string | undefined): void;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/core/harnesses/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/core/harnesses/profiles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,mBAAmB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA+BvF;gFACgF;AAChF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiFc,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAErE,eAAO,MAAM,mBAAmB,iDAE/B,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,gBAAgB,CAEnE;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE5E;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAUlF"}