harnery 0.33.0 → 0.34.0

package/dist/core/guard/evidence-v3.js

@@ -0,0 +1,171 @@
+import { createHash } from "node:crypto";
+import { canonicalJsonV3 } from "../events/v3/index.js";
+/**
+ * Convert one validated V3 row into the evaluator's privacy-safe evidence.
+ * Both the live guard and offline corpus use this exact adapter.
+ */
+export function normalizeRunQualityEventV3(event, priorEvents = new Map()) {
+    const base = { event_id: event.event_id, ts: event.time.observed_at };
+    const recovery = recoveryCategory(event, base);
+    switch (event.event_type) {
+        case "tool.requested":
+            return [
+                {
+                    ...base,
+                    kind: "tool_call",
+                    input_hash: bareDigest(event.payload.exact_input.digest),
+                    target_hash: combinedTargetHash(event.payload.targets.map(({ fingerprint }) => fingerprint.digest)),
+                },
+                ...recovery,
+            ];
+        case "tool.completed":
+            return [
+                {
+                    ...base,
+                    kind: event.payload.outcome === "succeeded" ? "tool_success" : "tool_failure",
+                },
+                ...recovery,
+            ];
+        case "command.completed":
+            return recovery;
+        case "turn.started":
+            return [{ ...base, kind: "progress" }];
+        case "progress.observed":
+            return trustedProgress(event, priorEvents) ? [{ ...base, kind: "progress" }] : [];
+        case "context.observed": {
+            const measurement = event.payload.measurement;
+            if (measurement.state !== "observed")
+                return [];
+            return [
+                {
+                    ...base,
+                    kind: "context_sample",
+                    used_tokens: measurement.value.used_tokens,
+                    confidence: evidenceConfidence(measurement.attestation, measurement.confidence),
+                    telemetry_source: telemetrySource(measurement.value.method),
+                },
+            ];
+        }
+        case "context.compaction_started":
+            return [{ ...base, kind: "compaction_started" }];
+        case "context.compaction_completed":
+            return [{ ...base, kind: "compaction_completed" }];
+        default:
+            return [];
+    }
+}
+/**
+ * Derive generation-level pairing markers from validated events. The markers
+ * are audit metadata, not behavioral guard evidence: callers keep them in a
+ * separate corpus-category dimension.
+ */
+export function normalizeRunQualityPairingV3(events) {
+    const spans = new Map();
+    for (const event of events) {
+        if (event.event_type !== "tool.requested" &&
+            event.event_type !== "tool.completed" &&
+            event.event_type !== "command.started" &&
+            event.event_type !== "command.completed") {
+            continue;
+        }
+        const spanId = event.links.span_id;
+        if (!spanId)
+            continue;
+        const span = spans.get(spanId) ?? {
+            tool_requested: [],
+            tool_completed: [],
+            started_commands: [],
+            completed_commands: [],
+        };
+        if (event.event_type === "tool.requested")
+            span.tool_requested.push(event);
+        else if (event.event_type === "tool.completed")
+            span.tool_completed.push(event);
+        else if (event.event_type === "command.started")
+            span.started_commands.push(event);
+        else
+            span.completed_commands.push(event);
+        spans.set(spanId, span);
+    }
+    const markers = [];
+    for (const span of spans.values()) {
+        if ((span.tool_requested.length > 0 || span.tool_completed.length > 0) &&
+            (span.tool_requested.length !== 1 || span.tool_completed.length !== 1)) {
+            markers.push(pairingMarker("tool_pairing_incomplete", span.tool_requested, span.tool_completed));
+        }
+        if ((span.started_commands.length > 0 || span.completed_commands.length > 0) &&
+            (span.started_commands.length !== 1 || span.completed_commands.length !== 1)) {
+            markers.push(pairingMarker("command_pairing_incomplete", span.started_commands, span.completed_commands));
+        }
+    }
+    return markers;
+}
+export function isRunQualityCorpusCategoryV3(kind) {
+    return (kind === "tool_pairing_incomplete" ||
+        kind === "command_pairing_incomplete" ||
+        kind === "recovered_terminal");
+}
+function recoveryCategory(event, base) {
+    if (!("recovery" in event.payload) || event.payload.recovery === undefined)
+        return [];
+    return [{ ...base, kind: "recovered_terminal" }];
+}
+function pairingMarker(kind, left, right) {
+    const witness = [...left, ...right].sort((a, b) => a.time.observed_at.localeCompare(b.time.observed_at) || a.event_id.localeCompare(b.event_id))[0];
+    return { event_id: witness.event_id, ts: witness.time.observed_at, kind };
+}
+function trustedProgress(event, priorEvents) {
+    const links = event.links;
+    const scope = event.scope;
+    if (!event.payload.evidence_event_ids.every((eventId) => links.caused_by.includes(eventId))) {
+        return false;
+    }
+    return event.payload.evidence_event_ids.every((eventId) => {
+        const evidence = priorEvents.get(eventId);
+        if (!evidence || !("generation_id" in evidence.scope))
+            return false;
+        if (evidence.scope.generation_id !== scope.generation_id)
+            return false;
+        switch (evidence.event_type) {
+            case "tool.completed":
+            case "turn.completed":
+            case "run.completed":
+            case "command.completed":
+            case "agent.completed":
+                return evidence.payload.outcome === "succeeded";
+            case "artifact.observed":
+                return evidence.payload.operation !== "viewed";
+            default:
+                return false;
+        }
+    });
+}
+function combinedTargetHash(digests) {
+    const unique = [...new Set(digests.map(bareDigest))].sort();
+    if (unique.length === 0)
+        return undefined;
+    if (unique.length === 1)
+        return unique[0];
+    return createHash("sha256").update(canonicalJsonV3(unique)).digest("hex");
+}
+function bareDigest(digest) {
+    return digest.slice("sha256:".length);
+}
+function evidenceConfidence(attestation, confidence) {
+    if (attestation === "native" && confidence === "exact")
+        return "exact";
+    if (attestation === "inferred")
+        return "estimated";
+    return "reported";
+}
+function telemetrySource(method) {
+    if (method.endsWith("_hook"))
+        return "hook";
+    if (method.includes("transcript"))
+        return "transcript";
+    if (method.includes("result"))
+        return "result";
+    if (method.includes("estimate"))
+        return "estimate";
+    return "native_event";
+}

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

