harnery 0.35.0 → 0.37.0

package/dist/core/resources/service.js

@@ -0,0 +1,292 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
+import { hostname, platform } from "node:os";
+import { resolve } from "node:path";
+import { checkPidToken, processStartToken } from "../agents/state/proc-start.js";
+import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.js";
+import { RESOURCE_SERVICE_STATUS_SCHEMA_VERSION, } from "./contract.js";
+import { sampleResources } from "./sampler.js";
+import { readResourceServiceStatus } from "./service-status.js";
+import { resourcePaths, writePrivateJsonAtomic } from "./storage.js";
+export const RESOURCE_SERVICE_DEFAULT_INTERVAL_MS = 2_000;
+const RESOURCE_SERVICE_MIN_INTERVAL_MS = 500;
+const RESOURCE_SERVICE_MAX_INTERVAL_MS = 60_000;
+export async function spawnResourceService(coordRootRaw, options = {}) {
+    const coordRoot = resolve(coordRootRaw);
+    const current = readResourceServiceStatus(coordRoot);
+    if (current.running) {
+        throw new Error(`resource observer is already running under pid ${current.record?.pid}`);
+    }
+    const intervalMs = normalizeInterval(options.intervalMs);
+    const paths = resourcePaths(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    rmSync(paths.stop, { force: true });
+    const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+    if (!existsSync(harnBin))
+        throw new Error(`cannot find harn executable at ${harnBin}`);
+    let spawnError;
+    const child = spawn(harnBin, ["resources", "service", "daemon", "--root", coordRoot, "--interval-ms", String(intervalMs)], {
+        cwd: coordRoot,
+        detached: true,
+        stdio: ["ignore", "ignore", "ignore"],
+        env: {
+            ...process.env,
+            HARNERY_COORD_ROOT_OVERRIDE: coordRoot,
+            HARNERY_OUTPUT_SESSION_TEE: "0",
+        },
+    });
+    child.once("error", (error) => {
+        spawnError = error;
+    });
+    child.unref();
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline) {
+        await delay(50);
+        if (spawnError)
+            throw spawnError;
+        const status = readResourceServiceStatus(coordRoot);
+        if (status.running && status.record?.pid === child.pid)
+            return status;
+        if (child.exitCode !== null)
+            break;
+    }
+    throw new Error(`resource observer failed to start; inspect ${paths.service}`);
+}
+export async function ensureResourceServiceRunning(coordRoot) {
+    const status = readResourceServiceStatus(coordRoot);
+    if (status.running)
+        return { state: "running", status };
+    if (platform() !== "linux") {
+        return {
+            state: "unsupported",
+            status,
+            error: `resource observer does not yet support ${platform()}`,
+        };
+    }
+    try {
+        const started = await spawnResourceService(coordRoot);
+        return { state: "started", status: started };
+    }
+    catch (error) {
+        return {
+            state: "unavailable",
+            status: readResourceServiceStatus(coordRoot),
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function requestResourceServiceStop(coordRootRaw) {
+    const coordRoot = resolve(coordRootRaw);
+    const paths = resourcePaths(coordRoot);
+    const status = readResourceServiceStatus(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    writePrivateJsonAtomic(paths.stop, {
+        requested_at: new Date().toISOString(),
+        requested_by_pid: process.pid,
+    });
+    if (status.running && status.record?.host === hostname()) {
+        try {
+            process.kill(status.record.pid, "SIGTERM");
+        }
+        catch {
+            // The durable stop file handles a racing exit.
+        }
+    }
+    return readResourceServiceStatus(coordRoot);
+}
+export async function runResourceService(input) {
+    const coordRoot = resolve(input.coordRoot);
+    const paths = resourcePaths(coordRoot);
+    const intervalMs = normalizeInterval(input.intervalMs);
+    const now = input.now ?? (() => new Date());
+    const sample = input.sample ?? sampleResources;
+    const wait = input.wait ?? delay;
+    const lease = acquireLease(coordRoot, now());
+    rmSync(paths.stop, { force: true });
+    const startedAt = now().toISOString();
+    const daemonStartToken = processStartToken(process.pid);
+    const status = {
+        schema_version: RESOURCE_SERVICE_STATUS_SCHEMA_VERSION,
+        pid: process.pid,
+        ...(daemonStartToken ? { start_token: daemonStartToken } : {}),
+        host: hostname(),
+        nonce: lease.nonce,
+        state: "starting",
+        started_at: startedAt,
+        heartbeat_at: startedAt,
+        interval_ms: intervalMs,
+        sample_count: 0,
+    };
+    let stopping = false;
+    let previous;
+    const writeStatus = () => {
+        status.heartbeat_at = now().toISOString();
+        writePrivateJsonAtomic(paths.service, status);
+    };
+    const requestStop = () => {
+        stopping = true;
+        status.state = "stopping";
+        writeStatus();
+    };
+    process.on("SIGINT", requestStop);
+    process.on("SIGTERM", requestStop);
+    status.state = "running";
+    writeStatus();
+    log(coordRoot, "resource_observer.started", { pid: process.pid, interval_ms: intervalMs });
+    try {
+        while (!stopping && !existsSync(paths.stop)) {
+            const cycleStarted = Date.now();
+            try {
+                const result = sample(coordRoot, previous);
+                previous = result.state;
+                writePrivateJsonAtomic(paths.snapshot, result.snapshot);
+                status.sample_count += 1;
+                status.last_sample_at = result.snapshot.sampled_at;
+                status.last_error_code = undefined;
+                log(coordRoot, "resource_observer.sample", {
+                    sample_count: status.sample_count,
+                    cpu_percent: result.snapshot.machine.cpu_percent ?? -1,
+                    memory_percent: result.snapshot.machine.memory_percent ?? -1,
+                    visible_processes: result.snapshot.visible_process_count,
+                    unattributed_processes: result.snapshot.unattributed_process_count,
+                    duration_ms: result.snapshot.sample_duration_ms,
+                    collector_cpu_ms: result.snapshot.collector_cpu_ms,
+                });
+            }
+            catch (error) {
+                status.last_error_code = resourceErrorCode(error);
+                status.state = "error";
+                log(coordRoot, "resource_observer.sample_error", { reason_code: status.last_error_code }, error);
+            }
+            if (status.state === "error")
+                status.state = "running";
+            writeStatus();
+            if (input.maxSamples !== undefined && status.sample_count >= input.maxSamples)
+                break;
+            const remaining = Math.max(0, intervalMs - (Date.now() - cycleStarted));
+            if (!stopping && !existsSync(paths.stop))
+                await wait(remaining);
+        }
+    }
+    finally {
+        process.off("SIGINT", requestStop);
+        process.off("SIGTERM", requestStop);
+        status.state = "stopped";
+        status.stopped_at = now().toISOString();
+        writeStatus();
+        log(coordRoot, "resource_observer.stopped", { sample_count: status.sample_count });
+        try {
+            await closeProcessLoggers();
+        }
+        finally {
+            releaseLease(paths.lease, lease.nonce);
+        }
+    }
+    return status;
+}
+function acquireLease(coordRoot, now) {
+    const paths = resourcePaths(coordRoot);
+    mkdirSync(paths.root, { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const daemonStartToken = processStartToken(process.pid);
+        const lease = {
+            pid: process.pid,
+            ...(daemonStartToken ? { start_token: daemonStartToken } : {}),
+            host: hostname(),
+            nonce: randomUUID(),
+            created_at: now.toISOString(),
+        };
+        try {
+            const fd = openSync(paths.lease, "wx", 0o600);
+            try {
+                writeFileSync(fd, `${JSON.stringify(lease)}\n`, "utf8");
+            }
+            finally {
+                closeSync(fd);
+            }
+            return lease;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const existing = readLease(paths.lease);
+            if (existing && leaseIsLive(existing)) {
+                throw new Error(`resource observer lease is held by pid ${existing.pid}`);
+            }
+            try {
+                unlinkSync(paths.lease);
+            }
+            catch {
+                // A concurrent starter may have replaced or removed the stale lease.
+            }
+        }
+    }
+    throw new Error("resource observer could not acquire its singleton lease");
+}
+function releaseLease(path, nonce) {
+    const current = readLease(path);
+    if (current?.nonce !== nonce)
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // A missing lease is already released.
+    }
+}
+function readLease(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && Number.isInteger(value.pid) && typeof value.nonce === "string"
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaseIsLive(lease) {
+    if (lease.host !== hostname())
+        return true;
+    try {
+        process.kill(lease.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== "EPERM")
+            return false;
+    }
+    return checkPidToken(lease.pid, lease.start_token) !== "mismatch";
+}
+function log(coordRoot, event, fields, error) {
+    try {
+        const logger = processLogger(coordRoot, "resource-observer");
+        if (error)
+            logger.error(event, legacyLogFields(fields), error);
+        else
+            logger.info(event, legacyLogFields(fields));
+    }
+    catch {
+        // Observability must never break the observer loop.
+    }
+}
+function resourceErrorCode(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/procfs|\/proc\//i.test(message))
+        return "procfs_read_failed";
+    if (/permission|EACCES|EPERM/i.test(message))
+        return "permission_denied";
+    return "sample_failed";
+}
+function normalizeInterval(value) {
+    const interval = value ?? RESOURCE_SERVICE_DEFAULT_INTERVAL_MS;
+    if (!Number.isFinite(interval) ||
+        interval < RESOURCE_SERVICE_MIN_INTERVAL_MS ||
+        interval > RESOURCE_SERVICE_MAX_INTERVAL_MS) {
+        throw new Error(`resource observer interval must be ${RESOURCE_SERVICE_MIN_INTERVAL_MS}-${RESOURCE_SERVICE_MAX_INTERVAL_MS} ms`);
+    }
+    return Math.round(interval);
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}

package/dist/core/resources/storage.d.ts

@@ -0,0 +1,13 @@
+import type { ResourceServiceStatusRecord, ResourceSnapshot } from "./contract.js";
+export { writePrivateJsonAtomic } from "../storage/atomic-json.js";
+export interface ResourcePaths {
+    root: string;
+    service: string;
+    lease: string;
+    stop: string;
+    snapshot: string;
+}
+export declare function resourcePaths(coordRootRaw: string): ResourcePaths;
+export declare function readResourceSnapshot(coordRoot: string): ResourceSnapshot | undefined;
+export declare function readResourceServiceRecord(coordRoot: string): ResourceServiceStatusRecord | undefined;
+//# sourceMappingURL=storage.d.ts.map

package/dist/core/resources/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/core/resources/storage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,2BAA2B,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa,CASjE;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEpF;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,GAChB,2BAA2B,GAAG,SAAS,CAEzC"}

package/dist/core/resources/storage.js

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+export { writePrivateJsonAtomic } from "../storage/atomic-json.js";
+export function resourcePaths(coordRootRaw) {
+    const root = join(resolve(coordRootRaw), ".harnery", "resources");
+    return {
+        root,
+        service: join(root, "service.json"),
+        lease: join(root, "service.lease.json"),
+        stop: join(root, "stop.json"),
+        snapshot: join(root, "snapshot.json"),
+    };
+}
+export function readResourceSnapshot(coordRoot) {
+    return readJson(resourcePaths(coordRoot).snapshot);
+}
+export function readResourceServiceRecord(coordRoot) {
+    return readJson(resourcePaths(coordRoot).service);
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return value && typeof value === "object" ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/semantic/adapters.d.ts

@@ -1,12 +1,7 @@
 import type { TSchema } from "@sinclair/typebox";
-import { type SemanticConfiguredModel, type SemanticHarness } from "./contract.js";
+import { type SemanticHarness, type SemanticUsageReceiptV1 } from "./contract.js";
+import { type SemanticReaderRoute } from "./routes.js";
 import type { SemanticReaderResolution } from "./storage.js";
-export interface SemanticReaderRoute {
-    harness: SemanticHarness;
-    binary: string;
-    configured_model: SemanticConfiguredModel;
-    invocation_model_id: string;
-}
 export interface SemanticAdapterSuccess {
     ok: true;
     text: string;
@@ -14,6 +9,7 @@ export interface SemanticAdapterSuccess {
     model_attestation: "verified" | "requested-only";
     duration_ms: number;
     output_bytes: number;
+    usage: SemanticUsageReceiptV1;
 }
 export interface SemanticAdapterFailure {
     ok: false;
@@ -21,6 +17,7 @@ export interface SemanticAdapterFailure {
     resolved_model_id?: string;
     model_attestation?: "verified" | "requested-only";
     duration_ms: number;
+    usage: SemanticUsageReceiptV1;
 }
 export type SemanticAdapterResult = SemanticAdapterSuccess | SemanticAdapterFailure;
 export interface SemanticAdapter {
@@ -28,7 +25,13 @@ export interface SemanticAdapter {
     discover(now?: () => Date): SemanticReaderResolution;
     invoke(prompt: string, timeoutMs?: number, responseSchema?: TSchema): Promise<SemanticAdapterResult>;
 }
-export declare const SEMANTIC_READER_ROUTES: Record<SemanticHarness, SemanticReaderRoute>;
+export { SEMANTIC_READER_ROUTES, type SemanticReaderRoute } from "./routes.js";
 export declare function createSemanticAdapters(): Record<SemanticHarness, SemanticAdapter>;
 export declare function discoverSemanticReaders(adapters?: Record<SemanticHarness, SemanticAdapter>): Record<SemanticHarness, SemanticReaderResolution>;
+export interface ParsedSemanticHarnessOutput {
+    text: string;
+    executedModelId?: string;
+    usage?: SemanticUsageReceiptV1;
+}
+export declare function parseSemanticHarnessOutput(harness: SemanticHarness, stdout: string, outputFileText?: string): ParsedSemanticHarnessOutput;
 //# sourceMappingURL=adapters.d.ts.map

package/dist/core/semantic/adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/adapters.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EAErB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAM7D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,UAAU,GAAG,gBAAgB,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,WAAW,EACP,qBAAqB,GACrB,4BAA4B,GAC5B,mBAAmB,GACnB,gBAAgB,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,GAAG,wBAAwB,CAAC;IACrD,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC;AAED,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,eAAe,EAAE,mBAAmB,CAmB/E,CAAC;AAEF,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAMjF;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,GAAE,MAAM,CAAC,eAAe,EAAE,eAAe,CAA4B,GAC5E,MAAM,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAMnD"}
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../../src/core/semantic/adapters.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AACvB,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAW7D,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,UAAU,GAAG,gBAAgB,CAAC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,sBAAsB,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,WAAW,EACP,qBAAqB,GACrB,4BAA4B,GAC5B,mBAAmB,GACnB,gBAAgB,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,sBAAsB,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,GAAG,wBAAwB,CAAC;IACrD,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,OAAO,GACvB,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC;AAED,OAAO,EAAE,sBAAsB,EAAE,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE/E,wBAAgB,sBAAsB,IAAI,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,CAMjF;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,GAAE,MAAM,CAAC,eAAe,EAAE,eAAe,CAA4B,GAC5E,MAAM,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAMnD;AAwKD,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,GACtB,2BAA2B,CAsC7B"}

package/dist/core/semantic/adapters.js

@@ -5,29 +5,12 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { whichBin } from "../../lib/headless/index.js";
 import { SemanticModelReplyV2Schema, } from "./contract.js";
+import { SEMANTIC_READER_ROUTES } from "./routes.js";
+import { estimateVisibleSemanticUsage, nativeSemanticUsage, unreportedSemanticUsage, } from "./usage.js";
 const execFileAsync = promisify(execFile);
 const MAX_OUTPUT_BYTES = 512 * 1024;
 const DEFAULT_TIMEOUT_MS = 90_000;
-export const SEMANTIC_READER_ROUTES = {
-    "claude-code": {
-        harness: "claude-code",
-        binary: "claude",
-        configured_model: "haiku-4.5",
-        invocation_model_id: "claude-haiku-4-5-20251001",
-    },
-    codex: {
-        harness: "codex",
-        binary: "codex",
-        configured_model: "gpt-5.6-luna",
-        invocation_model_id: "gpt-5.6-luna",
-    },
-    cursor: {
-        harness: "cursor",
-        binary: "cursor-agent",
-        configured_model: "composer-2.5",
-        invocation_model_id: "composer-2.5",
-    },
-};
+export { SEMANTIC_READER_ROUTES } from "./routes.js";
 export function createSemanticAdapters() {
     return {
         "claude-code": createAdapter(SEMANTIC_READER_ROUTES["claude-code"]),
@@ -62,7 +45,12 @@ function createAdapter(route) {
         },
         async invoke(prompt, timeoutMs = DEFAULT_TIMEOUT_MS, responseSchema = SemanticModelReplyV2Schema) {
             if (!whichBin(route.binary)) {
-                return { ok: false, reason_code: "harness_unavailable", duration_ms: 0 };
+                return {
+                    ok: false,
+                    reason_code: "harness_unavailable",
+                    duration_ms: 0,
+                    usage: unreportedSemanticUsage(),
+                };
             }
             return await invokeRoute(route, prompt, timeoutMs, responseSchema);
         },
@@ -81,17 +69,21 @@ async function invokeRoute(route, prompt, timeoutMs, responseSchema) {
         });
         pending.child.stdin?.end();
         const { stdout } = await pending;
-        const raw = invocation.outputFile ? readFileSync(invocation.outputFile, "utf8") : stdout;
-        const parsed = parseHarnessOutput(route.harness, raw);
+        const outputFileText = invocation.outputFile
+            ? readFileSync(invocation.outputFile, "utf8")
+            : undefined;
+        const parsed = parseSemanticHarnessOutput(route.harness, stdout, outputFileText);
         if (!parsed.text.trim())
             throw new Error("empty semantic response");
-        if (parsed.executedModelId && parsed.executedModelId !== route.invocation_model_id) {
+        if (parsed.executedModelId &&
+            !modelIdsMatch(parsed.executedModelId, route.invocation_model_id)) {
             return {
                 ok: false,
                 reason_code: "model_mismatch",
                 resolved_model_id: parsed.executedModelId,
                 model_attestation: "verified",
                 duration_ms: Date.now() - started,
+                usage: parsed.usage ?? unreportedSemanticUsage(),
             };
         }
         return {
@@ -101,6 +93,7 @@ async function invokeRoute(route, prompt, timeoutMs, responseSchema) {
             model_attestation: parsed.executedModelId ? "verified" : "requested-only",
             duration_ms: Date.now() - started,
             output_bytes: Buffer.byteLength(parsed.text),
+            usage: parsed.usage ?? estimateVisibleSemanticUsage(prompt, parsed.text),
         };
     }
     catch (error) {
@@ -110,6 +103,7 @@ async function invokeRoute(route, prompt, timeoutMs, responseSchema) {
             resolved_model_id: route.invocation_model_id,
             model_attestation: "requested-only",
             duration_ms: Date.now() - started,
+            usage: unreportedSemanticUsage(),
         };
     }
     finally {
@@ -156,6 +150,7 @@ function buildInvocation(route, prompt, dir, responseSchema) {
                 "--ephemeral",
                 "--ignore-user-config",
                 "--ignore-rules",
+                "--json",
                 "--output-last-message",
                 outputFile,
                 "--cd",
@@ -169,7 +164,7 @@ function buildInvocation(route, prompt, dir, responseSchema) {
             "-p",
             prompt,
             "--output-format",
-            "json",
+            "stream-json",
             "--mode",
             "ask",
             "--sandbox",
@@ -180,24 +175,167 @@ function buildInvocation(route, prompt, dir, responseSchema) {
         ],
     };
 }
-function parseHarnessOutput(harness, raw) {
+export function parseSemanticHarnessOutput(harness, stdout, outputFileText) {
     if (harness === "codex")
-        return { text: raw };
+        return parseCodexOutput(stdout, outputFileText);
+    if (harness === "cursor")
+        return parseCursorOutput(stdout);
     try {
-        const envelope = JSON.parse(raw);
+        const envelope = JSON.parse(stdout);
         if (envelope.is_error)
             throw new Error("harness returned an error envelope");
+        const structured = envelope.structured_output;
+        const modelUsage = objectValue(envelope.modelUsage) ?? objectValue(envelope.model_usage);
+        const modelUsageEntries = modelUsage ? Object.entries(modelUsage) : [];
+        const executedModelId = typeof envelope.model === "string"
+            ? envelope.model
+            : modelUsageEntries.length === 1
+                ? modelUsageEntries[0][0]
+                : undefined;
+        const usage = parseClaudeUsage(envelope.usage) ?? aggregateClaudeModelUsage(modelUsageEntries);
         return {
-            text: typeof envelope.result === "string" ? envelope.result : "",
-            ...(typeof envelope.model === "string" ? { executedModelId: envelope.model } : {}),
+            text: structured !== undefined
+                ? JSON.stringify(structured)
+                : typeof envelope.result === "string"
+                    ? envelope.result
+                    : "",
+            ...(executedModelId ? { executedModelId } : {}),
+            ...(usage ? { usage } : {}),
         };
     }
     catch (error) {
         if (error instanceof SyntaxError)
-            return { text: raw };
+            return { text: stdout };
         throw error;
     }
 }
+function parseCodexOutput(stdout, outputFileText) {
+    const events = parseJsonLines(stdout);
+    const completed = [...events]
+        .reverse()
+        .find((event) => event.type === "turn.completed" && objectValue(event.usage));
+    const usage = completed ? parseCodexUsage(completed.usage) : undefined;
+    const streamedText = [...events]
+        .reverse()
+        .map((event) => objectValue(event.item))
+        .find((item) => item?.type === "agent_message" && typeof item.text === "string")?.text;
+    return {
+        text: outputFileText ?? (typeof streamedText === "string" ? streamedText : ""),
+        ...(usage ? { usage } : {}),
+    };
+}
+function parseCursorOutput(stdout) {
+    const events = parseJsonLines(stdout);
+    const init = events.find((event) => event.type === "system" && event.subtype === "init" && typeof event.model === "string");
+    const terminal = [...events]
+        .reverse()
+        .find((event) => event.type === "result" && typeof event.result === "string");
+    if (!terminal) {
+        try {
+            const envelope = JSON.parse(stdout);
+            if (envelope.is_error)
+                throw new Error("harness returned an error envelope");
+            return {
+                text: typeof envelope.result === "string" ? envelope.result : "",
+                ...(typeof envelope.model === "string" ? { executedModelId: envelope.model } : {}),
+                ...(parseCursorUsage(envelope.usage) ? { usage: parseCursorUsage(envelope.usage) } : {}),
+            };
+        }
+        catch (error) {
+            if (error instanceof SyntaxError)
+                return { text: stdout };
+            throw error;
+        }
+    }
+    if (terminal.is_error)
+        throw new Error("harness returned an error envelope");
+    const usage = parseCursorUsage(terminal.usage);
+    return {
+        text: terminal.result,
+        ...(typeof init?.model === "string" ? { executedModelId: init.model } : {}),
+        ...(usage ? { usage } : {}),
+    };
+}
+function parseClaudeUsage(value) {
+    const usage = objectValue(value);
+    if (!usage)
+        return undefined;
+    return nativeSemanticUsage({
+        input_tokens: usage.input_tokens,
+        cached_input_tokens: usage.cache_read_input_tokens,
+        cache_creation_input_tokens: usage.cache_creation_input_tokens,
+        output_tokens: usage.output_tokens,
+        reasoning_tokens: usage.reasoning_tokens ?? usage.reasoning_output_tokens,
+        total_tokens: usage.total_tokens,
+    });
+}
+function aggregateClaudeModelUsage(entries) {
+    const values = {};
+    for (const [, raw] of entries) {
+        const usage = objectValue(raw);
+        if (!usage)
+            continue;
+        addNumber(values, "input_tokens", usage.inputTokens);
+        addNumber(values, "cached_input_tokens", usage.cacheReadInputTokens);
+        addNumber(values, "cache_creation_input_tokens", usage.cacheCreationInputTokens);
+        addNumber(values, "output_tokens", usage.outputTokens);
+    }
+    return nativeSemanticUsage(values);
+}
+function parseCodexUsage(value) {
+    const usage = objectValue(value);
+    if (!usage)
+        return undefined;
+    return nativeSemanticUsage({
+        input_tokens: usage.input_tokens,
+        cached_input_tokens: usage.cached_input_tokens,
+        cache_creation_input_tokens: usage.cache_write_input_tokens,
+        output_tokens: usage.output_tokens,
+        reasoning_tokens: usage.reasoning_output_tokens,
+        total_tokens: usage.total_tokens,
+    });
+}
+function parseCursorUsage(value) {
+    const usage = objectValue(value);
+    if (!usage)
+        return undefined;
+    return nativeSemanticUsage({
+        input_tokens: usage.inputTokens ?? usage.input_tokens,
+        cached_input_tokens: usage.cacheReadTokens ?? usage.cachedInputTokens ?? usage.cached_input_tokens,
+        cache_creation_input_tokens: usage.cacheWriteTokens ?? usage.cacheCreationInputTokens ?? usage.cache_write_input_tokens,
+        output_tokens: usage.outputTokens ?? usage.output_tokens,
+        reasoning_tokens: usage.reasoningTokens ?? usage.reasoning_output_tokens,
+        total_tokens: usage.totalTokens ?? usage.total_tokens,
+    });
+}
+function parseJsonLines(raw) {
+    return raw
+        .split(/\r?\n/)
+        .filter((line) => line.trim().length > 0)
+        .flatMap((line) => {
+        try {
+            const value = JSON.parse(line);
+            return objectValue(value) ? [value] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function objectValue(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function addNumber(target, field, value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) {
+        target[field] = (target[field] ?? 0) + value;
+    }
+}
+function modelIdsMatch(attested, requested) {
+    const normalize = (value) => value.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+    return normalize(attested) === normalize(requested);
+}
 function semanticChildEnv() {
     const env = { ...process.env };
     for (const key of Object.keys(env)) {