patchwarden 0.4.0 → 0.6.1

package/dist/direct/directGuards.js

@@ -0,0 +1,137 @@
+import { resolve, relative, isAbsolute } from "node:path";
+import { existsSync, statSync, openSync, readSync, closeSync } from "node:fs";
+import { PatchWardenError } from "../errors.js";
+import { isSensitivePath } from "../security/sensitiveGuard.js";
+import { getConfig } from "../config.js";
+// ── Session state guards ───────────────────────────────────────────
+export function guardDirectSessionActive(session) {
+    if (new Date(session.expires_at) < new Date()) {
+        throw new PatchWardenError("session_expired", `Direct session "${session.session_id}" expired at ${session.expires_at}.`, "Create a new direct session with create_direct_session.", true, { session_id: session.session_id, expires_at: session.expires_at });
+    }
+    if (session.finalized) {
+        throw new PatchWardenError("session_finalized", `Direct session "${session.session_id}" has been finalized. No further modifications are allowed.`, "Create a new direct session with create_direct_session to continue making changes.", true, { session_id: session.session_id, finalized_at: session.finalized_at });
+    }
+}
+export function guardDirectSessionFinalized(session) {
+    if (!session.finalized) {
+        throw new PatchWardenError("session_not_finalized", `Direct session "${session.session_id}" has not been finalized. Call finalize_direct_session first.`, "Call finalize_direct_session before audit_session.", true, { session_id: session.session_id });
+    }
+}
+// ── Path guards ────────────────────────────────────────────────────
+/**
+ * Resolve a relative path against the session's repo_path and verify it stays
+ * inside both the repo and the workspace root.
+ */
+export function guardDirectPath(filePath, resolvedRepoPath, workspaceRoot) {
+    const config = getConfig();
+    const resolved = resolve(resolvedRepoPath, filePath);
+    const normalizedRepo = resolve(resolvedRepoPath);
+    const normalizedWs = resolve(workspaceRoot);
+    // Check path is inside workspace root
+    const relToWs = relative(normalizedWs, resolved);
+    if (isAbsolute(relToWs) || relToWs.startsWith("..")) {
+        throw new PatchWardenError("path_outside_repo", `Path "${filePath}" resolves outside the session repo.`, "Use a relative path inside the session's repo_path.", true, { path: filePath, operation: "direct_path_access" });
+    }
+    // Check path is inside repo_path
+    const relToRepo = relative(normalizedRepo, resolved);
+    if (isAbsolute(relToRepo) || relToRepo.startsWith("..")) {
+        throw new PatchWardenError("path_outside_repo", `Path "${filePath}" is outside the session repo_path "${resolvedRepoPath}".`, "Use a relative path inside the session's repo_path.", true, { path: filePath, operation: "direct_path_access" });
+    }
+    return resolved;
+}
+/**
+ * Guard a read path: must be inside repo, not sensitive, not binary.
+ */
+export function guardDirectReadPath(filePath, resolvedRepoPath, workspaceRoot) {
+    const resolved = guardDirectPath(filePath, resolvedRepoPath, workspaceRoot);
+    const normalized = filePath.replace(/\\/g, "/");
+    // Block internal PatchWarden paths (sessions, tasks, plans, assessments)
+    if (normalized.startsWith(".patchwarden/") ||
+        normalized.includes("/.patchwarden/")) {
+        throw new PatchWardenError("internal_patchwarden_path_blocked", `Access denied: "${filePath}" is inside the internal .patchwarden directory.`, "Internal PatchWarden files cannot be accessed through Direct mode.", true, { path: filePath, operation: "direct_read" });
+    }
+    if (isSensitivePath(filePath)) {
+        throw new PatchWardenError("sensitive_path_blocked", `Access denied: "${filePath}" matches a sensitive file pattern.`, "Read only non-sensitive files within the session repo.", true, { path: filePath, operation: "direct_read" });
+    }
+    if (existsSync(resolved) && statSync(resolved).isFile() && isBinaryFile(resolved)) {
+        throw new PatchWardenError("binary_file_blocked", `File "${filePath}" appears to be a binary file.`, "Binary files cannot be read in Direct mode.", true, { path: filePath, operation: "direct_read" });
+    }
+    return resolved;
+}
+/**
+ * Guard a write path: must be inside repo, not sensitive, not binary,
+ * not in node_modules, release, or dist directories.
+ */
+export function guardDirectWritePath(filePath, resolvedRepoPath, workspaceRoot) {
+    const resolved = guardDirectPath(filePath, resolvedRepoPath, workspaceRoot);
+    const normalized = filePath.replace(/\\/g, "/");
+    // Block internal PatchWarden paths
+    if (normalized.startsWith(".patchwarden/") ||
+        normalized.includes("/.patchwarden/")) {
+        throw new PatchWardenError("internal_patchwarden_path_blocked", `Modification denied: "${filePath}" is inside the internal .patchwarden directory.`, "Internal PatchWarden files cannot be modified through Direct mode.", true, { path: filePath, operation: "direct_write" });
+    }
+    if (isSensitivePath(normalized)) {
+        throw new PatchWardenError("sensitive_path_blocked", `Modification denied: "${filePath}" matches a sensitive file pattern.`, "Do not modify .env, credentials, keys, or other sensitive files.", true, { path: filePath, operation: "direct_write" });
+    }
+    // Block node_modules
+    if (normalized.startsWith("node_modules/") || normalized.includes("/node_modules/")) {
+        throw new PatchWardenError("blocked_artifact_path", `Modification denied: "${filePath}" is inside node_modules.`, "Do not modify dependencies directly. Use package management tools instead.", true, { path: filePath, operation: "direct_write" });
+    }
+    // Block release/
+    if (normalized.startsWith("release/") || normalized.includes("/release/")) {
+        throw new PatchWardenError("blocked_artifact_path", `Modification denied: "${filePath}" is inside the release directory.`, "Do not manually modify release artifacts.", true, { path: filePath, operation: "direct_write" });
+    }
+    // Block dist/
+    if (normalized.startsWith("dist/") || normalized.includes("/dist/")) {
+        throw new PatchWardenError("blocked_artifact_path", `Modification denied: "${filePath}" is inside the dist directory.`, "Do not manually modify build output. Modify source files instead.", true, { path: filePath, operation: "direct_write" });
+    }
+    if (existsSync(resolved) && statSync(resolved).isFile() && isBinaryFile(resolved)) {
+        throw new PatchWardenError("binary_file_blocked", `Modification denied: "${filePath}" appears to be a binary file.`, "Binary files cannot be modified in Direct mode.", true, { path: filePath, operation: "direct_write" });
+    }
+    return resolved;
+}
+// ── Size guards ────────────────────────────────────────────────────
+export function guardDirectPatchSize(patchBytes) {
+    const config = getConfig();
+    if (patchBytes > config.directMaxPatchBytes) {
+        throw new PatchWardenError("patch_too_large", `Patch size ${patchBytes} bytes exceeds maximum ${config.directMaxPatchBytes} bytes.`, "Split the patch into smaller operations or reduce the patch size.", true, { patch_bytes: patchBytes, max_bytes: config.directMaxPatchBytes });
+    }
+}
+export function guardDirectFileSize(fileBytes) {
+    const config = getConfig();
+    if (fileBytes > config.directMaxFileBytes) {
+        throw new PatchWardenError("file_too_large", `File size ${fileBytes} bytes exceeds maximum ${config.directMaxFileBytes} bytes.`, "Use search_workspace to find specific content, or split the read into smaller portions.", true, { file_bytes: fileBytes, max_bytes: config.directMaxFileBytes });
+    }
+}
+// ── Binary detection ───────────────────────────────────────────────
+const BINARY_EXTENSIONS = new Set([
+    ".exe", ".dll", ".so", ".dylib", ".a", ".lib", ".o", ".obj",
+    ".zip", ".gz", ".tar", ".tgz", ".bz2", ".7z", ".rar",
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".webp", ".tiff",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+    ".mp3", ".mp4", ".avi", ".mov", ".wav", ".flv",
+    ".bin", ".dat", ".pak", ".pfx", ".p12", ".class", ".jar", ".war",
+    ".wasm", ".node",
+]);
+export function isBinaryFile(filePath) {
+    const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+    for (const ext of BINARY_EXTENSIONS) {
+        if (normalized.endsWith(ext))
+            return true;
+    }
+    // Check file content for null bytes (simple heuristic)
+    try {
+        const fd = openSync(filePath, "r");
+        const buffer = Buffer.alloc(8192);
+        const bytesRead = readSync(fd, buffer, 0, 8192, 0);
+        closeSync(fd);
+        for (let i = 0; i < bytesRead; i++) {
+            if (buffer[i] === 0)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/direct/directPatch.d.ts

@@ -0,0 +1,17 @@
+export type PatchOperationType = "replace_exact" | "insert_before" | "insert_after" | "replace_whole_file";
+export interface PatchOperation {
+    type: PatchOperationType;
+    old_text?: string;
+    new_text: string;
+    occurrence?: "first" | "all" | "exactly_once";
+}
+export interface ApplyPatchResult {
+    before_sha256: string;
+    after_sha256: string;
+    operations_applied: number;
+    bytes_changed: number;
+}
+export declare function computeFileSha256(filePath: string): string;
+export declare function computeContentSha256(content: string): string;
+export declare function validateExpectedSha256(filePath: string, expectedSha256: string): string;
+export declare function applyPatchOperations(filePath: string, operations: PatchOperation[]): ApplyPatchResult;

package/dist/direct/directPatch.js

@@ -0,0 +1,113 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname } from "node:path";
+import { PatchWardenError } from "../errors.js";
+// ── Hash helpers ───────────────────────────────────────────────────
+export function computeFileSha256(filePath) {
+    const content = readFileSync(filePath);
+    return createHash("sha256").update(content).digest("hex");
+}
+export function computeContentSha256(content) {
+    return createHash("sha256").update(content, "utf-8").digest("hex");
+}
+export function validateExpectedSha256(filePath, expectedSha256) {
+    if (!existsSync(filePath)) {
+        throw new PatchWardenError("file_hash_mismatch", `File does not exist: "${filePath}".`, "Ensure the file path is correct and the file exists before applying a patch.", true, { expected_sha256: expectedSha256 });
+    }
+    const currentHash = computeFileSha256(filePath);
+    if (currentHash !== expectedSha256) {
+        throw new PatchWardenError("file_hash_mismatch", `File hash mismatch. Expected "${expectedSha256}" but got "${currentHash}".`, "Re-read the file to get the current sha256, then retry the patch with the updated expected_sha256.", true, { expected_sha256: expectedSha256, actual_sha256: currentHash });
+    }
+    return currentHash;
+}
+// ── Patch application ──────────────────────────────────────────────
+export function applyPatchOperations(filePath, operations) {
+    if (!existsSync(filePath)) {
+        throw new PatchWardenError("patch_anchor_not_found", `File does not exist: "${filePath}".`, "Ensure the file exists before applying a patch. Direct mode does not support creating new files.", true, { path: filePath });
+    }
+    const beforeContent = readFileSync(filePath, "utf-8");
+    const beforeSha256 = computeContentSha256(beforeContent);
+    let content = beforeContent;
+    let operationsApplied = 0;
+    for (const op of operations) {
+        content = applySingleOperation(content, op);
+        operationsApplied++;
+    }
+    const afterSha256 = computeContentSha256(content);
+    const bytesChanged = Math.abs(Buffer.byteLength(content, "utf-8") - Buffer.byteLength(beforeContent, "utf-8"));
+    // Ensure parent directory exists (should already exist for existing files)
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, "utf-8");
+    return {
+        before_sha256: beforeSha256,
+        after_sha256: afterSha256,
+        operations_applied: operationsApplied,
+        bytes_changed: bytesChanged,
+    };
+}
+function applySingleOperation(content, op) {
+    switch (op.type) {
+        case "replace_exact":
+            return applyReplaceExact(content, op);
+        case "insert_before":
+            return applyInsertBefore(content, op);
+        case "insert_after":
+            return applyInsertAfter(content, op);
+        case "replace_whole_file":
+            return op.new_text;
+        default:
+            throw new PatchWardenError("patch_anchor_not_found", `Unknown operation type: "${op.type}".`, "Use one of: replace_exact, insert_before, insert_after, replace_whole_file.", true, { operation_type: op.type });
+    }
+}
+function applyReplaceExact(content, op) {
+    if (op.old_text === undefined || op.old_text === "") {
+        throw new PatchWardenError("patch_anchor_not_found", "replace_exact requires a non-empty old_text.", "Provide the exact text to replace.", true, { operation: "replace_exact" });
+    }
+    const occurrence = op.occurrence || "first";
+    const oldText = op.old_text;
+    const newText = op.new_text;
+    if (occurrence === "all") {
+        if (!content.includes(oldText)) {
+            throw new PatchWardenError("patch_anchor_not_found", `old_text not found in file content.`, "Ensure old_text exactly matches content in the file.", true, { operation: "replace_exact", occurrence: "all" });
+        }
+        return content.split(oldText).join(newText);
+    }
+    if (occurrence === "exactly_once") {
+        const firstIndex = content.indexOf(oldText);
+        if (firstIndex === -1) {
+            throw new PatchWardenError("patch_anchor_not_found", `old_text not found in file content.`, "Ensure old_text exactly matches content in the file.", true, { operation: "replace_exact", occurrence: "exactly_once" });
+        }
+        const secondIndex = content.indexOf(oldText, firstIndex + 1);
+        if (secondIndex !== -1) {
+            throw new PatchWardenError("patch_ambiguous", `old_text appears multiple times in file content, but occurrence is "exactly_once".`, "Use occurrence: \"first\" to replace the first match, or occurrence: \"all\" to replace all matches.", true, { operation: "replace_exact", occurrence: "exactly_once" });
+        }
+        return content.slice(0, firstIndex) + newText + content.slice(firstIndex + oldText.length);
+    }
+    // occurrence === "first" (default)
+    if (!content.includes(oldText)) {
+        throw new PatchWardenError("patch_anchor_not_found", `old_text not found in file content.`, "Ensure old_text exactly matches content in the file.", true, { operation: "replace_exact", occurrence: "first" });
+    }
+    const index = content.indexOf(oldText);
+    return content.slice(0, index) + newText + content.slice(index + oldText.length);
+}
+function applyInsertBefore(content, op) {
+    if (op.old_text === undefined || op.old_text === "") {
+        throw new PatchWardenError("patch_anchor_not_found", "insert_before requires a non-empty old_text as anchor.", "Provide the anchor text before which new_text should be inserted.", true, { operation: "insert_before" });
+    }
+    const index = content.indexOf(op.old_text);
+    if (index === -1) {
+        throw new PatchWardenError("patch_anchor_not_found", `Anchor text not found in file content for insert_before.`, "Ensure old_text exactly matches content in the file.", true, { operation: "insert_before" });
+    }
+    return content.slice(0, index) + op.new_text + content.slice(index);
+}
+function applyInsertAfter(content, op) {
+    if (op.old_text === undefined || op.old_text === "") {
+        throw new PatchWardenError("patch_anchor_not_found", "insert_after requires a non-empty old_text as anchor.", "Provide the anchor text after which new_text should be inserted.", true, { operation: "insert_after" });
+    }
+    const index = content.indexOf(op.old_text);
+    if (index === -1) {
+        throw new PatchWardenError("patch_anchor_not_found", `Anchor text not found in file content for insert_after.`, "Ensure old_text exactly matches content in the file.", true, { operation: "insert_after" });
+    }
+    const insertPos = index + op.old_text.length;
+    return content.slice(0, insertPos) + op.new_text + content.slice(insertPos);
+}

package/dist/direct/directSessionStore.d.ts

@@ -0,0 +1,63 @@
+import { type RepoSnapshot, type ChangeArtifacts } from "../runner/changeCapture.js";
+export interface DirectSessionOperation {
+    index: number;
+    timestamp: string;
+    path: string;
+    before_sha256: string;
+    after_sha256: string;
+    operations_applied: number;
+    bytes_changed: number;
+}
+export interface DirectSessionVerificationRun {
+    command: string;
+    exit_code: number | null;
+    passed: boolean;
+    timed_out: boolean;
+    stdout_tail: string;
+    stderr_tail: string;
+    started_at: string;
+    finished_at: string;
+    log_path: string;
+}
+export interface DirectSessionRecord {
+    session_id: string;
+    title: string;
+    repo_path: string;
+    resolved_repo_path: string;
+    created_at: string;
+    expires_at: string;
+    server_version: string;
+    schema_epoch: string;
+    tool_manifest_sha256: string;
+    workspace_snapshot_before: RepoSnapshot;
+    workspace_fingerprint_before: string;
+    allowed_commands: string[];
+    operations: DirectSessionOperation[];
+    verification_runs: DirectSessionVerificationRun[];
+    finalized: boolean;
+    finalized_at: string | null;
+    audited: boolean;
+    change_artifacts: ChangeArtifacts | null;
+}
+export interface DirectSessionCreateInput {
+    repo_path: string;
+    resolved_repo_path: string;
+    title?: string;
+    snapshot: RepoSnapshot;
+}
+export declare function generateDirectSessionId(): string;
+export declare function createDirectSessionDir(sessionId: string): string;
+export declare function getDirectSessionDir(sessionId: string): string;
+export declare function createDirectSession(input: DirectSessionCreateInput): DirectSessionRecord;
+export declare function readDirectSession(sessionId: string): DirectSessionRecord;
+export declare function updateDirectSession(sessionId: string, updates: Partial<DirectSessionRecord>): DirectSessionRecord;
+export declare function appendDirectSessionOperation(sessionId: string, operation: DirectSessionOperation): DirectSessionRecord;
+export declare function appendDirectSessionVerificationRun(sessionId: string, run: DirectSessionVerificationRun): DirectSessionRecord;
+export interface DirectSessionValidationResult {
+    valid: boolean;
+    failure_reason: string | null;
+    session: DirectSessionRecord | null;
+}
+export declare function validateDirectSessionFreshness(sessionId: string): DirectSessionValidationResult;
+export declare function finalizeDirectSessionRecord(sessionId: string, afterSnapshot: RepoSnapshot, changeArtifacts: ChangeArtifacts): DirectSessionRecord;
+export declare function computeWorkspaceFingerprint(snapshot: RepoSnapshot): string;

package/dist/direct/directSessionStore.js

@@ -0,0 +1,192 @@
+import { mkdirSync, writeFileSync, existsSync, readFileSync, } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { resolve, join } from "node:path";
+import { getDirectSessionsDir, getConfig, getRepoDirectAllowedCommands, } from "../config.js";
+import { guardPath } from "../security/pathGuard.js";
+import { PatchWardenError } from "../errors.js";
+import { PATCHWARDEN_VERSION, TOOL_SCHEMA_EPOCH } from "../version.js";
+import { getLastToolCatalogSnapshot } from "../tools/toolCatalog.js";
+// ── ID generation ──────────────────────────────────────────────────
+export function generateDirectSessionId() {
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace("T", "_")
+        .slice(0, 15);
+    const randomHex = randomBytes(16).toString("hex");
+    return `direct_${timestamp}_${randomHex}`;
+}
+// ── Directory management ───────────────────────────────────────────
+export function createDirectSessionDir(sessionId) {
+    const config = getConfig();
+    const sessionsDir = getDirectSessionsDir(config);
+    guardPath(sessionsDir, config.workspaceRoot, config.directSessionsDir);
+    mkdirSync(sessionsDir, { recursive: true });
+    const dir = resolve(sessionsDir, sessionId);
+    guardPath(dir, config.workspaceRoot, config.directSessionsDir);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function getDirectSessionDir(sessionId) {
+    const config = getConfig();
+    const sessionsDir = getDirectSessionsDir(config);
+    return resolve(sessionsDir, sessionId);
+}
+// ── CRUD ───────────────────────────────────────────────────────────
+export function createDirectSession(input) {
+    const config = getConfig();
+    const sessionId = generateDirectSessionId();
+    const dir = createDirectSessionDir(sessionId);
+    const toolManifest = getLastToolCatalogSnapshot()?.tool_manifest_sha256 ||
+        computeFallbackManifestHash(config);
+    const workspaceFingerprint = computeWorkspaceFingerprint(input.snapshot);
+    const allowedCommands = [
+        ...(config.directAllowedCommands || []),
+        ...getRepoDirectAllowedCommands(config, input.resolved_repo_path),
+    ];
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + config.directSessionTtlSeconds * 1000).toISOString();
+    const record = {
+        session_id: sessionId,
+        title: input.title || "",
+        repo_path: input.repo_path,
+        resolved_repo_path: input.resolved_repo_path,
+        created_at: now.toISOString(),
+        expires_at: expiresAt,
+        server_version: PATCHWARDEN_VERSION,
+        schema_epoch: TOOL_SCHEMA_EPOCH,
+        tool_manifest_sha256: toolManifest,
+        workspace_snapshot_before: input.snapshot,
+        workspace_fingerprint_before: workspaceFingerprint,
+        allowed_commands: allowedCommands,
+        operations: [],
+        verification_runs: [],
+        finalized: false,
+        finalized_at: null,
+        audited: false,
+        change_artifacts: null,
+    };
+    writeFileSync(join(dir, "session.json"), JSON.stringify(record, null, 2), "utf-8");
+    return record;
+}
+export function readDirectSession(sessionId) {
+    const config = getConfig();
+    const sessionsDir = getDirectSessionsDir(config);
+    const dir = resolve(sessionsDir, sessionId);
+    const file = join(dir, "session.json");
+    guardPath(file, config.workspaceRoot, config.directSessionsDir);
+    if (!existsSync(file)) {
+        throw new PatchWardenError("session_not_found", `Direct session "${sessionId}" not found.`, "Call create_direct_session first to get a valid session_id.", true, { session_id: sessionId });
+    }
+    return JSON.parse(readFileSync(file, "utf-8"));
+}
+export function updateDirectSession(sessionId, updates) {
+    const session = readDirectSession(sessionId);
+    const updated = { ...session, ...updates };
+    const dir = getDirectSessionDir(sessionId);
+    writeFileSync(join(dir, "session.json"), JSON.stringify(updated, null, 2), "utf-8");
+    return updated;
+}
+export function appendDirectSessionOperation(sessionId, operation) {
+    const session = readDirectSession(sessionId);
+    const operations = [...session.operations, operation];
+    return updateDirectSession(sessionId, { operations });
+}
+export function appendDirectSessionVerificationRun(sessionId, run) {
+    const session = readDirectSession(sessionId);
+    const verification_runs = [...session.verification_runs, run];
+    return updateDirectSession(sessionId, { verification_runs });
+}
+export function validateDirectSessionFreshness(sessionId) {
+    let session;
+    try {
+        session = readDirectSession(sessionId);
+    }
+    catch (e) {
+        return {
+            valid: false,
+            failure_reason: extractReason(e),
+            session: null,
+        };
+    }
+    if (new Date(session.expires_at) < new Date()) {
+        return { valid: false, failure_reason: "session_expired", session };
+    }
+    const currentManifest = getLastToolCatalogSnapshot()?.tool_manifest_sha256 ||
+        computeFallbackManifestHash(getConfig());
+    if (currentManifest !== session.tool_manifest_sha256) {
+        return {
+            valid: false,
+            failure_reason: "session_stale_config",
+            session,
+        };
+    }
+    return { valid: true, failure_reason: null, session };
+}
+// ── Finalization ───────────────────────────────────────────────────
+export function finalizeDirectSessionRecord(sessionId, afterSnapshot, changeArtifacts) {
+    const dir = getDirectSessionDir(sessionId);
+    // Write change artifacts to session directory
+    writeFileSync(join(dir, "changed-files.json"), JSON.stringify(changeArtifacts.changed_files, null, 2), "utf-8");
+    writeFileSync(join(dir, "diff.patch"), changeArtifacts.diff, "utf-8");
+    const summary = {
+        changed_files_total: changeArtifacts.changed_files.length,
+        additions: changeArtifacts.additions,
+        deletions: changeArtifacts.deletions,
+        patch_mode: changeArtifacts.patch_mode,
+        artifact_hygiene: changeArtifacts.artifact_hygiene,
+    };
+    writeFileSync(join(dir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
+    writeFileSync(join(dir, "summary.md"), formatSummaryMd(changeArtifacts), "utf-8");
+    return updateDirectSession(sessionId, {
+        finalized: true,
+        finalized_at: new Date().toISOString(),
+        change_artifacts: changeArtifacts,
+    });
+}
+// ── Helpers ────────────────────────────────────────────────────────
+export function computeWorkspaceFingerprint(snapshot) {
+    const fileHashes = Object.entries(snapshot.files)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, fp]) => `${path}:${fp.sha256}`)
+        .join("\n");
+    return createHash("sha256")
+        .update(`${snapshot.head || "null"}\n${snapshot.status}\n${fileHashes}`)
+        .digest("hex");
+}
+function computeFallbackManifestHash(config) {
+    return createHash("sha256")
+        .update(`${TOOL_SCHEMA_EPOCH}:${config.toolProfile || "full"}`)
+        .digest("hex");
+}
+function extractReason(error) {
+    if (error instanceof PatchWardenError)
+        return error.reason;
+    if (error instanceof Error)
+        return error.message.slice(0, 80);
+    return String(error).slice(0, 80);
+}
+function formatSummaryMd(artifacts) {
+    const lines = [
+        "# Direct Session Change Summary",
+        "",
+        `**Changed files:** ${artifacts.changed_files.length}`,
+        `**Additions:** ${artifacts.additions}`,
+        `**Deletions:** ${artifacts.deletions}`,
+        `**Patch mode:** ${artifacts.patch_mode}`,
+        "",
+        "## Artifact Hygiene",
+        "",
+        `- Source changes: ${artifacts.artifact_hygiene.counts.source_changes}`,
+        `- Tracked build artifacts: ${artifacts.artifact_hygiene.counts.tracked_build_artifacts}`,
+        `- Runtime generated files: ${artifacts.artifact_hygiene.counts.runtime_generated_files}`,
+        `- Suspicious changes: ${artifacts.artifact_hygiene.counts.suspicious_changes}`,
+        "",
+        "## Changed Files",
+        "",
+    ];
+    for (const file of artifacts.changed_files) {
+        lines.push(`- **${file.change}**: ${file.path}${file.old_path ? ` (from ${file.old_path})` : ""}`);
+    }
+    return lines.join("\n");
+}

