open-multi-agent-kit 0.96.1 → 0.96.2

package/dist/core/resource-governor-format.js

@@ -0,0 +1,113 @@
+import { effectiveAvailableMemoryBytes } from "./host-resource-snapshot.js";
+const REASON_LABELS = {
+    "resource.memory.low": "memory low",
+    "resource.memory.critical": "memory critical",
+    "resource.disk.low": "disk low",
+    "resource.disk.critical": "disk critical",
+    "resource.cpu.busy": "CPU busy",
+    "resource.heap.high": "heap high",
+    "resource.heap.critical": "heap critical",
+    "resource.probe.partial": "partial probe",
+    "resource.probe.timeout": "probe timeout",
+};
+/** Humanize reason codes for the §19.1 summary line ("memory low, CPU busy"). */
+export function describeResourceReasons(reasons) {
+    if (reasons.length === 0) {
+        return "none";
+    }
+    return reasons.map((reason) => REASON_LABELS[reason] ?? reason).join(", ");
+}
+/** §19.1 summary block shared by `/resource` and the doctor's human output. */
+export function formatResourceSummaryLines(mode, decision) {
+    return [
+        `mode: ${mode}`,
+        `pressure: ${decision.pressure}`,
+        `action: ${decision.action}`,
+        `tool concurrency: ${decision.maxToolConcurrency}`,
+        `subagent lanes: ${decision.maxParallelLanes}`,
+        `heavy processes: ${decision.maxHeavyProcesses}`,
+        `reasons: ${describeResourceReasons(decision.reasons)}`,
+    ];
+}
+/**
+ * Verbose probe details for explicit local diagnostics only (§19.1 verbose,
+ * §11.3: raw values never enter tool results or model prompts).
+ */
+export function formatResourceProbeLines(snapshot) {
+    const heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;
+    const lines = [
+        `observed at: ${snapshot.observedAt}`,
+        `environment: ${snapshot.environment} (${snapshot.platform}/${snapshot.arch}, ${snapshot.logicalCpuCount} CPUs)`,
+        `effective available memory: ${formatMiB(effectiveAvailableMemoryBytes(snapshot))}`,
+        `  process available: ${formatMiB(snapshot.processAvailableMemoryBytes)}`,
+        `  constrained limit: ${formatMiB(snapshot.constrainedMemoryBytes)}`,
+        `  host free: ${formatMiB(snapshot.hostFreeMemoryBytes)} of ${formatMiB(snapshot.hostTotalMemoryBytes)}`,
+        `workspace disk available: ${formatMiB(snapshot.workspaceAvailableBytes)}`,
+        `heap: ${formatMiB(snapshot.heapUsedBytes)} of ${formatMiB(snapshot.heapLimitBytes)}${heapRatio === null ? "" : ` (${(heapRatio * 100).toFixed(1)}%)`}`,
+        `system CPU: ${snapshot.systemCpuPercent === null ? "unknown" : `${snapshot.systemCpuPercent.toFixed(1)}%`}`,
+    ];
+    if (snapshot.diagnostics.length > 0) {
+        lines.push(`diagnostics: ${snapshot.diagnostics.join(", ")}`);
+    }
+    return lines;
+}
+/** Policy view: mode, §6.7 thresholds, §7.2 caps, and §18.1 validation errors. */
+export function formatResourcePolicyLines(resolved) {
+    const { thresholds, caps } = resolved.admission;
+    const lines = [
+        `mode: ${resolved.mode}`,
+        `probe deadline: ${resolved.maxProbeMs ?? 300} ms, CPU sample: ${resolved.cpuSampleMs ?? 180} ms`,
+        `memory MiB (constrained/critical): ${thresholds.constrainedAvailableMemoryMiB}/${thresholds.criticalAvailableMemoryMiB}`,
+        `disk MiB (constrained/critical): ${thresholds.constrainedDiskFreeMiB}/${thresholds.criticalDiskFreeMiB}`,
+        `heap ratio (constrained/critical): ${thresholds.constrainedHeapRatio}/${thresholds.criticalHeapRatio}`,
+        `busy CPU percent: ${thresholds.busyCpuPercent}`,
+        `caps normal: tools ${caps.normal.maxToolConcurrency}, lanes ${caps.normal.maxParallelLanes}, heavy ${caps.normal.maxHeavyProcesses}`,
+        `caps constrained: tools ${caps.constrained.maxToolConcurrency}, lanes ${caps.constrained.maxParallelLanes}, heavy ${caps.constrained.maxHeavyProcesses}`,
+        `caps critical: tools ${caps.critical.maxToolConcurrency}, lanes ${caps.critical.maxParallelLanes}, heavy ${caps.critical.maxHeavyProcesses}`,
+    ];
+    for (const error of resolved.errors) {
+        lines.push(`error: ${error}`);
+    }
+    return lines;
+}
+export function buildResourceDoctorReport(input) {
+    const { snapshot, decision, resolved } = input;
+    const heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;
+    return {
+        schemaVersion: 1,
+        command: "resource_doctor",
+        mode: resolved.mode,
+        pressure: decision.pressure,
+        action: decision.action,
+        caps: {
+            maxToolConcurrency: decision.maxToolConcurrency,
+            maxParallelLanes: decision.maxParallelLanes,
+            maxHeavyProcesses: decision.maxHeavyProcesses,
+        },
+        reasons: decision.reasons,
+        probeDurationMs: Math.round(input.probeDurationMs),
+        snapshot: {
+            environment: snapshot.environment,
+            logicalCpuCount: snapshot.logicalCpuCount,
+            effectiveAvailableMemoryMiB: toMiB(effectiveAvailableMemoryBytes(snapshot)),
+            processAvailableMemoryMiB: toMiB(snapshot.processAvailableMemoryBytes),
+            constrainedMemoryMiB: toMiB(snapshot.constrainedMemoryBytes),
+            hostFreeMemoryMiB: toMiB(snapshot.hostFreeMemoryBytes),
+            hostTotalMemoryMiB: toMiB(snapshot.hostTotalMemoryBytes),
+            workspaceAvailableMiB: toMiB(snapshot.workspaceAvailableBytes),
+            heapUsedRatio: heapRatio === null ? null : Number(heapRatio.toFixed(4)),
+            systemCpuPercent: snapshot.systemCpuPercent,
+            diagnostics: snapshot.diagnostics,
+        },
+        settingsErrors: resolved.errors,
+    };
+}
+const MIB = 1024 * 1024;
+function toMiB(bytes) {
+    return bytes === null ? null : Math.round(bytes / MIB);
+}
+function formatMiB(bytes) {
+    const mib = toMiB(bytes);
+    return mib === null ? "unknown" : `${mib.toLocaleString()} MiB`;
+}
+//# sourceMappingURL=resource-governor-format.js.map

