patchwarden 0.4.0 → 0.6.0

package/dist/tools/applyPatch.d.ts

@@ -0,0 +1,16 @@
+import { type PatchOperation } from "../direct/directPatch.js";
+export interface ApplyPatchInput {
+    session_id: string;
+    path: string;
+    expected_sha256: string;
+    operations: PatchOperation[];
+}
+export interface ApplyPatchOutput {
+    path: string;
+    before_sha256: string;
+    after_sha256: string;
+    operations_applied: number;
+    bytes_changed: number;
+    next_action: string;
+}
+export declare function applyPatch(input: ApplyPatchInput): ApplyPatchOutput;

package/dist/tools/applyPatch.js

@@ -0,0 +1,41 @@
+import { getConfig } from "../config.js";
+import { readDirectSession, appendDirectSessionOperation, } from "../direct/directSessionStore.js";
+import { guardDirectSessionActive, guardDirectWritePath, guardDirectPatchSize, } from "../direct/directGuards.js";
+import { applyPatchOperations, validateExpectedSha256, computeFileSha256, } from "../direct/directPatch.js";
+export function applyPatch(input) {
+    const config = getConfig();
+    // 1. Read session and guard active (not expired, not finalized)
+    const session = readDirectSession(input.session_id);
+    guardDirectSessionActive(session);
+    // 2. Guard write path (inside repo, not sensitive, not binary,
+    //    not node_modules/release/dist)
+    const resolvedPath = guardDirectWritePath(input.path, session.resolved_repo_path, config.workspaceRoot);
+    // 3. Calculate patch size and guard against directMaxPatchBytes
+    const patchBytes = JSON.stringify(input.operations).length;
+    guardDirectPatchSize(patchBytes);
+    // 4. Validate expected_sha256 matches current file hash
+    const beforeSha256 = validateExpectedSha256(resolvedPath, input.expected_sha256);
+    // 5. Apply patch operations
+    const patchResult = applyPatchOperations(resolvedPath, input.operations);
+    // Re-read the file from disk to compute the authoritative after_sha256
+    const afterSha256 = computeFileSha256(resolvedPath);
+    // 6. Append operation record to session
+    appendDirectSessionOperation(input.session_id, {
+        index: session.operations.length,
+        timestamp: new Date().toISOString(),
+        path: input.path,
+        before_sha256: beforeSha256,
+        after_sha256: afterSha256,
+        operations_applied: patchResult.operations_applied,
+        bytes_changed: patchResult.bytes_changed,
+    });
+    // 7. Return result
+    return {
+        path: input.path,
+        before_sha256: beforeSha256,
+        after_sha256: afterSha256,
+        operations_applied: patchResult.operations_applied,
+        bytes_changed: patchResult.bytes_changed,
+        next_action: "Call run_verification to test the changes, or apply_patch for more edits.",
+    };
+}

package/dist/tools/auditSession.d.ts

@@ -0,0 +1,5 @@
+import { type DirectSessionAuditOutput } from "../direct/directAudit.js";
+export interface AuditSessionInput {
+    session_id: string;
+}
+export declare function auditSession(input: AuditSessionInput): DirectSessionAuditOutput;

package/dist/tools/auditSession.js

@@ -0,0 +1,12 @@
+import { auditDirectSession, } from "../direct/directAudit.js";
+import { updateDirectSession } from "../direct/directSessionStore.js";
+// ── Main function ──────────────────────────────────────────────────
+export function auditSession(input) {
+    const { session_id } = input;
+    // 1. Perform independent audit (16 audit checks)
+    const output = auditDirectSession(session_id);
+    // 2. Mark session as audited
+    updateDirectSession(session_id, { audited: true });
+    // 3. Return the audit output
+    return output;
+}

package/dist/tools/auditTask.d.ts

@@ -13,6 +13,13 @@ export interface AuditTaskOutput {
     summary: string;
     checks: AuditCheck[];
     risks: AuditRisk[];
+    confirmed_failures: AuditCheck[];
+    possible_false_positives: Array<{
+        check: string;
+        reason: string;
+    }>;
+    manual_verification_required: boolean;
+    manual_verification_items: string[];
     recommended_next_actions: string[];
 }
 export declare function auditTask(taskId: string): AuditTaskOutput;

