patchwarden 1.5.1 → 1.6.1

package/dist/runner/simpleProcess.js

@@ -1,20 +1,30 @@
 import { spawn, spawnSync } from "node:child_process";
-import { createWriteStream, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { allowedEnvironmentValues, buildChildEnvironment, prepareShellFreeCommand, redactProcessOutput, resolveTrustedExecutable, SecureProcessLogCapture, } from "./processSecurity.js";
 const GRACEFUL_KILL_MS = 2000;
 const DEFAULT_MAX_STDOUT = 524288;
 const DEFAULT_MAX_STDERR = 131072;
 export function runSimpleProcessSync(options) {
     const maxStdout = options.maxStdoutBytes ?? DEFAULT_MAX_STDOUT;
     const maxStderr = options.maxStderrBytes ?? DEFAULT_MAX_STDERR;
+    const exactRedactionValues = allowedEnvironmentValues(options.environmentVariableNames);
+    const logCapture = new SecureProcessLogCapture([options.stdoutPath, options.stderrPath], options.maxLogBytes);
     let result;
     try {
-        result = spawnSync(options.command, options.args, {
+        const env = buildChildEnvironment({
+            cwd: options.cwd,
+            allowedNames: options.environmentVariableNames,
+            blockedNames: options.blockedEnvironmentVariableNames,
+        });
+        const prepared = prepareShellFreeCommand(options.command, options.args, options.cwd, { pathValue: env.PATH });
+        const command = resolveTrustedExecutable(prepared.command, options.cwd, { pathValue: env.PATH });
+        result = spawnSync(command, prepared.args, {
             cwd: options.cwd,
             stdio: ["ignore", "pipe", "pipe"],
             timeout: options.timeoutMs,
             windowsHide: true,
             maxBuffer: maxStdout + 1024,
             encoding: "utf-8",
+            env,
         });
     }
     catch (error) {
@@ -28,23 +38,16 @@ export function runSimpleProcessSync(options) {
             stderrTruncated: false,
         };
     }
-    const stdout = result.stdout || "";
-    const stderr = result.stderr || "";
+    const rawStdout = result.stdout || "";
+    const rawStderr = result.stderr || "";
+    const stdout = redactProcessOutput(rawStdout, exactRedactionValues);
+    const stderr = redactProcessOutput(rawStderr, exactRedactionValues);
     const timedOut = Boolean(result.signal === "SIGTERM" || result.signal === "SIGKILL" ||
         (result.signal !== null && result.status === null) ||
-        (result.error && result.error.code === "ETIMEDOUT"));
-    if (options.stdoutPath && stdout) {
-        try {
-            writeFileSyncAppend(options.stdoutPath, stdout);
-        }
-        catch { } // best-effort log write; failure doesn't affect result
-    }
-    if (options.stderrPath && stderr) {
-        try {
-            writeFileSyncAppend(options.stderrPath, stderr);
-        }
-        catch { } // best-effort log write; failure doesn't affect result
-    }
+        (result.error && errorCode(result.error) === "ETIMEDOUT"));
+    logCapture.append(options.stdoutPath, rawStdout);
+    logCapture.append(options.stderrPath, rawStderr);
+    logCapture.flush(exactRedactionValues);
     return {
         exitCode: result.status,
         stdout: stdout.length > maxStdout ? stdout.slice(0, maxStdout) : stdout,
@@ -52,21 +55,30 @@ export function runSimpleProcessSync(options) {
         // If timed out, don't report spawnError — it's a timeout, not a spawn failure
         spawnError: timedOut ? null : (result.error ? result.error.message : null),
         timedOut,
-        stdoutTruncated: stdout.length > maxStdout,
-        stderrTruncated: stderr.length > maxStderr,
+        stdoutTruncated: rawStdout.length > maxStdout || stdout.length > maxStdout,
+        stderrTruncated: rawStderr.length > maxStderr || stderr.length > maxStderr,
     };
 }
 export async function runSimpleProcess(options) {
     const maxStdout = options.maxStdoutBytes ?? DEFAULT_MAX_STDOUT;
     const maxStderr = options.maxStderrBytes ?? DEFAULT_MAX_STDERR;
-    const deadlineMs = Date.now() + options.timeoutMs;
+    const exactRedactionValues = allowedEnvironmentValues(options.environmentVariableNames);
+    const logCapture = new SecureProcessLogCapture([options.stdoutPath, options.stderrPath], options.maxLogBytes);
     let child;
     try {
-        child = spawn(options.command, options.args, {
+        const env = buildChildEnvironment({
+            cwd: options.cwd,
+            allowedNames: options.environmentVariableNames,
+            blockedNames: options.blockedEnvironmentVariableNames,
+        });
+        const prepared = prepareShellFreeCommand(options.command, options.args, options.cwd, { pathValue: env.PATH });
+        const command = resolveTrustedExecutable(prepared.command, options.cwd, { pathValue: env.PATH });
+        child = spawn(command, prepared.args, {
             cwd: options.cwd,
             stdio: ["ignore", "pipe", "pipe"],
             detached: process.platform !== "win32",
             windowsHide: true,
+            env,
         });
     }
     catch (error) {
@@ -80,8 +92,6 @@ export async function runSimpleProcess(options) {
             stderrTruncated: false,
         };
     }
-    const stdoutStream = options.stdoutPath ? createWriteStream(options.stdoutPath, { flags: "a" }) : null;
-    const stderrStream = options.stderrPath ? createWriteStream(options.stderrPath, { flags: "a" }) : null;
     let stdoutBuf = Buffer.alloc(0);
     let stderrBuf = Buffer.alloc(0);
     let stdoutTruncated = false;
@@ -105,7 +115,7 @@ export async function runSimpleProcess(options) {
         }
     };
     child.stdout?.on("data", (chunk) => {
-        stdoutStream?.write(chunk);
+        logCapture.append(options.stdoutPath, chunk);
         if (stdoutBuf.length < maxStdout) {
             const remaining = maxStdout - stdoutBuf.length;
             if (chunk.length <= remaining) {
@@ -121,7 +131,7 @@ export async function runSimpleProcess(options) {
         }
     });
     child.stderr?.on("data", (chunk) => {
-        stderrStream?.write(chunk);
+        logCapture.append(options.stderrPath, chunk);
         if (stderrBuf.length < maxStderr) {
             const remaining = maxStderr - stderrBuf.length;
             if (chunk.length <= remaining) {
@@ -146,7 +156,6 @@ export async function runSimpleProcess(options) {
             resolveExit(code);
         };
         child.once("close", (code) => finish(code));
-        child.once("exit", (code) => finish(code));
         child.once("error", (error) => {
             spawnError = error.message;
             finish(null);
@@ -155,16 +164,17 @@ export async function runSimpleProcess(options) {
     clearTimeout(timeoutTimer);
     if (forceTimer)
         clearTimeout(forceTimer);
-    stdoutStream?.destroy();
-    stderrStream?.destroy();
+    logCapture.flush(exactRedactionValues);
+    const stdout = redactProcessOutput(stdoutBuf.toString("utf-8"), exactRedactionValues);
+    const stderr = redactProcessOutput(stderrBuf.toString("utf-8"), exactRedactionValues);
     return {
         exitCode,
-        stdout: stdoutBuf.toString("utf-8"),
-        stderr: stderrBuf.toString("utf-8"),
+        stdout: stdout.length > maxStdout ? stdout.slice(0, maxStdout) : stdout,
+        stderr: stderr.length > maxStderr ? stderr.slice(0, maxStderr) : stderr,
         spawnError,
         timedOut,
-        stdoutTruncated,
-        stderrTruncated,
+        stdoutTruncated: stdoutTruncated || stdout.length > maxStdout,
+        stderrTruncated: stderrTruncated || stderr.length > maxStderr,
     };
 }
 function gracefulKill(child) {
@@ -181,10 +191,13 @@ function forceKill(child) {
         return;
     try {
         if (process.platform === "win32") {
-            const result = spawnSync("taskkill.exe", ["/PID", String(child.pid), "/T", "/F"], {
+            const systemRoot = process.env.SystemRoot || process.env.WINDIR || "C:\\Windows";
+            const taskkill = resolveTrustedExecutable(`${systemRoot}\\System32\\taskkill.exe`, process.cwd());
+            const result = spawnSync(taskkill, ["/PID", String(child.pid), "/T", "/F"], {
                 stdio: "ignore",
                 timeout: 5000,
                 windowsHide: true,
+                env: buildChildEnvironment({ cwd: process.cwd() }),
             });
             if (result.status !== 0)
                 child.kill("SIGKILL");
@@ -200,7 +213,8 @@ function forceKill(child) {
         catch { } // cleanup failure is safe to ignore
     }
 }
-function writeFileSyncAppend(path, content) {
-    const existing = existsSync(path) ? readFileSync(path, "utf-8") : "";
-    writeFileSync(path, existing + content, "utf-8");
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code || "")
+        : null;
 }

package/dist/{taskProgress.d.ts → runner/taskProgress.d.ts}

@@ -1,4 +1,4 @@
-import type { TaskPhase } from "./tools/createTask.js";
+import type { TaskPhase } from "../tools/tasks/createTask.js";
 export declare function writeTaskProgress(taskDir: string, phase: TaskPhase, options?: {
     currentCommand?: string | null;
     note?: string;

package/dist/{taskProgress.js → runner/taskProgress.js}

@@ -1,5 +1,5 @@
-import { writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { atomicWriteFileSync } from "../utils/atomicFile.js";
 const PHASES = [
     { phase: "queued", label: "Queued" },
     { phase: "preparing", label: "Preparing repository snapshot" },
@@ -32,5 +32,5 @@ export function writeTaskProgress(taskDir, phase, options) {
         lines.push(`Current command: ${options.currentCommand}`);
     if (options?.note)
         lines.push("", `Note: ${options.note}`);
-    writeFileSync(join(taskDir, "progress.md"), `${lines.join("\n")}\n`, "utf-8");
+    atomicWriteFileSync(join(taskDir, "progress.md"), `${lines.join("\n")}\n`);
 }

package/dist/{taskRuntime.d.ts → runner/taskRuntime.d.ts}

@@ -1,4 +1,4 @@
-import type { TaskPhase } from "./tools/createTask.js";
+import type { TaskPhase } from "../tools/tasks/createTask.js";
 export interface TaskRuntimeData {
     phase: TaskPhase;
     last_heartbeat_at: string;

package/dist/{taskRuntime.js → runner/taskRuntime.js}

@@ -1,5 +1,6 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { atomicWriteJsonFileSync } from "../utils/atomicFile.js";
 export function readTaskRuntime(taskDir) {
     const runtimeFile = join(taskDir, "runtime.json");
     if (!existsSync(runtimeFile))
@@ -20,6 +21,6 @@ export function writeTaskRuntime(taskDir, patch) {
         ...current,
         ...patch,
     };
-    writeFileSync(join(taskDir, "runtime.json"), JSON.stringify(next, null, 2), "utf-8");
+    atomicWriteJsonFileSync(join(taskDir, "runtime.json"), next);
     return next;
 }

package/dist/runner/taskStatusStore.d.ts

@@ -0,0 +1,11 @@
+import { type LockedJsonMutation } from "../utils/lockedJsonFile.js";
+export type TaskStatusRecord = Record<string, unknown>;
+export type TaskStatusMutation<T> = LockedJsonMutation<TaskStatusRecord, T>;
+export interface TaskClaimResult {
+    claimed: boolean;
+    status: TaskStatusRecord;
+}
+export declare function readTaskStatusFile(statusFile: string): TaskStatusRecord;
+export declare function mutateTaskStatus<T>(statusFile: string, mutation: (current: TaskStatusRecord) => TaskStatusMutation<T>): T;
+export declare function claimPendingTask(statusFile: string, patch: TaskStatusRecord): TaskClaimResult;
+export declare function updateTaskStatusFile(statusFile: string, patch: TaskStatusRecord): TaskStatusRecord;

package/dist/runner/taskStatusStore.js

@@ -0,0 +1,24 @@
+import { PatchWardenError } from "../errors.js";
+import { mutateLockedJsonFileSync, readJsonObjectFileSync, } from "../utils/lockedJsonFile.js";
+export function readTaskStatusFile(statusFile) {
+    return readJsonObjectFileSync(statusFile);
+}
+export function mutateTaskStatus(statusFile, mutation) {
+    return mutateLockedJsonFileSync(statusFile, mutation, {
+        busyError: () => new PatchWardenError("task_status_busy", "Task status is currently being updated by another PatchWarden process.", "Retry the operation after the current task status update completes.", true),
+    });
+}
+export function claimPendingTask(statusFile, patch) {
+    return mutateTaskStatus(statusFile, (current) => {
+        if (current.status !== "pending")
+            return { result: { claimed: false, status: current } };
+        const next = { ...current, ...patch, updated_at: new Date().toISOString() };
+        return { next, result: { claimed: true, status: next } };
+    });
+}
+export function updateTaskStatusFile(statusFile, patch) {
+    return mutateTaskStatus(statusFile, (current) => {
+        const next = { ...current, ...patch, updated_at: new Date().toISOString() };
+        return { next, result: next };
+    });
+}

package/dist/runner/watch.d.ts

@@ -16,4 +16,17 @@
  * Run: node dist/runner/watch.js
  *   or: npm run watch
  */
-export {};
+export declare class WatcherAlreadyRunningError extends Error {
+    constructor(message: string);
+}
+/**
+ * Acquire the watcher lock at `lockFilePath`. If a lock file exists and its
+ * recorded PID is still alive (per `process.kill(pid, 0)`), throws
+ * {@link WatcherAlreadyRunningError}. Otherwise overwrites the lock atomically.
+ *
+ * Exported for unit testing; `lockFilePath` defaults to the module-level
+ * {@link WATCHER_LOCK_FILE} but tests pass a temp path.
+ */
+export declare function acquireWatcherLock(lockFilePath?: string): void;
+export declare function releaseWatcherLock(lockFilePath?: string, instanceId?: string, pid?: number): boolean;
+export declare function createNonOverlappingRunner(operation: () => Promise<void>, onSkipped?: () => void): () => Promise<boolean>;

package/dist/runner/watch.js

@@ -16,15 +16,21 @@
  * Run: node dist/runner/watch.js
  *   or: npm run watch
  */
-import { readdirSync, readFileSync, existsSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from "node:fs";
 import { resolve, join, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
 import { loadConfig, getConfig, getTasksDir, resolveWorkspaceRoot } from "../config.js";
 import { guardWorkspacePath } from "../security/pathGuard.js";
 import { guardAgentCommand, guardTestCommand } from "../security/commandGuard.js";
 import { validateAssessmentFreshness } from "../assessments/assessmentStore.js";
 import { captureRepoSnapshot } from "./changeCapture.js";
-import { runTask } from "./runTask.js";
+import { mutateTaskStatus } from "./taskStatusStore.js";
 import { logger } from "../logging.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { atomicWriteFileSync } from "../utils/atomicFile.js";
+//  Note: `runTask` is imported lazily inside `tick()` via `await import("./runTask.js")`.
+//  This keeps `import { acquireWatcherLock }` side-effect-free for unit tests and
+//  avoids eagerly pulling in the full tools/dispatch graph at module load.
 // ── Bootstrap ─────────────────────────────────────────────────────
 loadConfig();
 const config = getConfig();
@@ -32,34 +38,160 @@ const tasksDir = getTasksDir(config);
 const wsRoot = resolveWorkspaceRoot(config);
 const POLL_INTERVAL_MS = 4000;
 const WATCHER_HEARTBEAT_FILE = join(dirname(tasksDir), "watcher-heartbeat.json");
+const WATCHER_LOCK_FILE = join(dirname(tasksDir), "watcher.lock");
 const WATCHER_STARTED_AT = new Date().toISOString();
 const WATCHER_INSTANCE_ID = process.env.PATCHWARDEN_WATCHER_INSTANCE_ID || `standalone-${process.pid}-${Date.now()}`;
 const WATCHER_LAUNCHER_PID = Number.isInteger(Number(process.env.PATCHWARDEN_WATCHER_LAUNCHER_PID))
     ? Number(process.env.PATCHWARDEN_WATCHER_LAUNCHER_PID)
     : null;
-mkdirSync(dirname(WATCHER_HEARTBEAT_FILE), { recursive: true });
-logger.info(`[watcher] Workspace: ${wsRoot}`);
-logger.info(`[watcher] Tasks:    ${tasksDir}`);
-logger.info(`[watcher] Polling every ${POLL_INTERVAL_MS / 1000}s`);
-logger.info(`[watcher] Press Ctrl+C to stop`);
 // Track executed tasks to prevent re-execution
 const executedTasks = new Set();
+let consecutiveTickFailures = 0;
+// ── Single-instance lock ─────────────────────────────────────────
+//  watch.ts is a long-running poller; without a lock, two watchers started
+//  against the same workspace would race on the same pending tasks. The lock
+//  is best-effort: it detects a live PID via process.kill(pid, 0) and refuses
+//  to start when one is found. A dead PID (crashed watcher) is taken over.
+export class WatcherAlreadyRunningError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WatcherAlreadyRunningError";
+    }
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code || "")
+        : null;
+}
+function readWatcherLock(lockFilePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockFilePath, "utf-8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but the current user cannot signal it.
+        return errorCode(error) === "EPERM";
+    }
+}
+function runningWatcherError(lockData) {
+    return new WatcherAlreadyRunningError(`[watcher] Already running (pid=${lockData?.pid ?? "unknown"}, instance=${lockData?.instance_id ?? "unknown"}). Exiting.`);
+}
+function createWatcherLockExclusive(lockFilePath, content) {
+    const descriptor = openSync(lockFilePath, "wx", 0o600);
+    let writeError = null;
+    try {
+        writeFileSync(descriptor, content, "utf-8");
+    }
+    catch (error) {
+        writeError = error;
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    if (writeError) {
+        try {
+            unlinkSync(lockFilePath);
+        }
+        catch { /* best effort after a partial write */ }
+        throw writeError;
+    }
+}
+/**
+ * Acquire the watcher lock at `lockFilePath`. If a lock file exists and its
+ * recorded PID is still alive (per `process.kill(pid, 0)`), throws
+ * {@link WatcherAlreadyRunningError}. Otherwise overwrites the lock atomically.
+ *
+ * Exported for unit testing; `lockFilePath` defaults to the module-level
+ * {@link WATCHER_LOCK_FILE} but tests pass a temp path.
+ */
+export function acquireWatcherLock(lockFilePath = WATCHER_LOCK_FILE) {
+    const lockContent = JSON.stringify({
+        pid: process.pid,
+        instance_id: WATCHER_INSTANCE_ID,
+        started_at: WATCHER_STARTED_AT,
+        launcher_pid: WATCHER_LAUNCHER_PID,
+    }, null, 2);
+    try {
+        createWatcherLockExclusive(lockFilePath, lockContent);
+        return;
+    }
+    catch (error) {
+        if (errorCode(error) !== "EEXIST")
+            throw error;
+    }
+    const existing = readWatcherLock(lockFilePath);
+    if (typeof existing?.pid === "number" && processIsAlive(existing.pid)) {
+        throw runningWatcherError(existing);
+    }
+    try {
+        unlinkSync(lockFilePath);
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT")
+            throw error;
+    }
+    try {
+        createWatcherLockExclusive(lockFilePath, lockContent);
+    }
+    catch (error) {
+        if (errorCode(error) === "EEXIST") {
+            throw runningWatcherError(readWatcherLock(lockFilePath));
+        }
+        throw error;
+    }
+}
+export function releaseWatcherLock(lockFilePath = WATCHER_LOCK_FILE, instanceId = WATCHER_INSTANCE_ID, pid = process.pid) {
+    const existing = readWatcherLock(lockFilePath);
+    if (existing?.pid !== pid || existing.instance_id !== instanceId)
+        return false;
+    try {
+        unlinkSync(lockFilePath);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export function createNonOverlappingRunner(operation, onSkipped = () => undefined) {
+    let running = false;
+    return async () => {
+        if (running) {
+            onSkipped();
+            return false;
+        }
+        running = true;
+        try {
+            await operation();
+            return true;
+        }
+        finally {
+            running = false;
+        }
+    };
+}
 // ── Main loop ─────────────────────────────────────────────────────
 async function tick() {
     try {
-        const heartbeatTemporary = `${WATCHER_HEARTBEAT_FILE}.${WATCHER_INSTANCE_ID}.tmp`;
-        writeFileSync(heartbeatTemporary, JSON.stringify({
-            status: "running",
-            pid: process.pid,
-            started_at: WATCHER_STARTED_AT,
-            last_heartbeat_at: new Date().toISOString(),
-            instance_id: WATCHER_INSTANCE_ID,
-            launcher_pid: WATCHER_LAUNCHER_PID,
-        }, null, 2), "utf-8");
-        renameSync(heartbeatTemporary, WATCHER_HEARTBEAT_FILE);
+        writeWatcherHeartbeat("running");
         // Ensure tasks directory exists
-        if (!existsSync(tasksDir))
+        if (!existsSync(tasksDir)) {
+            consecutiveTickFailures = 0;
+            writeWatcherHeartbeat("running");
             return;
+        }
         const entries = readdirSync(tasksDir, { withFileTypes: true });
         const taskDirs = entries.filter((e) => e.isDirectory());
         for (const entry of taskDirs) {
@@ -73,21 +205,34 @@ async function tick() {
                 continue;
             let statusData;
             try {
-                statusData = JSON.parse(readFileSync(statusFile, "utf-8"));
+                const parsed = JSON.parse(readFileSync(statusFile, "utf-8"));
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    throw new Error("status.json must contain an object");
+                }
+                statusData = parsed;
             }
-            catch {
-                continue; // corrupted status, skip
+            catch (error) {
+                logger.warn("[watcher] Skipping unreadable task status", {
+                    task_id: taskId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                continue;
             }
             if (statusData.status !== "pending")
                 continue;
             // ── Pre-flight safety checks ──
             try {
                 // Check repo_path
-                const resolvedRepoPath = guardWorkspacePath(statusData.resolved_repo_path || statusData.repo_path || wsRoot, wsRoot);
+                const repoPath = typeof statusData.resolved_repo_path === "string"
+                    ? statusData.resolved_repo_path
+                    : typeof statusData.repo_path === "string"
+                        ? statusData.repo_path
+                        : wsRoot;
+                const resolvedRepoPath = guardWorkspacePath(repoPath, wsRoot);
                 // Check agent
-                guardAgentCommand(statusData.agent, config);
+                guardAgentCommand(typeof statusData.agent === "string" ? statusData.agent : "", config);
                 // Check test_command
-                if (statusData.test_command) {
+                if (typeof statusData.test_command === "string" && statusData.test_command) {
                     guardTestCommand(statusData.test_command, config, resolvedRepoPath);
                 }
                 if (Array.isArray(statusData.verify_commands)) {
@@ -96,25 +241,31 @@ async function tick() {
                     }
                 }
                 // Assessment freshness revalidation
-                if (statusData.assessment_id) {
+                if (typeof statusData.assessment_id === "string" && statusData.assessment_id) {
                     const preExecSnapshot = await captureRepoSnapshot(resolvedRepoPath);
-                    const validation = validateAssessmentFreshness(String(statusData.assessment_id), preExecSnapshot);
+                    const validation = validateAssessmentFreshness(statusData.assessment_id, preExecSnapshot);
                     if (!validation.valid) {
                         throw new Error(`assessment validation failed: ${validation.failure_reason}`);
                     }
                 }
             }
             catch (err) {
-                const errMsg = `[watcher] Safety check failed for ${taskId}: ${err instanceof Error ? err.message : String(err)}`;
+                const errMsg = redactSensitiveContent(`[watcher] Safety check failed for ${taskId}: ${err instanceof Error ? err.message : String(err)}`).content;
                 logger.error(errMsg);
                 // Write error and mark as failed so it doesn't get re-picked
                 try {
-                    writeFileSync(join(taskDir, "error.log"), errMsg, "utf-8");
-                    const data = JSON.parse(readFileSync(statusFile, "utf-8"));
-                    data.status = "failed";
-                    data.error = errMsg;
-                    data.updated_at = new Date().toISOString();
-                    writeFileSync(statusFile, JSON.stringify(data, null, 2), "utf-8");
+                    atomicWriteFileSync(join(taskDir, "error.log"), errMsg);
+                    mutateTaskStatus(statusFile, (current) => {
+                        if (current.status !== "pending")
+                            return { result: undefined };
+                        const next = {
+                            ...current,
+                            status: "failed",
+                            error: errMsg,
+                            updated_at: new Date().toISOString(),
+                        };
+                        return { next, result: undefined };
+                    });
                 }
                 catch (err) {
                     logger.warn("watcher error-log write failed", { error: err instanceof Error ? err.message : String(err) });
@@ -126,6 +277,7 @@ async function tick() {
             logger.info(`[watcher] Executing: ${taskId}`);
             executedTasks.add(taskId);
             try {
+                const { runTask } = await import("./runTask.js");
                 const result = await runTask(taskId);
                 logger.info(`[watcher] ${taskId} → ${result.status}`);
             }
@@ -133,22 +285,78 @@ async function tick() {
                 logger.error(`[watcher] ${taskId} → error: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
+        consecutiveTickFailures = 0;
+        writeWatcherHeartbeat("running");
+    }
+    catch (err) {
+        consecutiveTickFailures += 1;
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`[watcher] Tick error (${consecutiveTickFailures} consecutive): ${message}`);
+        try {
+            writeWatcherHeartbeat(consecutiveTickFailures >= 3 ? "degraded" : "running", message);
+        }
+        catch (heartbeatError) {
+            logger.error("[watcher] Failed to persist degraded heartbeat", {
+                error: heartbeatError instanceof Error ? heartbeatError.message : String(heartbeatError),
+            });
+        }
+    }
+}
+function writeWatcherHeartbeat(status, lastError) {
+    atomicWriteFileSync(WATCHER_HEARTBEAT_FILE, JSON.stringify({
+        status,
+        pid: process.pid,
+        started_at: WATCHER_STARTED_AT,
+        last_heartbeat_at: new Date().toISOString(),
+        instance_id: WATCHER_INSTANCE_ID,
+        launcher_pid: WATCHER_LAUNCHER_PID,
+        consecutive_failures: consecutiveTickFailures,
+        last_error: lastError ? lastError.slice(0, 500) : null,
+    }, null, 2));
+}
+// ── Start (only when executed as a script) ─────────────────────────
+//  The bootstrap below has process-wide side effects (mkdir, signal handlers,
+//  polling interval, lock acquisition). Guarding it with a main-module check
+//  keeps `import { acquireWatcherLock }` safe for unit tests — without it,
+//  importing this module would start polling the real tasks dir and register
+//  SIGINT/SIGTERM handlers that interfere with the test runner.
+const isMainModule = !!process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+if (isMainModule) {
+    mkdirSync(dirname(WATCHER_HEARTBEAT_FILE), { recursive: true });
+    logger.info(`[watcher] Workspace: ${wsRoot}`);
+    logger.info(`[watcher] Tasks:    ${tasksDir}`);
+    logger.info(`[watcher] Polling every ${POLL_INTERVAL_MS / 1000}s`);
+    logger.info(`[watcher] Press Ctrl+C to stop`);
+    try {
+        acquireWatcherLock(WATCHER_LOCK_FILE);
     }
     catch (err) {
-        logger.error(`[watcher] Tick error: ${err instanceof Error ? err.message : String(err)}`);
+        if (err instanceof WatcherAlreadyRunningError) {
+            logger.error(err.message);
+            process.exit(1);
+        }
+        throw err;
+    }
+    logger.info("[watcher] Started");
+    const scheduledTick = createNonOverlappingRunner(tick, () => {
+        logger.warn("[watcher] Previous tick is still running; skipping overlapping poll");
+    });
+    setInterval(() => { void scheduledTick(); }, POLL_INTERVAL_MS);
+    // Run first tick immediately
+    void scheduledTick();
+    // Graceful shutdown
+    function shutdown() {
+        logger.info("[watcher] Stopped");
+        try {
+            releaseWatcherLock(WATCHER_LOCK_FILE);
+        }
+        catch (error) {
+            logger.warn("[watcher] Failed to release watcher lock", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        process.exit(0);
     }
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
 }
-// ── Start ─────────────────────────────────────────────────────────
-logger.info("[watcher] Started");
-setInterval(tick, POLL_INTERVAL_MS);
-// Run first tick immediately
-tick();
-// Graceful shutdown
-process.on("SIGINT", () => {
-    logger.info("[watcher] Stopped");
-    process.exit(0);
-});
-process.on("SIGTERM", () => {
-    logger.info("[watcher] Stopped");
-    process.exit(0);
-});