package/dist/core/resource-governor-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-format.js","sourceRoot":"","sources":["../../src/core/resource-governor-format.ts"],"names":[],"mappings":"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","sourcesContent":["import type { HostResourceSnapshot } from \"./host-resource-snapshot.ts\";\nimport { effectiveAvailableMemoryBytes } from \"./host-resource-snapshot.ts\";\nimport type { ResourceAdmissionDecision, ResourceGovernorMode, ResourceReasonCode } from \"./resource-admission.ts\";\nimport type { ResolvedResourceGovernorSettings } from \"./resource-governor-settings.ts\";\n\nconst REASON_LABELS: Record<ResourceReasonCode, string> = {\n\t\"resource.memory.low\": \"memory low\",\n\t\"resource.memory.critical\": \"memory critical\",\n\t\"resource.disk.low\": \"disk low\",\n\t\"resource.disk.critical\": \"disk critical\",\n\t\"resource.cpu.busy\": \"CPU busy\",\n\t\"resource.heap.high\": \"heap high\",\n\t\"resource.heap.critical\": \"heap critical\",\n\t\"resource.probe.partial\": \"partial probe\",\n\t\"resource.probe.timeout\": \"probe timeout\",\n};\n\n/** Humanize reason codes for the §19.1 summary line (\"memory low, CPU busy\"). */\nexport function describeResourceReasons(reasons: readonly ResourceReasonCode[]): string {\n\tif (reasons.length === 0) {\n\t\treturn \"none\";\n\t}\n\treturn reasons.map((reason) => REASON_LABELS[reason] ?? reason).join(\", \");\n}\n\n/** §19.1 summary block shared by `/resource` and the doctor's human output. */\nexport function formatResourceSummaryLines(mode: ResourceGovernorMode, decision: ResourceAdmissionDecision): string[] {\n\treturn [\n\t\t`mode: ${mode}`,\n\t\t`pressure: ${decision.pressure}`,\n\t\t`action: ${decision.action}`,\n\t\t`tool concurrency: ${decision.maxToolConcurrency}`,\n\t\t`subagent lanes: ${decision.maxParallelLanes}`,\n\t\t`heavy processes: ${decision.maxHeavyProcesses}`,\n\t\t`reasons: ${describeResourceReasons(decision.reasons)}`,\n\t];\n}\n\n/**\n * Verbose probe details for explicit local diagnostics only (§19.1 verbose,\n * §11.3: raw values never enter tool results or model prompts).\n */\nexport function formatResourceProbeLines(snapshot: HostResourceSnapshot): string[] {\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\tconst lines = [\n\t\t`observed at: ${snapshot.observedAt}`,\n\t\t`environment: ${snapshot.environment} (${snapshot.platform}/${snapshot.arch}, ${snapshot.logicalCpuCount} CPUs)`,\n\t\t`effective available memory: ${formatMiB(effectiveAvailableMemoryBytes(snapshot))}`,\n\t\t`  process available: ${formatMiB(snapshot.processAvailableMemoryBytes)}`,\n\t\t`  constrained limit: ${formatMiB(snapshot.constrainedMemoryBytes)}`,\n\t\t`  host free: ${formatMiB(snapshot.hostFreeMemoryBytes)} of ${formatMiB(snapshot.hostTotalMemoryBytes)}`,\n\t\t`workspace disk available: ${formatMiB(snapshot.workspaceAvailableBytes)}`,\n\t\t`heap: ${formatMiB(snapshot.heapUsedBytes)} of ${formatMiB(snapshot.heapLimitBytes)}${heapRatio === null ? \"\" : ` (${(heapRatio * 100).toFixed(1)}%)`}`,\n\t\t`system CPU: ${snapshot.systemCpuPercent === null ? \"unknown\" : `${snapshot.systemCpuPercent.toFixed(1)}%`}`,\n\t];\n\tif (snapshot.diagnostics.length > 0) {\n\t\tlines.push(`diagnostics: ${snapshot.diagnostics.join(\", \")}`);\n\t}\n\treturn lines;\n}\n\n/** Policy view: mode, §6.7 thresholds, §7.2 caps, and §18.1 validation errors. */\nexport function formatResourcePolicyLines(resolved: ResolvedResourceGovernorSettings): string[] {\n\tconst { thresholds, caps } = resolved.admission;\n\tconst lines = [\n\t\t`mode: ${resolved.mode}`,\n\t\t`probe deadline: ${resolved.maxProbeMs ?? 300} ms, CPU sample: ${resolved.cpuSampleMs ?? 180} ms`,\n\t\t`memory MiB (constrained/critical): ${thresholds.constrainedAvailableMemoryMiB}/${thresholds.criticalAvailableMemoryMiB}`,\n\t\t`disk MiB (constrained/critical): ${thresholds.constrainedDiskFreeMiB}/${thresholds.criticalDiskFreeMiB}`,\n\t\t`heap ratio (constrained/critical): ${thresholds.constrainedHeapRatio}/${thresholds.criticalHeapRatio}`,\n\t\t`busy CPU percent: ${thresholds.busyCpuPercent}`,\n\t\t`caps normal: tools ${caps.normal.maxToolConcurrency}, lanes ${caps.normal.maxParallelLanes}, heavy ${caps.normal.maxHeavyProcesses}`,\n\t\t`caps constrained: tools ${caps.constrained.maxToolConcurrency}, lanes ${caps.constrained.maxParallelLanes}, heavy ${caps.constrained.maxHeavyProcesses}`,\n\t\t`caps critical: tools ${caps.critical.maxToolConcurrency}, lanes ${caps.critical.maxParallelLanes}, heavy ${caps.critical.maxHeavyProcesses}`,\n\t];\n\tfor (const error of resolved.errors) {\n\t\tlines.push(`error: ${error}`);\n\t}\n\treturn lines;\n}\n\n/** Bounded JSON schema for `omk doctor resources --json` (§19.2). */\nexport interface ResourceDoctorReport {\n\treadonly schemaVersion: 1;\n\treadonly command: \"resource_doctor\";\n\treadonly mode: ResourceGovernorMode;\n\treadonly pressure: ResourceAdmissionDecision[\"pressure\"];\n\treadonly action: ResourceAdmissionDecision[\"action\"];\n\treadonly caps: {\n\t\treadonly maxToolConcurrency: number;\n\t\treadonly maxParallelLanes: number;\n\t\treadonly maxHeavyProcesses: number;\n\t};\n\treadonly reasons: readonly ResourceReasonCode[];\n\treadonly probeDurationMs: number;\n\treadonly snapshot: {\n\t\treadonly environment: HostResourceSnapshot[\"environment\"];\n\t\treadonly logicalCpuCount: number;\n\t\treadonly effectiveAvailableMemoryMiB: number | null;\n\t\treadonly processAvailableMemoryMiB: number | null;\n\t\treadonly constrainedMemoryMiB: number | null;\n\t\treadonly hostFreeMemoryMiB: number | null;\n\t\treadonly hostTotalMemoryMiB: number | null;\n\t\treadonly workspaceAvailableMiB: number | null;\n\t\treadonly heapUsedRatio: number | null;\n\t\treadonly systemCpuPercent: number | null;\n\t\treadonly diagnostics: readonly string[];\n\t};\n\treadonly settingsErrors: readonly string[];\n}\n\nexport function buildResourceDoctorReport(input: {\n\treadonly snapshot: HostResourceSnapshot;\n\treadonly decision: ResourceAdmissionDecision;\n\treadonly resolved: ResolvedResourceGovernorSettings;\n\treadonly probeDurationMs: number;\n}): ResourceDoctorReport {\n\tconst { snapshot, decision, resolved } = input;\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\treturn {\n\t\tschemaVersion: 1,\n\t\tcommand: \"resource_doctor\",\n\t\tmode: resolved.mode,\n\t\tpressure: decision.pressure,\n\t\taction: decision.action,\n\t\tcaps: {\n\t\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t\t},\n\t\treasons: decision.reasons,\n\t\tprobeDurationMs: Math.round(input.probeDurationMs),\n\t\tsnapshot: {\n\t\t\tenvironment: snapshot.environment,\n\t\t\tlogicalCpuCount: snapshot.logicalCpuCount,\n\t\t\teffectiveAvailableMemoryMiB: toMiB(effectiveAvailableMemoryBytes(snapshot)),\n\t\t\tprocessAvailableMemoryMiB: toMiB(snapshot.processAvailableMemoryBytes),\n\t\t\tconstrainedMemoryMiB: toMiB(snapshot.constrainedMemoryBytes),\n\t\t\thostFreeMemoryMiB: toMiB(snapshot.hostFreeMemoryBytes),\n\t\t\thostTotalMemoryMiB: toMiB(snapshot.hostTotalMemoryBytes),\n\t\t\tworkspaceAvailableMiB: toMiB(snapshot.workspaceAvailableBytes),\n\t\t\theapUsedRatio: heapRatio === null ? null : Number(heapRatio.toFixed(4)),\n\t\t\tsystemCpuPercent: snapshot.systemCpuPercent,\n\t\t\tdiagnostics: snapshot.diagnostics,\n\t\t},\n\t\tsettingsErrors: resolved.errors,\n\t};\n}\n\nconst MIB = 1024 * 1024;\n\nfunction toMiB(bytes: number | null): number | null {\n\treturn bytes === null ? null : Math.round(bytes / MIB);\n}\n\nfunction formatMiB(bytes: number | null): string {\n\tconst mib = toMiB(bytes);\n\treturn mib === null ? \"unknown\" : `${mib.toLocaleString()} MiB`;\n}\n"]}

