harnery 0.34.1 → 0.36.0

package/dist/core/storage/logger.js

@@ -0,0 +1,411 @@
+import { randomBytes } from "node:crypto";
+import { resolve } from "node:path";
+import { BoundedLogBuffer } from "./buffer.js";
+import { createStorageCatalog } from "./catalog.js";
+import { encodeLogRecord, sanitizeLogError, validateLogContext, validateLogEvent, validateLogFields, } from "./jsonl.js";
+import { LogMetricsAccumulator } from "./metrics.js";
+import { FileSegmentSink, familyLogDirectory } from "./segments.js";
+import { ProcessStormController } from "./storm-control.js";
+export class HarneryUnsupportedDurabilityError extends Error {
+    familyId;
+    constructor(familyId) {
+        super(`family ${familyId} does not support durable disk flush`);
+        this.familyId = familyId;
+        this.name = "HarneryUnsupportedDurabilityError";
+    }
+}
+const LEVELS = ["trace", "debug", "info", "warn", "error", "fatal"];
+export function createFileLoggerRuntime(options) {
+    return new LoggerRuntime(options.catalog, options.bindings ?? options.catalog.logger_bindings, options.level_config, options.env, options.strict_levels);
+}
+export function createInMemoryLoggerRuntime(options) {
+    const records = options.records ?? [];
+    const runtime = new LoggerRuntime(options.catalog, options.bindings, options.level_config, options.env ?? {}, false, async (items) => {
+        records.push(...items.map((item) => item.record));
+    });
+    return Object.assign(runtime, { records });
+}
+export function createNullLoggerRuntime() {
+    const logger = {
+        isEnabled: () => false,
+        child: () => logger,
+        trace() { },
+        debug() { },
+        info() { },
+        warn() { },
+        error() { },
+        fatal() { },
+        async flush() { },
+        async close() { },
+    };
+    return { logger: () => logger, async flush() { }, async close() { } };
+}
+class LoggerRuntime {
+    #catalog;
+    #bindings;
+    #pipelines = new Map();
+    #writerId = `${process.pid}-${Date.now()}-${randomBytes(8).toString("hex")}`;
+    #levels;
+    #env;
+    #strict;
+    #drainOverride;
+    #writerSeq = 0;
+    #closed = false;
+    constructor(catalog, bindings, levels, env = process.env, strict = true, drainOverride) {
+        this.#catalog = catalog;
+        this.#bindings = new Map(bindings.map((binding) => [binding.component_id, binding.family_id]));
+        this.#levels = levels ?? {};
+        this.#env = env;
+        this.#strict = strict;
+        this.#drainOverride = drainOverride;
+        for (const familyId of this.#bindings.values())
+            this.#pipeline(this.#catalog.require(familyId));
+    }
+    logger(componentId, context = {}) {
+        const familyId = this.#bindings.get(componentId);
+        if (!familyId)
+            throw new Error(`unknown logger binding: ${componentId}`);
+        const family = this.#catalog.require(familyId);
+        return new BoundLogger(this, componentId, family, validateLogContext(context));
+    }
+    async flush(options = {}) {
+        const pipelines = [...this.#pipelines.values()];
+        if (options.durability === "disk") {
+            for (const pipeline of pipelines) {
+                if (pipeline.family.durability === "best-effort")
+                    throw new HarneryUnsupportedDurabilityError(pipeline.family.id);
+                pipeline.durableNextFlush = true;
+            }
+        }
+        for (const pipeline of pipelines)
+            this.#emitStormSummaries(pipeline);
+        await Promise.all(pipelines.map((pipeline) => pipeline.buffer.flush()));
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const pipeline of this.#pipelines.values())
+            this.#emitStormSummaries(pipeline);
+        await Promise.all([...this.#pipelines.values()].map((pipeline) => pipeline.buffer.close()));
+    }
+    enabled(componentId, family, level) {
+        if (family.policy.writes !== "active" || this.#closed)
+            return false;
+        const minimum = resolveLogLevel({
+            component_id: componentId,
+            family,
+            config: this.#levels,
+            env: this.#env,
+            strict: this.#strict,
+        });
+        return LEVELS.indexOf(level) >= LEVELS.indexOf(minimum);
+    }
+    emit(componentId, family, context, level, event, lazy = {}, error) {
+        if (!this.enabled(componentId, family, level))
+            return;
+        const pipeline = this.#pipeline(family);
+        try {
+            validateLogEvent(event);
+            const fields = validateLogFields(typeof lazy === "function" ? lazy() : lazy, family.policy);
+            const record = {
+                schema: "harnery.log-record/v1",
+                kind: "record",
+                emitted_at: new Date().toISOString(),
+                family_id: family.id,
+                policy_version: family.policy.policy_version,
+                component_id: componentId,
+                level,
+                event,
+                writer_id: this.#writerId,
+                writer_seq: ++this.#writerSeq,
+                context,
+                fields,
+                ...(error === undefined ? {} : { error: sanitizeLogError(error) }),
+            };
+            const encoded = encodeLogRecord(record, family);
+            pipeline.metrics.increment("accepted");
+            pipeline.metrics.increment("encoded");
+            pipeline.metrics.increment("bytes_accepted", encoded.byteLength);
+            if (!pipeline.storm.admit(`${componentId}:${event}`, level, encoded.byteLength)) {
+                pipeline.metrics.increment("sampled");
+                return;
+            }
+            pipeline.buffer.enqueue({
+                value: { record, encoded },
+                bytes: encoded.byteLength,
+                high_priority: level === "warn" || level === "error" || level === "fatal",
+            });
+        }
+        catch {
+            pipeline.metrics.failure("encoding");
+        }
+    }
+    #pipeline(family) {
+        const current = this.#pipelines.get(family.id);
+        if (current)
+            return current;
+        const metrics = new LogMetricsAccumulator();
+        const sink = this.#drainOverride
+            ? undefined
+            : new FileSegmentSink({ directory: familyLogDirectory(family), family });
+        const pipeline = {};
+        pipeline.family = family;
+        pipeline.metrics = metrics;
+        pipeline.durableNextFlush = false;
+        pipeline.storm = new ProcessStormController({
+            enabled: family.storm_policy?.enabled ?? true,
+            window_ms: family.storm_policy?.window_ms ?? 1_000,
+            max_exemplars: family.storm_policy?.max_exemplars ?? 3,
+        });
+        const policy = family.buffer_policy ?? {
+            max_bytes: 1024 * 1024,
+            max_records: 2_000,
+            flush_interval_ms: 250,
+            high_severity_reserve_bytes: 128 * 1024,
+        };
+        pipeline.buffer = new BoundedLogBuffer({
+            ...policy,
+            minimum_high_priority_drain_interval_ms: 25,
+            on_drop: (_reason, item) => {
+                metrics.increment("dropped");
+                metrics.increment("bytes_dropped", item.encoded.byteLength);
+            },
+            on_drain_error: () => metrics.failure("sink"),
+            drain: async (items) => {
+                const started = Date.now();
+                try {
+                    if (this.#drainOverride)
+                        await this.#drainOverride(items.map((item) => item.value));
+                    else
+                        await sink.append(items.map((item) => item.value.encoded), metrics.take(), pipeline.durableNextFlush);
+                }
+                finally {
+                    pipeline.durableNextFlush = false;
+                    metrics.observeLatency("flush_latency_ms", Date.now() - started);
+                }
+            },
+        });
+        this.#pipelines.set(family.id, pipeline);
+        return pipeline;
+    }
+    #emitStormSummaries(pipeline) {
+        for (const summary of pipeline.storm.drainSummaries(true)) {
+            const record = {
+                schema: "harnery.log-record/v1",
+                kind: "aggregate",
+                emitted_at: summary.last_emitted_at,
+                family_id: pipeline.family.id,
+                policy_version: pipeline.family.policy.policy_version,
+                component_id: "harnery.logger",
+                level: "warn",
+                event: "log.storm_aggregate",
+                writer_id: this.#writerId,
+                writer_seq: ++this.#writerSeq,
+                context: {},
+                fields: { key: summary.key },
+                aggregate: {
+                    count: summary.count,
+                    represented_bytes: summary.represented_bytes,
+                    first_emitted_at: summary.first_emitted_at,
+                    last_emitted_at: summary.last_emitted_at,
+                    exemplar_digests: summary.exemplar_digests,
+                },
+            };
+            const encoded = encodeLogRecord(record, pipeline.family);
+            pipeline.buffer.enqueue({
+                value: { record, encoded },
+                bytes: encoded.byteLength,
+                high_priority: true,
+            });
+            pipeline.metrics.increment("coalesced", summary.count);
+        }
+    }
+}
+class BoundLogger {
+    runtime;
+    componentId;
+    family;
+    context;
+    constructor(runtime, componentId, family, context) {
+        this.runtime = runtime;
+        this.componentId = componentId;
+        this.family = family;
+        this.context = context;
+    }
+    isEnabled(level) {
+        return this.runtime.enabled(this.componentId, this.family, level);
+    }
+    child(context) {
+        return new BoundLogger(this.runtime, this.componentId, this.family, validateLogContext({ ...this.context, ...context }));
+    }
+    trace(e, f, x) {
+        this.runtime.emit(this.componentId, this.family, this.context, "trace", e, f, x);
+    }
+    debug(e, f, x) {
+        this.runtime.emit(this.componentId, this.family, this.context, "debug", e, f, x);
+    }
+    info(e, f, x) {
+        this.runtime.emit(this.componentId, this.family, this.context, "info", e, f, x);
+    }
+    warn(e, f, x) {
+        this.runtime.emit(this.componentId, this.family, this.context, "warn", e, f, x);
+    }
+    error(e, f, x) {
+        this.runtime.emit(this.componentId, this.family, this.context, "error", e, f, x);
+    }
+    fatal(e, f, x) {
+        this.runtime.emit(this.componentId, this.family, this.context, "fatal", e, f, x);
+    }
+    flush(o) {
+        return this.runtime.flush(o);
+    }
+    close() {
+        return this.runtime.close();
+    }
+}
+export function resolveLogLevel(options) {
+    const env = options.env ?? process.env;
+    const strict = options.strict ?? true;
+    const scoped = parseScopedLevels(env.HARNERY_LOG_LEVELS, strict);
+    const raw = scoped.components[options.component_id] ??
+        scoped.families[options.family.id] ??
+        options.config?.components?.[options.component_id] ??
+        options.config?.families?.[options.family.id] ??
+        env.HARNERY_LOG_LEVEL ??
+        options.config?.default ??
+        options.family.default_level ??
+        "info";
+    if (isLevel(raw))
+        return raw;
+    if (strict)
+        throw new Error(`invalid Harnery log level: ${raw}`);
+    return options.family.default_level ?? "info";
+}
+function parseScopedLevels(raw, strict) {
+    const result = {
+        components: {},
+        families: {},
+    };
+    if (!raw)
+        return result;
+    for (const token of raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)) {
+        const [scope, value] = token.split("=", 2);
+        const [kind, id] = (scope ?? "").split(":", 2);
+        if (!id || !isLevel(value)) {
+            if (strict)
+                throw new Error(`invalid HARNERY_LOG_LEVELS entry: ${token}`);
+            continue;
+        }
+        if (kind === "component")
+            result.components[id] = value;
+        else if (kind === "family")
+            result.families[id] = value;
+        else if (strict)
+            throw new Error(`invalid HARNERY_LOG_LEVELS scope: ${token}`);
+    }
+    return result;
+}
+function isLevel(value) {
+    return typeof value === "string" && LEVELS.includes(value);
+}
+export function legacyLogFields(value) {
+    const out = {};
+    for (const [key, candidate] of Object.entries(value)) {
+        if (candidate === undefined)
+            continue;
+        if (candidate === null ||
+            typeof candidate === "string" ||
+            typeof candidate === "number" ||
+            typeof candidate === "boolean")
+            out[key] = candidate;
+        else if (Array.isArray(candidate) &&
+            candidate.every((item) => item === null || ["string", "number", "boolean"].includes(typeof item)))
+            out[key] = candidate;
+        else {
+            const encoded = JSON.stringify(candidate);
+            if (encoded !== undefined && Buffer.byteLength(encoded) <= 4_096)
+                out[key] = encoded;
+        }
+    }
+    return out;
+}
+/** Encode an allow-listed array of scalar records without slicing a JSON token. */
+export function encodeBoundedLogObjectArray(values, options) {
+    if (!Number.isSafeInteger(options.max_bytes) || options.max_bytes < 2) {
+        throw new Error("bounded log object array needs at least two bytes");
+    }
+    const allowed = new Set(options.allowed_fields);
+    if (allowed.size !== options.allowed_fields.length || allowed.size === 0) {
+        throw new Error("bounded log object array needs unique allowed fields");
+    }
+    const normalized = values.map((value, index) => {
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+            throw new Error(`bounded log object array item ${index} must be an object`);
+        }
+        const source = value;
+        for (const key of Object.keys(source)) {
+            if (!allowed.has(key))
+                throw new Error(`bounded log object array rejects field: ${key}`);
+        }
+        const item = {};
+        for (const key of options.allowed_fields) {
+            const candidate = source[key];
+            if (candidate === undefined)
+                continue;
+            if (candidate !== null &&
+                typeof candidate !== "string" &&
+                typeof candidate !== "boolean" &&
+                (typeof candidate !== "number" || !Number.isFinite(candidate))) {
+                throw new Error(`bounded log object array field ${key} must be scalar`);
+            }
+            item[key] = candidate;
+        }
+        return item;
+    });
+    const included = [];
+    let bytes = 2;
+    for (const item of normalized) {
+        const encoded = JSON.stringify(item);
+        const nextBytes = Buffer.byteLength(encoded) + (included.length > 0 ? 1 : 0);
+        if (bytes + nextBytes > options.max_bytes)
+            break;
+        included.push(item);
+        bytes += nextBytes;
+    }
+    return {
+        json: JSON.stringify(included),
+        included: included.length,
+        omitted: normalized.length - included.length,
+        truncated: included.length !== normalized.length,
+    };
+}
+const PROCESS_RUNTIMES = new Map();
+const PROCESS_LOGGER_BINDINGS = {
+    "agent-hook": "agent-hook-debug-log",
+    "agent-coord": "agent-coord-debug-log",
+    "semantic-service": "semantic-service-log",
+    "governor-service": "governor-service-log",
+    "presence-relay": "presence-relay-log",
+};
+export function processLogger(coordRoot, componentId) {
+    const root = resolve(coordRoot);
+    let runtime = PROCESS_RUNTIMES.get(root);
+    if (!runtime) {
+        const bindings = Object.entries(PROCESS_LOGGER_BINDINGS).map(([component_id, family_id]) => ({
+            component_id,
+            family_id,
+        }));
+        const catalog = createStorageCatalog({ coord_root: root }, { logger_bindings: bindings });
+        runtime = createFileLoggerRuntime({ catalog, bindings, strict_levels: false });
+        PROCESS_RUNTIMES.set(root, runtime);
+    }
+    return runtime.logger(componentId);
+}
+export async function closeProcessLoggers() {
+    await Promise.all([...PROCESS_RUNTIMES.values()].map((runtime) => runtime.close()));
+    PROCESS_RUNTIMES.clear();
+}

package/dist/core/storage/maintenance-providers.d.ts

@@ -0,0 +1,26 @@
+import { type HarneryStorageCatalog } from "./catalog.js";
+import { type HarneryAutomaticMaintenanceResult, type HarneryMaintenanceBudget, type HarneryMaintenanceProvider } from "./maintenance.js";
+export declare const SESSION_START_MAINTENANCE_BUDGET: HarneryMaintenanceBudget;
+export interface ExistingMaintenanceJanitors {
+    journal(): unknown;
+    images(): unknown;
+    artifacts(): unknown;
+}
+export interface AutomaticMaintenanceComposition {
+    catalog: HarneryStorageCatalog;
+    providers: readonly HarneryMaintenanceProvider[];
+}
+export declare function createExistingMaintenanceProviders(janitors: ExistingMaintenanceJanitors): readonly HarneryMaintenanceProvider[];
+/** Providers exist only for manifest-backed JSONL partitions with valid policy. */
+export declare function createStructuredLogMaintenanceProviders(catalog: HarneryStorageCatalog): readonly HarneryMaintenanceProvider[];
+export declare function createAutomaticMaintenanceComposition(coordRoot: string, janitors: ExistingMaintenanceJanitors): AutomaticMaintenanceComposition;
+/**
+ * Run the bounded SessionStart slice. This path is permanently planning-only:
+ * owner janitors retain their current direct activation until a later,
+ * provider-specific production decision.
+ */
+export declare function runAutomaticMaintenancePass(composition: AutomaticMaintenanceComposition, options?: {
+    now?: Date;
+    budget?: HarneryMaintenanceBudget;
+}): Promise<HarneryAutomaticMaintenanceResult>;
+//# sourceMappingURL=maintenance-providers.d.ts.map

package/dist/core/storage/maintenance-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance-providers.d.ts","sourceRoot":"","sources":["../../../src/core/storage/maintenance-providers.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGhF,OAAO,EAEL,KAAK,iCAAiC,EACtC,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAGhC,MAAM,kBAAkB,CAAC;AAI1B,eAAO,MAAM,gCAAgC,EAAE,wBAI7C,CAAC;AAEH,MAAM,WAAW,2BAA2B;IAC1C,OAAO,IAAI,OAAO,CAAC;IACnB,MAAM,IAAI,OAAO,CAAC;IAClB,SAAS,IAAI,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,qBAAqB,CAAC;IAC/B,SAAS,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAClD;AAED,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,2BAA2B,GACpC,SAAS,0BAA0B,EAAE,CAMvC;AAED,mFAAmF;AACnF,wBAAgB,uCAAuC,CACrD,OAAO,EAAE,qBAAqB,GAC7B,SAAS,0BAA0B,EAAE,CAYvC;AAED,wBAAgB,qCAAqC,CACnD,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,2BAA2B,GACpC,+BAA+B,CAMjC;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,+BAA+B,EAC5C,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,wBAAwB,CAAA;CAAO,GAC9D,OAAO,CAAC,iCAAiC,CAAC,CAS5C"}

package/dist/core/storage/maintenance-providers.js

@@ -0,0 +1,141 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { createStorageCatalog } from "./catalog.js";
+import { HARNERY_STRUCTURED_LOG_PROVIDER_ID } from "./contract.js";
+import { createStructuredLogRetentionProvider } from "./log-retention.js";
+import { HARNERY_MAINTENANCE_CURSOR_SCHEMA, readMaintenanceTransaction, runAutomaticMaintenanceSlice, } from "./maintenance.js";
+const STALE_RUNNING_CLAIM_MS = 10 * 60 * 1_000;
+export const SESSION_START_MAINTENANCE_BUDGET = Object.freeze({
+    max_duration_ms: 250,
+    max_files: 50,
+    max_bytes: 16 * 1024 * 1024,
+});
+export function createExistingMaintenanceProviders(janitors) {
+    return [
+        delegatedJanitorProvider("journal-history", "journal-janitor", janitors.journal),
+        delegatedJanitorProvider("captured-images", "image-janitor", janitors.images),
+        delegatedJanitorProvider("managed-artifacts", "artifact-janitor", janitors.artifacts),
+    ];
+}
+/** Providers exist only for manifest-backed JSONL partitions with valid policy. */
+export function createStructuredLogMaintenanceProviders(catalog) {
+    return catalog.families
+        .filter((family) => family.provider.provider_id === HARNERY_STRUCTURED_LOG_PROVIDER_ID &&
+        family.format === "jsonl" &&
+        family.effective_log_retention?.state === "valid" &&
+        family.resolved_roots.some((root) => root.match === "provider-partition" && root.ownership !== "external"))
+        .map(createStructuredLogRetentionProvider);
+}
+export function createAutomaticMaintenanceComposition(coordRoot, janitors) {
+    const root = resolve(coordRoot);
+    return {
+        catalog: createStorageCatalog({ coord_root: root, project_root: root }),
+        providers: createExistingMaintenanceProviders(janitors),
+    };
+}
+/**
+ * Run the bounded SessionStart slice. This path is permanently planning-only:
+ * owner janitors retain their current direct activation until a later,
+ * provider-specific production decision.
+ */
+export async function runAutomaticMaintenancePass(composition, options = {}) {
+    if (process.env.HARNERY_SESSIONSTART_MAINTENANCE === "0")
+        return disabledResult();
+    const now = options.now ?? new Date();
+    recoverInterruptedDailyClaim(composition.catalog.context.coord_root, now);
+    return runAutomaticMaintenanceSlice(composition.catalog, composition.providers, {
+        now,
+        budget: options.budget ?? SESSION_START_MAINTENANCE_BUDGET,
+        execute: false,
+    });
+}
+function delegatedJanitorProvider(familyId, janitorId, janitor) {
+    const destructiveScope = `${janitorId}-retention`;
+    return {
+        family_id: familyId,
+        destructive_scope: destructiveScope,
+        budget: { max_duration_ms: 100, max_files: 25, max_bytes: 8 * 1024 * 1024 },
+        plan: ({ pressure, budget, cursor, now }) => {
+            const day = now.toISOString().slice(0, 10);
+            if (cursor === day || pressure.regular_files === 0)
+                return { actions: [], next_cursor: day };
+            return {
+                actions: [
+                    {
+                        action_id: `${janitorId}-${day}`,
+                        family_id: familyId,
+                        kind: "delegated-janitor",
+                        target_ref: janitorId,
+                        files: Math.min(pressure.regular_files, budget.max_files),
+                        bytes: Math.min(pressure.logical_bytes, budget.max_bytes),
+                        destructive: true,
+                        authorization_scope: destructiveScope,
+                        metadata: { activation: "explicit-only", existing_owner_rules: true },
+                    },
+                ],
+                next_cursor: day,
+            };
+        },
+        apply: ({ action }) => {
+            if (action.family_id !== familyId ||
+                action.kind !== "delegated-janitor" ||
+                action.target_ref !== janitorId ||
+                !action.destructive) {
+                return { outcome: "refused", detail: "delegated janitor action did not match its scope" };
+            }
+            janitor();
+            return { outcome: "applied", detail: "existing owner janitor completed" };
+        },
+    };
+}
+function recoverInterruptedDailyClaim(coordRoot, now) {
+    const path = join(resolve(coordRoot), ".harnery", "maintenance", "cursors", "daily.json");
+    if (!existsSync(path))
+        return;
+    let cursor;
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024)
+            return;
+        cursor = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return;
+    }
+    if (cursor.schema !== HARNERY_MAINTENANCE_CURSOR_SCHEMA ||
+        cursor.state !== "running" ||
+        !Number.isFinite(Date.parse(cursor.claimed_at)) ||
+        now.getTime() - Date.parse(cursor.claimed_at) < STALE_RUNNING_CLAIM_MS ||
+        !/^[a-z0-9][a-z0-9._-]{0,127}$/.test(cursor.transaction_id)) {
+        return;
+    }
+    const transactionPath = join(resolve(coordRoot), ".harnery", "maintenance", "transactions", `${cursor.transaction_id}.json`);
+    if (existsSync(transactionPath)) {
+        try {
+            const transaction = readMaintenanceTransaction(coordRoot, cursor.transaction_id);
+            if (transaction.state !== "planned")
+                return;
+            atomicCursor(path, { ...cursor, state: "complete" });
+            return;
+        }
+        catch {
+            return;
+        }
+    }
+    const preserved = join(dirname(path), `daily.interrupted-${now.toISOString().replaceAll(/[:.]/g, "-")}-${randomUUID()}.json`);
+    try {
+        renameSync(path, preserved);
+    }
+    catch {
+        // Another SessionStart may own or have completed the claim.
+    }
+}
+function atomicCursor(path, cursor) {
+    const temporary = `${path}.tmp-${process.pid}-${randomUUID()}`;
+    writeFileSync(temporary, `${JSON.stringify(cursor, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, path);
+}
+function disabledResult() {
+    return { ran: false, reason: "disabled", actions: 0, files: 0, bytes: 0 };
+}