package/dist/tools/auditTask.js

@@ -55,6 +55,17 @@ export function auditTask(taskId) {
     const checks = [];
     const risks = [];
     const actions = [];
+    const possibleFalsePositives = [];
+    const manualVerificationItems = [];
+    const addManualVerification = (item) => {
+        if (!manualVerificationItems.includes(item))
+            manualVerificationItems.push(item);
+    };
+    const addPossibleFalsePositive = (check, reason) => {
+        if (!possibleFalsePositives.some((item) => item.check === check && item.reason === reason)) {
+            possibleFalsePositives.push({ check, reason });
+        }
+    };
     // ── 1. Task status ──
     const taskStatus = statusData.status || "unknown";
     const failedStatuses = new Set(["failed", "failed_verification", "failed_scope_violation", "failed_policy_violation", "canceled"]);
@@ -63,6 +74,9 @@ export function auditTask(taskId) {
         result: taskStatus === "done" ? "pass" : failedStatuses.has(taskStatus) ? "fail" : "warn",
         detail: `Task status is "${taskStatus}".`,
     });
+    if (taskStatus !== "done" && !failedStatuses.has(taskStatus)) {
+        addManualVerification(`Task status is "${taskStatus}"; audit evidence may be incomplete until terminal state.`);
+    }
     // ── 2. result.md ──
     const resultFile = join(taskDir, "result.md");
     const hasResult = existsSync(resultFile);
@@ -85,6 +99,9 @@ export function auditTask(taskId) {
         result: existsSync(verifyJsonFile) ? "pass" : "warn",
         detail: existsSync(verifyJsonFile) ? "verify.json found." : "verify.json is missing.",
     });
+    if (!existsSync(verifyJsonFile)) {
+        addManualVerification("verify.json is missing; determine whether independent verification was expected.");
+    }
     if (existsSync(verifyJsonFile)) {
         try {
             const verify = JSON.parse(readFileSync(verifyJsonFile, "utf-8"));
@@ -106,6 +123,43 @@ export function auditTask(taskId) {
             ? `${outOfScope.length} out-of-scope change(s) detected.`
             : "No out-of-scope changes recorded.",
     });
+    const changedFilesFile = join(taskDir, "changed-files.json");
+    if (existsSync(changedFilesFile)) {
+        try {
+            const changeEvidence = JSON.parse(readFileSync(changedFilesFile, "utf-8"));
+            const hygiene = changeEvidence.artifact_hygiene;
+            if (hygiene?.counts) {
+                const trackedArtifacts = Number(hygiene.counts.tracked_build_artifacts || 0);
+                const ignoredArtifacts = Number(hygiene.counts.ignored_untracked_artifacts || 0);
+                const runtimeFiles = Number(hygiene.counts.runtime_generated_files || 0);
+                const suspicious = Number(hygiene.counts.suspicious_changes || 0);
+                checks.push({
+                    name: "artifact_hygiene",
+                    result: suspicious > 0 ? "warn" : "pass",
+                    detail: suspicious > 0
+                        ? `${suspicious} generated or artifact-like change(s) are tracked or not ignored and require review.`
+                        : `${ignoredArtifacts} ignored artifact change(s) and ${runtimeFiles} runtime-generated change(s) are classified separately from source risk.`,
+                });
+                if (trackedArtifacts > 0) {
+                    risks.push({ severity: "medium", description: `${trackedArtifacts} tracked build artifact change(s) require intentional source-control review.` });
+                    addPossibleFalsePositive("artifact_hygiene", "Tracked build outputs may be intentional release assets rather than accidental source changes.");
+                }
+                if (suspicious > 0) {
+                    actions.push("Review artifact_hygiene.suspicious_changes before accepting the task; add generated paths to Git ignore rules when appropriate.");
+                    addPossibleFalsePositive("artifact_hygiene", "Artifact-like path classification is heuristic and may include intentionally maintained files.");
+                    addManualVerification("Review artifact_hygiene.suspicious_changes and decide whether each path is intentional.");
+                }
+            }
+            else {
+                checks.push({ name: "artifact_hygiene", result: "warn", detail: "Change evidence uses the legacy format without artifact classification." });
+                addManualVerification("Legacy changed-files evidence has no artifact classification; inspect changed paths manually.");
+            }
+        }
+        catch {
+            checks.push({ name: "artifact_hygiene", result: "warn", detail: "changed-files.json could not be parsed for artifact classification." });
+            addManualVerification("changed-files.json could not be parsed; inspect repository changes directly.");
+        }
+    }
     // ── 3. test.log ──
     const testLogFile = join(taskDir, "test.log");
     const hasTestLog = existsSync(testLogFile);
@@ -114,6 +168,8 @@ export function auditTask(taskId) {
         result: hasTestLog ? "pass" : "warn",
         detail: hasTestLog ? "test.log found." : "test.log is missing.",
     });
