patchwarden 0.4.0

package/dist/tools/taskOutputs.d.ts

@@ -0,0 +1,49 @@
+import { GetTaskFileOutput } from "./getTaskFile.js";
+export declare function getResult(taskId: string): GetTaskFileOutput;
+export declare function getResultJson(taskId: string): GetTaskFileOutput;
+export declare function getDiff(taskId: string): GetTaskFileOutput;
+export declare function getTestLog(taskId: string, options?: {
+    tailLines?: number;
+    maxBytes?: number;
+}): GetTaskFileOutput;
+/**
+ * Read the tail of a task log file with automatic redaction.
+ * Supports test.log, stdout.log, stderr.log, verify.log.
+ */
+export declare function getTaskLogTail(taskId: string, file: "stdout" | "stderr" | "test" | "verify", options?: {
+    lines?: number;
+    redact?: boolean;
+}): {
+    file: "stdout" | "stderr" | "test" | "verify";
+    lines: number;
+    total_bytes: number;
+    task_id: string;
+    filename: string;
+    content: string;
+    path: string;
+    available: boolean;
+    reason?: "task_not_terminal" | "artifact_missing";
+    task_status?: string;
+    phase?: string;
+    pending_reason?: string | null;
+    watcher?: unknown;
+    next_action?: string;
+    next_tool_call?: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    redacted?: boolean;
+    redaction_categories?: string[];
+    truncated?: undefined;
+} | {
+    task_id: string;
+    file: "stdout" | "stderr" | "test" | "verify";
+    filename: string;
+    content: string;
+    available: boolean;
+    lines: number;
+    total_bytes: number;
+    truncated: boolean;
+    redacted: boolean;
+    redaction_categories: string[];
+};

package/dist/tools/taskOutputs.js