package/dist/core/resource-governor-settings.d.ts

@@ -0,0 +1,56 @@
+import type { ResourceAdmissionConfig, ResourceGovernorMode } from "./resource-admission.ts";
+export { buildResourceDoctorReport, describeResourceReasons, formatResourcePolicyLines, formatResourceProbeLines, formatResourceSummaryLines, type ResourceDoctorReport, } from "./resource-governor-format.ts";
+/**
+ * Resource governor settings surface (OMK v0.97.x roadmap §18, M1/PR2).
+ *
+ * Pure translation from the additive `resourceGovernor` settings block (and
+ * the §18.2 `OMK_RESOURCE_GOVERNOR` env override) to the layer-1 admission
+ * config plus probe options. Validation follows §18.1: explicit errors over
+ * silent clamps, and invalid input fails closed to the defaults.
+ *
+ * Resolved values feed the `/resource` command, `omk doctor resources`, and
+ * the M2 prompt preflight: `observe` records decisions only, while
+ * `adaptive`/`strict` let the run lease throttle per-run tool concurrency.
+ * Lane and heavy-process caps become authoritative in later milestones.
+ */
+/** Additive settings block (§18, §29.1: absent block keeps v0.96.1 behavior). */
+export interface ResourceGovernorSettings {
+    enabled?: boolean;
+    mode?: ResourceGovernorMode;
+    maxProbeMs?: number;
+    cpuSampleMs?: number;
+    constrainedAvailableMemoryMiB?: number;
+    criticalAvailableMemoryMiB?: number;
+    constrainedDiskFreeMiB?: number;
+    criticalDiskFreeMiB?: number;
+    constrainedHeapRatio?: number;
+    criticalHeapRatio?: number;
+    busyCpuPercent?: number;
+    normalMaxToolConcurrency?: number;
+    constrainedMaxToolConcurrency?: number;
+    criticalMaxToolConcurrency?: number;
+    normalMaxParallelLanes?: number;
+    constrainedMaxParallelLanes?: number;
+    criticalMaxParallelLanes?: number;
+    normalMaxHeavyProcesses?: number;
+    constrainedMaxHeavyProcesses?: number;
+    criticalMaxHeavyProcesses?: number;
+}
+export declare const RESOURCE_GOVERNOR_MODE_ENV = "OMK_RESOURCE_GOVERNOR";
+export declare const DEFAULT_RESOURCE_GOVERNOR_MODE: ResourceGovernorMode;
+export interface ResolvedResourceGovernorSettings {
+    readonly mode: ResourceGovernorMode;
+    /** Only present when the setting is valid; the probe applies its own defaults otherwise. */
+    readonly maxProbeMs?: number;
+    readonly cpuSampleMs?: number;
+    readonly admission: ResourceAdmissionConfig;
+    /** §18.1 explicit validation errors; non-empty means defaults were applied for the failed area. */
+    readonly errors: readonly string[];
+}
+/**
+ * Resolve settings + environment into governor mode, probe options, and the
+ * admission config. Never throws; every invalid field produces an explicit
+ * error and falls back to the corresponding default (§18.1 fail-closed).
+ */
+export declare function resolveResourceGovernorSettings(settings?: ResourceGovernorSettings, env?: NodeJS.ProcessEnv): ResolvedResourceGovernorSettings;
+//# sourceMappingURL=resource-governor-settings.d.ts.map