+    if (!hasTestLog)
+        addManualVerification("test.log is missing; confirm whether the task required an agent-side test run.");
     // ── 4. git.diff ──
     const diffFile = join(taskDir, "git.diff");
     checks.push({
@@ -121,6 +177,8 @@ export function auditTask(taskId) {
         result: existsSync(diffFile) ? "pass" : "warn",
         detail: existsSync(diffFile) ? "git.diff found." : "git.diff is missing.",
     });
+    if (!existsSync(diffFile))
+        addManualVerification("git.diff is missing; inspect repository state before accepting code changes.");
     // ── 5. repo_path consistency — use resolved_repo_path, NOT resolve() ──
     let repoPathSafe = "";
     let repoConsistent = false;
@@ -167,6 +225,7 @@ export function auditTask(taskId) {
         }
         catch {
             checks.push({ name: "package_json_scripts", result: "warn", detail: "package.json exists but could not be read (may be sensitive)." });
+            addManualVerification("package.json could not be read, so documented commands were not fully cross-checked.");
         }
     }
     // ── 7. Scan all docs (result.md, README.md, docs/**/*.md) ──
@@ -220,6 +279,8 @@ export function auditTask(taskId) {
                 description: `Command "npm run ${scriptName}" referenced in docs but not found in package.json scripts.`,
             });
             actions.push(`Verify whether "npm run ${scriptName}" should exist or if the agent fabricated it.`);
+            addPossibleFalsePositive(`npm_script_${scriptName}`, "Documentation may describe another package, historical version, or example command rather than the current package.json.");
+            addManualVerification(`Check whether documented command "npm run ${scriptName}" belongs to another package or should be added here.`);
         }
     }
     if (allNpmRunRefs.size > 0 && pkgScripts.length > 0) {
@@ -244,6 +305,7 @@ export function auditTask(taskId) {
             description: `${allReleaseClaims.length} remote publish/release/deploy claim(s) found in docs. PatchWarden cannot independently verify npm/GitHub actions. Manual confirmation required.`,
         });
         actions.push("Manually verify all npm publish / GitHub release / git tag claims before accepting the task as complete.");