@@ -0,0 +1,136 @@
+import { getTaskFile } from "./getTaskFile.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, getTasksDir } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+export function getResult(taskId) {
+    return getTaskFile(taskId, "result.md");
+}
+export function getResultJson(taskId) {
+    return getTaskFile(taskId, "result.json");
+}
+export function getDiff(taskId) {
+    const config = getConfig();
+    const taskDir = resolve(getTasksDir(config), taskId);
+    const preferred = join(taskDir, "diff.patch");
+    const fallback = join(taskDir, "git.diff");
+    if (!existsSync(preferred) && !existsSync(fallback)) {
+        return getTaskFile(taskId, "diff.patch");
+    }
+    const filePath = existsSync(preferred) ? preferred : fallback;
+    guardPath(filePath, config.workspaceRoot, config.tasksDir);
+    const size = statSync(filePath).size;
+    const raw = readFileSync(filePath, "utf-8");
+    const patchHead = raw.slice(0, config.maxReadFileBytes);
+    const rawReturnedBytes = Buffer.byteLength(patchHead, "utf-8");
+    const redaction = redactSensitiveContent(patchHead);
+    const content = redaction.content;
+    const diff = {
+        task_id: taskId,
+        filename: existsSync(preferred) ? "diff.patch" : "git.diff",
+        content,
+        path: filePath,
+        available: true,
+        truncated: size > rawReturnedBytes,
+        total_bytes: size,
+        returned_bytes: Buffer.byteLength(content, "utf-8"),
+        patch_head: content,
+        diff_patch_path: filePath,
+        redacted: redaction.redacted,
+        redaction_categories: redaction.redaction_categories,
+    };
+    try {
+        const evidence = JSON.parse(getTaskFile(taskId, "changed-files.json").content);
+        return {
+            ...diff,
+            changed_files: evidence.changed_files || [],
+            diff_available: Boolean(evidence.diff_available),
+            workspace_dirty_before: Boolean(evidence.workspace_dirty_before),
+            workspace_dirty_after: Boolean(evidence.workspace_dirty_after),
+            diff_truncated: Boolean(evidence.diff_truncated || diff.truncated),
+            diff_size_bytes: Number(evidence.diff_size_bytes || size),
+            additions: Number(evidence.additions || 0),
+            deletions: Number(evidence.deletions || 0),
+            file_stats: evidence.file_stats || [],
+            patch_mode: evidence.patch_mode || (evidence.diff_available ? "hash_only" : "no_changes"),
+            unavailable_reason: evidence.unavailable_reason || null,
+            message: evidence.diff_available ? "Task diff available" : "No task file changes detected",
+        };
+    }
+    catch {
+        return diff;
+    }
+}
+export function getTestLog(taskId, options) {
+    const maxBytes = options?.maxBytes ?? 0;
+    const tailLines = options?.tailLines ?? 0;
+    if (tailLines > 0 || maxBytes > 0) {
+        return getTaskFileTail(taskId, "test.log", { tailLines, maxBytes });
+    }
+    return getTaskFile(taskId, "test.log");
+}
+/**
+ * Read the tail of a task log file with automatic redaction.
+ * Supports test.log, stdout.log, stderr.log, verify.log.
+ */
+export function getTaskLogTail(taskId, file, options) {
+    const config = getConfig();
+    const taskDir = resolve(getTasksDir(config), taskId);
+    const filename = file === "stdout" ? "stdout.log"
+        : file === "stderr" ? "stderr.log"
+            : file === "test" ? "test.log"
+                : "verify.log";
+    const filePath = join(taskDir, filename);
+    guardPath(filePath, config.workspaceRoot, config.tasksDir);
+    const maxLines = Math.min(options?.lines ?? 80, 200);
+    const applyRedact = options?.redact !== false; // default true
+    if (!existsSync(filePath)) {
+        return { ...getTaskFile(taskId, filename), file, lines: 0, total_bytes: 0 };
+    }
+    const stat = statSync(filePath);
+    const totalBytes = stat.size;
+    const raw = readFileSync(filePath, "utf-8");
+    const tail = raw.split("\n").slice(-maxLines).join("\n");
+    const content = applyRedact ? redactSensitiveContent(tail) : { content: tail, redacted: false, redaction_categories: [] };
+    return {
+        task_id: taskId,
+        file,
+        filename,
+        content: content.content,
+        available: true,
+        lines: tail.split("\n").length,
+        total_bytes: totalBytes,
+        truncated: totalBytes > Buffer.byteLength(tail, "utf-8"),
+        redacted: content.redacted,
+        redaction_categories: content.redaction_categories,
+    };
+}
+function getTaskFileTail(taskId, filename, options) {
+    const config = getConfig();
+    const taskDir = resolve(getTasksDir(config), taskId);
+    const filePath = join(taskDir, filename);
+    guardPath(filePath, config.workspaceRoot, config.tasksDir);
+    if (!existsSync(filePath)) {
+        return getTaskFile(taskId, filename);
+    }
+    const stat = statSync(filePath);
+    const raw = readFileSync(filePath, "utf-8");
+    let content = raw;
+    if (options.tailLines > 0) {
+        content = raw.split("\n").slice(-options.tailLines).join("\n");
+    }
+    if (options.maxBytes > 0 && Buffer.byteLength(content, "utf-8") > options.maxBytes) {
+        content = content.slice(0, options.maxBytes);
+    }
+    const redaction = redactSensitiveContent(content);
+    return {
+        task_id: taskId,
+        filename,
+        content: redaction.content,
+        path: filePath,
+        available: true,
+        redacted: redaction.redacted,
+        redaction_categories: redaction.redaction_categories,
+    };
+}

package/dist/tools/taskTemplates.d.ts