package/dist/core/resource-governor-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-settings.d.ts","sourceRoot":"","sources":["../../src/core/resource-governor-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,uBAAuB,EAEvB,oBAAoB,EACpB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACN,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,oBAAoB,GACzB,MAAM,+BAA+B,CAAC;AAEvC;;;;;;;;;;;;GAYG;AAEH,mFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAE5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,eAAO,MAAM,8BAA8B,EAAE,oBAAgC,CAAC;AAG9E,MAAM,WAAW,gCAAgC;IAChD,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;IAC5C,oGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC9C,QAAQ,CAAC,EAAE,wBAAwB,EACnC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,gCAAgC,CA6ClC","sourcesContent":["import type {\n\tResourceAdmissionConfig,\n\tResourceAdmissionConfigOverrides,\n\tResourceGovernorMode,\n} from \"./resource-admission.ts\";\nimport { resolveResourceAdmissionConfig } from \"./resource-admission.ts\";\nimport { MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS } from \"./system-cpu-sampler.ts\";\n\nexport {\n\tbuildResourceDoctorReport,\n\tdescribeResourceReasons,\n\tformatResourcePolicyLines,\n\tformatResourceProbeLines,\n\tformatResourceSummaryLines,\n\ttype ResourceDoctorReport,\n} from \"./resource-governor-format.ts\";\n\n/**\n * Resource governor settings surface (OMK v0.97.x roadmap §18, M1/PR2).\n *\n * Pure translation from the additive `resourceGovernor` settings block (and\n * the §18.2 `OMK_RESOURCE_GOVERNOR` env override) to the layer-1 admission\n * config plus probe options. Validation follows §18.1: explicit errors over\n * silent clamps, and invalid input fails closed to the defaults.\n *\n * Resolved values feed the `/resource` command, `omk doctor resources`, and\n * the M2 prompt preflight: `observe` records decisions only, while\n * `adaptive`/`strict` let the run lease throttle per-run tool concurrency.\n * Lane and heavy-process caps become authoritative in later milestones.\n */\n\n/** Additive settings block (§18, §29.1: absent block keeps v0.96.1 behavior). */\nexport interface ResourceGovernorSettings {\n\tenabled?: boolean; // default: true; false forces mode \"off\"\n\tmode?: ResourceGovernorMode; // default: \"observe\" (v0.97.0-alpha rollout stage, §7.4)\n\n\tmaxProbeMs?: number; // default: 300; async probe deadline, valid 50..5000 (§18.1)\n\tcpuSampleMs?: number; // default: 180; CPU two-sample interval, valid 150..250 (§6.3)\n\n\tconstrainedAvailableMemoryMiB?: number; // default: 1536 (§6.7)\n\tcriticalAvailableMemoryMiB?: number; // default: 512\n\tconstrainedDiskFreeMiB?: number; // default: 4096\n\tcriticalDiskFreeMiB?: number; // default: 1024\n\tconstrainedHeapRatio?: number; // default: 0.75\n\tcriticalHeapRatio?: number; // default: 0.85\n\tbusyCpuPercent?: number; // default: 85\n\n\tnormalMaxToolConcurrency?: number; // default: 4 (§7.2)\n\tconstrainedMaxToolConcurrency?: number; // default: 2\n\tcriticalMaxToolConcurrency?: number; // default: 1\n\tnormalMaxParallelLanes?: number; // default: 4\n\tconstrainedMaxParallelLanes?: number; // default: 2\n\tcriticalMaxParallelLanes?: number; // default: 1\n\tnormalMaxHeavyProcesses?: number; // default: 2\n\tconstrainedMaxHeavyProcesses?: number; // default: 1\n\tcriticalMaxHeavyProcesses?: number; // default: 1\n}\n\nexport const RESOURCE_GOVERNOR_MODE_ENV = \"OMK_RESOURCE_GOVERNOR\";\nexport const DEFAULT_RESOURCE_GOVERNOR_MODE: ResourceGovernorMode = \"observe\";\nconst RESOURCE_GOVERNOR_MODES: ReadonlySet<string> = new Set([\"off\", \"observe\", \"adaptive\", \"strict\"]);\n\nexport interface ResolvedResourceGovernorSettings {\n\treadonly mode: ResourceGovernorMode;\n\t/** Only present when the setting is valid; the probe applies its own defaults otherwise. */\n\treadonly maxProbeMs?: number;\n\treadonly cpuSampleMs?: number;\n\treadonly admission: ResourceAdmissionConfig;\n\t/** §18.1 explicit validation errors; non-empty means defaults were applied for the failed area. */\n\treadonly errors: readonly string[];\n}\n\n/**\n * Resolve settings + environment into governor mode, probe options, and the\n * admission config. Never throws; every invalid field produces an explicit\n * error and falls back to the corresponding default (§18.1 fail-closed).\n */\nexport function resolveResourceGovernorSettings(\n\tsettings?: ResourceGovernorSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedResourceGovernorSettings {\n\tconst errors: string[] = [];\n\tconst mode = resolveMode(settings, env, errors);\n\n\tconst maxProbeMs = validateRange(settings?.maxProbeMs, \"maxProbeMs\", 50, 5000, errors);\n\tconst cpuSampleMs = validateRange(\n\t\tsettings?.cpuSampleMs,\n\t\t\"cpuSampleMs\",\n\t\tMIN_CPU_SAMPLE_MS,\n\t\tMAX_CPU_SAMPLE_MS,\n\t\terrors,\n\t);\n\n\tconst overrides: ResourceAdmissionConfigOverrides = {\n\t\tthresholds: pruneUndefined({\n\t\t\tconstrainedAvailableMemoryMiB: settings?.constrainedAvailableMemoryMiB,\n\t\t\tcriticalAvailableMemoryMiB: settings?.criticalAvailableMemoryMiB,\n\t\t\tconstrainedDiskFreeMiB: settings?.constrainedDiskFreeMiB,\n\t\t\tcriticalDiskFreeMiB: settings?.criticalDiskFreeMiB,\n\t\t\tconstrainedHeapRatio: settings?.constrainedHeapRatio,\n\t\t\tcriticalHeapRatio: settings?.criticalHeapRatio,\n\t\t\tbusyCpuPercent: settings?.busyCpuPercent,\n\t\t}),\n\t\tcaps: {\n\t\t\tnormal: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.normalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.normalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.normalMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tconstrained: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.constrainedMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.constrainedMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.constrainedMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tcritical: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.criticalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.criticalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.criticalMaxHeavyProcesses,\n\t\t\t}),\n\t\t},\n\t};\n\tconst admission = resolveResourceAdmissionConfig(overrides);\n\terrors.push(...admission.errors);\n\n\treturn { mode, maxProbeMs, cpuSampleMs, admission: admission.config, errors };\n}\n\nfunction resolveMode(\n\tsettings: ResourceGovernorSettings | undefined,\n\tenv: NodeJS.ProcessEnv,\n\terrors: string[],\n): ResourceGovernorMode {\n\t// §18.2/§30.1: the env override is the operator kill switch and wins.\n\tconst envMode = env[RESOURCE_GOVERNOR_MODE_ENV]?.trim();\n\tif (envMode !== undefined && envMode !== \"\") {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(envMode)) {\n\t\t\treturn envMode as ResourceGovernorMode;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid ${RESOURCE_GOVERNOR_MODE_ENV} value ${JSON.stringify(envMode)}`);\n\t}\n\tif (settings?.enabled === false) {\n\t\treturn \"off\";\n\t}\n\tconst configured = settings?.mode;\n\tif (configured !== undefined) {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(configured)) {\n\t\t\treturn configured;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid value ${JSON.stringify(configured)}`);\n\t}\n\treturn DEFAULT_RESOURCE_GOVERNOR_MODE;\n}\n\nfunction validateRange(\n\tvalue: number | undefined,\n\tfield: string,\n\tmin: number,\n\tmax: number,\n\terrors: string[],\n): number | undefined {\n\tif (value === undefined) {\n\t\treturn undefined;\n\t}\n\tif (!Number.isSafeInteger(value) || value < min || value > max) {\n\t\terrors.push(`resourceGovernor.${field}: must be an integer within [${min}, ${max}], got ${String(value)}`);\n\t\treturn undefined;\n\t}\n\treturn value;\n}\n\nfunction pruneUndefined<T extends Record<string, number | undefined>>(record: T): Partial<T> {\n\tconst pruned: Record<string, number> = {};\n\tfor (const [key, value] of Object.entries(record)) {\n\t\tif (value !== undefined) {\n\t\t\tpruned[key] = value;\n\t\t}\n\t}\n\treturn pruned as Partial<T>;\n}\n"]}

package/dist/core/resource-governor-settings.js

@@ -0,0 +1,89 @@
+import { resolveResourceAdmissionConfig } from "./resource-admission.js";
+import { MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS } from "./system-cpu-sampler.js";
+export { buildResourceDoctorReport, describeResourceReasons, formatResourcePolicyLines, formatResourceProbeLines, formatResourceSummaryLines, } from "./resource-governor-format.js";
+export const RESOURCE_GOVERNOR_MODE_ENV = "OMK_RESOURCE_GOVERNOR";
+export const DEFAULT_RESOURCE_GOVERNOR_MODE = "observe";
+const RESOURCE_GOVERNOR_MODES = new Set(["off", "observe", "adaptive", "strict"]);
+/**
+ * Resolve settings + environment into governor mode, probe options, and the
+ * admission config. Never throws; every invalid field produces an explicit
+ * error and falls back to the corresponding default (§18.1 fail-closed).
+ */
+export function resolveResourceGovernorSettings(settings, env = process.env) {
+    const errors = [];
+    const mode = resolveMode(settings, env, errors);
+    const maxProbeMs = validateRange(settings?.maxProbeMs, "maxProbeMs", 50, 5000, errors);
+    const cpuSampleMs = validateRange(settings?.cpuSampleMs, "cpuSampleMs", MIN_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS, errors);
+    const overrides = {
+        thresholds: pruneUndefined({
+            constrainedAvailableMemoryMiB: settings?.constrainedAvailableMemoryMiB,
+            criticalAvailableMemoryMiB: settings?.criticalAvailableMemoryMiB,
+            constrainedDiskFreeMiB: settings?.constrainedDiskFreeMiB,
+            criticalDiskFreeMiB: settings?.criticalDiskFreeMiB,
+            constrainedHeapRatio: settings?.constrainedHeapRatio,
+            criticalHeapRatio: settings?.criticalHeapRatio,
+            busyCpuPercent: settings?.busyCpuPercent,
+        }),
+        caps: {
+            normal: pruneUndefined({
+                maxToolConcurrency: settings?.normalMaxToolConcurrency,
+                maxParallelLanes: settings?.normalMaxParallelLanes,
+                maxHeavyProcesses: settings?.normalMaxHeavyProcesses,
+            }),
+            constrained: pruneUndefined({
+                maxToolConcurrency: settings?.constrainedMaxToolConcurrency,
+                maxParallelLanes: settings?.constrainedMaxParallelLanes,
+                maxHeavyProcesses: settings?.constrainedMaxHeavyProcesses,
+            }),
+            critical: pruneUndefined({
+                maxToolConcurrency: settings?.criticalMaxToolConcurrency,
+                maxParallelLanes: settings?.criticalMaxParallelLanes,
+                maxHeavyProcesses: settings?.criticalMaxHeavyProcesses,
+            }),
+        },
+    };
+    const admission = resolveResourceAdmissionConfig(overrides);
+    errors.push(...admission.errors);
+    return { mode, maxProbeMs, cpuSampleMs, admission: admission.config, errors };
+}
+function resolveMode(settings, env, errors) {
+    // §18.2/§30.1: the env override is the operator kill switch and wins.
+    const envMode = env[RESOURCE_GOVERNOR_MODE_ENV]?.trim();
+    if (envMode !== undefined && envMode !== "") {
+        if (RESOURCE_GOVERNOR_MODES.has(envMode)) {
+            return envMode;
+        }
+        errors.push(`resourceGovernor.mode: invalid ${RESOURCE_GOVERNOR_MODE_ENV} value ${JSON.stringify(envMode)}`);
+    }
+    if (settings?.enabled === false) {
+        return "off";
+    }
+    const configured = settings?.mode;
+    if (configured !== undefined) {
+        if (RESOURCE_GOVERNOR_MODES.has(configured)) {
+            return configured;
+        }
+        errors.push(`resourceGovernor.mode: invalid value ${JSON.stringify(configured)}`);
+    }
+    return DEFAULT_RESOURCE_GOVERNOR_MODE;
+}
+function validateRange(value, field, min, max, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        errors.push(`resourceGovernor.${field}: must be an integer within [${min}, ${max}], got ${String(value)}`);
+        return undefined;
+    }
+    return value;
+}
+function pruneUndefined(record) {
+    const pruned = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined) {
+            pruned[key] = value;
+        }
+    }
+    return pruned;
+}
+//# sourceMappingURL=resource-governor-settings.js.map

