patchwarden 1.5.1 → 1.6.2

package/dist/utils/lockedJsonFile.js

@@ -0,0 +1,224 @@
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteJsonFileSync } from "./atomicFile.js";
+const waitArray = new Int32Array(new SharedArrayBuffer(4));
+const lockReleaseRetryCodes = new Set(["EACCES", "EBUSY", "ENOTEMPTY", "EPERM"]);
+const lockReleaseRetryMs = 5_000;
+const lockReleaseRetryDelayMs = 10;
+const deadOwnerGraceMs = 250;
+const lockOwnerFile = "owner.json";
+export function readJsonObjectFileSync(path) {
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Expected a JSON object in ${path}`);
+    }
+    return parsed;
+}
+export function mutateLockedJsonFileSync(path, mutation, options = {}) {
+    return withFileLockSync(path, () => {
+        const current = readJsonObjectFileSync(path);
+        const outcome = mutation(current);
+        if (outcome.next)
+            atomicWriteJsonFileSync(path, outcome.next);
+        return outcome.result;
+    }, options);
+}
+/** Serialize an arbitrary same-file read/modify/write sequence across processes. */
+export function withFileLockSync(path, action, options = {}) {
+    const lock = acquireLock(path, options);
+    try {
+        return action();
+    }
+    finally {
+        releaseLock(lock.path, lock.owner);
+    }
+}
+/** Hold the same cross-process lock for the lifetime of an async operation. */
+export async function withFileLock(path, action, options = {}) {
+    // Async callers must not use the synchronous Atomics.wait loop: a second
+    // request in the same Node event loop would otherwise block the first
+    // request from finishing its awaited mutation and releasing the lock.
+    const lock = await acquireLockAsync(path, options);
+    try {
+        return await action();
+    }
+    finally {
+        releaseLock(lock.path, lock.owner);
+    }
+}
+async function acquireLockAsync(path, options) {
+    const lockPath = `${path}.lock`;
+    const owner = `${process.pid}-${randomBytes(8).toString("hex")}`;
+    const deadline = Date.now() + (options.waitMs ?? 2000);
+    while (true) {
+        if (tryCreateLock(lockPath, owner))
+            return { path: lockPath, owner };
+        if (removeStaleLock(lockPath, options.corruptLockStaleMs ?? 30_000) &&
+            tryCreateLock(lockPath, owner)) {
+            return { path: lockPath, owner };
+        }
+        if (Date.now() >= deadline) {
+            throw options.busyError?.() ?? new Error(`JSON file is busy: ${path}`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, lockReleaseRetryDelayMs));
+    }
+}
+function acquireLock(path, options) {
+    const lockPath = `${path}.lock`;
+    const owner = `${process.pid}-${randomBytes(8).toString("hex")}`;
+    const deadline = Date.now() + (options.waitMs ?? 2000);
+    while (true) {
+        if (tryCreateLock(lockPath, owner))
+            return { path: lockPath, owner };
+        if (removeStaleLock(lockPath, options.corruptLockStaleMs ?? 30_000) &&
+            tryCreateLock(lockPath, owner)) {
+            return { path: lockPath, owner };
+        }
+        if (Date.now() >= deadline) {
+            throw options.busyError?.() ?? new Error(`JSON file is busy: ${path}`);
+        }
+        Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+    }
+}
+function tryCreateLock(lockPath, owner) {
+    try {
+        mkdirSync(lockPath, { mode: 0o700 });
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "EEXIST" || lockReleaseRetryCodes.has(code || ""))
+            return false;
+        throw error;
+    }
+    try {
+        writeFileSync(join(lockPath, lockOwnerFile), JSON.stringify({
+            owner,
+            pid: process.pid,
+            created_at: new Date().toISOString(),
+        }), { encoding: "utf-8", flag: "wx", mode: 0o600 });
+        return true;
+    }
+    catch (error) {
+        try {
+            rmSync(lockPath, { recursive: true, force: true });
+        }
+        catch { /* leave fail-closed */ }
+        throw error;
+    }
+}
+function releaseLock(lockPath, owner) {
+    const detachDeadline = Date.now() + lockReleaseRetryMs;
+    const releasePath = `${lockPath}.release-${owner}`;
+    // Rename the owned lock directory out of the active lock path before
+    // recursive cleanup. A new contender can then create lockPath immediately,
+    // while Windows rimraf retries cannot delete that replacement lock.
+    while (true) {
+        const currentOwner = readLock(lockPath)?.owner;
+        if (currentOwner !== owner) {
+            if (!existsSync(lockPath))
+                return;
+            if (currentOwner !== undefined)
+                return;
+            if (Date.now() >= detachDeadline) {
+                throw new Error(`Unable to verify lock ownership before release: ${lockPath}`);
+            }
+            Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+            continue;
+        }
+        try {
+            renameSync(lockPath, releasePath);
+            break;
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code === "ENOENT")
+                return;
+            if (!code || !lockReleaseRetryCodes.has(code) || Date.now() >= detachDeadline)
+                throw error;
+            Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+        }
+    }
+    // Cleanup is no longer ownership-sensitive after the atomic detach, so give
+    // it an independent retry budget instead of consuming whatever remained
+    // from a slow antivirus-delayed rename.
+    const cleanupDeadline = Date.now() + lockReleaseRetryMs;
+    while (true) {
+        try {
+            rmSync(releasePath, { recursive: true, force: false });
+            return;
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code === "ENOENT")
+                return;
+            if (!code || !lockReleaseRetryCodes.has(code) || Date.now() >= cleanupDeadline)
+                throw error;
+            Atomics.wait(waitArray, 0, 0, lockReleaseRetryDelayMs);
+        }
+    }
+}
+function removeStaleLock(lockPath, corruptLockStaleMs) {
+    const lock = readLock(lockPath);
+    let ageMs;
+    try {
+        ageMs = Date.now() - statSync(lockPath).mtimeMs;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return true;
+        throw error;
+    }
+    const stale = typeof lock?.pid === "number"
+        ? !processIsAlive(lock.pid) && ageMs >= deadOwnerGraceMs
+        : ageMs >= corruptLockStaleMs;
+    if (!stale)
+        return false;
+    // Re-read immediately before removal so one stale-lock contender cannot
+    // delete a replacement acquired after its first observation.
+    const latest = readLock(lockPath);
+    if (lock?.owner) {
+        if (latest?.owner !== lock.owner || latest.pid !== lock.pid)
+            return false;
+    }
+    else if (latest) {
+        return false;
+    }
+    try {
+        rmSync(lockPath, { recursive: true, force: false });
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return true;
+        if (lockReleaseRetryCodes.has(errorCode(error) || ""))
+            return false;
+        throw error;
+    }
+}
+function readLock(path) {
+    try {
+        const metadata = statSync(path);
+        const recordPath = metadata.isDirectory() ? join(path, lockOwnerFile) : path;
+        return readJsonObjectFileSync(recordPath);
+    }
+    catch {
+        return null;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // Only ESRCH proves the process does not exist. Access-denied and unknown
+        // platform errors must keep the lock fail-closed.
+        return errorCode(error) !== "ESRCH";
+    }
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code || "")
+        : null;
+}

package/dist/utils/platform.d.ts

@@ -0,0 +1,11 @@
+export declare const isWindows: boolean;
+export declare const pathSep: string;
+export declare const nullDevice: string;
+export declare function isSamePath(left: string, right: string): boolean;
+/**
+ * Returns true when `child` is located inside `parent` (or equals it is NOT
+ * treated as a child here — callers that need equality should check it
+ * separately). Uses `path.relative` so mixed Windows separators are normalized
+ * before comparison, unlike `String.prototype.startsWith`.
+ */
+export declare function isPathChildOf(child: string, parent: string): boolean;

package/dist/utils/platform.js

@@ -0,0 +1,26 @@
+/**
+ * Cross-platform abstractions for PatchWarden.
+ *
+ * Centralizes platform detection, path separators, the platform-specific null
+ * device, and a path-containment helper that works correctly on Windows where
+ * forward and backward slashes may be mixed. Use these helpers instead of
+ * hard-coded Unix assumptions so the runtime guard and change capture behave
+ * consistently across Windows and Unix hosts.
+ */
+import { sep, relative, isAbsolute } from "node:path";
+export const isWindows = process.platform === "win32";
+export const pathSep = sep;
+export const nullDevice = isWindows ? "NUL" : "/dev/null";
+export function isSamePath(left, right) {
+    return relative(left, right) === "";
+}
+/**
+ * Returns true when `child` is located inside `parent` (or equals it is NOT
+ * treated as a child here — callers that need equality should check it
+ * separately). Uses `path.relative` so mixed Windows separators are normalized
+ * before comparison, unlike `String.prototype.startsWith`.
+ */
+export function isPathChildOf(child, parent) {
+    const rel = relative(parent, child);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}

package/dist/utils/stableJson.d.ts

@@ -0,0 +1,2 @@
+/** Canonical JSON with object keys sorted recursively. */
+export declare function stableJsonStringify(value: unknown): string;

package/dist/utils/stableJson.js

@@ -0,0 +1,12 @@
+/** Canonical JSON with object keys sorted recursively. */
+export function stableJsonStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJsonStringify).join(",")}]`;
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJsonStringify(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/version.d.ts

@@ -1,2 +1,3 @@
-export declare const PATCHWARDEN_VERSION = "1.5.1";
-export declare const TOOL_SCHEMA_EPOCH = "2026-07-05-v13";
+export declare const PATCHWARDEN_VERSION = "1.6.2";
+export declare const TOOL_SCHEMA_EPOCH = "2026-07-19-v15";
+export declare const ARTIFACT_SCHEMA_VERSION = "2026-07-19-v15";

package/dist/version.js

@@ -1,2 +1,3 @@
-export const PATCHWARDEN_VERSION = "1.5.1";
-export const TOOL_SCHEMA_EPOCH = "2026-07-05-v13";
+export const PATCHWARDEN_VERSION = "1.6.2";
+export const TOOL_SCHEMA_EPOCH = "2026-07-19-v15";
+export const ARTIFACT_SCHEMA_VERSION = TOOL_SCHEMA_EPOCH;

package/dist/watcherStatus.d.ts

@@ -1,6 +1,6 @@
 import { type PatchWardenConfig } from "./config.js";
-export type WatcherState = "healthy" | "stale" | "missing" | "unreadable";
-export type PendingReason = "queued_waiting_for_watcher" | "queued_but_watcher_stale" | "queued_but_watcher_missing" | "queued_but_watcher_unreadable" | "agent_running" | "verification_running" | "preparing" | "collecting_artifacts" | null;
+export type WatcherState = "healthy" | "degraded" | "stale" | "missing" | "unreadable";
+export type PendingReason = "queued_waiting_for_watcher" | "queued_but_watcher_stale" | "queued_but_watcher_degraded" | "queued_but_watcher_missing" | "queued_but_watcher_unreadable" | "agent_running" | "verification_running" | "preparing" | "collecting_artifacts" | null;
 export interface WatcherStatusSnapshot {
     status: WatcherState;
     available: boolean;

package/dist/watcherStatus.js

@@ -45,6 +45,22 @@ export function readWatcherStatus(config = getConfig(), nowMs = Date.now()) {
             throw new Error("invalid heartbeat timestamp");
         const ageMs = Math.max(0, nowMs - heartbeatMs);
         const ageSeconds = Math.round(ageMs / 1000);
+        if (data.status === "degraded") {
+            return {
+                status: "degraded",
+                available: false,
+                stale_after_seconds: staleAfterSeconds,
+                last_heartbeat_at: String(data.last_heartbeat_at),
+                heartbeat_age_seconds: ageSeconds,
+                heartbeat_pid: Number.isInteger(Number(data.pid)) ? Number(data.pid) : null,
+                instance_id: typeof data.instance_id === "string" ? data.instance_id : null,
+                launcher_pid: Number.isInteger(Number(data.launcher_pid)) ? Number(data.launcher_pid) : null,
+                reason: typeof data.last_error === "string" && data.last_error
+                    ? `Watcher is degraded after repeated tick failures: ${data.last_error}`
+                    : "Watcher is degraded after repeated tick failures. Restart the PatchWarden watcher.",
+                activity: null,
+            };
+        }
         const healthy = ageMs < staleAfterSeconds * 1000;
         if (healthy) {
             return {
@@ -149,6 +165,8 @@ function checkRunningTaskHeartbeat(config, nowMs, staleAfterSeconds) {
 }
 export function derivePendingReason(task, watcher) {
     if (task.status === "pending") {
+        if (watcher.status === "degraded")
+            return "queued_but_watcher_degraded";
         if (watcher.status === "stale")
             return "queued_but_watcher_stale";
         if (watcher.status === "missing")