package/dist/direct/directVerification.d.ts

@@ -0,0 +1,12 @@
+import type { DirectSessionVerificationRun } from "./directSessionStore.js";
+export interface RunDirectVerificationInput {
+    command: string;
+    resolvedRepoPath: string;
+    sessionId: string;
+    timeoutSeconds?: number;
+}
+export interface RunDirectVerificationResult {
+    run: DirectSessionVerificationRun;
+    log_path: string;
+}
+export declare function runDirectVerification(input: RunDirectVerificationInput): Promise<RunDirectVerificationResult>;

package/dist/direct/directVerification.js

@@ -0,0 +1,96 @@
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfig } from "../config.js";
+import { guardDirectCommand } from "../security/commandGuard.js";
+import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { runSimpleProcess } from "../runner/simpleProcess.js";
+import { getDirectSessionDir } from "./directSessionStore.js";
+const MAX_TAIL_CHARS = 10_000;
+const DEFAULT_TIMEOUT_SECONDS = 120;
+export async function runDirectVerification(input) {
+    const config = getConfig();
+    const allowedCommand = guardDirectCommand(input.command, config, input.resolvedRepoPath);
+    const timeoutSeconds = input.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const timeoutMs = timeoutSeconds * 1000;
+    // Parse command into command + args
+    const parts = parseCommand(allowedCommand);
+    if (!parts) {
+        throw new Error(`Failed to parse command: "${allowedCommand}"`);
+    }
+    const sessionDir = getDirectSessionDir(input.sessionId);
+    const logPath = join(sessionDir, "verification.log");
+    const startedAt = new Date().toISOString();
+    const result = await runSimpleProcess({
+        command: parts.command,
+        args: parts.args,
+        cwd: input.resolvedRepoPath,
+        timeoutMs,
+        stdoutPath: logPath,
+        stderrPath: logPath,
+    });
+    const finishedAt = new Date().toISOString();
+    // Redact and truncate output
+    const stdoutRedacted = redactSensitiveContent(result.stdout || "");
+    const stderrRedacted = redactSensitiveContent(result.stderr || "");
+    const stdoutTail = truncateTail(stdoutRedacted.content, MAX_TAIL_CHARS);
+    const stderrTail = truncateTail(stderrRedacted.content, MAX_TAIL_CHARS);
+    const passed = result.exitCode === 0 && !result.timedOut;
+    const run = {
+        command: allowedCommand,
+        exit_code: result.exitCode,
+        passed,
+        timed_out: result.timedOut,
+        stdout_tail: stdoutTail,
+        stderr_tail: stderrTail,
+        started_at: startedAt,
+        finished_at: finishedAt,
+        log_path: logPath,
+    };
+    // Write verification.json
+    const verificationJson = {
+        command: allowedCommand,
+        exit_code: result.exitCode,
+        passed,
+        timed_out: result.timedOut,
+        started_at: startedAt,
+        finished_at: finishedAt,
+        duration_ms: new Date(finishedAt).getTime() - new Date(startedAt).getTime(),
+        stdout_truncated: result.stdoutTruncated,
+        stderr_truncated: result.stderrTruncated,
+        redacted: stdoutRedacted.redacted || stderrRedacted.redacted,
+        redaction_categories: [
+            ...new Set([
+                ...stdoutRedacted.redaction_categories,
+                ...stderrRedacted.redaction_categories,
+            ]),
+        ],
+        spawn_error: result.spawnError,
+    };
+    writeFileSync(join(sessionDir, "verification.json"), JSON.stringify(verificationJson, null, 2), "utf-8");
+    return { run, log_path: logPath };
+}
+// ── Helpers ────────────────────────────────────────────────────────
+function parseCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return null;
+    // Simple split by spaces - sufficient for allowlisted commands like "npm test"
+    const parts = trimmed.split(/\s+/);
+    // On Windows, npm/npx are batch files (.cmd) and spawn() cannot find them
+    // without shell resolution. Wrap with cmd.exe /c for those commands.
+    if (process.platform === "win32" && (parts[0] === "npm" || parts[0] === "npx")) {
+        return {
+            command: "cmd",
+            args: ["/c", ...parts],
+        };
+    }
+    return {
+        command: parts[0],
+        args: parts.slice(1),
+    };
+}
+function truncateTail(content, maxChars) {
+    if (content.length <= maxChars)
+        return content;
+    return "...(truncated)\n" + content.slice(content.length - maxChars);
+}