open-multi-agent-kit 0.80.5 → 0.80.7

package/dist/core/harness-control-events.d.ts

@@ -0,0 +1,91 @@
+export type HarnessControlEventStatus = "prepared" | "started" | "applying" | "verifying" | "completed" | "failed" | "blocked" | "rolled_back" | "in_doubt";
+export type HarnessControlEventKind = "compaction.summary.generated" | "extension.migration.plan" | "extension.migration.apply" | "interactive.model_thinking.commit" | "interactive.theme.apply" | "keybinding.conflict" | "spec.compile" | "spec.verify" | "cli.contract.verify" | (string & {});
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export interface HarnessControlArtifactManifestEntry {
+    path: string;
+    exists: boolean;
+    allowed: boolean;
+    sizeBytes?: number;
+    sha256?: string;
+    error?: string;
+}
+export interface HarnessControlEvent {
+    schemaVersion: "omk.harness-control.event.v2";
+    eventId: string;
+    runId: string;
+    sessionId: string;
+    operationId: string;
+    causationId: string | null;
+    correlationId: string;
+    sequence: number;
+    timestamp: string;
+    kind: HarnessControlEventKind;
+    status: HarnessControlEventStatus;
+    cwd: string;
+    beforeStateHash: string;
+    afterStateHash: string;
+    data: JsonObject;
+    dataHash: string;
+    artifacts: HarnessControlArtifactManifestEntry[];
+    previousEventHash: string;
+    eventHash: string;
+}
+export interface HarnessControlLedgerAnchor {
+    schemaVersion: "omk.harness-control.anchor.v1";
+    anchoredSequence: number;
+    anchoredEventHash: string;
+    rotatedFrom: string;
+    timestamp: string;
+}
+export interface HarnessControlEventWriteResult {
+    ok: boolean;
+    path?: string;
+    event?: HarnessControlEvent;
+    error?: string;
+}
+export interface HarnessControlEventOptions {
+    cwd?: string;
+    logPath?: string;
+    now?: Date;
+    id?: string;
+    eventId?: string;
+    runId?: string;
+    sessionId?: string;
+    operationId?: string;
+    causationId?: string | null;
+    correlationId?: string;
+    beforeState?: unknown;
+    afterState?: unknown;
+    artifactRefs?: string[];
+    allowedArtifactRoots?: string[];
+    lockTimeoutMs?: number;
+    maxLedgerBytes?: number;
+}
+export interface HarnessControlLedgerQuarantineEntry {
+    lineNumber: number;
+    reason: string;
+}
+export interface HarnessControlLedgerVerificationResult {
+    ok: boolean;
+    events: HarnessControlEvent[];
+    errors: string[];
+    quarantinedLines: HarnessControlLedgerQuarantineEntry[];
+}
+interface PreviousEventState {
+    sequence: number;
+    eventHash: string;
+}
+export declare function sanitizeHarnessControlEventData(data: unknown): JsonObject;
+export declare function canonicalJson(value: JsonValue): string;
+export declare function hashCanonical(value: unknown): string;
+export declare function resolveHarnessControlEventLogPath(options?: HarnessControlEventOptions): string | undefined;
+export declare function createHarnessControlEvent(kind: HarnessControlEventKind, status: HarnessControlEventStatus, data?: unknown, options?: HarnessControlEventOptions, previous?: PreviousEventState): HarnessControlEvent;
+export declare function recordHarnessControlEvent(kind: HarnessControlEventKind, status: HarnessControlEventStatus, data?: unknown, options?: HarnessControlEventOptions): HarnessControlEventWriteResult;
+export declare function verifyHarnessControlLedger(logPath: string): HarnessControlLedgerVerificationResult;
+export {};
+//# sourceMappingURL=harness-control-events.d.ts.map