package/dist/core/resource-governor-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-settings.js","sourceRoot":"","sources":["../../src/core/resource-governor-settings.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n\tResourceAdmissionConfig,\n\tResourceAdmissionConfigOverrides,\n\tResourceGovernorMode,\n} from \"./resource-admission.ts\";\nimport { resolveResourceAdmissionConfig } from \"./resource-admission.ts\";\nimport { MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS } from \"./system-cpu-sampler.ts\";\n\nexport {\n\tbuildResourceDoctorReport,\n\tdescribeResourceReasons,\n\tformatResourcePolicyLines,\n\tformatResourceProbeLines,\n\tformatResourceSummaryLines,\n\ttype ResourceDoctorReport,\n} from \"./resource-governor-format.ts\";\n\n/**\n * Resource governor settings surface (OMK v0.97.x roadmap §18, M1/PR2).\n *\n * Pure translation from the additive `resourceGovernor` settings block (and\n * the §18.2 `OMK_RESOURCE_GOVERNOR` env override) to the layer-1 admission\n * config plus probe options. Validation follows §18.1: explicit errors over\n * silent clamps, and invalid input fails closed to the defaults.\n *\n * Resolved values feed the `/resource` command, `omk doctor resources`, and\n * the M2 prompt preflight: `observe` records decisions only, while\n * `adaptive`/`strict` let the run lease throttle per-run tool concurrency.\n * Lane and heavy-process caps become authoritative in later milestones.\n */\n\n/** Additive settings block (§18, §29.1: absent block keeps v0.96.1 behavior). */\nexport interface ResourceGovernorSettings {\n\tenabled?: boolean; // default: true; false forces mode \"off\"\n\tmode?: ResourceGovernorMode; // default: \"observe\" (v0.97.0-alpha rollout stage, §7.4)\n\n\tmaxProbeMs?: number; // default: 300; async probe deadline, valid 50..5000 (§18.1)\n\tcpuSampleMs?: number; // default: 180; CPU two-sample interval, valid 150..250 (§6.3)\n\n\tconstrainedAvailableMemoryMiB?: number; // default: 1536 (§6.7)\n\tcriticalAvailableMemoryMiB?: number; // default: 512\n\tconstrainedDiskFreeMiB?: number; // default: 4096\n\tcriticalDiskFreeMiB?: number; // default: 1024\n\tconstrainedHeapRatio?: number; // default: 0.75\n\tcriticalHeapRatio?: number; // default: 0.85\n\tbusyCpuPercent?: number; // default: 85\n\n\tnormalMaxToolConcurrency?: number; // default: 4 (§7.2)\n\tconstrainedMaxToolConcurrency?: number; // default: 2\n\tcriticalMaxToolConcurrency?: number; // default: 1\n\tnormalMaxParallelLanes?: number; // default: 4\n\tconstrainedMaxParallelLanes?: number; // default: 2\n\tcriticalMaxParallelLanes?: number; // default: 1\n\tnormalMaxHeavyProcesses?: number; // default: 2\n\tconstrainedMaxHeavyProcesses?: number; // default: 1\n\tcriticalMaxHeavyProcesses?: number; // default: 1\n}\n\nexport const RESOURCE_GOVERNOR_MODE_ENV = \"OMK_RESOURCE_GOVERNOR\";\nexport const DEFAULT_RESOURCE_GOVERNOR_MODE: ResourceGovernorMode = \"observe\";\nconst RESOURCE_GOVERNOR_MODES: ReadonlySet<string> = new Set([\"off\", \"observe\", \"adaptive\", \"strict\"]);\n\nexport interface ResolvedResourceGovernorSettings {\n\treadonly mode: ResourceGovernorMode;\n\t/** Only present when the setting is valid; the probe applies its own defaults otherwise. */\n\treadonly maxProbeMs?: number;\n\treadonly cpuSampleMs?: number;\n\treadonly admission: ResourceAdmissionConfig;\n\t/** §18.1 explicit validation errors; non-empty means defaults were applied for the failed area. */\n\treadonly errors: readonly string[];\n}\n\n/**\n * Resolve settings + environment into governor mode, probe options, and the\n * admission config. Never throws; every invalid field produces an explicit\n * error and falls back to the corresponding default (§18.1 fail-closed).\n */\nexport function resolveResourceGovernorSettings(\n\tsettings?: ResourceGovernorSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedResourceGovernorSettings {\n\tconst errors: string[] = [];\n\tconst mode = resolveMode(settings, env, errors);\n\n\tconst maxProbeMs = validateRange(settings?.maxProbeMs, \"maxProbeMs\", 50, 5000, errors);\n\tconst cpuSampleMs = validateRange(\n\t\tsettings?.cpuSampleMs,\n\t\t\"cpuSampleMs\",\n\t\tMIN_CPU_SAMPLE_MS,\n\t\tMAX_CPU_SAMPLE_MS,\n\t\terrors,\n\t);\n\n\tconst overrides: ResourceAdmissionConfigOverrides = {\n\t\tthresholds: pruneUndefined({\n\t\t\tconstrainedAvailableMemoryMiB: settings?.constrainedAvailableMemoryMiB,\n\t\t\tcriticalAvailableMemoryMiB: settings?.criticalAvailableMemoryMiB,\n\t\t\tconstrainedDiskFreeMiB: settings?.constrainedDiskFreeMiB,\n\t\t\tcriticalDiskFreeMiB: settings?.criticalDiskFreeMiB,\n\t\t\tconstrainedHeapRatio: settings?.constrainedHeapRatio,\n\t\t\tcriticalHeapRatio: settings?.criticalHeapRatio,\n\t\t\tbusyCpuPercent: settings?.busyCpuPercent,\n\t\t}),\n\t\tcaps: {\n\t\t\tnormal: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.normalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.normalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.normalMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tconstrained: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.constrainedMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.constrainedMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.constrainedMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tcritical: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.criticalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.criticalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.criticalMaxHeavyProcesses,\n\t\t\t}),\n\t\t},\n\t};\n\tconst admission = resolveResourceAdmissionConfig(overrides);\n\terrors.push(...admission.errors);\n\n\treturn { mode, maxProbeMs, cpuSampleMs, admission: admission.config, errors };\n}\n\nfunction resolveMode(\n\tsettings: ResourceGovernorSettings | undefined,\n\tenv: NodeJS.ProcessEnv,\n\terrors: string[],\n): ResourceGovernorMode {\n\t// §18.2/§30.1: the env override is the operator kill switch and wins.\n\tconst envMode = env[RESOURCE_GOVERNOR_MODE_ENV]?.trim();\n\tif (envMode !== undefined && envMode !== \"\") {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(envMode)) {\n\t\t\treturn envMode as ResourceGovernorMode;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid ${RESOURCE_GOVERNOR_MODE_ENV} value ${JSON.stringify(envMode)}`);\n\t}\n\tif (settings?.enabled === false) {\n\t\treturn \"off\";\n\t}\n\tconst configured = settings?.mode;\n\tif (configured !== undefined) {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(configured)) {\n\t\t\treturn configured;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid value ${JSON.stringify(configured)}`);\n\t}\n\treturn DEFAULT_RESOURCE_GOVERNOR_MODE;\n}\n\nfunction validateRange(\n\tvalue: number | undefined,\n\tfield: string,\n\tmin: number,\n\tmax: number,\n\terrors: string[],\n): number | undefined {\n\tif (value === undefined) {\n\t\treturn undefined;\n\t}\n\tif (!Number.isSafeInteger(value) || value < min || value > max) {\n\t\terrors.push(`resourceGovernor.${field}: must be an integer within [${min}, ${max}], got ${String(value)}`);\n\t\treturn undefined;\n\t}\n\treturn value;\n}\n\nfunction pruneUndefined<T extends Record<string, number | undefined>>(record: T): Partial<T> {\n\tconst pruned: Record<string, number> = {};\n\tfor (const [key, value] of Object.entries(record)) {\n\t\tif (value !== undefined) {\n\t\t\tpruned[key] = value;\n\t\t}\n\t}\n\treturn pruned as Partial<T>;\n}\n"]}