+        addManualVerification("Verify remote npm, GitHub Release, and Git tag claims against authoritative remote services.");
     }
     // ── 9. test.log Exit code check ──
     if (hasTestLog) {
@@ -254,6 +316,7 @@ export function auditTask(taskId) {
         }
         else if (statusData.test_command) {
             checks.push({ name: "test_command_in_log", result: "warn", detail: `test.log does not clearly show "${statusData.test_command}".` });
+            addManualVerification("Confirm that test.log belongs to the configured test command.");
         }
         // Extract Exit code
         const exitMatch = testLogContent.match(/Exit\s*code:\s*(\d+)/i);
@@ -271,6 +334,7 @@ export function auditTask(taskId) {
         else if (statusData.test_command) {
             checks.push({ name: "test_exit_code", result: "warn", detail: "test.log does not contain 'Exit code:' line — cannot verify test result." });
             risks.push({ severity: "medium", description: "Test command was configured but test.log has no exit code." });
+            addManualVerification("The configured test command has no recorded exit code; rerun or inspect verification evidence.");
         }
     }
     // ── 10. Summarize ──
@@ -278,8 +342,10 @@ export function auditTask(taskId) {
     const warnCount = checks.filter((c) => c.result === "warn").length;
     const passCount = checks.filter((c) => c.result === "pass").length;
     const verdict = failCount > 0 ? "fail" : warnCount > 0 ? "warn" : "pass";
+    const confirmedFailures = checks.filter((check) => check.result === "fail");
     let summary = `Audit complete: ${passCount} pass, ${warnCount} warn, ${failCount} fail across ${checks.length} checks. `;
-    summary += risks.length > 0 ? `${risks.length} risk(s) identified.` : "No risks identified.";
+    summary += risks.length > 0 ? `${risks.length} risk(s) identified. ` : "No risks identified. ";
+    summary += `${confirmedFailures.length} confirmed failure(s), ${possibleFalsePositives.length} possible false-positive warning(s), and ${manualVerificationItems.length} manual verification item(s).`;
     if (actions.length === 0) {
         actions.push("No specific actions recommended.");
     }
@@ -299,9 +365,35 @@ export function auditTask(taskId) {
         "## Risks",
         ...risks.map((r) => `- [${r.severity}] ${r.description}`),
         "",
+        "## Confirmed Failures",
+        ...(confirmedFailures.length > 0
+            ? confirmedFailures.map((check) => `- **${check.name}**: ${check.detail}`)
+            : ["- None."]),
+        "",
+        "## Possible False Positives",
+        ...(possibleFalsePositives.length > 0
+            ? possibleFalsePositives.map((item) => `- **${item.check}**: ${item.reason}`)
+            : ["- None identified."]),
+        "",
+        "## Manual Verification Required",
+        ...(manualVerificationItems.length > 0
+            ? manualVerificationItems.map((item) => `- ${item}`)
+            : ["- No additional manual verification identified by this audit."]),
+        "",
         "## Recommended Actions",
         ...actions.map((a) => `- ${a}`),
     ].join("\n");
     writeFileSync(join(taskDir, "independent-review.md"), reviewMd, "utf-8");
-    return { task_id: taskId, verdict, summary, checks, risks, recommended_next_actions: actions };
+    return {
+        task_id: taskId,
+        verdict,
+        summary,
+        checks,
+        risks,
+        confirmed_failures: confirmedFailures,
+        possible_false_positives: possibleFalsePositives,
+        manual_verification_required: manualVerificationItems.length > 0,
+        manual_verification_items: manualVerificationItems,
+        recommended_next_actions: actions,
+    };
 }

package/dist/tools/createDirectSession.d.ts

@@ -0,0 +1,14 @@
+export interface CreateDirectSessionInput {
+    repo_path: string;
+    title?: string;
+}
+export interface CreateDirectSessionOutput {
+    session_id: string;
+    repo_path: string;
+    resolved_repo_path: string;
+    workspace_clean: boolean;
+    allowed_commands: string[];
+    expires_at: string;
+    next_action: string;
+}
+export declare function createDirectSession(input: CreateDirectSessionInput): CreateDirectSessionOutput;

package/dist/tools/createDirectSession.js

@@ -0,0 +1,54 @@
+import { existsSync, statSync } from "node:fs";
+import { getConfig } from "../config.js";
+import { PatchWardenError } from "../errors.js";
+import { guardWorkspacePath } from "../security/pathGuard.js";
+import { guardRuntimeSelfModification } from "../security/runtimeGuard.js";
+import { captureRepoSnapshot } from "../runner/changeCapture.js";
+import { createDirectSession as createDirectSessionRecord, } from "../direct/directSessionStore.js";
+// ── Tool implementation ────────────────────────────────────────────
+export function createDirectSession(input) {
+    const config = getConfig();
+    // ── Validate repo_path ───────────────────────────────────────────
+    if (!input.repo_path || input.repo_path.trim() === "") {
+        throw new PatchWardenError("invalid_input", "repo_path is required and must be a non-empty string.", "Provide a repository path inside the configured workspaceRoot.", true, { operation: "create_direct_session" });
+    }
+    const resolvedRepoPath = guardWorkspacePath(input.repo_path, config.workspaceRoot);
+    // ── Verify existence ─────────────────────────────────────────────
+    if (!existsSync(resolvedRepoPath)) {
+        throw new PatchWardenError("repo_not_found", `repo_path "${input.repo_path}" does not exist (resolved: "${resolvedRepoPath}").`, "Provide a valid repository path inside the configured workspaceRoot.", true, {
+            repo_path: input.repo_path,
+            resolved_repo_path: resolvedRepoPath,
+            operation: "create_direct_session",
+        });
+    }
+    // ── Verify it is a directory ─────────────────────────────────────
+    const stat = statSync(resolvedRepoPath);
+    if (!stat.isDirectory()) {
+        throw new PatchWardenError("repo_not_directory", `repo_path "${input.repo_path}" is not a directory.`, "Provide a directory path, not a file path.", true, {
+            repo_path: input.repo_path,
+            resolved_repo_path: resolvedRepoPath,
+            operation: "create_direct_session",
+        });
+    }
+    // ── Runtime self-modification protection ─────────────────────────
+    guardRuntimeSelfModification(resolvedRepoPath);
+    // ── Capture repo snapshot ────────────────────────────────────────
+    const snapshot = captureRepoSnapshot(resolvedRepoPath);
+    // ── Create session record ────────────────────────────────────────
+    const session = createDirectSessionRecord({
+        repo_path: input.repo_path,
+        resolved_repo_path: resolvedRepoPath,
+        title: input.title,
+        snapshot,
+    });
+    return {
+        session_id: session.session_id,
+        repo_path: session.repo_path,
+        resolved_repo_path: session.resolved_repo_path,
+        workspace_clean: !snapshot.workspace_dirty,
+        allowed_commands: session.allowed_commands,
+        expires_at: session.expires_at,
+        next_action: "Use search_workspace/read_workspace_file, then apply_patch to make file changes within this session. " +
+            "After editing, call run_verification, finalize_direct_session, and audit_session.",
+    };
+}

package/dist/tools/createTask.d.ts

@@ -9,12 +9,56 @@ export interface CreateTaskInput {
     template?: TaskTemplateName;
     goal?: string;
     source_task_id?: string;
-    agent: string;
+    agent?: string;
     repo_path?: string;
     test_command?: string;
     verify_commands?: string[];
     timeout_seconds?: number;
+    execution_mode?: "assess_only" | "execute";
+    assessment_id?: string;
+}
+export interface AssessOnlyOutput {
+    assessment_id: string;
+    assessment_short_id: string;
+    decision: "allow" | "needs_confirm" | "blocked";
+    risk_level: "low" | "medium" | "high";
+    risk_hints: string[];
+    hard_rule_hits: string[];
+    reason_codes: string[];
+    expires_at: string;
+    requires_confirm: boolean;
+    workspace_snapshot_summary: {
+        head: string | null;
+        file_count: number;
+        workspace_dirty: boolean;
+        snapshot_truncated: boolean;
+    };
+    next_action: string;
+    next_tool_call?: {
+        name: "create_task";
+        arguments: {
+            execution_mode: "execute";
+            assessment_id: string;
+        };
+    };
+    local_confirmation: {
+        required: boolean;
+        command: "patchwarden-confirm" | null;
+        arguments: string[];
+    };
+    suggestion?: string;
+    agent_assessment?: {
+        status: string;
+        merged_risk: string;
+        merged_decision: string;
+        confidence: number | null;
+        notes: string | null;
+        read_only_violation: boolean;
+        stdout_truncated: boolean;
+        stderr_truncated: boolean;
+    } | null;
 }
+export type CreateTaskResult = CreateTaskOutput | AssessOnlyOutput;
 export interface CreateTaskOutput {
     task_id: string;
     plan_id: string;
@@ -39,4 +83,7 @@ export interface CreateTaskOutput {
         arguments: Record<string, unknown>;
     };
 }
+export declare function createTask(input: CreateTaskInput & {
+    execution_mode: "assess_only";
+}): AssessOnlyOutput;
 export declare function createTask(input: CreateTaskInput): CreateTaskOutput;