@@ -0,0 +1,10 @@
+export { DEFAULT_RUN_QUALITY_CONFIG, readRunQualityConfig } from "./config.js";
+export type { RunQualityEvaluationResult } from "./coordinator.js";
+export { evaluateRunQualityIfDue } from "./coordinator.js";
+export { evaluateRunQuality } from "./evaluator.js";
+export { isRunQualityCorpusCategoryV3, normalizeRunQualityEventV3, normalizeRunQualityPairingV3, } from "./evidence-v3.js";
+export type { RunQualityLiveGenerationV3, RunQualityLiveSourceV3, } from "./live-source-v3.js";
+export { projectRunQualityLiveSourceV3, RunQualityLiveSourceV3Error, readRunQualityLiveSourceV3, } from "./live-source-v3.js";
+export { readFreshRunQualitySnapshot, readRunQualitySnapshot, } from "./storage.js";
+export type { EvaluateRunQualityInput, RunQualityConfig, RunQualityConfigResult, RunQualityCorpusCategoryV3, RunQualityEvidenceEvent, RunQualityMode, RunQualityRoleWait, RunQualitySignal, RunQualitySnapshot, RunQualityStatus, RunQualityWaitKind, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/guard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC/E,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,4BAA4B,EAC5B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,6BAA6B,EAC7B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC"}

package/dist/core/guard/index.js

@@ -0,0 +1,6 @@
+export { DEFAULT_RUN_QUALITY_CONFIG, readRunQualityConfig } from "./config.js";
+export { evaluateRunQualityIfDue } from "./coordinator.js";
+export { evaluateRunQuality } from "./evaluator.js";
+export { isRunQualityCorpusCategoryV3, normalizeRunQualityEventV3, normalizeRunQualityPairingV3, } from "./evidence-v3.js";
+export { projectRunQualityLiveSourceV3, RunQualityLiveSourceV3Error, readRunQualityLiveSourceV3, } from "./live-source-v3.js";
+export { readFreshRunQualitySnapshot, readRunQualitySnapshot, } from "./storage.js";

package/dist/core/guard/live-source-v3.d.ts

@@ -0,0 +1,40 @@
+import { type ReadLedgerV3Result } from "../events/v3/index.js";
+import type { RunQualityCorpusCategoryV3, RunQualityEvidenceEvent, RunQualityRoleWait } from "./types.js";
+export type RunQualityLiveEpochStateV3 = "candidate" | "active";
+export interface RunQualityLiveGenerationV3 {
+    instance_id: string;
+    session_id: string;
+    generation_id: string;
+    adapter: string;
+    events: RunQualityEvidenceEvent[];
+    corpus_categories: RunQualityCorpusCategoryV3[];
+    role_wait: RunQualityRoleWait;
+    evidence: {
+        first_event_id?: string;
+        last_event_id?: string;
+        window_started_at?: string;
+        window_ended_at?: string;
+        segment: string;
+        truncated: boolean;
+    };
+    sufficient_history: boolean;
+}
+export interface RunQualityLiveSourceV3 {
+    contract_major: 3;
+    genesis_id: string;
+    epoch_state: RunQualityLiveEpochStateV3;
+    generations: RunQualityLiveGenerationV3[];
+}
+export declare class RunQualityLiveSourceV3Error extends Error {
+    readonly code: "control_not_ready" | "ledger_integrity_failure";
+    readonly details: string[];
+    constructor(code: "control_not_ready" | "ledger_integrity_failure", details: string[]);
+}
+/**
+ * Read live advisory inputs from the validated V3 ledger. Candidate epochs are
+ * observable here for rehearsal, but corpus eligibility remains active-only.
+ */
+export declare function readRunQualityLiveSourceV3(coordRoot: string, now?: Date): RunQualityLiveSourceV3;
+/** Pure projection used by the live coordinator and replay-equivalence tests. */
+export declare function projectRunQualityLiveSourceV3(read: ReadLedgerV3Result, genesisId: string, epochState: RunQualityLiveEpochStateV3, now: Date): RunQualityLiveSourceV3;
+//# sourceMappingURL=live-source-v3.d.ts.map

package/dist/core/guard/live-source-v3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-source-v3.d.ts","sourceRoot":"","sources":["../../../src/core/guard/live-source-v3.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EAIxB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,KAAK,EACV,0BAA0B,EAC1B,uBAAuB,EACvB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,0BAA0B,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEhE,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,iBAAiB,EAAE,0BAA0B,EAAE,CAAC;IAChD,SAAS,EAAE,kBAAkB,CAAC;IAC9B,QAAQ,EAAE;QACR,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,CAAC,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,0BAA0B,CAAC;IACxC,WAAW,EAAE,0BAA0B,EAAE,CAAC;CAC3C;AAED,qBAAa,2BAA4B,SAAQ,KAAK;aAElC,IAAI,EAAE,mBAAmB,GAAG,0BAA0B;aACtD,OAAO,EAAE,MAAM,EAAE;gBADjB,IAAI,EAAE,mBAAmB,GAAG,0BAA0B,EACtD,OAAO,EAAE,MAAM,EAAE;CAKpC;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,IAAiB,GACrB,sBAAsB,CAcxB;AAED,iFAAiF;AACjF,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,kBAAkB,EACxB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,0BAA0B,EACtC,GAAG,EAAE,IAAI,GACR,sBAAsB,CAwDxB"}

package/dist/core/guard/live-source-v3.js

@@ -0,0 +1,128 @@
+import { readEventV3ControlState, readLedgerV3, reduceSafetyProjectionV3, } from "../events/v3/index.js";
+import { isRunQualityCorpusCategoryV3, normalizeRunQualityEventV3, normalizeRunQualityPairingV3, } from "./evidence-v3.js";
+export class RunQualityLiveSourceV3Error extends Error {
+    code;
+    details;
+    constructor(code, details) {
+        super(`run_quality_live_v3:${code}:${details.join(",")}`);
+        this.code = code;
+        this.details = details;
+        this.name = "RunQualityLiveSourceV3Error";
+    }
+}
+/**
+ * Read live advisory inputs from the validated V3 ledger. Candidate epochs are
+ * observable here for rehearsal, but corpus eligibility remains active-only.
+ */
+export function readRunQualityLiveSourceV3(coordRoot, now = new Date()) {
+    const control = readEventV3ControlState(coordRoot);
+    if (control.state !== "candidate" && control.state !== "active") {
+        throw new RunQualityLiveSourceV3Error("control_not_ready", [
+            control.state,
+            "reason" in control ? control.reason : "unknown",
+        ]);
+    }
+    return projectRunQualityLiveSourceV3(readLedgerV3(coordRoot), control.genesis.event.payload.genesis_id, control.state, now);
+}
+/** Pure projection used by the live coordinator and replay-equivalence tests. */
+export function projectRunQualityLiveSourceV3(read, genesisId, epochState, now) {
+    if (!read.complete) {
+        throw new RunQualityLiveSourceV3Error("ledger_integrity_failure", [
+            ...new Set(read.diagnostics.map(({ code }) => code)),
+        ]);
+    }
+    const safety = reduceSafetyProjectionV3(read);
+    const generations = [];
+    for (const state of Object.values(safety.generations)) {
+        if (state.phase !== "live")
+            continue;
+        const positioned = read.events.filter(({ event }) => "generation_id" in event.scope && event.scope.generation_id === state.generation_id);
+        const started = positioned.find(({ event }) => event.event_type === "session.started")?.event;
+        if (started?.event_type !== "session.started")
+            continue;
+        const prior = new Map();
+        const evidenceEvents = [];
+        const corpusCategories = new Set();
+        for (const { event } of positioned) {
+            for (const normalized of normalizeRunQualityEventV3(event, prior)) {
+                if (isRunQualityCorpusCategoryV3(normalized.kind))
+                    corpusCategories.add(normalized.kind);
+                else
+                    evidenceEvents.push(normalized);
+            }
+            prior.set(event.event_id, event);
+        }
+        for (const marker of normalizeRunQualityPairingV3(positioned.map(({ event }) => event))) {
+            if (isRunQualityCorpusCategoryV3(marker.kind))
+                corpusCategories.add(marker.kind);
+        }
+        const first = evidenceEvents[0];
+        const last = evidenceEvents.at(-1);
+        const lastPosition = positioned.at(-1)?.position;
+        const diagnostic = safety.diagnostics.some((entry) => entry.generation_id === state.generation_id && entry.authority_blocking);
+        generations.push({
+            instance_id: state.instance_id,
+            session_id: state.session_id,
+            generation_id: state.generation_id,
+            adapter: observedAdapter(started),
+            events: evidenceEvents,
+            corpus_categories: [...corpusCategories].sort(),
+            role_wait: roleWait(state.waits, state.started_at, now),
+            evidence: {
+                first_event_id: first?.event_id,
+                last_event_id: last?.event_id,
+                window_started_at: first?.ts,
+                window_ended_at: last?.ts,
+                segment: `v3:${lastPosition?.segment_ordinal ?? 0}`,
+                truncated: diagnostic,
+            },
+            sufficient_history: !diagnostic,
+        });
+    }
+    generations.sort((left, right) => left.generation_id.localeCompare(right.generation_id));
+    return { contract_major: 3, genesis_id: genesisId, epoch_state: epochState, generations };
+}
+function observedAdapter(event) {
+    const adapter = event.payload.runtime_attestation.adapter;
+    return adapter.state === "observed" ? adapter.value.id : "unknown";
+}
+function roleWait(waits, generationStartedAt, now) {
+    const current = Object.values(waits).sort((left, right) => left.started_at.localeCompare(right.started_at));
+    if (current.length === 0) {
+        return {
+            role: "agent",
+            wait_kind: "none",
+            source: "event_v3",
+            observed_at: generationStartedAt,
+            fresh: false,
+        };
+    }
+    const latest = current.at(-1);
+    const scheduledExpired = latest.kind === "scheduled" &&
+        latest.wake_at !== undefined &&
+        Date.parse(latest.wake_at) <= now.getTime();
+    return {
+        role: "agent",
+        wait_kind: current.length > 1 ? "unknown" : waitKind(latest.kind),
+        source: "event_v3",
+        observed_at: latest.started_at,
+        fresh: !scheduledExpired,
+        record_id: latest.wait_id,
+        wake_at: latest.wake_at,
+    };
+}
+function waitKind(kind) {
+    switch (kind) {
+        case "operator_input":
+            return "needs_input";
+        case "decision":
+            return "decision";
+        case "permission":
+        case "approval":
+            return "approval";
+        case "scheduled":
+            return "scheduled";
+        default:
+            return "unknown";
+    }
+}

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

@@ -0,0 +1,27 @@
+import type { RunQualitySnapshot } from "./types.js";
+export interface GuardCursor {
+    schema_version: 1;
+    segment: string;
+    last_event_id?: string;
+    next_eligible_at: string;
+    config_digest: string;
+    updated_at: string;
+}
+export interface EvaluationLock {
+    pid: number;
+    acquired_at: string;
+    nonce: string;
+}
+export declare function guardDir(coordRoot: string): string;
+export declare function snapshotPath(coordRoot: string, instanceId: string): string;
+export declare function readRunQualitySnapshot(coordRoot: string, instanceId: string): RunQualitySnapshot | null;
+export declare function readFreshRunQualitySnapshot(coordRoot: string, instanceId: string, now?: Date): RunQualitySnapshot | null;
+export declare function readGuardCursor(coordRoot: string): GuardCursor | null;
+export declare function writeGuardCursor(coordRoot: string, cursor: GuardCursor, nonce: string): void;
+export declare function writeRunQualitySnapshot(coordRoot: string, snapshot: RunQualitySnapshot, nonce: string): void;
+export declare function acquireEvaluationLock(coordRoot: string, now: Date, staleSeconds: number): EvaluationLock | null;
+export declare function evaluationLockOwned(coordRoot: string, nonce: string): boolean;
+export declare function releaseEvaluationLock(coordRoot: string, nonce: string): void;
+export declare function cleanupOrphanSnapshots(coordRoot: string, liveIds: Set<string>): void;
+export declare function writeAtomicJson(path: string, value: unknown, nonce: string, beforeRename?: () => boolean): void;
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/core/guard/storage.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,CAAC,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1E;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,IAAI,CAE3B;AAED,wBAAgB,2BAA2B,CACzC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,IAAiB,GACrB,kBAAkB,GAAG,IAAI,CAG3B;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAErE;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAI5F;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,MAAM,GACZ,IAAI,CAIN;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,IAAI,EACT,YAAY,EAAE,MAAM,GACnB,cAAc,GAAG,IAAI,CAoBvB;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK7E;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAQ5E;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAcpF;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,OAAO,GAC3B,IAAI,CAaN"}

package/dist/core/guard/storage.js

@@ -0,0 +1,140 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export function guardDir(coordRoot) {
+    return join(coordRoot, ".harnery", "guard");
+}
+export function snapshotPath(coordRoot, instanceId) {
+    return join(guardDir(coordRoot), `${instanceId}.json`);
+}
+export function readRunQualitySnapshot(coordRoot, instanceId) {
+    return readBoundedJson(snapshotPath(coordRoot, instanceId), 1024 * 1024);
+}
+export function readFreshRunQualitySnapshot(coordRoot, instanceId, now = new Date()) {
+    const snapshot = readRunQualitySnapshot(coordRoot, instanceId);
+    return snapshot && Date.parse(snapshot.expires_at) > now.getTime() ? snapshot : null;
+}
+export function readGuardCursor(coordRoot) {
+    return readBoundedJson(join(guardDir(coordRoot), "cursor.json"), 64 * 1024);
+}
+export function writeGuardCursor(coordRoot, cursor, nonce) {
+    writeAtomicJson(join(guardDir(coordRoot), "cursor.json"), cursor, nonce, () => evaluationLockOwned(coordRoot, nonce));
+}
+export function writeRunQualitySnapshot(coordRoot, snapshot, nonce) {
+    writeAtomicJson(snapshotPath(coordRoot, snapshot.instance_id), snapshot, nonce, () => evaluationLockOwned(coordRoot, nonce));
+}
+export function acquireEvaluationLock(coordRoot, now, staleSeconds) {
+    const path = join(guardDir(coordRoot), "evaluate.lock");
+    mkdirSync(dirname(path), { recursive: true });
+    const lock = {
+        pid: process.pid,
+        acquired_at: now.toISOString(),
+        nonce: randomUUID(),
+    };
+    if (createExclusive(path, lock))
+        return lock;
+    const existing = readBoundedJson(path, 16 * 1024);
+    const age = existing
+        ? now.getTime() - Date.parse(existing.acquired_at)
+        : Number.POSITIVE_INFINITY;
+    if (existing && processAlive(existing.pid) && age <= staleSeconds * 1000)
+        return null;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        return null;
+    }
+    return createExclusive(path, lock) ? lock : null;
+}
+export function evaluationLockOwned(coordRoot, nonce) {
+    return (readBoundedJson(join(guardDir(coordRoot), "evaluate.lock"), 16 * 1024)
+        ?.nonce === nonce);
+}
+export function releaseEvaluationLock(coordRoot, nonce) {
+    const path = join(guardDir(coordRoot), "evaluate.lock");
+    if (!evaluationLockOwned(coordRoot, nonce))
+        return;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // A replacement owner won the race; nonce ownership already prevents removal.
+    }
+}
+export function cleanupOrphanSnapshots(coordRoot, liveIds) {
+    const dir = guardDir(coordRoot);
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith(".json") || name === "cursor.json" || name === "config-invalid.json")
+            continue;
+        const instanceId = name.slice(0, -5);
+        if (liveIds.has(instanceId))
+            continue;
+        try {
+            unlinkSync(join(dir, name));
+        }
+        catch {
+            // Cleanup is advisory and retries on the next evaluation.
+        }
+    }
+}
+export function writeAtomicJson(path, value, nonce, beforeRename) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.tmp-${process.pid}-${nonce}`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        if (beforeRename && !beforeRename())
+            throw new Error("run_quality_lock_stolen");
+        renameSync(temporary, path);
+    }
+    finally {
+        if (existsSync(temporary))
+            unlinkSync(temporary);
+    }
+}
+function createExclusive(path, value) {
+    let fd;
+    try {
+        fd = openSync(path, "wx", 0o600);
+        writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+        return true;
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function processAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function readBoundedJson(path, maxBytes) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const size = statSync(path).size;
+        if (size <= 0 || size > maxBytes)
+            return null;
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/guard/types.d.ts

@@ -0,0 +1,119 @@
+export declare const RUN_QUALITY_SCHEMA_VERSION: 1;
+export type RunQualityMode = "off" | "shadow" | "report";
+export type RunQualityStatus = "unknown" | "healthy" | "attention" | "critical";
+export type RunQualitySignalState = "inactive" | "active" | "unknown" | "suppressed";
+export type RunQualityWaitKind = "none" | "needs_input" | "decision" | "approval" | "scheduled" | "unknown";
+export interface RunQualityThresholds {
+    repeated_tool_calls: number;
+    consecutive_failures: number;
+    context_growth_per_minute: number;
+    compaction_grace_seconds: number;
+    no_progress_evaluations: number;
+}
+export interface RunQualityConfig {
+    mode: RunQualityMode;
+    evaluation_interval_seconds: number;
+    snapshot_ttl_seconds: number;
+    max_tail_bytes: number;
+    evaluation_timeout_seconds: number;
+    lock_stale_seconds: number;
+    supervised_roots_per_sweep: number;
+    thresholds: RunQualityThresholds;
+}
+export interface RunQualityConfigResult {
+    config: RunQualityConfig | null;
+    digest: string;
+    valid: boolean;
+    requested_mode: RunQualityMode;
+    reason_codes: string[];
+}
+export interface RunQualityRoleWait {
+    role: string;
+    wait_kind: RunQualityWaitKind;
+    source: string;
+    observed_at: string;
+    fresh: boolean;
+    record_id?: string;
+    wake_at?: string;
+}
+export type RunQualityEvidenceKind = "tool_call" | "tool_success" | "tool_failure" | "tool_pairing_incomplete" | "command_pairing_incomplete" | "recovered_terminal" | "context_sample" | "progress" | "compaction_started" | "compaction_completed";
+export type RunQualityCorpusCategoryV3 = Extract<RunQualityEvidenceKind, "tool_pairing_incomplete" | "command_pairing_incomplete" | "recovered_terminal">;
+export interface RunQualityEvidenceEvent {
+    event_id: string;
+    ts: string;
+    kind: RunQualityEvidenceKind;
+    input_hash?: string;
+    target_hash?: string;
+    used_tokens?: number;
+    confidence?: "exact" | "reported" | "estimated";
+    telemetry_source?: string;
+}
+export interface RunQualitySignal {
+    id: "repeated_tool_calls" | "consecutive_failures" | "context_growth" | "target_stagnation" | "no_progress" | "compaction_grace";
+    state: RunQualitySignalState;
+    severity: "none" | "attention" | "critical";
+    count: number;
+    reason_code: string;
+}
+export interface RunQualityEvaluatorState {
+    repeated_hash?: string;
+    repeated_count: number;
+    exact_hash_seen: boolean;
+    missing_hash_seen: boolean;
+    target_hash?: string;
+    target_streak: number;
+    target_hash_seen: boolean;
+    failure_streak: number;
+    work_since_progress: number;
+    last_context?: {
+        used_tokens: number;
+        ts: string;
+    };
+    context_growth_per_minute?: number;
+    no_progress_epochs: number;
+    no_progress_deadline_epochs: number;
+    compaction_grace_until?: string;
+}
+export interface RunQualitySnapshot {
+    schema_version: typeof RUN_QUALITY_SCHEMA_VERSION;
+    instance_id: string;
+    session_id: string;
+    session_generation: string;
+    adapter: string;
+    config_digest: string;
+    mode: Exclude<RunQualityMode, "off">;
+    status: RunQualityStatus;
+    previous_status: RunQualityStatus;
+    evaluated_at: string;
+    next_eligible_at: string;
+    expires_at: string;
+    evidence: {
+        first_event_id?: string;
+        last_event_id?: string;
+        window_started_at?: string;
+        window_ended_at?: string;
+        segment: string;
+        truncated: boolean;
+    };
+    signals: RunQualitySignal[];
+    role_wait: RunQualityRoleWait;
+    state: RunQualityEvaluatorState;
+    epoch: "evidence" | "deadline" | "read";
+    reason: "evidence" | "deadline" | "config_changed" | "insufficient_evidence";
+}
+export interface EvaluateRunQualityInput {
+    instance_id: string;
+    session_id: string;
+    session_generation: string;
+    adapter: string;
+    now: string;
+    config: RunQualityConfig;
+    config_digest: string;
+    events: RunQualityEvidenceEvent[];
+    previous?: RunQualitySnapshot;
+    role_wait: RunQualityRoleWait;
+    evidence: RunQualitySnapshot["evidence"];
+    sufficient_history: boolean;
+    live: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/guard/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/guard/types.ts"],"names":[],"mappings":"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"}

package/dist/core/guard/types.js

@@ -0,0 +1 @@
+export const RUN_QUALITY_SCHEMA_VERSION = 1;