@@ -0,0 +1,15 @@
+export declare const TASK_TEMPLATE_NAMES: readonly ["inspect_only", "feature_small", "fix_tests", "release_check", "rollback_scope_violation"];
+export type TaskTemplateName = typeof TASK_TEMPLATE_NAMES[number];
+export type ChangePolicy = "repo_scoped_changes" | "no_changes";
+export interface TaskTemplateInput {
+    template: TaskTemplateName;
+    goal: string;
+    source_task_id?: string;
+    verify_commands: string[];
+}
+export interface ExpandedTaskTemplate {
+    title: string;
+    content: string;
+    change_policy: ChangePolicy;
+}
+export declare function expandTaskTemplate(input: TaskTemplateInput): ExpandedTaskTemplate;

package/dist/tools/taskTemplates.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { getConfig, getTasksDir } from "../config.js";
+import { PatchWardenError } from "../errors.js";
+import { guardReadPath } from "../security/pathGuard.js";
+export const TASK_TEMPLATE_NAMES = [
+    "inspect_only",
+    "feature_small",
+    "fix_tests",
+    "release_check",
+    "rollback_scope_violation",
+];
+export function expandTaskTemplate(input) {
+    const goal = input.goal.trim();
+    if (!goal) {
+        throw new PatchWardenError("template_goal_required", "Template tasks require a non-empty goal.", "Pass a concise goal describing the desired inspection or repository-local change.");
+    }
+    const common = [
+        `## Goal\n${goal}`,
+        "## Safety boundaries",
+        "- Work only inside the resolved repository path.",
+        "- Do not commit, push, publish, expose credentials, or modify unrelated files.",
+        "- Report exact files inspected or changed and any remaining uncertainty.",
+    ];
+    switch (input.template) {
+        case "inspect_only":
+            return {
+                title: `Inspect only: ${shortTitle(goal)}`,
+                change_policy: "no_changes",
+                content: [
+                    ...common,
+                    "## Execution contract",
+                    "- Perform read-only inspection only.",
+                    "- Do not create, edit, delete, rename, format, or generate repository files.",
+                    "- Return findings, evidence, and the smallest safe next action.",
+                ].join("\n\n"),
+            };
+        case "feature_small":
+            return {
+                title: `Small feature: ${shortTitle(goal)}`,
+                change_policy: "repo_scoped_changes",
+                content: [
+                    ...common,
+                    "## Execution contract",
+                    "- Read the repository instructions, README, and package metadata first.",
+                    "- Make the smallest coherent implementation; avoid framework, dependency, and directory changes unless required.",
+                    "- Run only the independently configured verification commands.",
+                ].join("\n\n"),
+            };
+        case "fix_tests":
+            if (input.verify_commands.length === 0) {
+                throw new PatchWardenError("template_verification_required", "The fix_tests template requires at least one allow-listed verify_commands entry.", "Pass the failing test or check command in verify_commands.");
+            }
+            return {
+                title: `Fix tests: ${shortTitle(goal)}`,
+                change_policy: "repo_scoped_changes",
+                content: [
+                    ...common,
+                    "## Execution contract",
+                    "- Reproduce the relevant failure before editing when possible.",
+                    "- Fix the root cause without deleting tests, weakening checks, or changing unrelated behavior.",
+                    `- PatchWarden will independently run: ${input.verify_commands.join(", ")}.`,
+                ].join("\n\n"),
+            };
+        case "release_check":
+            return {
+                title: `Release check: ${shortTitle(goal)}`,
+                change_policy: "repo_scoped_changes",
+                content: [
+                    ...common,
+                    "## Execution contract",
+                    "- Perform local release-readiness checks and inspect package contents and generated artifacts.",
+                    "- Do not publish, push, create tags/releases, or claim remote completion without live remote evidence.",
+                    "- Clearly separate local readiness from remote publication state.",
+                ].join("\n\n"),
+            };
+        case "rollback_scope_violation": {
+            const evidence = readRollbackEvidence(input.source_task_id);
+            return {
+                title: `Scope violation review: ${shortTitle(goal)}`,
+                change_policy: "no_changes",
+                content: [
+                    ...common,
+                    "## Execution contract",
+                    `- Review scope-violation evidence from source task ${input.source_task_id}.`,
+                    "- Do not perform an automatic rollback, deletion, reset, checkout, or cross-repository edit.",
+                    "- Produce a file-by-file recovery proposal with backup and verification steps for user approval.",
+                    "## Source task recovery evidence",
+                    evidence,
+                ].join("\n\n"),
+            };
+        }
+    }
+}
+function readRollbackEvidence(sourceTaskId) {
+    if (!sourceTaskId?.trim()) {
+        throw new PatchWardenError("source_task_required", "rollback_scope_violation requires source_task_id.", "Pass the task ID that ended with failed_scope_violation.");
+    }
+    const config = getConfig();
+    const taskDir = resolve(getTasksDir(config), sourceTaskId);
+    const statusFile = join(taskDir, "status.json");
+    const rollbackFile = join(taskDir, "rollback_scope_violation_plan.md");
+    guardReadPath(statusFile, config.workspaceRoot, config.tasksDir);
+    guardReadPath(rollbackFile, config.workspaceRoot, config.tasksDir);
+    if (!existsSync(statusFile) || !existsSync(rollbackFile)) {
+        throw new PatchWardenError("scope_violation_evidence_missing", `Source task "${sourceTaskId}" does not contain scope-violation recovery evidence.`, "Use a task that ended with failed_scope_violation and has rollback_scope_violation_plan.md.");
+    }
+    const status = JSON.parse(readFileSync(statusFile, "utf-8"));
+    if (status.status !== "failed_scope_violation") {
+        throw new PatchWardenError("source_task_not_scope_violation", `Source task "${sourceTaskId}" has status "${status.status}", not failed_scope_violation.`, "Use the scope-violating task as source_task_id.");
+    }
+    return readFileSync(rollbackFile, "utf-8").slice(0, 20_000);
+}
+function shortTitle(goal) {
+    return goal.replace(/\s+/g, " ").slice(0, 80);
+}