package/dist/core/resource-observation-journal.d.ts

@@ -0,0 +1,74 @@
+import type { CompletionSoundResult } from "./completion-sound.ts";
+import type { PromptSettledEvent } from "./prompt-settlement.ts";
+import type { ResourceAdmissionDecision } from "./resource-admission.ts";
+import type { WorkloadClassification } from "./workload-classifier.ts";
+/**
+ * Local-only resource observation journal (roadmap §15.1/§15.2/§20.2).
+ *
+ * A dedicated JSONL artifact under `.omk/runs/<promptRunId>/` — deliberately
+ * NOT the hash-chained run journal: §15.2 restricts raw host facts to a
+ * separate local-only artifact, and extending the run journal's closed audit
+ * union would invalidate old readers. Shard plan/transition entries stay in
+ * `workload-shards.jsonl` (they already journal there); this file carries
+ * the remaining §20.2 entries.
+ *
+ * Privacy (§15.2, §20.3, §30): facts are flat primitives only — pressure
+ * levels, caps, digests, durations, reason codes. Never raw memory/cpu
+ * numbers, hostnames, usernames, or command text. Observability is
+ * fail-open: a write/read failure degrades to diagnostics, never breaks the
+ * run (probe failure is non-fatal by contract).
+ */
+export declare const RESOURCE_OBSERVATION_JOURNAL_FILE = "resource-observations.jsonl";
+/** §20.2 journal entry kinds handled by this artifact. */
+export declare const RESOURCE_OBSERVATION_KINDS: readonly ["resource_snapshot_v1", "resource_admission_v1", "resource_lease_acquired_v1", "resource_lease_released_v1", "workload_classification_v1", "workload_permit_wait_v1", "workload_permit_acquired_v1", "workload_permit_released_v1", "prompt_settled_v1", "completion_sound_result_v1"];
+export type ResourceObservationKind = (typeof RESOURCE_OBSERVATION_KINDS)[number];
+export type ResourceObservationFacts = Readonly<Record<string, string | number | boolean | null>>;
+export interface ResourceObservationRecord {
+    readonly schemaVersion: 1;
+    readonly seq: number;
+    readonly kind: ResourceObservationKind;
+    readonly at: string;
+    readonly promptRunId: string;
+    readonly facts: ResourceObservationFacts;
+}
+/** §15.1 protocol observation projection of one journal record. */
+export interface ResourceProtocolObservation {
+    readonly kind: "resource_snapshot.v1" | "resource_admission.v1" | "workload_classification.v1" | "workload_permit.v1" | "prompt_settled.v1" | "notification_result.v1";
+    readonly facts: ResourceObservationFacts;
+}
+/**
+ * Project a journal record onto the §15.1 protocol observation surface.
+ * Lease entries are local-only operational detail and project to null.
+ */
+export declare function toProtocolObservation(record: ResourceObservationRecord): ResourceProtocolObservation | null;
+/** §15.2: probe health and digest only — raw host values never leave the process. */
+export declare function snapshotObservationFacts(snapshot: {
+    readonly systemCpuPercent: number | null;
+    readonly processAvailableMemoryBytes: number | null;
+    readonly hostFreeMemoryBytes: number | null;
+    readonly heapLimitBytes: number;
+}): ResourceObservationFacts;
+/** §15.2 example shape: pressure, action, and the three caps. */
+export declare function admissionObservationFacts(decision: ResourceAdmissionDecision): ResourceObservationFacts;
+export declare function classificationObservationFacts(classification: WorkloadClassification): ResourceObservationFacts;
+export declare function settledObservationFacts(event: PromptSettledEvent): ResourceObservationFacts;
+export declare function soundObservationFacts(result: CompletionSoundResult): ResourceObservationFacts;
+export interface ResourceObservationLoadResult {
+    readonly records: readonly ResourceObservationRecord[];
+    readonly diagnostics: readonly string[];
+}
+export declare class ResourceObservationJournal {
+    private readonly journalPath;
+    private readonly promptRunId;
+    private readonly now;
+    private seq;
+    private disabled;
+    constructor(journalPath: string, promptRunId: string, now?: () => Date);
+    static open(cwd: string, promptRunId: string, now?: () => Date): ResourceObservationJournal;
+    get filePath(): string;
+    /** Fail-open append: returns false (and stops trying) instead of throwing. */
+    record(kind: ResourceObservationKind, facts: ResourceObservationFacts): boolean;
+    /** Fail-open load: malformed lines become diagnostics, never throws. */
+    load(): ResourceObservationLoadResult;
+}
+//# sourceMappingURL=resource-observation-journal.d.ts.map

