patchwarden 1.5.0 → 1.6.1

package/dist/utils/boundedFile.js

@@ -0,0 +1,93 @@
+import { appendFileSync, closeSync, existsSync, fstatSync, openSync, readSync, statSync, } from "node:fs";
+import { atomicWriteFileSync } from "./atomicFile.js";
+import { withFileLockSync } from "./lockedJsonFile.js";
+const TRUNCATION_MARKER = Buffer.from("[earlier content truncated]\n", "utf-8");
+export function readTextFilePrefixSync(path, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new Error("maxBytes must be a positive integer");
+    }
+    const descriptor = openSync(path, "r");
+    try {
+        const totalBytes = fstatSync(descriptor).size;
+        const length = Math.min(totalBytes, maxBytes);
+        const buffer = Buffer.alloc(length);
+        let offset = 0;
+        while (offset < length) {
+            const bytesRead = readSync(descriptor, buffer, offset, length - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        let content = buffer.subarray(0, offset).toString("utf-8");
+        if (totalBytes > offset && content.endsWith("\uFFFD"))
+            content = content.slice(0, -1);
+        return { content, totalBytes, truncated: totalBytes > offset };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+export function readTextFileTailLinesSync(path, lines, maxBytes = 1024 * 1024) {
+    if (!existsSync(path))
+        return "";
+    const boundedLines = Number.isFinite(lines)
+        ? Math.max(1, Math.min(1000, Math.trunc(lines)))
+        : 100;
+    const suffix = readFileSuffix(path, maxBytes);
+    let text = suffix.content.toString("utf-8");
+    if (suffix.truncated) {
+        const firstNewline = text.indexOf("\n");
+        if (firstNewline >= 0)
+            text = text.slice(firstNewline + 1);
+    }
+    const allLines = text.split(/\r?\n/);
+    if (allLines.at(-1) === "")
+        allLines.pop();
+    return allLines.slice(-boundedLines).join("\n");
+}
+export function appendBoundedTextFileSync(path, content, maxBytes = 2 * 1024 * 1024) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= TRUNCATION_MARKER.length) {
+        throw new Error("maxBytes must exceed the truncation marker size");
+    }
+    withFileLockSync(path, () => {
+        const incoming = Buffer.from(content, "utf-8");
+        const existingSize = existsSync(path) ? statSync(path).size : 0;
+        if (existingSize + incoming.length <= maxBytes) {
+            appendFileSync(path, incoming, { mode: 0o600 });
+            return;
+        }
+        const incomingSuffix = incoming.subarray(Math.max(0, incoming.length - maxBytes + TRUNCATION_MARKER.length));
+        const existingBudget = Math.max(0, maxBytes - TRUNCATION_MARKER.length - incomingSuffix.length);
+        const existingSuffix = existingBudget > 0 && existingSize > 0
+            ? readFileSuffix(path, existingBudget).content
+            : Buffer.alloc(0);
+        const output = Buffer.concat([TRUNCATION_MARKER, existingSuffix, incomingSuffix]);
+        const mode = existsSync(path) ? statSync(path).mode : 0o600;
+        atomicWriteFileSync(path, output, { mode });
+    });
+}
+function readFileSuffix(path, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new Error("maxBytes must be a positive integer");
+    }
+    const descriptor = openSync(path, "r");
+    try {
+        const size = fstatSync(descriptor).size;
+        const length = Math.min(size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        let offset = 0;
+        while (offset < length) {
+            const bytesRead = readSync(descriptor, buffer, offset, length - offset, size - length + offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        return {
+            content: offset === length ? buffer : buffer.subarray(0, offset),
+            truncated: size > length,
+        };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/utils/lockedJsonFile.d.ts

@@ -0,0 +1,15 @@
+export interface LockedJsonMutation<T extends object, R> {
+    next?: T;
+    result: R;
+}
+export interface LockedJsonOptions {
+    waitMs?: number;
+    corruptLockStaleMs?: number;
+    busyError?: () => Error;
+}
+export declare function readJsonObjectFileSync<T extends object>(path: string): T;
+export declare function mutateLockedJsonFileSync<T extends object, R>(path: string, mutation: (current: T) => LockedJsonMutation<T, R>, options?: LockedJsonOptions): R;
+/** Serialize an arbitrary same-file read/modify/write sequence across processes. */
+export declare function withFileLockSync<R>(path: string, action: () => R, options?: LockedJsonOptions): R;
+/** Hold the same cross-process lock for the lifetime of an async operation. */
+export declare function withFileLock<R>(path: string, action: () => Promise<R>, options?: LockedJsonOptions): Promise<R>;

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.0";
-export declare const TOOL_SCHEMA_EPOCH = "2026-07-05-v13";
+export declare const PATCHWARDEN_VERSION = "1.6.1";
+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.0";
-export const TOOL_SCHEMA_EPOCH = "2026-07-05-v13";
+export const PATCHWARDEN_VERSION = "1.6.1";
+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")