patchwarden 1.5.1 → 1.6.1

package/dist/tools/workspace/syncFile.js

@@ -0,0 +1,134 @@
+import { readFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+import { PatchWardenError } from "../../errors.js";
+import { getConfig } from "../../config.js";
+import { guardDirectReadPath, guardDirectFileSize, guardDirectSessionActive, guardDirectWritePath, } from "../../direct/directGuards.js";
+import { appendDirectSessionOperation, readDirectSession, withDirectSessionMutationLock, } from "../../direct/directSessionStore.js";
+import { computeFileSha256 } from "../../direct/directPatch.js";
+import { atomicWriteFileSync } from "../../utils/atomicFile.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+/**
+ * Copy a file from source to target within the same session repo.
+ * Both source and target must be inside the session's repo_path.
+ */
+export function syncFile(sessionId, sourcePath, targetPath, options, config) {
+    const cfg = config || getConfig();
+    return withDirectSessionMutationLock(sessionId, () => {
+        const session = readDirectSession(sessionId, cfg);
+        guardDirectSessionActive(session);
+        const repoPath = session.resolved_repo_path;
+        const workspaceRoot = cfg.workspaceRoot;
+        // Guard source path — must be inside repo and not internal/sensitive/binary.
+        const resolvedSource = guardDirectReadPath(sourcePath, repoPath, workspaceRoot);
+        if (!existsSync(resolvedSource)) {
+            throw new PatchWardenError("source_file_not_found", `Source file does not exist: "${sourcePath}".`, "Ensure the source path is correct.", true, { source_path: sourcePath });
+        }
+        // Guard target path — must be inside repo, not in blocked dirs
+        const resolvedTarget = guardDirectWritePath(targetPath, repoPath, workspaceRoot);
+        const sourceMetadata = statSync(resolvedSource);
+        if (!sourceMetadata.isFile()) {
+            throw new PatchWardenError("direct_source_not_file", `Source path is not a regular file: "${sourcePath}".`, "Choose an existing text file inside the Direct session repository.", true, { source_path: sourcePath });
+        }
+        guardDirectFileSize(sourceMetadata.size, cfg);
+        // Read once, then hash the exact bytes that will be copied.
+        const sourceContent = readFileSync(resolvedSource);
+        guardDirectFileSize(sourceContent.length, cfg);
+        const sourceText = sourceContent.toString("utf-8");
+        if (!Buffer.from(sourceText, "utf-8").equals(sourceContent)) {
+            throw new PatchWardenError("unsupported_text_encoding", `Source file "${sourcePath}" is not valid UTF-8 text.`, "Use a normal task or convert the file to UTF-8 before Direct sync.", true, { source_path: sourcePath });
+        }
+        const sensitive = redactSensitiveContent(sourceText);
+        if (sensitive.redacted) {
+            throw new PatchWardenError("sensitive_content_blocked", `Source file contains credential-like content (${sensitive.redaction_categories.join(", ")}).`, "Remove the sensitive value and retry with placeholders or environment-variable references.", true, { source_path: sourcePath, redaction_categories: sensitive.redaction_categories });
+        }
+        const sourceSha256 = createHash("sha256").update(sourceContent).digest("hex");
+        if (options?.expected_source_sha256 && options.expected_source_sha256 !== sourceSha256) {
+            throw new PatchWardenError("source_hash_mismatch", `Source file hash mismatch. Expected "${options.expected_source_sha256}" but got "${sourceSha256}".`, "Re-read the source file to get the current sha256.", true, { expected_sha256: options.expected_source_sha256, actual_sha256: sourceSha256 });
+        }
+        // Get target sha256 before copy
+        let beforeTargetSha256 = null;
+        if (existsSync(resolvedTarget)) {
+            const targetMetadata = statSync(resolvedTarget);
+            if (!targetMetadata.isFile()) {
+                throw new PatchWardenError("direct_target_not_file", `Target path is not a regular file: "${targetPath}".`, "Choose a text-file target inside the Direct session repository.", true, { target_path: targetPath });
+            }
+            guardDirectFileSize(targetMetadata.size, cfg);
+            beforeTargetSha256 = computeFileSha256(resolvedTarget);
+            // Verify target sha256 if provided
+            if (options?.expected_target_sha256 && options.expected_target_sha256 !== beforeTargetSha256) {
+                throw new PatchWardenError("target_hash_mismatch", `Target file hash mismatch. Expected "${options.expected_target_sha256}" but got "${beforeTargetSha256}".`, "Re-read the target file to get the current sha256.", true, { expected_sha256: options.expected_target_sha256, actual_sha256: beforeTargetSha256 });
+            }
+        }
+        const copiedBytes = sourceContent.length;
+        if (beforeTargetSha256 === sourceSha256) {
+            assertSourceUnchanged(sourcePath, resolvedSource, sourceSha256, repoPath, workspaceRoot);
+            appendSyncOperation(sessionId, sourcePath, targetPath, beforeTargetSha256, sourceSha256, 0, 0, cfg);
+            return buildSyncResult(sourcePath, targetPath, beforeTargetSha256, sourceSha256, copiedBytes, false);
+        }
+        // Create target directory if needed
+        mkdirSync(dirname(resolvedTarget), { recursive: true });
+        // Re-resolve after directory creation so a newly exposed link/reparse point
+        // cannot reuse the earlier lexical decision. Replace atomically in the
+        // validated target directory and preserve an existing file's permissions.
+        const revalidatedTarget = guardDirectWritePath(resolvedTarget, repoPath, workspaceRoot);
+        const currentTargetSha256 = existsSync(revalidatedTarget)
+            ? computeFileSha256(revalidatedTarget)
+            : null;
+        if (currentTargetSha256 !== beforeTargetSha256) {
+            throw new PatchWardenError("direct_target_changed_during_sync", `Target file "${targetPath}" changed while sync_file was preparing the copy.`, "Re-read the target file and retry after concurrent filesystem changes stop.", true, {
+                path: targetPath,
+                before_sha256: beforeTargetSha256,
+                current_sha256: currentTargetSha256,
+            });
+        }
+        assertSourceUnchanged(sourcePath, resolvedSource, sourceSha256, repoPath, workspaceRoot);
+        const existingMode = existsSync(revalidatedTarget) ? statSync(revalidatedTarget).mode : undefined;
+        atomicWriteFileSync(revalidatedTarget, sourceContent, { mode: existingMode });
+        const finalTarget = guardDirectWritePath(revalidatedTarget, repoPath, workspaceRoot);
+        if (finalTarget !== revalidatedTarget) {
+            throw new PatchWardenError("direct_path_changed_during_write", `Target path "${targetPath}" changed while sync_file was writing it.`, "Inspect the repository path and retry only after concurrent filesystem changes stop.", true, { path: targetPath, operation: "sync_file" });
+        }
+        // Compute after hash
+        const afterTargetSha256 = computeFileSha256(finalTarget);
+        const changed = beforeTargetSha256 !== afterTargetSha256;
+        appendSyncOperation(sessionId, sourcePath, targetPath, beforeTargetSha256, afterTargetSha256, 1, copiedBytes, cfg);
+        return buildSyncResult(sourcePath, targetPath, beforeTargetSha256, afterTargetSha256, copiedBytes, changed);
+    }, cfg);
+}
+function assertSourceUnchanged(sourcePath, resolvedSource, expectedSha256, repoPath, workspaceRoot) {
+    const currentPath = guardDirectReadPath(sourcePath, repoPath, workspaceRoot);
+    const samePath = process.platform === "win32"
+        ? currentPath.toLowerCase() === resolvedSource.toLowerCase()
+        : currentPath === resolvedSource;
+    const currentSha256 = samePath && existsSync(currentPath)
+        ? computeFileSha256(currentPath)
+        : null;
+    if (!samePath || currentSha256 !== expectedSha256) {
+        throw new PatchWardenError("direct_source_changed_during_sync", `Source file "${sourcePath}" changed while sync_file was preparing the copy.`, "Re-read the source file and retry after concurrent filesystem changes stop.", true, { source_path: sourcePath, expected_sha256: expectedSha256, actual_sha256: currentSha256 });
+    }
+}
+function appendSyncOperation(sessionId, sourcePath, targetPath, beforeSha256, afterSha256, operationsApplied, bytesChanged, config) {
+    appendDirectSessionOperation(sessionId, {
+        index: 0,
+        timestamp: new Date().toISOString(),
+        path: targetPath,
+        source_path: sourcePath,
+        operation_type: "sync",
+        before_sha256: beforeSha256,
+        after_sha256: afterSha256,
+        operations_applied: operationsApplied,
+        bytes_changed: bytesChanged,
+    }, config);
+}
+function buildSyncResult(sourcePath, targetPath, beforeSha256, afterSha256, copiedBytes, changed) {
+    return {
+        source_path: sourcePath,
+        target_path: targetPath,
+        before_target_sha256: beforeSha256,
+        after_target_sha256: afterSha256,
+        source_sha256: afterSha256,
+        copied_bytes: copiedBytes,
+        changed,
+    };
+}

package/dist/utils/atomicFile.d.ts

@@ -0,0 +1,7 @@
+export interface AtomicWriteOptions {
+    encoding?: BufferEncoding;
+    mode?: number;
+}
+/** Replace a file from a complete same-directory temporary file. */
+export declare function atomicWriteFileSync(path: string, content: string | NodeJS.ArrayBufferView, options?: AtomicWriteOptions): void;
+export declare function atomicWriteJsonFileSync(path: string, value: unknown, mode?: number): void;

package/dist/utils/atomicFile.js

@@ -0,0 +1,48 @@
+import { randomBytes } from "node:crypto";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+const transientWindowsRenameErrors = new Set(["EACCES", "EBUSY", "EPERM"]);
+const renameRetryDeadlineMs = 1_000;
+const renameRetryDelayMs = 10;
+const waitArray = new Int32Array(new SharedArrayBuffer(4));
+/** Replace a file from a complete same-directory temporary file. */
+export function atomicWriteFileSync(path, content, options = {}) {
+    const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        writeFileSync(temporaryPath, content, {
+            encoding: options.encoding ?? "utf-8",
+            flag: "wx",
+            ...(options.mode === undefined ? {} : { mode: options.mode }),
+        });
+        replaceFileSync(temporaryPath, path);
+    }
+    catch (error) {
+        try {
+            rmSync(temporaryPath, { force: true });
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+function replaceFileSync(temporaryPath, path) {
+    const deadline = Date.now() + renameRetryDeadlineMs;
+    while (true) {
+        try {
+            renameSync(temporaryPath, path);
+            return;
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? String(error.code || "")
+                : "";
+            if (process.platform !== "win32" ||
+                !transientWindowsRenameErrors.has(code) ||
+                Date.now() >= deadline) {
+                throw error;
+            }
+            Atomics.wait(waitArray, 0, 0, renameRetryDelayMs);
+        }
+    }
+}
+export function atomicWriteJsonFileSync(path, value, mode = 0o600) {
+    atomicWriteFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { mode });
+}

package/dist/utils/boundedFile.d.ts

@@ -0,0 +1,8 @@
+export interface BoundedTextRead {
+    content: string;
+    totalBytes: number;
+    truncated: boolean;
+}
+export declare function readTextFilePrefixSync(path: string, maxBytes: number): BoundedTextRead;
+export declare function readTextFileTailLinesSync(path: string, lines: number, maxBytes?: number): string;
+export declare function appendBoundedTextFileSync(path: string, content: string, maxBytes?: number): void;

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.1";
-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.1";
-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")