package/dist/tools/toolCatalog.d.ts

@@ -0,0 +1,19 @@
+export type ToolProfile = "full" | "chatgpt_core";
+export interface CatalogTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+export interface ToolCatalogSnapshot {
+    server_version: string;
+    schema_epoch: string;
+    tool_profile: ToolProfile;
+    tool_count: number;
+    tool_names: string[];
+    tool_manifest_sha256: string;
+}
+export declare const CHATGPT_CORE_TOOL_NAMES: readonly ["health_check", "list_agents", "list_workspace", "read_workspace_file", "save_plan", "create_task", "wait_for_task", "get_task_summary", "get_diff", "get_result", "get_result_json", "get_test_log", "get_task_status", "list_tasks", "cancel_task", "audit_task"];
+export declare function resolveToolProfile(configProfile?: string): ToolProfile;
+export declare function selectToolsForProfile<T extends CatalogTool>(tools: T[], profile: ToolProfile): T[];
+export declare function buildToolCatalogSnapshot(tools: CatalogTool[], profile: ToolProfile): ToolCatalogSnapshot;
+export declare function getLastToolCatalogSnapshot(): ToolCatalogSnapshot | null;

package/dist/tools/toolCatalog.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+export const CHATGPT_CORE_TOOL_NAMES = [
+    "health_check",
+    "list_agents",
+    "list_workspace",
+    "read_workspace_file",
+    "save_plan",
+    "create_task",
+    "wait_for_task",
+    "get_task_summary",
+    "get_diff",
+    "get_result",
+    "get_result_json",
+    "get_test_log",
+    "get_task_status",
+    "list_tasks",
+    "cancel_task",
+    "audit_task",
+];
+let lastSnapshot = null;
+export function resolveToolProfile(configProfile) {
+    const raw = (process.env.PATCHWARDEN_TOOL_PROFILE || configProfile || "full").trim();
+    if (raw !== "full" && raw !== "chatgpt_core") {
+        throw new Error(`Invalid tool profile "${raw}". Expected "full" or "chatgpt_core".`);
+    }
+    return raw;
+}
+export function selectToolsForProfile(tools, profile) {
+    if (profile === "full")
+        return tools;
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    return CHATGPT_CORE_TOOL_NAMES.map((name) => {
+        const tool = byName.get(name);
+        if (!tool)
+            throw new Error(`chatgpt_core tool profile requires missing tool "${name}".`);
+        return tool;
+    });
+}
+export function buildToolCatalogSnapshot(tools, profile) {
+    const manifestInput = tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+    }));
+    const tool_manifest_sha256 = createHash("sha256")
+        .update(stableJson(manifestInput))
+        .digest("hex");
+    lastSnapshot = {
+        server_version: PATCHWARDEN_VERSION,
+        schema_epoch: TOOL_SCHEMA_EPOCH,
+        tool_profile: profile,
+        tool_count: tools.length,
+        tool_names: tools.map((tool) => tool.name),
+        tool_manifest_sha256,
+    };
+    return lastSnapshot;
+}
+export function getLastToolCatalogSnapshot() {
+    return lastSnapshot ? { ...lastSnapshot, tool_names: [...lastSnapshot.tool_names] } : null;
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}