package/dist/core/harness-control-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-control-events.d.ts","sourceRoot":"","sources":["../../src/core/harness-control-events.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport {\n\tchmodSync,\n\tcloseSync,\n\texistsSync,\n\tfsyncSync,\n\tlstatSync,\n\tmkdirSync,\n\topenSync,\n\treadFileSync,\n\trealpathSync,\n\trenameSync,\n\trmSync,\n\tstatSync,\n\twriteSync,\n} from \"node:fs\";\nimport { basename, dirname, join, resolve, sep } from \"node:path\";\n\nexport type HarnessControlEventStatus =\n\t| \"prepared\"\n\t| \"started\"\n\t| \"applying\"\n\t| \"verifying\"\n\t| \"completed\"\n\t| \"failed\"\n\t| \"blocked\"\n\t| \"rolled_back\"\n\t| \"in_doubt\";\n\nexport type HarnessControlEventKind =\n\t| \"compaction.summary.generated\"\n\t| \"extension.migration.plan\"\n\t| \"extension.migration.apply\"\n\t| \"interactive.model_thinking.commit\"\n\t| \"interactive.theme.apply\"\n\t| \"keybinding.conflict\"\n\t| \"spec.compile\"\n\t| \"spec.verify\"\n\t| \"cli.contract.verify\"\n\t| (string & {});\n\nexport type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };\nexport type JsonObject = { [key: string]: JsonValue };\n\nexport interface HarnessControlArtifactManifestEntry {\n\tpath: string;\n\texists: boolean;\n\tallowed: boolean;\n\tsizeBytes?: number;\n\tsha256?: string;\n\terror?: string;\n}\n\nexport interface HarnessControlEvent {\n\tschemaVersion: \"omk.harness-control.event.v2\";\n\teventId: string;\n\trunId: string;\n\tsessionId: string;\n\toperationId: string;\n\tcausationId: string | null;\n\tcorrelationId: string;\n\tsequence: number;\n\ttimestamp: string;\n\tkind: HarnessControlEventKind;\n\tstatus: HarnessControlEventStatus;\n\tcwd: string;\n\tbeforeStateHash: string;\n\tafterStateHash: string;\n\tdata: JsonObject;\n\tdataHash: string;\n\tartifacts: HarnessControlArtifactManifestEntry[];\n\tpreviousEventHash: string;\n\teventHash: string;\n}\n\nexport interface HarnessControlLedgerAnchor {\n\tschemaVersion: \"omk.harness-control.anchor.v1\";\n\tanchoredSequence: number;\n\tanchoredEventHash: string;\n\trotatedFrom: string;\n\ttimestamp: string;\n}\n\nexport interface HarnessControlEventWriteResult {\n\tok: boolean;\n\tpath?: string;\n\tevent?: HarnessControlEvent;\n\terror?: string;\n}\n\nexport interface HarnessControlEventOptions {\n\tcwd?: string;\n\tlogPath?: string;\n\tnow?: Date;\n\tid?: string;\n\teventId?: string;\n\trunId?: string;\n\tsessionId?: string;\n\toperationId?: string;\n\tcausationId?: string | null;\n\tcorrelationId?: string;\n\tbeforeState?: unknown;\n\tafterState?: unknown;\n\tartifactRefs?: string[];\n\tallowedArtifactRoots?: string[];\n\tlockTimeoutMs?: number;\n\tmaxLedgerBytes?: number;\n}\n\nexport interface HarnessControlLedgerQuarantineEntry {\n\tlineNumber: number;\n\treason: string;\n}\n\nexport interface HarnessControlLedgerVerificationResult {\n\tok: boolean;\n\tevents: HarnessControlEvent[];\n\terrors: string[];\n\tquarantinedLines: HarnessControlLedgerQuarantineEntry[];\n}\n\ninterface PreviousEventState {\n\tsequence: number;\n\teventHash: string;\n}\n\ninterface ParsedLedgerLine {\n\tschemaVersion?: string;\n\tsequence?: number;\n\teventHash?: string;\n\tanchoredSequence?: number;\n\tanchoredEventHash?: string;\n}\n\nconst MAX_EVENT_DEPTH = 6;\nconst MAX_EVENT_OBJECT_KEYS = 80;\nconst MAX_EVENT_ARRAY_ITEMS = 80;\nconst MAX_EVENT_STRING_LENGTH = 2000;\nconst REDACTED = \"[redacted]\";\nconst GENESIS_EVENT_HASH = \"0\".repeat(64);\nconst EVENT_SCHEMA_VERSION = \"omk.harness-control.event.v2\";\nconst ANCHOR_SCHEMA_VERSION = \"omk.harness-control.anchor.v1\";\nconst DEFAULT_RUN_ID = \"default-run\";\nconst DEFAULT_SESSION_ID = \"sessionless\";\nconst LOCK_STALE_MS = 30000;\n\nfunction isSensitiveKey(key: string): boolean {\n\treturn /(?:secret|token|api[_-]?key|authorization|password|credential|private[_-]?key)/i.test(key);\n}\n\nfunction redactSensitiveValue(value: string): string {\n\tlet redacted = value;\n\tredacted = redacted.replace(/Bearer\\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED}`);\n\tredacted = redacted.replace(/sk-(?:proj-|ant-)?[A-Za-z0-9_-]{16,}/g, REDACTED);\n\tredacted = redacted.replace(/\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\b/g, REDACTED);\n\tredacted = redacted.replace(/-----BEGIN [^-]+PRIVATE KEY-----[\\s\\S]*?-----END [^-]+PRIVATE KEY-----/g, REDACTED);\n\tredacted = redacted.replace(/\\b[A-Fa-f0-9]{64,}\\b/g, REDACTED);\n\treturn redacted;\n}\n\nfunction truncateString(value: string): string {\n\tconst redacted = redactSensitiveValue(value);\n\tif (redacted.length <= MAX_EVENT_STRING_LENGTH) return redacted;\n\treturn `${redacted.slice(0, MAX_EVENT_STRING_LENGTH)}…[truncated]`;\n}\n\nfunction sanitizeValue(value: unknown, depth: number, seen: WeakSet<object>): JsonValue {\n\tif (value === null) return null;\n\tif (typeof value === \"string\") return truncateString(value);\n\tif (typeof value === \"number\") return Number.isFinite(value) ? value : String(value);\n\tif (typeof value === \"boolean\") return value;\n\tif (typeof value === \"bigint\") return value.toString();\n\tif (typeof value === \"undefined\" || typeof value === \"function\" || typeof value === \"symbol\") return String(value);\n\tif (depth >= MAX_EVENT_DEPTH) return \"[max-depth]\";\n\n\tif (Array.isArray(value)) {\n\t\treturn value.slice(0, MAX_EVENT_ARRAY_ITEMS).map((entry) => sanitizeValue(entry, depth + 1, seen));\n\t}\n\n\tif (value instanceof Date) return value.toISOString();\n\tif (value instanceof Error) {\n\t\treturn {\n\t\t\tname: value.name,\n\t\t\tmessage: truncateString(value.message),\n\t\t};\n\t}\n\n\tif (typeof value === \"object\") {\n\t\tif (seen.has(value)) return \"[circular]\";\n\t\tseen.add(value);\n\t\tconst result: JsonObject = {};\n\t\tfor (const [key, entry] of Object.entries(value).slice(0, MAX_EVENT_OBJECT_KEYS)) {\n\t\t\tresult[key] = isSensitiveKey(key) ? REDACTED : sanitizeValue(entry, depth + 1, seen);\n\t\t}\n\t\tseen.delete(value);\n\t\treturn result;\n\t}\n\n\treturn String(value);\n}\n\nexport function sanitizeHarnessControlEventData(data: unknown): JsonObject {\n\tconst sanitized = sanitizeValue(data ?? {}, 0, new WeakSet<object>());\n\treturn typeof sanitized === \"object\" && sanitized !== null && !Array.isArray(sanitized)\n\t\t? sanitized\n\t\t: { value: sanitized };\n}\n\nexport function canonicalJson(value: JsonValue): string {\n\tif (value === null) return \"null\";\n\tif (typeof value === \"string\" || typeof value === \"number\" || typeof value === \"boolean\") {\n\t\treturn JSON.stringify(value);\n\t}\n\tif (Array.isArray(value)) {\n\t\treturn `[${value.map((entry) => canonicalJson(entry)).join(\",\")}]`;\n\t}\n\treturn `{${Object.keys(value)\n\t\t.sort()\n\t\t.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key] ?? null)}`)\n\t\t.join(\",\")}}`;\n}\n\nexport function hashCanonical(value: unknown): string {\n\treturn createHash(\"sha256\")\n\t\t.update(canonicalJson(sanitizeValue(value, 0, new WeakSet<object>())))\n\t\t.digest(\"hex\");\n}\n\nfunction sha256Text(value: string): string {\n\treturn createHash(\"sha256\").update(value).digest(\"hex\");\n}\n\nfunction sha256File(path: string): string {\n\treturn createHash(\"sha256\").update(readFileSync(path)).digest(\"hex\");\n}\n\nfunction isPathWithin(parent: string, child: string): boolean {\n\tconst resolvedParent = resolve(parent);\n\tconst resolvedChild = resolve(child);\n\treturn resolvedChild === resolvedParent || resolvedChild.startsWith(`${resolvedParent}${sep}`);\n}\n\nfunction isSensitivePath(path: string): boolean {\n\treturn /(?:^|[/\\\\])(?:\\.env[^/\\\\]*|auth\\.json|oauth\\.json|.*(?:secret|token|credential|private[_-]?key).*)$/i.test(\n\t\tpath,\n\t);\n}\n\nfunction defaultAllowedArtifactRoots(cwd: string, logPath: string): string[] {\n\treturn [cwd, dirname(logPath)];\n}\n\nfunction safeRealPath(target: string): string {\n\ttry {\n\t\treturn realpathSync(target);\n\t} catch {\n\t\treturn resolve(target);\n\t}\n}\n\nfunction createArtifactManifest(\n\tartifactRefs: string[] | undefined,\n\tcwd: string,\n\tlogPath: string,\n\tallowedArtifactRoots: string[] | undefined,\n): HarnessControlArtifactManifestEntry[] {\n\tif (!artifactRefs || artifactRefs.length === 0) return [];\n\tconst logicalRoots = (allowedArtifactRoots ?? defaultAllowedArtifactRoots(cwd, logPath)).map((root) =>\n\t\tresolve(root),\n\t);\n\tconst canonicalRoots = logicalRoots.map((root) => safeRealPath(root));\n\treturn artifactRefs.map((artifactPath) => {\n\t\tconst resolvedPath = resolve(cwd, artifactPath);\n\t\tconst allowed = logicalRoots.some((root) => isPathWithin(root, resolvedPath)) && !isSensitivePath(resolvedPath);\n\t\tif (!allowed) return { path: artifactPath, exists: existsSync(resolvedPath), allowed: false };\n\t\tif (!existsSync(resolvedPath)) return { path: artifactPath, exists: false, allowed: true };\n\t\ttry {\n\t\t\tconst linkStats = lstatSync(resolvedPath);\n\t\t\tconst realPath = realpathSync(resolvedPath);\n\t\t\tif (!canonicalRoots.some((root) => isPathWithin(root, realPath))) {\n\t\t\t\treturn {\n\t\t\t\t\tpath: artifactPath,\n\t\t\t\t\texists: true,\n\t\t\t\t\tallowed: false,\n\t\t\t\t\terror: linkStats.isSymbolicLink()\n\t\t\t\t\t\t? \"artifact symlink resolves outside allowed roots\"\n\t\t\t\t\t\t: \"artifact resolves outside allowed roots\",\n\t\t\t\t};\n\t\t\t}\n\t\t\tconst stats = statSync(realPath);\n\t\t\tif (!stats.isFile()) return { path: artifactPath, exists: true, allowed: true, sizeBytes: stats.size };\n\t\t\treturn {\n\t\t\t\tpath: artifactPath,\n\t\t\t\texists: true,\n\t\t\t\tallowed: true,\n\t\t\t\tsizeBytes: stats.size,\n\t\t\t\tsha256: sha256File(realPath),\n\t\t\t};\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tpath: artifactPath,\n\t\t\t\texists: existsSync(resolvedPath),\n\t\t\t\tallowed: true,\n\t\t\t\terror: error instanceof Error ? error.message : String(error),\n\t\t\t};\n\t\t}\n\t});\n}\n\nexport function resolveHarnessControlEventLogPath(options: HarnessControlEventOptions = {}): string | undefined {\n\tif (process.env.OMK_HARNESS_CONTROL_EVENTS === \"0\") return undefined;\n\tif (options.logPath) return options.logPath;\n\tif (process.env.OMK_HARNESS_CONTROL_EVENT_LOG) return process.env.OMK_HARNESS_CONTROL_EVENT_LOG;\n\tconst runId = options.runId ?? DEFAULT_RUN_ID;\n\treturn join(options.cwd ?? process.cwd(), \".omk\", \"runs\", runId, \"harness-control\", \"events.jsonl\");\n}\n\nfunction eventHashInput(eventWithoutHash: Omit<HarnessControlEvent, \"eventHash\">): string {\n\treturn `${canonicalJson(eventWithoutHash as unknown as JsonObject)}${eventWithoutHash.previousEventHash}`;\n}\n\nfunction computeEventHash(eventWithoutHash: Omit<HarnessControlEvent, \"eventHash\">): string {\n\treturn sha256Text(eventHashInput(eventWithoutHash));\n}\n\nfunction readPreviousEventState(logPath: string): PreviousEventState {\n\tif (!existsSync(logPath)) return { sequence: 0, eventHash: GENESIS_EVENT_HASH };\n\tconst lines = readFileSync(logPath, \"utf-8\")\n\t\t.split(\"\\n\")\n\t\t.map((line) => line.trim())\n\t\t.filter((line) => line.length > 0);\n\tif (lines.length === 0) return { sequence: 0, eventHash: GENESIS_EVENT_HASH };\n\n\tlet parsed: ParsedLedgerLine;\n\ttry {\n\t\tparsed = JSON.parse(lines.at(-1)!) as ParsedLedgerLine;\n\t} catch {\n\t\tthrow new Error(\"Last harness ledger line is not valid JSON — ledger may be truncated or corrupted\");\n\t}\n\tif (parsed.schemaVersion === ANCHOR_SCHEMA_VERSION) {\n\t\tif (typeof parsed.anchoredSequence !== \"number\" || typeof parsed.anchoredEventHash !== \"string\") {\n\t\t\tthrow new Error(\"Previous harness ledger anchor is missing anchoredSequence or anchoredEventHash\");\n\t\t}\n\t\treturn { sequence: parsed.anchoredSequence, eventHash: parsed.anchoredEventHash };\n\t}\n\tif (parsed.schemaVersion !== EVENT_SCHEMA_VERSION) {\n\t\treturn { sequence: 0, eventHash: GENESIS_EVENT_HASH };\n\t}\n\tif (typeof parsed.sequence !== \"number\" || !Number.isInteger(parsed.sequence) || parsed.sequence < 0) {\n\t\tthrow new Error(\"Previous harness event has invalid or missing sequence\");\n\t}\n\tif (typeof parsed.eventHash !== \"string\" || !/^[a-f0-9]{64}$/.test(parsed.eventHash)) {\n\t\tthrow new Error(\"Previous harness event has invalid or missing eventHash\");\n\t}\n\treturn { sequence: parsed.sequence, eventHash: parsed.eventHash };\n}\n\nfunction acquireLock(lockPath: string, timeoutMs: number): number {\n\tconst start = Date.now();\n\twhile (true) {\n\t\ttry {\n\t\t\treturn openSync(lockPath, \"wx\", 0o600);\n\t\t} catch (error) {\n\t\t\tif (existsSync(lockPath)) {\n\t\t\t\ttry {\n\t\t\t\t\tconst stats = statSync(lockPath);\n\t\t\t\t\tif (Date.now() - stats.mtimeMs > LOCK_STALE_MS) rmSync(lockPath, { force: true });\n\t\t\t\t} catch {}\n\t\t\t}\n\t\t\tif (Date.now() - start >= timeoutMs) {\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t}\n}\n\nfunction formatRotationTimestamp(date: Date): string {\n\treturn date.toISOString().replace(/[:.]/g, \"-\");\n}\n\nfunction fsyncDirectory(dirPath: string): void {\n\ttry {\n\t\tconst dirFd = openSync(dirPath, \"r\");\n\t\ttry {\n\t\t\tfsyncSync(dirFd);\n\t\t} finally {\n\t\t\tcloseSync(dirFd);\n\t\t}\n\t} catch {\n\t\t// Some platforms/filesystems do not support directory fsync; file fsync above is still mandatory.\n\t}\n}\n\nfunction enforcePrivateFilePermissions(filePath: string): void {\n\ttry {\n\t\tif (existsSync(filePath) && (statSync(filePath).mode & 0o777) !== 0o600) {\n\t\t\tchmodSync(filePath, 0o600);\n\t\t}\n\t} catch {\n\t\t/* best-effort permission enforcement */\n\t}\n}\n\nfunction rotateLedgerIfNeeded(path: string, maxLedgerBytes: number | undefined, now: Date): string | undefined {\n\tif (!Number.isFinite(maxLedgerBytes) || (maxLedgerBytes ?? 0) <= 0 || !existsSync(path)) return undefined;\n\tenforcePrivateFilePermissions(path);\n\tconst stats = statSync(path);\n\tif (stats.size < Math.floor(maxLedgerBytes ?? 0)) return undefined;\n\t// Capture the rotated segment's terminal state so the fresh segment continues\n\t// the global sequence and hash chain instead of restarting from genesis.\n\tconst anchorState = readPreviousEventState(path);\n\tconst rotatedPath = `${path}.${formatRotationTimestamp(now)}.rotated`;\n\trenameSync(path, rotatedPath);\n\tenforcePrivateFilePermissions(rotatedPath);\n\tfsyncDirectory(dirname(path));\n\tif (anchorState.sequence > 0) {\n\t\tconst anchor: HarnessControlLedgerAnchor = {\n\t\t\tschemaVersion: ANCHOR_SCHEMA_VERSION,\n\t\t\tanchoredSequence: anchorState.sequence,\n\t\t\tanchoredEventHash: anchorState.eventHash,\n\t\t\trotatedFrom: basename(rotatedPath),\n\t\t\ttimestamp: now.toISOString(),\n\t\t};\n\t\tappendJsonLineWithFsync(path, JSON.stringify(anchor));\n\t}\n\treturn rotatedPath;\n}\n\nfunction appendJsonLineWithFsync(path: string, line: string): void {\n\tconst fd = openSync(path, \"a\", 0o600);\n\ttry {\n\t\tenforcePrivateFilePermissions(path);\n\t\twriteSync(fd, `${line}\\n`, undefined, \"utf-8\");\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\tfsyncDirectory(dirname(path));\n}\n\nexport function createHarnessControlEvent(\n\tkind: HarnessControlEventKind,\n\tstatus: HarnessControlEventStatus,\n\tdata: unknown = {},\n\toptions: HarnessControlEventOptions = {},\n\tprevious: PreviousEventState = { sequence: 0, eventHash: GENESIS_EVENT_HASH },\n): HarnessControlEvent {\n\tconst eventId = options.eventId ?? options.id ?? randomUUID();\n\tconst operationId = options.operationId ?? eventId;\n\tconst logPath = resolveHarnessControlEventLogPath(options) ?? \"\";\n\tconst cwd = options.cwd ?? process.cwd();\n\tconst sanitizedData = sanitizeHarnessControlEventData(data);\n\tconst eventWithoutHash: Omit<HarnessControlEvent, \"eventHash\"> = {\n\t\tschemaVersion: \"omk.harness-control.event.v2\",\n\t\teventId,\n\t\trunId: options.runId ?? DEFAULT_RUN_ID,\n\t\tsessionId: options.sessionId ?? DEFAULT_SESSION_ID,\n\t\toperationId,\n\t\tcausationId: options.causationId ?? null,\n\t\tcorrelationId: options.correlationId ?? operationId,\n\t\tsequence: previous.sequence + 1,\n\t\ttimestamp: (options.now ?? new Date()).toISOString(),\n\t\tkind,\n\t\tstatus,\n\t\tcwd,\n\t\tbeforeStateHash: hashCanonical(options.beforeState ?? null),\n\t\tafterStateHash: hashCanonical(options.afterState ?? null),\n\t\tdata: sanitizedData,\n\t\tdataHash: hashCanonical(sanitizedData),\n\t\tartifacts: createArtifactManifest(options.artifactRefs, cwd, logPath, options.allowedArtifactRoots),\n\t\tpreviousEventHash: previous.eventHash,\n\t};\n\treturn { ...eventWithoutHash, eventHash: computeEventHash(eventWithoutHash) };\n}\n\nexport function recordHarnessControlEvent(\n\tkind: HarnessControlEventKind,\n\tstatus: HarnessControlEventStatus,\n\tdata: unknown = {},\n\toptions: HarnessControlEventOptions = {},\n): HarnessControlEventWriteResult {\n\tconst logPath = resolveHarnessControlEventLogPath(options);\n\tif (!logPath) return { ok: false, error: \"harness control event logging disabled\" };\n\tconst lockPath = `${logPath}.lock`;\n\tlet lockFd: number | undefined;\n\ttry {\n\t\tmkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });\n\t\t// Re-apply directory permissions on platforms where umask\n\t\t// overrides the mode passed to mkdirSync.\n\t\ttry {\n\t\t\tconst dirStats = statSync(dirname(logPath));\n\t\t\tif ((dirStats.mode & 0o777) !== 0o700) {\n\t\t\t\tchmodSync(dirname(logPath), 0o700);\n\t\t\t}\n\t\t} catch {\n\t\t\t/* best-effort permission enforcement */\n\t\t}\n\t\tlockFd = acquireLock(lockPath, options.lockTimeoutMs ?? 1000);\n\t\trotateLedgerIfNeeded(logPath, options.maxLedgerBytes, options.now ?? new Date());\n\t\tconst previous = readPreviousEventState(logPath);\n\t\tconst event = createHarnessControlEvent(kind, status, data, options, previous);\n\t\tappendJsonLineWithFsync(logPath, JSON.stringify(event));\n\t\treturn { ok: true, path: logPath, event };\n\t} catch (error) {\n\t\treturn { ok: false, path: logPath, error: error instanceof Error ? error.message : String(error) };\n\t} finally {\n\t\tif (lockFd !== undefined) {\n\t\t\ttry {\n\t\t\t\tcloseSync(lockFd);\n\t\t\t} catch {}\n\t\t\trmSync(lockPath, { force: true });\n\t\t}\n\t}\n}\n\nfunction validateLedgerAnchor(anchor: ParsedLedgerLine): string | undefined {\n\tif (\n\t\ttypeof anchor.anchoredSequence !== \"number\" ||\n\t\t!Number.isInteger(anchor.anchoredSequence) ||\n\t\tanchor.anchoredSequence < 1\n\t) {\n\t\treturn \"ledger anchor has an invalid anchoredSequence\";\n\t}\n\tif (typeof anchor.anchoredEventHash !== \"string\" || !/^[a-f0-9]{64}$/.test(anchor.anchoredEventHash)) {\n\t\treturn \"ledger anchor has an invalid anchoredEventHash\";\n\t}\n\treturn undefined;\n}\n\nconst VALID_EVENT_STATUSES = new Set<string>([\n\t\"prepared\",\n\t\"started\",\n\t\"applying\",\n\t\"verifying\",\n\t\"completed\",\n\t\"failed\",\n\t\"blocked\",\n\t\"rolled_back\",\n\t\"in_doubt\",\n]);\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction validateHarnessControlEventRecord(record: Record<string, unknown>): string | undefined {\n\tif (record.schemaVersion !== EVENT_SCHEMA_VERSION) return \"unsupported schemaVersion\";\n\tconst stringFields = [\n\t\t\"eventId\",\n\t\t\"runId\",\n\t\t\"sessionId\",\n\t\t\"operationId\",\n\t\t\"correlationId\",\n\t\t\"timestamp\",\n\t\t\"kind\",\n\t\t\"cwd\",\n\t\t\"beforeStateHash\",\n\t\t\"afterStateHash\",\n\t\t\"dataHash\",\n\t\t\"previousEventHash\",\n\t\t\"eventHash\",\n\t] as const;\n\tfor (const field of stringFields) {\n\t\tif (typeof record[field] !== \"string\") return `event is missing or has invalid ${field}`;\n\t}\n\tif (typeof record.sequence !== \"number\" || !Number.isInteger(record.sequence) || record.sequence < 1) {\n\t\treturn \"event has invalid sequence\";\n\t}\n\tif (typeof record.causationId !== \"string\" && record.causationId !== null) {\n\t\treturn \"event has invalid causationId\";\n\t}\n\tif (typeof record.status !== \"string\" || !VALID_EVENT_STATUSES.has(record.status)) {\n\t\treturn \"event has invalid status\";\n\t}\n\tif (typeof record.eventHash !== \"string\" || !/^[a-f0-9]{64}$/.test(record.eventHash)) {\n\t\treturn \"event has invalid eventHash\";\n\t}\n\tif (typeof record.previousEventHash !== \"string\" || !/^[a-f0-9]{64}$/.test(record.previousEventHash)) {\n\t\treturn \"event has invalid previousEventHash\";\n\t}\n\tif (!isRecord(record.data)) return \"event has invalid data\";\n\tif (!Array.isArray(record.artifacts)) return \"event has invalid artifacts\";\n\treturn undefined;\n}\n\nfunction validateEventHash(event: HarnessControlEvent): string | undefined {\n\tconst { eventHash: _eventHash, ...eventWithoutHash } = event;\n\tconst expectedEventHash = computeEventHash(eventWithoutHash);\n\tif (expectedEventHash !== event.eventHash) {\n\t\treturn `event ${event.eventId} hash mismatch`;\n\t}\n\tif (hashCanonical(event.data) !== event.dataHash) {\n\t\treturn `event ${event.eventId} dataHash mismatch`;\n\t}\n\treturn undefined;\n}\n\nexport function verifyHarnessControlLedger(logPath: string): HarnessControlLedgerVerificationResult {\n\tconst errors: string[] = [];\n\tconst events: HarnessControlEvent[] = [];\n\tconst quarantinedLines: HarnessControlLedgerQuarantineEntry[] = [];\n\tif (!existsSync(logPath)) return { ok: true, events, errors, quarantinedLines };\n\tconst lines = readFileSync(logPath, \"utf-8\")\n\t\t.split(\"\\n\")\n\t\t.map((line) => line.trim())\n\t\t.filter((line) => line.length > 0);\n\tlet previousSequence = 0;\n\tlet previousEventHash = GENESIS_EVENT_HASH;\n\n\tfunction quarantine(lineNumber: number, reason: string): void {\n\t\tquarantinedLines.push({ lineNumber, reason });\n\t\terrors.push(`line ${lineNumber}: quarantined — ${reason}`);\n\t}\n\n\tfor (let index = 0; index < lines.length; index++) {\n\t\tconst lineNumber = index + 1;\n\t\tlet parsed: Record<string, unknown>;\n\t\ttry {\n\t\t\tparsed = JSON.parse(lines[index]!) as Record<string, unknown>;\n\t\t} catch (error) {\n\t\t\tquarantine(lineNumber, error instanceof Error ? error.message : String(error));\n\t\t\tcontinue;\n\t\t}\n\t\tif (parsed.schemaVersion === ANCHOR_SCHEMA_VERSION) {\n\t\t\tif (index !== 0) {\n\t\t\t\tquarantine(lineNumber, \"ledger anchor must be the first line\");\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst anchorError = validateLedgerAnchor(parsed as ParsedLedgerLine);\n\t\t\tif (anchorError) {\n\t\t\t\tquarantine(lineNumber, anchorError);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tpreviousSequence = parsed.anchoredSequence as number;\n\t\t\tpreviousEventHash = parsed.anchoredEventHash as string;\n\t\t\tcontinue;\n\t\t}\n\t\tconst shapeError = validateHarnessControlEventRecord(parsed);\n\t\tif (shapeError) {\n\t\t\tquarantine(lineNumber, shapeError);\n\t\t\tcontinue;\n\t\t}\n\t\tconst event = parsed as unknown as HarnessControlEvent;\n\t\tif (event.sequence !== previousSequence + 1) {\n\t\t\tquarantine(lineNumber, `sequence gap: expected ${previousSequence + 1}, got ${event.sequence}`);\n\t\t\tcontinue;\n\t\t}\n\t\tif (event.previousEventHash !== previousEventHash) {\n\t\t\tquarantine(lineNumber, \"previousEventHash mismatch\");\n\t\t\tcontinue;\n\t\t}\n\t\tconst hashError = validateEventHash(event);\n\t\tif (hashError) {\n\t\t\tquarantine(lineNumber, hashError);\n\t\t\tcontinue;\n\t\t}\n\t\tevents.push(event);\n\t\tpreviousSequence = event.sequence;\n\t\tpreviousEventHash = event.eventHash;\n\t}\n\treturn { ok: errors.length === 0, events, errors, quarantinedLines };\n}\n"]}