package/dist/core/resource-observation-journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-observation-journal.d.ts","sourceRoot":"","sources":["../../src/core/resource-observation-journal.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport type { CompletionSoundResult } from \"./completion-sound.ts\";\nimport type { PromptSettledEvent } from \"./prompt-settlement.ts\";\nimport type { ResourceAdmissionDecision } from \"./resource-admission.ts\";\nimport type { WorkloadClassification } from \"./workload-classifier.ts\";\n\n/**\n * Local-only resource observation journal (roadmap §15.1/§15.2/§20.2).\n *\n * A dedicated JSONL artifact under `.omk/runs/<promptRunId>/` — deliberately\n * NOT the hash-chained run journal: §15.2 restricts raw host facts to a\n * separate local-only artifact, and extending the run journal's closed audit\n * union would invalidate old readers. Shard plan/transition entries stay in\n * `workload-shards.jsonl` (they already journal there); this file carries\n * the remaining §20.2 entries.\n *\n * Privacy (§15.2, §20.3, §30): facts are flat primitives only — pressure\n * levels, caps, digests, durations, reason codes. Never raw memory/cpu\n * numbers, hostnames, usernames, or command text. Observability is\n * fail-open: a write/read failure degrades to diagnostics, never breaks the\n * run (probe failure is non-fatal by contract).\n */\n\nexport const RESOURCE_OBSERVATION_JOURNAL_FILE = \"resource-observations.jsonl\";\n\n/** §20.2 journal entry kinds handled by this artifact. */\nexport const RESOURCE_OBSERVATION_KINDS = [\n\t\"resource_snapshot_v1\",\n\t\"resource_admission_v1\",\n\t\"resource_lease_acquired_v1\",\n\t\"resource_lease_released_v1\",\n\t\"workload_classification_v1\",\n\t\"workload_permit_wait_v1\",\n\t\"workload_permit_acquired_v1\",\n\t\"workload_permit_released_v1\",\n\t\"prompt_settled_v1\",\n\t\"completion_sound_result_v1\",\n] as const;\n\nexport type ResourceObservationKind = (typeof RESOURCE_OBSERVATION_KINDS)[number];\n\nexport type ResourceObservationFacts = Readonly<Record<string, string | number | boolean | null>>;\n\nexport interface ResourceObservationRecord {\n\treadonly schemaVersion: 1;\n\treadonly seq: number;\n\treadonly kind: ResourceObservationKind;\n\treadonly at: string;\n\treadonly promptRunId: string;\n\treadonly facts: ResourceObservationFacts;\n}\n\n/** §15.1 protocol observation projection of one journal record. */\nexport interface ResourceProtocolObservation {\n\treadonly kind:\n\t\t| \"resource_snapshot.v1\"\n\t\t| \"resource_admission.v1\"\n\t\t| \"workload_classification.v1\"\n\t\t| \"workload_permit.v1\"\n\t\t| \"prompt_settled.v1\"\n\t\t| \"notification_result.v1\";\n\treadonly facts: ResourceObservationFacts;\n}\n\nconst PROTOCOL_KIND_BY_JOURNAL_KIND: Readonly<\n\tPartial<Record<ResourceObservationKind, ResourceProtocolObservation[\"kind\"]>>\n> = {\n\tresource_snapshot_v1: \"resource_snapshot.v1\",\n\tresource_admission_v1: \"resource_admission.v1\",\n\tworkload_classification_v1: \"workload_classification.v1\",\n\tworkload_permit_wait_v1: \"workload_permit.v1\",\n\tworkload_permit_acquired_v1: \"workload_permit.v1\",\n\tworkload_permit_released_v1: \"workload_permit.v1\",\n\tprompt_settled_v1: \"prompt_settled.v1\",\n\tcompletion_sound_result_v1: \"notification_result.v1\",\n};\n\n/**\n * Project a journal record onto the §15.1 protocol observation surface.\n * Lease entries are local-only operational detail and project to null.\n */\nexport function toProtocolObservation(record: ResourceObservationRecord): ResourceProtocolObservation | null {\n\tconst kind = PROTOCOL_KIND_BY_JOURNAL_KIND[record.kind];\n\treturn kind === undefined ? null : { kind, facts: record.facts };\n}\n\n/** §15.2: probe health and digest only — raw host values never leave the process. */\nexport function snapshotObservationFacts(snapshot: {\n\treadonly systemCpuPercent: number | null;\n\treadonly processAvailableMemoryBytes: number | null;\n\treadonly hostFreeMemoryBytes: number | null;\n\treadonly heapLimitBytes: number;\n}): ResourceObservationFacts {\n\treturn {\n\t\tcpuProbe: snapshot.systemCpuPercent !== null,\n\t\tmemoryProbe: snapshot.processAvailableMemoryBytes !== null || snapshot.hostFreeMemoryBytes !== null,\n\t\theapLimitKnown: snapshot.heapLimitBytes > 0,\n\t};\n}\n\n/** §15.2 example shape: pressure, action, and the three caps. */\nexport function admissionObservationFacts(decision: ResourceAdmissionDecision): ResourceObservationFacts {\n\treturn {\n\t\tdecisionId: decision.decisionId,\n\t\tsnapshotDigest: decision.snapshotDigest,\n\t\tpressure: decision.pressure,\n\t\taction: decision.action,\n\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t};\n}\n\nexport function classificationObservationFacts(classification: WorkloadClassification): ResourceObservationFacts {\n\treturn {\n\t\tworkloadClass: classification.workloadClass,\n\t\tcommandFamily: classification.commandFamily,\n\t\tcomplexity: classification.complexity,\n\t\tsafeToAutoShard: classification.safeToAutoShard,\n\t\treasonCodes: classification.reasonCodes.slice(0, 8).join(\",\"),\n\t};\n}\n\nexport function settledObservationFacts(event: PromptSettledEvent): ResourceObservationFacts {\n\treturn {\n\t\toutcome: event.outcome,\n\t\tdurationMs: event.durationMs,\n\t\t...(event.terminationKind !== undefined ? { terminationKind: event.terminationKind } : {}),\n\t};\n}\n\nexport function soundObservationFacts(result: CompletionSoundResult): ResourceObservationFacts {\n\treturn {\n\t\tbackend: result.backend,\n\t\tattempted: result.attempted,\n\t\tsuccess: result.success,\n\t\t...(result.diagnostic !== undefined ? { diagnostic: result.diagnostic.slice(0, 120) } : {}),\n\t};\n}\n\nconst MAX_LINE_BYTES = 8 * 1024;\nconst MAX_RECORDS = 10_000;\n\nexport interface ResourceObservationLoadResult {\n\treadonly records: readonly ResourceObservationRecord[];\n\treadonly diagnostics: readonly string[];\n}\n\nexport class ResourceObservationJournal {\n\tprivate readonly journalPath: string;\n\tprivate readonly promptRunId: string;\n\tprivate readonly now: () => Date;\n\tprivate seq = 0;\n\tprivate disabled = false;\n\n\tconstructor(journalPath: string, promptRunId: string, now: () => Date = () => new Date()) {\n\t\tthis.journalPath = journalPath;\n\t\tthis.promptRunId = promptRunId;\n\t\tthis.now = now;\n\t}\n\n\tstatic open(cwd: string, promptRunId: string, now?: () => Date): ResourceObservationJournal {\n\t\treturn new ResourceObservationJournal(\n\t\t\tpath.join(cwd, \".omk\", \"runs\", promptRunId, RESOURCE_OBSERVATION_JOURNAL_FILE),\n\t\t\tpromptRunId,\n\t\t\tnow,\n\t\t);\n\t}\n\n\tget filePath(): string {\n\t\treturn this.journalPath;\n\t}\n\n\t/** Fail-open append: returns false (and stops trying) instead of throwing. */\n\trecord(kind: ResourceObservationKind, facts: ResourceObservationFacts): boolean {\n\t\tif (this.disabled || this.seq >= MAX_RECORDS) return false;\n\t\tconst entry: ResourceObservationRecord = {\n\t\t\tschemaVersion: 1,\n\t\t\tseq: this.seq + 1,\n\t\t\tkind,\n\t\t\tat: this.now().toISOString(),\n\t\t\tpromptRunId: this.promptRunId,\n\t\t\tfacts,\n\t\t};\n\t\tconst line = `${JSON.stringify(entry)}\\n`;\n\t\tif (line.length > MAX_LINE_BYTES) return false;\n\t\ttry {\n\t\t\tfs.mkdirSync(path.dirname(this.journalPath), { recursive: true });\n\t\t\tfs.appendFileSync(this.journalPath, line, \"utf8\");\n\t\t\tthis.seq = entry.seq;\n\t\t\treturn true;\n\t\t} catch {\n\t\t\t// Observability must never break the run; stop retrying this run.\n\t\t\tthis.disabled = true;\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Fail-open load: malformed lines become diagnostics, never throws. */\n\tload(): ResourceObservationLoadResult {\n\t\tlet raw: string;\n\t\ttry {\n\t\t\traw = fs.readFileSync(this.journalPath, \"utf8\");\n\t\t} catch {\n\t\t\treturn { records: [], diagnostics: [] };\n\t\t}\n\t\tconst records: ResourceObservationRecord[] = [];\n\t\tconst diagnostics: string[] = [];\n\t\tconst lines = raw.split(\"\\n\");\n\t\tfor (let index = 0; index < lines.length && records.length < MAX_RECORDS; index++) {\n\t\t\tconst line = lines[index].trim();\n\t\t\tif (line === \"\") continue;\n\t\t\tconst parsed = parseObservationLine(line);\n\t\t\tif (parsed === null) {\n\t\t\t\tdiagnostics.push(`line ${index + 1}: invalid observation record`);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\trecords.push(parsed);\n\t\t}\n\t\treturn { records, diagnostics };\n\t}\n}\n\nconst KIND_SET: ReadonlySet<string> = new Set(RESOURCE_OBSERVATION_KINDS);\n\nfunction parseObservationLine(line: string): ResourceObservationRecord | null {\n\tif (line.length > MAX_LINE_BYTES) return null;\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(line);\n\t} catch {\n\t\treturn null;\n\t}\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return null;\n\tconst record = value as Record<string, unknown>;\n\tif (record.schemaVersion !== 1) return null;\n\tif (typeof record.seq !== \"number\" || !Number.isSafeInteger(record.seq) || record.seq < 1) return null;\n\tif (typeof record.kind !== \"string\" || !KIND_SET.has(record.kind)) return null;\n\tif (typeof record.at !== \"string\" || typeof record.promptRunId !== \"string\") return null;\n\tif (typeof record.facts !== \"object\" || record.facts === null || Array.isArray(record.facts)) return null;\n\tfor (const factValue of Object.values(record.facts)) {\n\t\tconst kind = typeof factValue;\n\t\tif (factValue !== null && kind !== \"string\" && kind !== \"number\" && kind !== \"boolean\") return null;\n\t}\n\treturn record as unknown as ResourceObservationRecord;\n}\n"]}

