patchwarden 0.4.0 → 0.6.1

package/dist/tools/createTask.js

@@ -1,9 +1,15 @@
-import { mkdirSync, writeFileSync, existsSync, statSync } from "node:fs";
-import { resolve, join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { mkdirSync, writeFileSync, existsSync, statSync, readFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { resolve, join } from "node:path";
 import { getTasksDir, getPlansDir, getConfig } from "../config.js";
 import { guardPath, guardWorkspacePath, guardReadPath } from "../security/pathGuard.js";
 import { guardTestCommand } from "../security/commandGuard.js";
+import { guardRuntimeSelfModification } from "../security/runtimeGuard.js";
+import { guardPlanContent } from "../security/planGuard.js";
+import { assessRisk } from "../security/riskEngine.js";
+import { createAssessment, readAssessment, validateAssessmentFreshness, generateAssessmentId, createAssessmentDir, } from "../assessments/assessmentStore.js";
+import { runAgentAssessment } from "../assessments/agentAssessor.js";
+import { captureRepoSnapshot } from "../runner/changeCapture.js";
 import { writeTaskProgress } from "../taskProgress.js";
 import { PatchWardenError } from "../errors.js";
 import { savePlan } from "./savePlan.js";
@@ -15,19 +21,34 @@ export function createTask(input) {
     const config = getConfig();
     const tasksDir = getTasksDir(config);
     const plansDir = getPlansDir(config);
+    const executionMode = input.execution_mode || "execute";
+    // ── assessment_id execute mode: load record and override params ──
+    let assessmentRecord = null;
+    let effectiveInput = input;
+    if (executionMode === "execute" && input.assessment_id) {
+        assessmentRecord = readAssessment(input.assessment_id);
+        // Parameter mismatch check: if ChatGPT passes params that differ from the assessment, reject
+        effectiveInput = mergeAssessmentIntoInput(input, assessmentRecord);
+    }
+    // ── Validate required fields ──
+    // agent and repo_path are required unless assessment_id fills them.
+    // assess_only always requires them because the risk engine needs to check them.
+    if (!effectiveInput.agent || effectiveInput.agent.trim() === "") {
+        throw new PatchWardenError("agent_required", "create_task requires an agent name.", "Pass a configured agent name, or use assessment_id from a prior assess_only call.");
+    }
     const planSources = [
-        input.plan_id?.trim() ? "plan_id" : "",
-        input.inline_plan?.trim() ? "inline_plan" : "",
-        input.template ? "template" : "",
+        effectiveInput.plan_id?.trim() ? "plan_id" : "",
+        effectiveInput.inline_plan?.trim() ? "inline_plan" : "",
+        effectiveInput.template ? "template" : "",
     ].filter(Boolean);
     if (planSources.length !== 1) {
         throw new PatchWardenError("invalid_plan_source", "create_task requires exactly one of plan_id, inline_plan, or template.", "Use an existing plan_id, pass inline_plan text, or choose one built-in template.");
     }
-    if (input.template && !TASK_TEMPLATE_NAMES.includes(input.template)) {
-        throw new PatchWardenError("invalid_task_template", `Unknown task template "${input.template}".`, `Use one of: ${TASK_TEMPLATE_NAMES.join(", ")}.`);
+    if (effectiveInput.template && !TASK_TEMPLATE_NAMES.includes(effectiveInput.template)) {
+        throw new PatchWardenError("invalid_task_template", `Unknown task template "${effectiveInput.template}".`, `Use one of: ${TASK_TEMPLATE_NAMES.join(", ")}.`);
     }
     // Resolve repo alias if configured
-    let resolvedRepoPath = input.repo_path?.trim() || "";
+    let resolvedRepoPath = effectiveInput.repo_path?.trim() || "";
     const aliases = config.repoAliases;
     if (aliases && resolvedRepoPath && aliases[resolvedRepoPath]) {
         resolvedRepoPath = aliases[resolvedRepoPath];
@@ -36,8 +57,8 @@ export function createTask(input) {
         throw new PatchWardenError("repo_path_required", "create_task requires an explicit repo_path; PatchWarden will not default to workspaceRoot.", 'Pass a repository path inside workspaceRoot, for example repo_path: "my-project".', true, { operation: "create_task", safe_alternative: "Pass an existing repository directory under workspaceRoot." });
     }
     // Validate agent
-    if (!config.agents[input.agent]) {
-        throw new PatchWardenError("agent_not_configured", `Unknown agent "${input.agent}". Available: ${Object.keys(config.agents).join(", ")}`, "Call list_agents and use an available configured agent.");
+    if (!config.agents[effectiveInput.agent]) {
+        throw new PatchWardenError("agent_not_configured", `Unknown agent "${effectiveInput.agent}". Available: ${Object.keys(config.agents).join(", ")}`, "Call list_agents and use an available configured agent.");
     }
     // Validate repo_path is within workspace
     const safeRepoPath = guardWorkspacePath(resolvedRepoPath, config.workspaceRoot);
@@ -49,93 +70,273 @@ export function createTask(input) {
     }
     // Runtime self-modification protection: refuse to modify the active
     // PatchWarden runtime directory or its critical subdirectories.
-    const runtimeRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-    const criticalDirs = ["dist", "src", "scripts", "release"];
-    if (safeRepoPath === runtimeRoot || safeRepoPath.startsWith(runtimeRoot + resolve("/")[0])) {
-        const isCritical = criticalDirs.some((dir) => safeRepoPath === join(runtimeRoot, dir) ||
-            safeRepoPath.startsWith(join(runtimeRoot, dir) + resolve("/")[0]));
-        if (safeRepoPath === runtimeRoot || isCritical) {
-            throw new PatchWardenError("runtime_self_modification_blocked", `repo_path "${resolvedRepoPath}" points to the active PatchWarden runtime or its critical subdirectories.`, "Use a dev copy or git worktree for PatchWarden development. The running MCP server must not be modified by a task.", true, {
-                operation: "create_task",
-                path: resolvedRepoPath,
-                resolved_repo_path: safeRepoPath,
-                runtime_root: runtimeRoot,
-                safe_alternative: "Clone or copy PatchWarden to a separate directory for development tasks.",
-            });
-        }
-    }
+    guardRuntimeSelfModification(safeRepoPath);
     // Validate test command — must be in allowlist, no swallowing
     let testCmd = "";
-    if (input.test_command && input.test_command.trim() !== "") {
-        testCmd = guardTestCommand(input.test_command, config);
+    if (effectiveInput.test_command && effectiveInput.test_command.trim() !== "") {
+        testCmd = guardTestCommand(effectiveInput.test_command, config, safeRepoPath);
         // guardTestCommand throws if not in allowedTestCommands
     }
-    if (input.verify_commands !== undefined && !Array.isArray(input.verify_commands)) {
+    if (effectiveInput.verify_commands !== undefined && !Array.isArray(effectiveInput.verify_commands)) {
         throw new PatchWardenError("invalid_verify_commands", "verify_commands must be an array of allow-listed command strings.", "Pass an array such as [\"npm test\", \"npm run build\"].");
     }
-    if ((input.verify_commands?.length || 0) > 20) {
+    if ((effectiveInput.verify_commands?.length || 0) > 20) {
         throw new PatchWardenError("invalid_verify_commands", "verify_commands cannot contain more than 20 commands.", "Keep verification focused and use no more than 20 allow-listed commands.");
     }
     const verifyCommands = [...new Set([
-            ...(input.verify_commands || []).map((command) => guardTestCommand(command, config)),
+            ...(effectiveInput.verify_commands || []).map((command) => guardTestCommand(command, config, safeRepoPath)),
             ...(testCmd ? [testCmd] : []),
         ])];
-    const timeoutSeconds = input.timeout_seconds ?? config.defaultTaskTimeoutSeconds;
+    const timeoutSeconds = effectiveInput.timeout_seconds ?? config.defaultTaskTimeoutSeconds;
     if (!Number.isInteger(timeoutSeconds) || timeoutSeconds <= 0) {
         throw new PatchWardenError("invalid_timeout", "timeout_seconds must be a positive integer", `Use a whole number from 1 to ${config.maxTaskTimeoutSeconds}.`);
     }
     if (timeoutSeconds > config.maxTaskTimeoutSeconds) {
         throw new PatchWardenError("invalid_timeout", `timeout_seconds cannot exceed configured maximum ${config.maxTaskTimeoutSeconds}`, `Use a value no greater than ${config.maxTaskTimeoutSeconds}.`);
     }
-    let planId = input.plan_id?.trim() || "";
+    let planId = effectiveInput.plan_id?.trim() || "";
     let planSource = "saved";
     let changePolicy = "repo_scoped_changes";
+    let planContentForHash = null;
+    // ── assess_only: check plan content WITHOUT saving first ──
+    // This catches guardPlanContent violations as hard rule hits instead of throwing.
+    if (executionMode === "assess_only") {
+        let assessPlanContent = "";
+        let assessPlanTitle = effectiveInput.plan_title?.trim() || "Assessment plan";
+        if (planId) {
+            const planFile = join(resolve(plansDir, planId), "plan.md");
+            guardReadPath(planFile, config.workspaceRoot, config.plansDir);
+            if (!existsSync(planFile)) {
+                throw new PatchWardenError("plan_not_found", `Plan "${planId}" not found.`, "Call save_plan first, or pass inline_plan/template directly to create_task.");
+            }
+            assessPlanContent = readFileSync(planFile, "utf-8");
+        }
+        else if (effectiveInput.inline_plan?.trim()) {
+            assessPlanContent = effectiveInput.inline_plan.trim();
+        }
+        else if (effectiveInput.template) {
+            const expanded = expandTaskTemplate({
+                template: effectiveInput.template,
+                goal: effectiveInput.goal || "",
+                source_task_id: effectiveInput.source_task_id,
+                verify_commands: verifyCommands,
+            });
+            assessPlanContent = expanded.content;
+            assessPlanTitle = expanded.title;
+            changePolicy = expanded.change_policy;
+        }
+        // Run risk engine WITHOUT saving the plan
+        let planBlocked = false;
+        let planBlockReason = "";
+        try {
+            guardPlanContent(assessPlanTitle, assessPlanContent);
+        }
+        catch (e) {
+            planBlocked = true;
+            planBlockReason = e instanceof PatchWardenError ? e.reason : "plan_content_blocked";
+        }
+        const snapshot = captureRepoSnapshot(safeRepoPath);
+        const snapshotTruncated = snapshot.warnings.some((w) => w.includes("snapshot limited"));
+        let riskResult;
+        if (planBlocked) {
+            riskResult = {
+                risk_level: "high",
+                decision: "blocked",
+                reason_codes: [],
+                risk_hints: [],
+                hard_rule_hits: [planBlockReason],
+            };
+        }
+        else {
+            riskResult = assessRisk({
+                repoPath: resolvedRepoPath,
+                resolvedRepoPath: safeRepoPath,
+                planContent: assessPlanContent,
+                planTitle: assessPlanTitle,
+                testCommand: testCmd,
+                verifyCommands: verifyCommands,
+                template: effectiveInput.template,
+                goal: effectiveInput.goal,
+                agent: effectiveInput.agent,
+                config,
+                snapshotTruncated,
+            });
+        }
+        // Save the plan now that risk assessment is done (for allow/needs_confirm)
+        if (!planBlocked) {
+            if (effectiveInput.inline_plan?.trim()) {
+                const saved = savePlan({
+                    title: effectiveInput.plan_title?.trim() || "Inline task plan",
+                    content: effectiveInput.inline_plan.trim(),
+                });
+                planId = saved.plan_id;
+                planSource = "inline";
+                planContentForHash = readFileSync(saved.path, "utf-8");
+            }
+            else if (effectiveInput.template) {
+                const saved = savePlan({ title: assessPlanTitle, content: assessPlanContent });
+                planId = saved.plan_id;
+                planSource = "template";
+                planContentForHash = readFileSync(saved.path, "utf-8");
+            }
+            else {
+                planContentForHash = assessPlanContent;
+            }
+        }
+        // ── Agent assessment: only when enabled AND deterministic decision is "allow" ──
+        let finalRiskResult = riskResult;
+        let agentAssessmentSummary = null;
+        let preGeneratedAssessmentId;
+        let preGeneratedAssessmentDir;
+        if (config.enableAgentAssessment === true && riskResult.decision === "allow" && !planBlocked) {
+            preGeneratedAssessmentId = generateAssessmentId();
+            preGeneratedAssessmentDir = createAssessmentDir(preGeneratedAssessmentId);
+            const assessorAgentName = config.agentAssessmentAgentName || effectiveInput.agent;
+            agentAssessmentSummary = runAgentAssessment({
+                assessmentId: preGeneratedAssessmentId,
+                assessmentDir: preGeneratedAssessmentDir,
+                agentName: assessorAgentName,
+                repoPath: safeRepoPath,
+                workspaceRoot: config.workspaceRoot,
+                goal: effectiveInput.goal || "",
+                planContent: assessPlanContent,
+                timeoutSeconds: config.agentAssessmentTimeoutSeconds || 120,
+                maxOutputBytes: config.agentAssessmentMaxOutputBytes || 524288,
+                config,
+            });
+            finalRiskResult = {
+                risk_level: agentAssessmentSummary.merged_risk,
+                decision: agentAssessmentSummary.merged_decision,
+                reason_codes: [...riskResult.reason_codes, ...agentAssessmentSummary.merged_reason_codes],
+                risk_hints: riskResult.risk_hints,
+                hard_rule_hits: riskResult.hard_rule_hits,
+            };
+        }
+        const record = createAssessment({
+            decision: finalRiskResult.decision,
+            risk_level: finalRiskResult.risk_level,
+            risk_hints: finalRiskResult.risk_hints,
+            hard_rule_hits: finalRiskResult.hard_rule_hits,
+            reason_codes: finalRiskResult.reason_codes,
+            repo_path: resolvedRepoPath,
+            resolved_repo_path: safeRepoPath,
+            plan_id: planId || null,
+            plan_content: planContentForHash,
+            template: effectiveInput.template || null,
+            goal: effectiveInput.goal || null,
+            test_command: testCmd || null,
+            verify_commands: verifyCommands,
+            agent: effectiveInput.agent,
+            timeout_seconds: timeoutSeconds,
+            change_policy: changePolicy,
+            snapshot,
+            ...(preGeneratedAssessmentId ? { assessment_id: preGeneratedAssessmentId } : {}),
+            ...(preGeneratedAssessmentDir ? { assessment_dir: preGeneratedAssessmentDir } : {}),
+            agent_assessment_summary: agentAssessmentSummary,
+        });
+        const nextAction = record.decision === "allow"
+            ? "Call the returned next_tool_call exactly as provided; do not resend goal, plan, repository, agent, or verification arguments."
+            : record.decision === "needs_confirm"
+                ? `Assessment requires local confirmation. Run patchwarden-confirm ${record.assessment_id} locally, then call the returned next_tool_call exactly as provided.`
+                : `Assessment blocked. Fix the reported hard rule hit and re-run assess_only.`;
+        const nextToolCall = record.decision === "blocked" ? undefined : {
+            name: "create_task",
+            arguments: {
+                execution_mode: "execute",
+                assessment_id: record.assessment_id,
+            },
+        };
+        return {
+            assessment_id: record.assessment_id,
+            assessment_short_id: record.assessment_short_id,
+            decision: record.decision,
+            risk_level: record.risk_level,
+            risk_hints: record.risk_hints,
+            hard_rule_hits: record.hard_rule_hits,
+            reason_codes: record.reason_codes,
+            expires_at: record.expires_at,
+            requires_confirm: record.requires_confirm,
+            workspace_snapshot_summary: record.workspace_snapshot_summary,
+            next_action: nextAction,
+            ...(nextToolCall ? { next_tool_call: nextToolCall } : {}),
+            local_confirmation: {
+                required: record.requires_confirm,
+                command: record.requires_confirm ? "patchwarden-confirm" : null,
+                arguments: record.requires_confirm ? [record.assessment_id] : [],
+            },
+            ...(finalRiskResult.hard_rule_hits.length > 0
+                ? { suggestion: `Hard rule hit: ${finalRiskResult.hard_rule_hits.join(", ")}` }
+                : {}),
+            ...(agentAssessmentSummary ? {
+                agent_assessment: {
+                    status: agentAssessmentSummary.status,
+                    merged_risk: agentAssessmentSummary.merged_risk,
+                    merged_decision: agentAssessmentSummary.merged_decision,
+                    confidence: agentAssessmentSummary.output?.confidence ?? null,
+                    notes: agentAssessmentSummary.output?.notes ?? null,
+                    read_only_violation: agentAssessmentSummary.read_only_violation,
+                    stdout_truncated: agentAssessmentSummary.stdout_truncated,
+                    stderr_truncated: agentAssessmentSummary.stderr_truncated,
+                }
+            } : {}),
+        };
+    }
+    // ── execute mode: resolve plan normally ──
     if (planId) {
         const planFile = join(resolve(plansDir, planId), "plan.md");
         guardReadPath(planFile, config.workspaceRoot, config.plansDir);
         if (!existsSync(planFile)) {
             throw new PatchWardenError("plan_not_found", `Plan "${planId}" not found.`, "Call save_plan first, or pass inline_plan/template directly to create_task.");
         }
+        planContentForHash = readFileSync(planFile, "utf-8");
     }
-    else if (input.inline_plan?.trim()) {
+    else if (effectiveInput.inline_plan?.trim()) {
         const saved = savePlan({
-            title: input.plan_title?.trim() || "Inline task plan",
-            content: input.inline_plan.trim(),
+            title: effectiveInput.plan_title?.trim() || "Inline task plan",
+            content: effectiveInput.inline_plan.trim(),
         });
         planId = saved.plan_id;
         planSource = "inline";
+        planContentForHash = readFileSync(saved.path, "utf-8");
     }
     else {
         const expanded = expandTaskTemplate({
-            template: input.template,
-            goal: input.goal || "",
-            source_task_id: input.source_task_id,
+            template: effectiveInput.template,
+            goal: effectiveInput.goal || "",
+            source_task_id: effectiveInput.source_task_id,
             verify_commands: verifyCommands,
         });
         const saved = savePlan({ title: expanded.title, content: expanded.content });
         planId = saved.plan_id;
         planSource = "template";
         changePolicy = expanded.change_policy;
+        planContentForHash = readFileSync(saved.path, "utf-8");
     }
-    const taskId = `task_${Date.now()}_${planId.replace(/^plan_/, "")}`;
-    const taskDir = resolve(tasksDir, taskId);
-    guardPath(taskDir, config.workspaceRoot, config.tasksDir);
-    mkdirSync(taskDir, { recursive: true });
+    // ── execute mode with assessment_id: validate freshness ──
+    if (assessmentRecord) {
+        const snapshot = captureRepoSnapshot(safeRepoPath);
+        const validation = validateAssessmentFreshness(input.assessment_id, snapshot);
+        if (!validation.valid) {
+            throw new PatchWardenError(validation.failure_reason || "assessment_validation_failed", `Assessment "${input.assessment_id}" is no longer valid: ${validation.failure_reason}`, "Re-run create_task with execution_mode=assess_only to get a fresh assessment_id.", true, { assessment_id: input.assessment_id, failure_reason: validation.failure_reason });
+        }
+    }
+    const { taskId, taskDir } = createTaskDirectory(tasksDir, config.workspaceRoot, config.tasksDir);
     const status = "pending";
     const statusFile = join(taskDir, "status.json");
     const statusData = {
         task_id: taskId,
         plan_id: planId,
         plan_source: planSource,
-        template: input.template || null,
+        template: effectiveInput.template || null,
         change_policy: changePolicy,
-        agent: input.agent,
+        agent: effectiveInput.agent,
         workspace_root: resolve(config.workspaceRoot),
         repo_path: resolvedRepoPath,
         resolved_repo_path: safeRepoPath,
         test_command: testCmd,
         verify_commands: verifyCommands,
         timeout_seconds: timeoutSeconds,
+        assessment_id: assessmentRecord?.assessment_id || input.assessment_id || null,
         status,
         phase: "queued",
         created_at: new Date().toISOString(),
@@ -163,14 +364,14 @@ export function createTask(input) {
     return {
         task_id: taskId,
         plan_id: planId,
-        agent: input.agent,
+        agent: effectiveInput.agent,
         status,
         timeout_seconds: timeoutSeconds,
         continuation_required: watcher.available && hasWaitForTask,
         next_action: !watcher.available ? nextActionBlocked : hasWaitForTask ? nextActionWait : nextActionPoll,
         path: taskDir,
         plan_source: planSource,
-        ...(input.template ? { template: input.template } : {}),
+        ...(effectiveInput.template ? { template: effectiveInput.template } : {}),
         change_policy: changePolicy,
         server_version: PATCHWARDEN_VERSION,
         tool_profile: catalog?.tool_profile || resolveToolProfile(config.toolProfile),
@@ -186,3 +387,53 @@ export function createTask(input) {
                 : { name: "get_task_status", arguments: { task_id: taskId } },
     };
 }
+function mergeAssessmentIntoInput(input, record) {
+    // Use plan_id from the assessment record (the plan was already saved during assess_only).
+    // Do NOT set template/inline_plan alongside plan_id — createTask requires exactly one plan source.
+    const merged = {
+        ...input,
+        plan_id: record.plan_id || input.plan_id,
+        template: undefined,
+        inline_plan: undefined,
+        goal: record.goal || input.goal,
+        agent: record.agent,
+        repo_path: record.repo_path,
+        test_command: record.test_command || undefined,
+        verify_commands: record.verify_commands || input.verify_commands,
+        timeout_seconds: record.timeout_seconds || input.timeout_seconds,
+    };
+    // Parameter mismatch check: if caller passed explicit params that differ from assessment
+    if (input.template && record.template && input.template !== record.template) {
+        throw new PatchWardenError("assessment_parameter_mismatch", `template mismatch: caller passed "${input.template}" but assessment has "${record.template}".`, "Do not override assessment-locked parameters. Use the same assessment_id as-is.", true, { field: "template", assessment_value: record.template, caller_value: input.template });
+    }
+    if (input.goal && record.goal && input.goal !== record.goal) {
+        throw new PatchWardenError("assessment_parameter_mismatch", `goal mismatch: caller passed a different goal than the assessment.`, "Do not override assessment-locked parameters. Use the same assessment_id as-is.", true, { field: "goal" });
+    }
+    if (input.repo_path && record.repo_path && input.repo_path !== record.repo_path) {
+        throw new PatchWardenError("assessment_parameter_mismatch", `repo_path mismatch: caller passed "${input.repo_path}" but assessment has "${record.repo_path}".`, "Do not override assessment-locked parameters. Use the same assessment_id as-is.", true, { field: "repo_path", assessment_value: record.repo_path, caller_value: input.repo_path });
+    }
+    return merged;
+}
+function createTaskDirectory(tasksDir, workspaceRoot, configuredTasksDir) {
+    guardPath(tasksDir, workspaceRoot, configuredTasksDir);
+    mkdirSync(tasksDir, { recursive: true });
+    for (let attempt = 0; attempt < 10; attempt += 1) {
+        const timestamp = new Date().toISOString()
+            .replace(/[-:]/g, "")
+            .replace("T", "_")
+            .slice(0, 15);
+        const taskId = `task_${timestamp}_${randomBytes(3).toString("hex")}`;
+        const taskDir = resolve(tasksDir, taskId);
+        guardPath(taskDir, workspaceRoot, configuredTasksDir);
+        try {
+            mkdirSync(taskDir, { recursive: false });
+            return { taskId, taskDir };
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                continue;
+            throw error;
+        }
+    }
+    throw new PatchWardenError("task_id_generation_failed", "Could not allocate a unique short task ID.", "Retry create_task; no task directory was created.");
+}

package/dist/tools/finalizeDirectSession.d.ts

@@ -0,0 +1,19 @@
+import { type ClassifiedChange } from "../runner/changeCapture.js";
+export interface FinalizeDirectSessionInput {
+    session_id: string;
+}
+export interface FinalizeDirectSessionOutput {
+    session_id: string;
+    changed_files_total: number;
+    source_changes: ClassifiedChange[];
+    tracked_build_artifacts: ClassifiedChange[];
+    runtime_generated_files: ClassifiedChange[];
+    suspicious_changes: ClassifiedChange[];
+    out_of_scope_changes: ClassifiedChange[];
+    verification_summary: Record<string, "passed" | "failed">;
+    diff_path: string;
+    summary_path: string;
+    finalized: boolean;
+    next_action: string;
+}
+export declare function finalizeDirectSession(input: FinalizeDirectSessionInput): FinalizeDirectSessionOutput;

package/dist/tools/finalizeDirectSession.js

@@ -0,0 +1,84 @@
+import { join, resolve, relative, isAbsolute } from "node:path";
+import { readDirectSession, finalizeDirectSessionRecord, getDirectSessionDir, } from "../direct/directSessionStore.js";
+import { guardDirectSessionActive } from "../direct/directGuards.js";
+import { captureRepoSnapshot, buildChangeArtifacts, } from "../runner/changeCapture.js";
+// ── Main function ──────────────────────────────────────────────────
+export function finalizeDirectSession(input) {
+    const { session_id } = input;
+    // 1. Read session and guard active (not expired, not finalized)
+    const session = readDirectSession(session_id);
+    guardDirectSessionActive(session);
+    // 2. Capture after snapshot
+    const afterSnapshot = captureRepoSnapshot(session.resolved_repo_path);
+    // 3. Build change artifacts from before/after snapshots
+    const changeArtifacts = buildChangeArtifacts(session.resolved_repo_path, session.workspace_snapshot_before, afterSnapshot);
+    // 4. Finalize session record — writes changed-files.json, diff.patch,
+    //    summary.json, summary.md and marks the session as finalized.
+    finalizeDirectSessionRecord(session_id, afterSnapshot, changeArtifacts);
+    // 5. Build verification summary from session.verification_runs
+    const verification_summary = {};
+    for (const run of session.verification_runs) {
+        verification_summary[run.command] = run.passed ? "passed" : "failed";
+    }
+    // 6. Identify out-of-scope changes (paths outside resolved_repo_path)
+    const out_of_scope_changes = findOutOfScopeChanges(changeArtifacts, session.resolved_repo_path);
+    // 7. Build compact summary with categorized changes
+    const sessionDir = getDirectSessionDir(session_id);
+    return {
+        session_id,
+        changed_files_total: changeArtifacts.changed_files.length,
+        source_changes: changeArtifacts.artifact_hygiene.source_changes,
+        tracked_build_artifacts: changeArtifacts.artifact_hygiene.tracked_build_artifacts,
+        runtime_generated_files: changeArtifacts.artifact_hygiene.runtime_generated_files,
+        suspicious_changes: changeArtifacts.artifact_hygiene.suspicious_changes,
+        out_of_scope_changes,
+        verification_summary,
+        diff_path: join(sessionDir, "diff.patch"),
+        summary_path: join(sessionDir, "summary.md"),
+        finalized: true,
+        next_action: "Call audit_session to independently review the changes.",
+    };
+}
+// ── Helpers ────────────────────────────────────────────────────────
+/**
+ * Filter changeArtifacts.changed_files for paths that resolve outside the
+ * session's resolved_repo_path and map them to ClassifiedChange format.
+ */
+function findOutOfScopeChanges(artifacts, resolvedRepoPath) {
+    const normalizedRepo = resolve(resolvedRepoPath);
+    return artifacts.changed_files
+        .filter((file) => {
+        const fullPath = resolve(normalizedRepo, file.path);
+        const rel = relative(normalizedRepo, fullPath);
+        return isAbsolute(rel) || rel.startsWith("..");
+    })
+        .map((file) => toClassifiedChange(file));
+}
+/**
+ * Map a ChangedFile to the ClassifiedChange format by adding a reason string.
+ */
+function toClassifiedChange(file) {
+    return {
+        path: file.path,
+        change: file.change,
+        tracked: file.tracked,
+        ignored: file.ignored,
+        kind: file.kind,
+        reason: classificationReason(file),
+    };
+}
+/**
+ * Produce a human-readable reason for a changed file classification.
+ * Mirrors the logic in changeCapture.ts classifyArtifactHygiene.
+ */
+function classificationReason(change) {
+    if (change.ignored)
+        return "untracked path is ignored by repository Git rules";
+    if (change.kind === "build_artifact" && change.tracked)
+        return "artifact-like path is tracked by Git and requires review";
+    if (change.kind === "build_artifact")
+        return "artifact-like path is not ignored and requires review";
+    if (change.kind === "runtime_generated")
+        return "runtime-generated path is not ignored and requires review";
+    return change.tracked ? "tracked source change" : "untracked source change";
+}

package/dist/tools/getTaskSummary.d.ts

@@ -62,5 +62,55 @@ export interface TaskSummaryOutput {
     watcher: unknown;
     pending_reason: string | null;
     execution_blocked: boolean;
+    artifact_hygiene: Record<string, unknown>;
 }
+export interface CompactTaskSummaryOutput {
+    view: "compact";
+    task_id: string;
+    status: string;
+    terminal: boolean;
+    acceptance_status: TaskSummaryOutput["acceptance_status"];
+    phase: string;
+    repo_path: string;
+    changed_files_total: number;
+    out_of_scope_changes_total: number;
+    artifact_hygiene: {
+        counts: Record<string, number>;
+        source_changes: unknown[];
+        tracked_build_artifacts: unknown[];
+        ignored_untracked_artifacts: unknown[];
+        runtime_generated_files: unknown[];
+        suspicious_changes: unknown[];
+        max_items: number;
+        truncated: boolean;
+    };
+    release_artifacts_count: number;
+    release_artifact_paths: string[];
+    artifact_status: string | null;
+    verification_summary: TaskSummaryOutput["verification_summary"];
+    summary: string;
+    warnings: string[];
+    errors: string[];
+    failure_reason: string | null;
+    failed_command: string | null;
+    suggested_next_action: string;
+    execution_blocked: boolean;
+    pending_reason: string | null;
+    redacted: boolean;
+    redaction_categories: string[];
+}
+export interface GetTaskSummaryOptions {
+    view?: "compact" | "standard";
+    max_items?: number;
+}
+export type TaskSummaryResult = TaskSummaryOutput | CompactTaskSummaryOutput;
 export declare function getTaskSummary(taskId: string): TaskSummaryOutput;
+export declare function getTaskSummary(taskId: string, options: {
+    view: "compact";
+    max_items?: number;
+}): CompactTaskSummaryOutput;
+export declare function getTaskSummary(taskId: string, options: {
+    view?: "standard";
+    max_items?: number;
+}): TaskSummaryOutput;
+export declare function getTaskSummary(taskId: string, options: GetTaskSummaryOptions): TaskSummaryResult;