package/dist/core/harness-control-events.js

@@ -0,0 +1,514 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeSync, } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+const MAX_EVENT_DEPTH = 6;
+const MAX_EVENT_OBJECT_KEYS = 80;
+const MAX_EVENT_ARRAY_ITEMS = 80;
+const MAX_EVENT_STRING_LENGTH = 2000;
+const REDACTED = "[redacted]";
+const GENESIS_EVENT_HASH = "0".repeat(64);
+const EVENT_SCHEMA_VERSION = "omk.harness-control.event.v2";
+const ANCHOR_SCHEMA_VERSION = "omk.harness-control.anchor.v1";
+const DEFAULT_RUN_ID = "default-run";
+const DEFAULT_SESSION_ID = "sessionless";
+const LOCK_STALE_MS = 30000;
+function isSensitiveKey(key) {
+    return /(?:secret|token|api[_-]?key|authorization|password|credential|private[_-]?key)/i.test(key);
+}
+function redactSensitiveValue(value) {
+    let redacted = value;
+    redacted = redacted.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/gi, `Bearer ${REDACTED}`);
+    redacted = redacted.replace(/sk-(?:proj-|ant-)?[A-Za-z0-9_-]{16,}/g, REDACTED);
+    redacted = redacted.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, REDACTED);
+    redacted = redacted.replace(/-----BEGIN [^-]+PRIVATE KEY-----[\s\S]*?-----END [^-]+PRIVATE KEY-----/g, REDACTED);
+    redacted = redacted.replace(/\b[A-Fa-f0-9]{64,}\b/g, REDACTED);
+    return redacted;
+}
+function truncateString(value) {
+    const redacted = redactSensitiveValue(value);
+    if (redacted.length <= MAX_EVENT_STRING_LENGTH)
+        return redacted;
+    return `${redacted.slice(0, MAX_EVENT_STRING_LENGTH)}…[truncated]`;
+}
+function sanitizeValue(value, depth, seen) {
+    if (value === null)
+        return null;
+    if (typeof value === "string")
+        return truncateString(value);
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : String(value);
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "undefined" || typeof value === "function" || typeof value === "symbol")
+        return String(value);
+    if (depth >= MAX_EVENT_DEPTH)
+        return "[max-depth]";
+    if (Array.isArray(value)) {
+        return value.slice(0, MAX_EVENT_ARRAY_ITEMS).map((entry) => sanitizeValue(entry, depth + 1, seen));
+    }
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof Error) {
+        return {
+            name: value.name,
+            message: truncateString(value.message),
+        };
+    }
+    if (typeof value === "object") {
+        if (seen.has(value))
+            return "[circular]";
+        seen.add(value);
+        const result = {};
+        for (const [key, entry] of Object.entries(value).slice(0, MAX_EVENT_OBJECT_KEYS)) {
+            result[key] = isSensitiveKey(key) ? REDACTED : sanitizeValue(entry, depth + 1, seen);
+        }
+        seen.delete(value);
+        return result;
+    }
+    return String(value);
+}
+export function sanitizeHarnessControlEventData(data) {
+    const sanitized = sanitizeValue(data ?? {}, 0, new WeakSet());
+    return typeof sanitized === "object" && sanitized !== null && !Array.isArray(sanitized)
+        ? sanitized
+        : { value: sanitized };
+}
+export function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key] ?? null)}`)
+        .join(",")}}`;
+}
+export function hashCanonical(value) {
+    return createHash("sha256")
+        .update(canonicalJson(sanitizeValue(value, 0, new WeakSet())))
+        .digest("hex");
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function sha256File(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function isPathWithin(parent, child) {
+    const resolvedParent = resolve(parent);
+    const resolvedChild = resolve(child);
+    return resolvedChild === resolvedParent || resolvedChild.startsWith(`${resolvedParent}${sep}`);
+}
+function isSensitivePath(path) {
+    return /(?:^|[/\\])(?:\.env[^/\\]*|auth\.json|oauth\.json|.*(?:secret|token|credential|private[_-]?key).*)$/i.test(path);
+}
+function defaultAllowedArtifactRoots(cwd, logPath) {
+    return [cwd, dirname(logPath)];
+}
+function safeRealPath(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return resolve(target);
+    }
+}
+function createArtifactManifest(artifactRefs, cwd, logPath, allowedArtifactRoots) {
+    if (!artifactRefs || artifactRefs.length === 0)
+        return [];
+    const logicalRoots = (allowedArtifactRoots ?? defaultAllowedArtifactRoots(cwd, logPath)).map((root) => resolve(root));
+    const canonicalRoots = logicalRoots.map((root) => safeRealPath(root));
+    return artifactRefs.map((artifactPath) => {
+        const resolvedPath = resolve(cwd, artifactPath);
+        const allowed = logicalRoots.some((root) => isPathWithin(root, resolvedPath)) && !isSensitivePath(resolvedPath);
+        if (!allowed)
+            return { path: artifactPath, exists: existsSync(resolvedPath), allowed: false };
+        if (!existsSync(resolvedPath))
+            return { path: artifactPath, exists: false, allowed: true };
+        try {
+            const linkStats = lstatSync(resolvedPath);
+            const realPath = realpathSync(resolvedPath);
+            if (!canonicalRoots.some((root) => isPathWithin(root, realPath))) {
+                return {
+                    path: artifactPath,
+                    exists: true,
+                    allowed: false,
+                    error: linkStats.isSymbolicLink()
+                        ? "artifact symlink resolves outside allowed roots"
+                        : "artifact resolves outside allowed roots",
+                };
+            }
+            const stats = statSync(realPath);
+            if (!stats.isFile())
+                return { path: artifactPath, exists: true, allowed: true, sizeBytes: stats.size };
+            return {
+                path: artifactPath,
+                exists: true,
+                allowed: true,
+                sizeBytes: stats.size,
+                sha256: sha256File(realPath),
+            };
+        }
+        catch (error) {
+            return {
+                path: artifactPath,
+                exists: existsSync(resolvedPath),
+                allowed: true,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+}
+export function resolveHarnessControlEventLogPath(options = {}) {
+    if (process.env.OMK_HARNESS_CONTROL_EVENTS === "0")
+        return undefined;
+    if (options.logPath)
+        return options.logPath;
+    if (process.env.OMK_HARNESS_CONTROL_EVENT_LOG)
+        return process.env.OMK_HARNESS_CONTROL_EVENT_LOG;
+    const runId = options.runId ?? DEFAULT_RUN_ID;
+    return join(options.cwd ?? process.cwd(), ".omk", "runs", runId, "harness-control", "events.jsonl");
+}
+function eventHashInput(eventWithoutHash) {
+    return `${canonicalJson(eventWithoutHash)}${eventWithoutHash.previousEventHash}`;
+}
+function computeEventHash(eventWithoutHash) {
+    return sha256Text(eventHashInput(eventWithoutHash));
+}
+function readPreviousEventState(logPath) {
+    if (!existsSync(logPath))
+        return { sequence: 0, eventHash: GENESIS_EVENT_HASH };
+    const lines = readFileSync(logPath, "utf-8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    if (lines.length === 0)
+        return { sequence: 0, eventHash: GENESIS_EVENT_HASH };
+    let parsed;
+    try {
+        parsed = JSON.parse(lines.at(-1));
+    }
+    catch {
+        throw new Error("Last harness ledger line is not valid JSON — ledger may be truncated or corrupted");
+    }
+    if (parsed.schemaVersion === ANCHOR_SCHEMA_VERSION) {
+        if (typeof parsed.anchoredSequence !== "number" || typeof parsed.anchoredEventHash !== "string") {
+            throw new Error("Previous harness ledger anchor is missing anchoredSequence or anchoredEventHash");
+        }
+        return { sequence: parsed.anchoredSequence, eventHash: parsed.anchoredEventHash };
+    }
+    if (parsed.schemaVersion !== EVENT_SCHEMA_VERSION) {
+        return { sequence: 0, eventHash: GENESIS_EVENT_HASH };
+    }
+    if (typeof parsed.sequence !== "number" || !Number.isInteger(parsed.sequence) || parsed.sequence < 0) {
+        throw new Error("Previous harness event has invalid or missing sequence");
+    }
+    if (typeof parsed.eventHash !== "string" || !/^[a-f0-9]{64}$/.test(parsed.eventHash)) {
+        throw new Error("Previous harness event has invalid or missing eventHash");
+    }
+    return { sequence: parsed.sequence, eventHash: parsed.eventHash };
+}
+function acquireLock(lockPath, timeoutMs) {
+    const start = Date.now();
+    while (true) {
+        try {
+            return openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (existsSync(lockPath)) {
+                try {
+                    const stats = statSync(lockPath);
+                    if (Date.now() - stats.mtimeMs > LOCK_STALE_MS)
+                        rmSync(lockPath, { force: true });
+                }
+                catch { }
+            }
+            if (Date.now() - start >= timeoutMs) {
+                throw error;
+            }
+        }
+    }
+}
+function formatRotationTimestamp(date) {
+    return date.toISOString().replace(/[:.]/g, "-");
+}
+function fsyncDirectory(dirPath) {
+    try {
+        const dirFd = openSync(dirPath, "r");
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    }
+    catch {
+        // Some platforms/filesystems do not support directory fsync; file fsync above is still mandatory.
+    }
+}
+function enforcePrivateFilePermissions(filePath) {
+    try {
+        if (existsSync(filePath) && (statSync(filePath).mode & 0o777) !== 0o600) {
+            chmodSync(filePath, 0o600);
+        }
+    }
+    catch {
+        /* best-effort permission enforcement */
+    }
+}
+function rotateLedgerIfNeeded(path, maxLedgerBytes, now) {
+    if (!Number.isFinite(maxLedgerBytes) || (maxLedgerBytes ?? 0) <= 0 || !existsSync(path))
+        return undefined;
+    enforcePrivateFilePermissions(path);
+    const stats = statSync(path);
+    if (stats.size < Math.floor(maxLedgerBytes ?? 0))
+        return undefined;
+    // Capture the rotated segment's terminal state so the fresh segment continues
+    // the global sequence and hash chain instead of restarting from genesis.
+    const anchorState = readPreviousEventState(path);
+    const rotatedPath = `${path}.${formatRotationTimestamp(now)}.rotated`;
+    renameSync(path, rotatedPath);
+    enforcePrivateFilePermissions(rotatedPath);
+    fsyncDirectory(dirname(path));
+    if (anchorState.sequence > 0) {
+        const anchor = {
+            schemaVersion: ANCHOR_SCHEMA_VERSION,
+            anchoredSequence: anchorState.sequence,
+            anchoredEventHash: anchorState.eventHash,
+            rotatedFrom: basename(rotatedPath),
+            timestamp: now.toISOString(),
+        };
+        appendJsonLineWithFsync(path, JSON.stringify(anchor));
+    }
+    return rotatedPath;
+}
+function appendJsonLineWithFsync(path, line) {
+    const fd = openSync(path, "a", 0o600);
+    try {
+        enforcePrivateFilePermissions(path);
+        writeSync(fd, `${line}\n`, undefined, "utf-8");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    fsyncDirectory(dirname(path));
+}
+export function createHarnessControlEvent(kind, status, data = {}, options = {}, previous = { sequence: 0, eventHash: GENESIS_EVENT_HASH }) {
+    const eventId = options.eventId ?? options.id ?? randomUUID();
+    const operationId = options.operationId ?? eventId;
+    const logPath = resolveHarnessControlEventLogPath(options) ?? "";
+    const cwd = options.cwd ?? process.cwd();
+    const sanitizedData = sanitizeHarnessControlEventData(data);
+    const eventWithoutHash = {
+        schemaVersion: "omk.harness-control.event.v2",
+        eventId,
+        runId: options.runId ?? DEFAULT_RUN_ID,
+        sessionId: options.sessionId ?? DEFAULT_SESSION_ID,
+        operationId,
+        causationId: options.causationId ?? null,
+        correlationId: options.correlationId ?? operationId,
+        sequence: previous.sequence + 1,
+        timestamp: (options.now ?? new Date()).toISOString(),
+        kind,
+        status,
+        cwd,
+        beforeStateHash: hashCanonical(options.beforeState ?? null),
+        afterStateHash: hashCanonical(options.afterState ?? null),
+        data: sanitizedData,
+        dataHash: hashCanonical(sanitizedData),
+        artifacts: createArtifactManifest(options.artifactRefs, cwd, logPath, options.allowedArtifactRoots),
+        previousEventHash: previous.eventHash,
+    };
+    return { ...eventWithoutHash, eventHash: computeEventHash(eventWithoutHash) };
+}
+export function recordHarnessControlEvent(kind, status, data = {}, options = {}) {
+    const logPath = resolveHarnessControlEventLogPath(options);
+    if (!logPath)
+        return { ok: false, error: "harness control event logging disabled" };
+    const lockPath = `${logPath}.lock`;
+    let lockFd;
+    try {
+        mkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });
+        // Re-apply directory permissions on platforms where umask
+        // overrides the mode passed to mkdirSync.
+        try {
+            const dirStats = statSync(dirname(logPath));
+            if ((dirStats.mode & 0o777) !== 0o700) {
+                chmodSync(dirname(logPath), 0o700);
+            }
+        }
+        catch {
+            /* best-effort permission enforcement */
+        }
+        lockFd = acquireLock(lockPath, options.lockTimeoutMs ?? 1000);
+        rotateLedgerIfNeeded(logPath, options.maxLedgerBytes, options.now ?? new Date());
+        const previous = readPreviousEventState(logPath);
+        const event = createHarnessControlEvent(kind, status, data, options, previous);
+        appendJsonLineWithFsync(logPath, JSON.stringify(event));
+        return { ok: true, path: logPath, event };
+    }
+    catch (error) {
+        return { ok: false, path: logPath, error: error instanceof Error ? error.message : String(error) };
+    }
+    finally {
+        if (lockFd !== undefined) {
+            try {
+                closeSync(lockFd);
+            }
+            catch { }
+            rmSync(lockPath, { force: true });
+        }
+    }
+}
+function validateLedgerAnchor(anchor) {
+    if (typeof anchor.anchoredSequence !== "number" ||
+        !Number.isInteger(anchor.anchoredSequence) ||
+        anchor.anchoredSequence < 1) {
+        return "ledger anchor has an invalid anchoredSequence";
+    }
+    if (typeof anchor.anchoredEventHash !== "string" || !/^[a-f0-9]{64}$/.test(anchor.anchoredEventHash)) {
+        return "ledger anchor has an invalid anchoredEventHash";
+    }
+    return undefined;
+}
+const VALID_EVENT_STATUSES = new Set([
+    "prepared",
+    "started",
+    "applying",
+    "verifying",
+    "completed",
+    "failed",
+    "blocked",
+    "rolled_back",
+    "in_doubt",
+]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateHarnessControlEventRecord(record) {
+    if (record.schemaVersion !== EVENT_SCHEMA_VERSION)
+        return "unsupported schemaVersion";
+    const stringFields = [
+        "eventId",
+        "runId",
+        "sessionId",
+        "operationId",
+        "correlationId",
+        "timestamp",
+        "kind",
+        "cwd",
+        "beforeStateHash",
+        "afterStateHash",
+        "dataHash",
+        "previousEventHash",
+        "eventHash",
+    ];
+    for (const field of stringFields) {
+        if (typeof record[field] !== "string")
+            return `event is missing or has invalid ${field}`;
+    }
+    if (typeof record.sequence !== "number" || !Number.isInteger(record.sequence) || record.sequence < 1) {
+        return "event has invalid sequence";
+    }
+    if (typeof record.causationId !== "string" && record.causationId !== null) {
+        return "event has invalid causationId";
+    }
+    if (typeof record.status !== "string" || !VALID_EVENT_STATUSES.has(record.status)) {
+        return "event has invalid status";
+    }
+    if (typeof record.eventHash !== "string" || !/^[a-f0-9]{64}$/.test(record.eventHash)) {
+        return "event has invalid eventHash";
+    }
+    if (typeof record.previousEventHash !== "string" || !/^[a-f0-9]{64}$/.test(record.previousEventHash)) {
+        return "event has invalid previousEventHash";
+    }
+    if (!isRecord(record.data))
+        return "event has invalid data";
+    if (!Array.isArray(record.artifacts))
+        return "event has invalid artifacts";
+    return undefined;
+}
+function validateEventHash(event) {
+    const { eventHash: _eventHash, ...eventWithoutHash } = event;
+    const expectedEventHash = computeEventHash(eventWithoutHash);
+    if (expectedEventHash !== event.eventHash) {
+        return `event ${event.eventId} hash mismatch`;
+    }
+    if (hashCanonical(event.data) !== event.dataHash) {
+        return `event ${event.eventId} dataHash mismatch`;
+    }
+    return undefined;
+}
+export function verifyHarnessControlLedger(logPath) {
+    const errors = [];
+    const events = [];
+    const quarantinedLines = [];
+    if (!existsSync(logPath))
+        return { ok: true, events, errors, quarantinedLines };
+    const lines = readFileSync(logPath, "utf-8")
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    let previousSequence = 0;
+    let previousEventHash = GENESIS_EVENT_HASH;
+    function quarantine(lineNumber, reason) {
+        quarantinedLines.push({ lineNumber, reason });
+        errors.push(`line ${lineNumber}: quarantined — ${reason}`);
+    }
+    for (let index = 0; index < lines.length; index++) {
+        const lineNumber = index + 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(lines[index]);
+        }
+        catch (error) {
+            quarantine(lineNumber, error instanceof Error ? error.message : String(error));
+            continue;
+        }
+        if (parsed.schemaVersion === ANCHOR_SCHEMA_VERSION) {
+            if (index !== 0) {
+                quarantine(lineNumber, "ledger anchor must be the first line");
+                continue;
+            }
+            const anchorError = validateLedgerAnchor(parsed);
+            if (anchorError) {
+                quarantine(lineNumber, anchorError);
+                continue;
+            }
+            previousSequence = parsed.anchoredSequence;
+            previousEventHash = parsed.anchoredEventHash;
+            continue;
+        }
+        const shapeError = validateHarnessControlEventRecord(parsed);
+        if (shapeError) {
+            quarantine(lineNumber, shapeError);
+            continue;
+        }
+        const event = parsed;
+        if (event.sequence !== previousSequence + 1) {
+            quarantine(lineNumber, `sequence gap: expected ${previousSequence + 1}, got ${event.sequence}`);
+            continue;
+        }
+        if (event.previousEventHash !== previousEventHash) {
+            quarantine(lineNumber, "previousEventHash mismatch");
+            continue;
+        }
+        const hashError = validateEventHash(event);
+        if (hashError) {
+            quarantine(lineNumber, hashError);
+            continue;
+        }
+        events.push(event);
+        previousSequence = event.sequence;
+        previousEventHash = event.eventHash;
+    }
+    return { ok: errors.length === 0, events, errors, quarantinedLines };
+}
+//# sourceMappingURL=harness-control-events.js.map