package/dist/core/resource-observation-journal.js

@@ -0,0 +1,198 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Local-only resource observation journal (roadmap §15.1/§15.2/§20.2).
+ *
+ * A dedicated JSONL artifact under `.omk/runs/<promptRunId>/` — deliberately
+ * NOT the hash-chained run journal: §15.2 restricts raw host facts to a
+ * separate local-only artifact, and extending the run journal's closed audit
+ * union would invalidate old readers. Shard plan/transition entries stay in
+ * `workload-shards.jsonl` (they already journal there); this file carries
+ * the remaining §20.2 entries.
+ *
+ * Privacy (§15.2, §20.3, §30): facts are flat primitives only — pressure
+ * levels, caps, digests, durations, reason codes. Never raw memory/cpu
+ * numbers, hostnames, usernames, or command text. Observability is
+ * fail-open: a write/read failure degrades to diagnostics, never breaks the
+ * run (probe failure is non-fatal by contract).
+ */
+export const RESOURCE_OBSERVATION_JOURNAL_FILE = "resource-observations.jsonl";
+/** §20.2 journal entry kinds handled by this artifact. */
+export const RESOURCE_OBSERVATION_KINDS = [
+    "resource_snapshot_v1",
+    "resource_admission_v1",
+    "resource_lease_acquired_v1",
+    "resource_lease_released_v1",
+    "workload_classification_v1",
+    "workload_permit_wait_v1",
+    "workload_permit_acquired_v1",
+    "workload_permit_released_v1",
+    "prompt_settled_v1",
+    "completion_sound_result_v1",
+];
+const PROTOCOL_KIND_BY_JOURNAL_KIND = {
+    resource_snapshot_v1: "resource_snapshot.v1",
+    resource_admission_v1: "resource_admission.v1",
+    workload_classification_v1: "workload_classification.v1",
+    workload_permit_wait_v1: "workload_permit.v1",
+    workload_permit_acquired_v1: "workload_permit.v1",
+    workload_permit_released_v1: "workload_permit.v1",
+    prompt_settled_v1: "prompt_settled.v1",
+    completion_sound_result_v1: "notification_result.v1",
+};
+/**
+ * Project a journal record onto the §15.1 protocol observation surface.
+ * Lease entries are local-only operational detail and project to null.
+ */
+export function toProtocolObservation(record) {
+    const kind = PROTOCOL_KIND_BY_JOURNAL_KIND[record.kind];
+    return kind === undefined ? null : { kind, facts: record.facts };
+}
+/** §15.2: probe health and digest only — raw host values never leave the process. */
+export function snapshotObservationFacts(snapshot) {
+    return {
+        cpuProbe: snapshot.systemCpuPercent !== null,
+        memoryProbe: snapshot.processAvailableMemoryBytes !== null || snapshot.hostFreeMemoryBytes !== null,
+        heapLimitKnown: snapshot.heapLimitBytes > 0,
+    };
+}
+/** §15.2 example shape: pressure, action, and the three caps. */
+export function admissionObservationFacts(decision) {
+    return {
+        decisionId: decision.decisionId,
+        snapshotDigest: decision.snapshotDigest,
+        pressure: decision.pressure,
+        action: decision.action,
+        maxToolConcurrency: decision.maxToolConcurrency,
+        maxParallelLanes: decision.maxParallelLanes,
+        maxHeavyProcesses: decision.maxHeavyProcesses,
+    };
+}
+export function classificationObservationFacts(classification) {
+    return {
+        workloadClass: classification.workloadClass,
+        commandFamily: classification.commandFamily,
+        complexity: classification.complexity,
+        safeToAutoShard: classification.safeToAutoShard,
+        reasonCodes: classification.reasonCodes.slice(0, 8).join(","),
+    };
+}
+export function settledObservationFacts(event) {
+    return {
+        outcome: event.outcome,
+        durationMs: event.durationMs,
+        ...(event.terminationKind !== undefined ? { terminationKind: event.terminationKind } : {}),
+    };
+}
+export function soundObservationFacts(result) {
+    return {
+        backend: result.backend,
+        attempted: result.attempted,
+        success: result.success,
+        ...(result.diagnostic !== undefined ? { diagnostic: result.diagnostic.slice(0, 120) } : {}),
+    };
+}
+const MAX_LINE_BYTES = 8 * 1024;
+const MAX_RECORDS = 10_000;
+export class ResourceObservationJournal {
+    journalPath;
+    promptRunId;
+    now;
+    seq = 0;
+    disabled = false;
+    constructor(journalPath, promptRunId, now = () => new Date()) {
+        this.journalPath = journalPath;
+        this.promptRunId = promptRunId;
+        this.now = now;
+    }
+    static open(cwd, promptRunId, now) {
+        return new ResourceObservationJournal(path.join(cwd, ".omk", "runs", promptRunId, RESOURCE_OBSERVATION_JOURNAL_FILE), promptRunId, now);
+    }
+    get filePath() {
+        return this.journalPath;
+    }
+    /** Fail-open append: returns false (and stops trying) instead of throwing. */
+    record(kind, facts) {
+        if (this.disabled || this.seq >= MAX_RECORDS)
+            return false;
+        const entry = {
+            schemaVersion: 1,
+            seq: this.seq + 1,
+            kind,
+            at: this.now().toISOString(),
+            promptRunId: this.promptRunId,
+            facts,
+        };
+        const line = `${JSON.stringify(entry)}\n`;
+        if (line.length > MAX_LINE_BYTES)
+            return false;
+        try {
+            fs.mkdirSync(path.dirname(this.journalPath), { recursive: true });
+            fs.appendFileSync(this.journalPath, line, "utf8");
+            this.seq = entry.seq;
+            return true;
+        }
+        catch {
+            // Observability must never break the run; stop retrying this run.
+            this.disabled = true;
+            return false;
+        }
+    }
+    /** Fail-open load: malformed lines become diagnostics, never throws. */
+    load() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.journalPath, "utf8");
+        }
+        catch {
+            return { records: [], diagnostics: [] };
+        }
+        const records = [];
+        const diagnostics = [];
+        const lines = raw.split("\n");
+        for (let index = 0; index < lines.length && records.length < MAX_RECORDS; index++) {
+            const line = lines[index].trim();
+            if (line === "")
+                continue;
+            const parsed = parseObservationLine(line);
+            if (parsed === null) {
+                diagnostics.push(`line ${index + 1}: invalid observation record`);
+                continue;
+            }
+            records.push(parsed);
+        }
+        return { records, diagnostics };
+    }
+}
+const KIND_SET = new Set(RESOURCE_OBSERVATION_KINDS);
+function parseObservationLine(line) {
+    if (line.length > MAX_LINE_BYTES)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.schemaVersion !== 1)
+        return null;
+    if (typeof record.seq !== "number" || !Number.isSafeInteger(record.seq) || record.seq < 1)
+        return null;
+    if (typeof record.kind !== "string" || !KIND_SET.has(record.kind))
+        return null;
+    if (typeof record.at !== "string" || typeof record.promptRunId !== "string")
+        return null;
+    if (typeof record.facts !== "object" || record.facts === null || Array.isArray(record.facts))
+        return null;
+    for (const factValue of Object.values(record.facts)) {
+        const kind = typeof factValue;
+        if (factValue !== null && kind !== "string" && kind !== "number" && kind !== "boolean")
+            return null;
+    }
+    return record;
+}
+//# sourceMappingURL=resource-observation-journal.js.map