package/dist/tools/waitForTask.d.ts

@@ -0,0 +1,25 @@
+import { type TaskSummaryOutput } from "./getTaskSummary.js";
+export interface WaitForTaskProgressSummary {
+    phase: string;
+    heartbeat_at: string;
+    elapsed_seconds: number;
+    current_command: string | null;
+    hint: string;
+}
+export interface WaitForTaskOutput {
+    task_id: string;
+    status: string;
+    phase: string;
+    terminal: boolean;
+    timed_out: boolean;
+    continuation_required: boolean;
+    waited_ms: number;
+    next_action: string;
+    next_tool_call: {
+        name: "wait_for_task" | "audit_task" | "health_check";
+        arguments: Record<string, unknown>;
+    };
+    summary?: TaskSummaryOutput;
+    progress_summary?: WaitForTaskProgressSummary;
+}
+export declare function waitForTask(taskId: string, waitSeconds?: number): Promise<WaitForTaskOutput>;

package/dist/tools/waitForTask.js

@@ -0,0 +1,59 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { getTaskStatus } from "./getTaskStatus.js";
+import { getTaskSummary } from "./getTaskSummary.js";
+const TERMINAL_STATUSES = new Set([
+    "done",
+    "failed",
+    "failed_verification",
+    "failed_scope_violation",
+    "failed_policy_violation",
+    "canceled",
+]);
+export async function waitForTask(taskId, waitSeconds = 25) {
+    if (!Number.isInteger(waitSeconds) || waitSeconds < 1 || waitSeconds > 30) {
+        throw new Error("wait_seconds must be an integer from 1 to 30.");
+    }
+    const started = Date.now();
+    const deadline = started + waitSeconds * 1000;
+    let status = getTaskStatus(taskId);
+    while (!TERMINAL_STATUSES.has(status.status) && Date.now() < deadline) {
+        await sleep(Math.min(500, Math.max(1, deadline - Date.now())));
+        status = getTaskStatus(taskId);
+    }
+    const terminal = TERMINAL_STATUSES.has(status.status);
+    const executionBlocked = !terminal && status.execution_blocked;
+    const elapsed = Math.round((Date.now() - started) / 1000);
+    const progressSummary = {
+        phase: status.phase,
+        heartbeat_at: status.last_heartbeat_at || status.updated_at || "",
+        elapsed_seconds: elapsed,
+        current_command: status.current_command || null,
+        hint: executionBlocked
+            ? `Watcher is ${status.watcher_status}. Call health_check and restart the owned watcher; do not keep polling this task yet.`
+            : status.phase === "queued"
+                ? "Watcher is healthy and has not picked up this task yet. Continue waiting."
+                : status.phase === "executing_agent"
+                    ? `Agent "${status.agent}" is running. Continue waiting, or call get_task_status for phase and current_command.`
+                    : `Phase "${status.phase}". Task is still in progress.`,
+    };
+    return {
+        task_id: taskId,
+        status: status.status,
+        phase: status.phase,
+        terminal,
+        timed_out: !terminal,
+        continuation_required: !terminal && !executionBlocked,
+        waited_ms: Date.now() - started,
+        next_action: terminal
+            ? "Review the returned summary, then call audit_task for independent acceptance evidence."
+            : executionBlocked
+                ? "Call health_check and restore the owned watcher. The saved task will remain queued for recovery."
+                : `Call wait_for_task again immediately for task_id ${taskId}; do not end the assistant turn while continuation_required is true.`,
+        next_tool_call: terminal
+            ? { name: "audit_task", arguments: { task_id: taskId } }
+            : executionBlocked
+                ? { name: "health_check", arguments: {} }
+                : { name: "wait_for_task", arguments: { task_id: taskId, timeout_seconds: waitSeconds } },
+        ...(terminal ? { summary: getTaskSummary(taskId) } : { progress_summary: progressSummary }),
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const PATCHWARDEN_VERSION = "0.4.0";
+export declare const TOOL_SCHEMA_EPOCH = "2026-06-21-v3";

package/dist/version.js

@@ -0,0 +1,2 @@
+export const PATCHWARDEN_VERSION = "0.4.0";
+export const TOOL_SCHEMA_EPOCH = "2026-06-21-v3";

package/dist/watcherStatus.d.ts

@@ -0,0 +1,20 @@
+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 interface WatcherStatusSnapshot {
+    status: WatcherState;
+    available: boolean;
+    stale_after_seconds: number;
+    last_heartbeat_at: string | null;
+    heartbeat_age_seconds: number | null;
+    heartbeat_pid: number | null;
+    instance_id: string | null;
+    launcher_pid: number | null;
+    reason: string | null;
+}
+export declare function getWatcherHeartbeatPath(config?: PatchWardenConfig): string;
+export declare function readWatcherStatus(config?: PatchWardenConfig, nowMs?: number): WatcherStatusSnapshot;
+export declare function derivePendingReason(task: {
+    status?: string;
+    phase?: string;
+}, watcher: WatcherStatusSnapshot): PendingReason;

package/dist/watcherStatus.js

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getConfig, getTasksDir } from "./config.js";
+export function getWatcherHeartbeatPath(config = getConfig()) {
+    return join(dirname(getTasksDir(config)), "watcher-heartbeat.json");
+}
+export function readWatcherStatus(config = getConfig(), nowMs = Date.now()) {
+    const staleAfterSeconds = config.watcherStaleSeconds;
+    const heartbeatPath = getWatcherHeartbeatPath(config);
+    if (!existsSync(heartbeatPath)) {
+        return {
+            status: "missing",
+            available: false,
+            stale_after_seconds: staleAfterSeconds,
+            last_heartbeat_at: null,
+            heartbeat_age_seconds: null,
+            heartbeat_pid: null,
+            instance_id: null,
+            launcher_pid: null,
+            reason: "Watcher heartbeat has not been observed. Start or restart the PatchWarden watcher.",
+        };
+    }
+    try {
+        const raw = readFileSync(heartbeatPath, "utf-8");
+        const data = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+        const heartbeatMs = Date.parse(String(data.last_heartbeat_at || ""));
+        if (!Number.isFinite(heartbeatMs))
+            throw new Error("invalid heartbeat timestamp");
+        const ageMs = Math.max(0, nowMs - heartbeatMs);
+        const ageSeconds = Math.round(ageMs / 1000);
+        const healthy = ageMs < staleAfterSeconds * 1000;
+        return {
+            status: healthy ? "healthy" : "stale",
+            available: healthy,
+            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: healthy ? null : "Watcher heartbeat is stale. Restart the PatchWarden watcher.",
+        };
+    }
+    catch {
+        return {
+            status: "unreadable",
+            available: false,
+            stale_after_seconds: staleAfterSeconds,
+            last_heartbeat_at: null,
+            heartbeat_age_seconds: null,
+            heartbeat_pid: null,
+            instance_id: null,
+            launcher_pid: null,
+            reason: "Watcher heartbeat file is unreadable.",
+        };
+    }
+}
+export function derivePendingReason(task, watcher) {
+    if (task.status === "pending") {
+        if (watcher.status === "stale")
+            return "queued_but_watcher_stale";
+        if (watcher.status === "missing")
+            return "queued_but_watcher_missing";
+        if (watcher.status === "unreadable")
+            return "queued_but_watcher_unreadable";
+        return "queued_waiting_for_watcher";
+    }
+    if (task.status !== "running")
+        return null;
+    if (task.phase === "executing_agent")
+        return "agent_running";
+    if (task.phase === "running_tests")
+        return "verification_running";
+    if (task.phase === "collecting_artifacts")
+        return "collecting_artifacts";
+    return "preparing";
+}

package/docs/assets/patchwarden-chatgpt-demo.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="720" viewBox="0 0 1280 720" role="img" aria-labelledby="title desc">
+  <title id="title">PatchWarden ChatGPT connector demo</title>
+  <desc id="desc">A sanitized demo showing ChatGPT calling PatchWarden list_workspace and receiving a workspace file list.</desc>
+  <rect width="1280" height="720" fill="#f7f7f5"/>
+  <rect x="40" y="38" width="260" height="644" rx="16" fill="#ffffff" stroke="#deded8"/>
+  <text x="72" y="88" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="28" font-weight="700" fill="#1f1f1f">ChatGPT</text>
+  <rect x="72" y="128" width="188" height="44" rx="10" fill="#eeeeea"/>
+  <text x="96" y="157" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" fill="#333">patchwarden</text>
+  <rect x="340" y="48" width="900" height="624" rx="22" fill="#ffffff" stroke="#e2e2dc"/>
+  <text x="380" y="96" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="22" font-weight="700" fill="#202020">PatchWarden Connector</text>
+  <rect x="672" y="126" width="500" height="88" rx="26" fill="#f0f0ec"/>
+  <text x="704" y="158" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="20" fill="#202020">Use patchwarden.list_workspace</text>
+  <text x="704" y="188" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="20" fill="#202020">to list the configured workspace.</text>
+  <rect x="410" y="270" width="620" height="274" rx="18" fill="#fafafa" stroke="#d9d9d2"/>
+  <text x="448" y="318" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="24" font-weight="700" fill="#1f1f1f">Workspace files</text>
+  <line x1="448" y1="348" x2="990" y2="348" stroke="#ddddda"/>
+  <text x="448" y="388" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" font-weight="700" fill="#2a2a2a">Name</text>
+  <text x="720" y="388" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" font-weight="700" fill="#2a2a2a">Type</text>
+  <text x="850" y="388" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" font-weight="700" fill="#2a2a2a">Size</text>
+  <rect x="448" y="414" width="178" height="34" rx="8" fill="#ececea"/>
+  <text x="462" y="437" font-family="JetBrains Mono,Consolas,monospace" font-size="17" fill="#222">README.md</text>
+  <text x="720" y="437" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" fill="#222">file</text>
+  <text x="850" y="437" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" fill="#222">1.2 KB</text>
+  <rect x="448" y="464" width="164" height="34" rx="8" fill="#ececea"/>
+  <text x="462" y="487" font-family="JetBrains Mono,Consolas,monospace" font-size="17" fill="#222">package.json</text>
+  <text x="720" y="487" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" fill="#222">file</text>
+  <text x="850" y="487" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" fill="#222">320 B</text>
+  <rect x="410" y="584" width="620" height="52" rx="16" fill="#f3f8f5" stroke="#b9dfc7"/>
+  <text x="440" y="617" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" fill="#176b38">ChatGPT can plan; PatchWarden stores tasks; local agents execute safely.</text>
+</svg>