@kenkaiiii/ggcoder 4.3.211 → 4.3.213

package/dist/tools/goals.js

@@ -1,8 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { log } from "../core/logger.js";
-import { canCompleteGoalRun, decideGoalNextAction } from "../core/goal-controller.js";
-import { appendGoalDecision, appendGoalEvidence, createGoalEvidence, formatGoalBlockingPrerequisiteList, formatGoalBlockingPrerequisites, getActiveGoalRun, getGoalRun, goalHasBlockingPrerequisites, loadGoalRuns, upsertGoalRun, updateGoalTask, } from "../core/goal-store.js";
+import { canCompleteGoalRun, decideGoalNextAction, hasFreshGoalCompletionAudit, } from "../core/goal-controller.js";
+import { runGoalPrerequisiteCheckCommand } from "../core/goal-prerequisites.js";
+import { appendGoalBlockers, appendGoalDecision, appendGoalEvidence, createGoalEvidence, formatGoalBlockingPrerequisiteList, formatGoalBlockingPrerequisites, getActiveGoalRun, getGoalRun, goalHasBlockingPrerequisites, loadGoalRuns, upsertGoalRun, updateGoalTask, } from "../core/goal-store.js";
+import { referencesRequiringAcknowledgement } from "../core/goal-references.js";
+import { getActiveGoalMode } from "../core/runtime-mode.js";
 const PrerequisiteInput = z.object({
     id: z.string().optional().describe("Stable prerequisite id"),
     label: z.string().describe("Human-readable prerequisite label"),
@@ -51,7 +54,9 @@ const GoalsParams = z.object({
         "prerequisite",
         "task",
         "evidence",
+        "evidence_plan",
         "verify",
+        "audit",
         "status",
         "pause",
         "resume",
@@ -81,6 +86,11 @@ const GoalsParams = z.object({
         .array(EvidencePlanInput)
         .optional()
         .describe("Planned proof paths for end-to-end verification"),
+    evidence_plan_item_id: z.string().optional().describe("Evidence-plan item id to update"),
+    evidence_plan_status: z
+        .enum(["planned", "ready", "blocked"])
+        .optional()
+        .describe("Updated evidence-plan item status"),
     verifier_command: z.string().optional().describe("Command that verifies the goal end-to-end"),
     verifier_description: z.string().optional().describe("Natural-language verifier description"),
     task_id: z.string().optional().describe("Goal task id to update"),
@@ -116,6 +126,40 @@ function asPrerequisiteStatus(value) {
         return value;
     return "unknown";
 }
+function requiresPrerequisiteCheck(status, evidence) {
+    return status === "unknown" || (status === "met" && !evidence?.trim());
+}
+function uncheckedPrerequisiteInstructions(label) {
+    return `Check ${label} locally and record non-secret evidence before workers can start.`;
+}
+async function normalizePrerequisiteInput(cwd, item) {
+    const requestedStatus = asPrerequisiteStatus(item.status);
+    const id = item.id ?? randomUUID();
+    if (item.check_command && requiresPrerequisiteCheck(requestedStatus, item.evidence)) {
+        const result = await runGoalPrerequisiteCheckCommand({ cwd, command: item.check_command });
+        return {
+            id,
+            label: item.label,
+            status: result.status,
+            checkCommand: item.check_command,
+            evidence: result.evidence,
+            ...(result.status === "missing" || item.instructions
+                ? { instructions: item.instructions ?? `Make \`${item.check_command}\` pass locally.` }
+                : {}),
+        };
+    }
+    return {
+        id,
+        label: item.label,
+        status: requestedStatus,
+        ...(item.check_command ? { checkCommand: item.check_command } : {}),
+        ...(item.instructions ? { instructions: item.instructions } : {}),
+        ...(item.evidence ? { evidence: item.evidence } : {}),
+        ...(requiresPrerequisiteCheck(requestedStatus, item.evidence) && !item.instructions
+            ? { instructions: uncheckedPrerequisiteInstructions(item.label) }
+            : {}),
+    };
+}
 function asTaskStatus(value) {
     if (value === "pending" ||
         value === "running" ||
@@ -137,6 +181,11 @@ function asEvidenceKind(value) {
     }
     return "summary";
 }
+function asEvidencePlanStatus(value) {
+    if (value === "ready" || value === "blocked" || value === "planned")
+        return value;
+    return "planned";
+}
 function asEvidenceMechanism(value) {
     if (value === "command" ||
         value === "test" ||
@@ -159,6 +208,12 @@ function asVerificationStatus(value) {
         return value;
     return "unknown";
 }
+function formatRunReferences(run) {
+    if (!run.references?.length)
+        return "";
+    const lines = run.references.map((reference) => `- ${reference.id}: ${reference.kind}; ${reference.label}${reference.value ? `; value=${reference.value}` : ""}${reference.path ? `; path=${reference.path}` : ""}`);
+    return `\nReferences:\n${lines.join("\n")}`;
+}
 function formatRun(run) {
     const prereqs = run.prerequisites.length
         ? `${run.prerequisites.filter((item) => item.status === "met").length}/${run.prerequisites.length} prereqs met`
@@ -171,31 +226,144 @@ function formatRun(run) {
         : run.verifier?.command
             ? "verifier configured"
             : "no verifier";
+    const refs = run.references?.length ? `, ${run.references.length} reference(s)` : "";
+    const audit = run.completionAudit
+        ? `, final audit ${run.completionAudit.status}`
+        : run.verifier?.lastResult?.status === "pass"
+            ? ", final audit missing"
+            : "";
     const blocker = goalHasBlockingPrerequisites(run)
         ? `\nUser prerequisites: ${formatGoalBlockingPrerequisites(run)}`
         : "";
-    return `[${run.status}] ${run.title} (id: ${run.id.slice(0, 8)}) — ${prereqs}, ${tasks}, ${verifier}${blocker}`;
+    return `[${run.status}] ${run.title} (id: ${run.id.slice(0, 8)}) — ${prereqs}, ${tasks}, ${verifier}${refs}${audit}${blocker}${formatRunReferences(run)}`;
 }
 function recoverableTaskStatus(status) {
     return status === "pending" || status === "failed";
 }
 function statusAfterTaskPatch(run, status) {
-    if (run.status !== "failed" || !recoverableTaskStatus(status))
+    if ((run.status !== "failed" && run.status !== "passed") || !recoverableTaskStatus(status)) {
         return run.status;
+    }
     return goalHasBlockingPrerequisites(run) ? "blocked" : "ready";
 }
+const SETUP_BLOCKER_PREFIX = "Goal setup incomplete:";
+function referencesAcknowledged(references, fields) {
+    const required = referencesRequiringAcknowledgement(references ?? []);
+    if (required.length === 0)
+        return true;
+    const haystack = fields.join("\n").toLowerCase();
+    return required.every((reference) => {
+        const tokens = [reference.id, reference.label, reference.value, reference.path]
+            .filter((token) => !!token?.trim())
+            .map((token) => token.toLowerCase());
+        return tokens.some((token) => haystack.includes(token));
+    });
+}
+function hasOriginalGoalPromptReference(references) {
+    return (references ?? []).some((reference) => reference.id === "original-goal-prompt" &&
+        reference.kind === "prompt" &&
+        reference.content?.trim());
+}
+function setupBlockersForRun(run) {
+    const blockers = [];
+    const contractFields = [
+        run.goal ?? "",
+        ...run.successCriteria,
+        ...(run.references ?? []).map((reference) => `${reference.id} ${reference.label} ${reference.content ?? ""}`),
+        ...(run.evidence ?? []).map((item) => `${item.label}\n${item.path ?? ""}\n${item.content ?? ""}`),
+    ].join("\n");
+    const requiresReliabilityContract = /GOAL_PLAN/.test(contractFields);
+    if (requiresReliabilityContract && !hasOriginalGoalPromptReference(run.references)) {
+        blockers.push(`${SETUP_BLOCKER_PREFIX} durable [original-goal-prompt] reference is required.`);
+    }
+    const plannerFields = [
+        run.goal ?? "",
+        ...(run.evidence ?? []).map((item) => `${item.label}\n${item.path ?? ""}\n${item.content ?? ""}`),
+    ].join("\n");
+    if (requiresReliabilityContract &&
+        (!/GOAL_PLAN/.test(plannerFields) ||
+            !/research=/.test(plannerFields) ||
+            !/success=/.test(plannerFields))) {
+        blockers.push(`${SETUP_BLOCKER_PREFIX} durable planner GOAL_PLAN evidence/state is required.`);
+    }
+    if (run.successCriteria.length === 0)
+        blockers.push(`${SETUP_BLOCKER_PREFIX} success criteria are required.`);
+    if (run.evidencePlan.length === 0)
+        blockers.push(`${SETUP_BLOCKER_PREFIX} evidence_plan is required.`);
+    if (!run.verifier?.command)
+        blockers.push(`${SETUP_BLOCKER_PREFIX} verifier_command is required.`);
+    const referenceFields = [
+        ...run.successCriteria,
+        ...run.evidencePlan.map((item) => `${item.id} ${item.label} ${item.description} ${item.command ?? ""} ${item.path ?? ""} ${item.evidence ?? ""}`),
+        ...run.tasks.map((task) => `${task.title} ${task.prompt}`),
+        run.verifier?.description ?? "",
+        run.verifier?.command ?? "",
+    ];
+    if (!referencesAcknowledged(run.references, referenceFields)) {
+        blockers.push(`${SETUP_BLOCKER_PREFIX} every non-prompt Goal reference must be named in success criteria, task prompts, evidence_plan, or verifier metadata.`);
+    }
+    return blockers;
+}
+function blockersAfterSetupCheck(run, setupBlockers) {
+    if (run.status !== "draft")
+        return run.blockers;
+    return Array.from(new Set([
+        ...run.blockers.filter((blocker) => !blocker.startsWith(SETUP_BLOCKER_PREFIX)),
+        ...setupBlockers,
+    ]));
+}
+function statusAfterSetupCheck(run, setupBlockers) {
+    if (run.status !== "draft")
+        return run.status;
+    if (setupBlockers.length > 0)
+        return "draft";
+    return goalHasBlockingPrerequisites(run) ? "blocked" : "ready";
+}
+function validatePassAuditContract(run, summary, outputPath) {
+    const verifier = run.verifier?.lastResult;
+    if (!verifier)
+        return "cannot audit completion before a verifier result exists.";
+    if (!summary.startsWith("FINAL_AUDIT_PASS"))
+        return "pass audit summary must start with FINAL_AUDIT_PASS.";
+    if (!summary.includes(`verifier_checked_at=${verifier.checkedAt}`)) {
+        return `pass audit summary must include verifier_checked_at=${verifier.checkedAt}.`;
+    }
+    if (!outputPath && !summary.match(/(?:output|artifact|log|path)=\S+/)) {
+        return "pass audit must include output_path or an output/artifact/log/path reference in the summary.";
+    }
+    const contractFields = [
+        run.goal,
+        ...run.successCriteria,
+        ...(run.references ?? []).map((reference) => `${reference.id} ${reference.label} ${reference.content ?? ""}`),
+        ...run.evidence.map((item) => `${item.label}\n${item.path ?? ""}\n${item.content ?? ""}`),
+    ].join("\n");
+    const requiresReliabilityContract = /GOAL_PLAN/.test(contractFields);
+    if (requiresReliabilityContract && !summary.includes("original-goal-prompt")) {
+        return "pass audit summary must explicitly reference original-goal-prompt.";
+    }
+    if (requiresReliabilityContract && !summary.includes("GOAL_PLAN")) {
+        return "pass audit summary must explicitly reference durable GOAL_PLAN evidence.";
+    }
+    if (!referencesAcknowledged(run.references, [summary, outputPath ?? ""])) {
+        return "pass audit summary or output_path must explicitly reference every non-prompt Goal reference id, label, URL, or path.";
+    }
+    return undefined;
+}
 async function resolveRun(cwd, id) {
     if (id)
         return getGoalRun(cwd, id);
     return getActiveGoalRun(cwd);
 }
-export function createGoalsTool(cwd) {
+export function createGoalsTool(cwd, goalModeRef, getGoalReferences) {
     return {
         name: "goals",
-        description: "Manage durable Goal runs for /goal and Ctrl+G workflows. Use this instead of tasks when the user wants a programmatic goal loop: define success criteria first, check prerequisites before launching workers, persist harness/diagnostics/evidence, add standalone worker tasks, and only mark the goal complete when verifier evidence proves the original objective. Do not require paid services or signups without recording a blocker and asking the user for the missing prerequisite.",
+        description: "Manage durable Goal runs for /goal and Ctrl+G workflows. Use this instead of tasks when the user wants a programmatic goal loop: define success criteria first, check prerequisites before launching workers, persist harness/diagnostics/evidence, add standalone worker tasks, record final completion audits, and only mark the goal complete when verifier plus final-audit evidence proves the original objective. Do not require paid services or signups without recording a blocker and asking the user for the missing prerequisite.",
         parameters: GoalsParams,
         executionMode: "sequential",
         async execute(args) {
+            if (getActiveGoalMode(goalModeRef) === "planner") {
+                return "Error: goals is restricted in Goal planner mode. Emit a compact GOAL_PLAN block only; setup creates durable Goal state.";
+            }
             switch (args.action) {
                 case "create": {
                     if (!args.title)
@@ -203,14 +371,9 @@ export function createGoalsTool(cwd) {
                     if (!args.goal)
                         return "Error: goal is required for create.";
                     const existing = args.run_id ? await getGoalRun(cwd, args.run_id) : null;
-                    const prerequisites = args.prerequisites?.map((item) => ({
-                        id: item.id ?? randomUUID(),
-                        label: item.label,
-                        status: asPrerequisiteStatus(item.status),
-                        ...(item.check_command ? { checkCommand: item.check_command } : {}),
-                        ...(item.instructions ? { instructions: item.instructions } : {}),
-                        ...(item.evidence ? { evidence: item.evidence } : {}),
-                    }));
+                    const prerequisites = args.prerequisites
+                        ? await Promise.all(args.prerequisites.map((item) => normalizePrerequisiteInput(cwd, item)))
+                        : undefined;
                     const harness = args.harness?.map((item) => ({
                         id: item.id ?? randomUUID(),
                         label: item.label,
@@ -243,28 +406,58 @@ export function createGoalsTool(cwd) {
                     const nextPrerequisites = prerequisites ?? existing?.prerequisites ?? [];
                     const missingPrerequisites = formatGoalBlockingPrerequisiteList(nextPrerequisites);
                     const hasBlockingPrerequisites = missingPrerequisites !== "Goal has no missing user prerequisites.";
+                    const references = [...(getGoalReferences?.() ?? existing?.references ?? [])];
+                    const plannerEvidence = args.summary?.includes("GOAL_PLAN")
+                        ? [
+                            createGoalEvidence({
+                                kind: "summary",
+                                label: "Planner GOAL_PLAN",
+                                content: args.summary,
+                            }),
+                        ]
+                        : undefined;
+                    const draftProbe = {
+                        goal: args.goal,
+                        successCriteria: args.success_criteria ?? existing?.successCriteria ?? [],
+                        evidencePlan: evidencePlan ?? existing?.evidencePlan ?? [],
+                        references,
+                        tasks: existing?.tasks ?? [],
+                        evidence: plannerEvidence ?? existing?.evidence ?? [],
+                        verifier,
+                    };
+                    const setupBlockers = setupBlockersForRun(draftProbe);
+                    const blockers = Array.from(new Set([
+                        ...(args.blockers ?? existing?.blockers ?? []),
+                        ...(hasBlockingPrerequisites ? [missingPrerequisites] : []),
+                        ...setupBlockers,
+                    ]));
                     const run = await upsertGoalRun(cwd, {
                         ...(args.run_id ? { id: args.run_id } : {}),
                         title: args.title,
                         goal: args.goal,
-                        status: hasBlockingPrerequisites ? "blocked" : (existing?.status ?? "ready"),
-                        successCriteria: args.success_criteria ?? existing?.successCriteria ?? [],
+                        status: setupBlockers.length > 0
+                            ? "draft"
+                            : hasBlockingPrerequisites
+                                ? "blocked"
+                                : (existing?.status ?? "ready"),
+                        successCriteria: draftProbe.successCriteria,
                         prerequisites: nextPrerequisites,
                         harness: harness ?? existing?.harness ?? [],
-                        evidencePlan: evidencePlan ?? existing?.evidencePlan ?? [],
+                        evidencePlan: draftProbe.evidencePlan,
+                        references: draftProbe.references,
+                        ...(plannerEvidence ? { evidence: plannerEvidence } : {}),
                         ...(verifier ? { verifier } : {}),
-                        blockers: hasBlockingPrerequisites
-                            ? Array.from(new Set([...(args.blockers ?? existing?.blockers ?? []), missingPrerequisites]))
-                            : (args.blockers ?? []),
+                        blockers,
                     });
                     await appendGoalDecision(cwd, run.id, {
                         kind: args.run_id ? "update" : "create",
-                        reason: `criteria=${run.successCriteria.length}; prerequisites=${run.prerequisites.length}; harness=${run.harness.length}; evidence_plan=${run.evidencePlan.length}; verifier=${run.verifier?.command ? "configured" : "missing"}`,
+                        reason: `criteria=${run.successCriteria.length}; prerequisites=${run.prerequisites.length}; harness=${run.harness.length}; evidence_plan=${run.evidencePlan.length}; references=${run.references?.length ?? 0}; verifier=${run.verifier?.command ? "configured" : "missing"}`,
                     });
                     log("INFO", "goals", `Goal created: ${run.title}`, { id: run.id, status: run.status });
+                    const setupMessage = setupBlockers.length > 0 ? ` Setup blockers: ${setupBlockers.join(" ")}` : "";
                     return goalHasBlockingPrerequisites(run)
-                        ? `Goal ${args.run_id ? "updated" : "created"}: "${run.title}" (id: ${run.id.slice(0, 8)}, ${run.status}). User prerequisites: ${formatGoalBlockingPrerequisites(run)}`
-                        : `Goal ${args.run_id ? "updated" : "created"}: "${run.title}" (id: ${run.id.slice(0, 8)}, ${run.status})`;
+                        ? `Goal ${args.run_id ? "updated" : "created"}: "${run.title}" (id: ${run.id.slice(0, 8)}, ${run.status}). User prerequisites: ${formatGoalBlockingPrerequisites(run)}${setupMessage}`
+                        : `Goal ${args.run_id ? "updated" : "created"}: "${run.title}" (id: ${run.id.slice(0, 8)}, ${run.status}).${setupMessage}`;
                 }
                 case "status": {
                     if (args.run_id) {
@@ -288,12 +481,22 @@ export function createGoalsTool(cwd) {
                     const index = prereqId
                         ? prerequisites.findIndex((item) => item.id === prereqId || item.id.startsWith(prereqId))
                         : -1;
+                    const existingPrerequisite = index >= 0 ? prerequisites[index] : undefined;
                     const patch = {
                         id: prereqId ?? randomUUID(),
-                        label: args.prerequisite_label ?? prereqId ?? "Prerequisite",
+                        label: args.prerequisite_label ?? existingPrerequisite?.label ?? prereqId ?? "Prerequisite",
                         status: asPrerequisiteStatus(args.prerequisite_status),
                         ...(args.instructions ? { instructions: args.instructions } : {}),
                         ...(args.summary ? { evidence: args.summary } : {}),
+                        ...(asPrerequisiteStatus(args.prerequisite_status) === "met" && !args.summary
+                            ? {
+                                instructions: args.instructions ??
+                                    uncheckedPrerequisiteInstructions(args.prerequisite_label ??
+                                        existingPrerequisite?.label ??
+                                        prereqId ??
+                                        "Prerequisite"),
+                            }
+                            : {}),
                     };
                     if (index >= 0) {
                         prerequisites[index] = {
@@ -305,12 +508,17 @@ export function createGoalsTool(cwd) {
                     else {
                         prerequisites.push(patch);
                     }
-                    const stillBlocked = goalHasBlockingPrerequisites({ ...run, prerequisites });
-                    const updated = await upsertGoalRun(cwd, {
+                    const prerequisiteRun = {
                         ...run,
                         prerequisites,
-                        status: stillBlocked ? "blocked" : "ready",
-                        blockers: stillBlocked ? run.blockers : [],
+                        status: goalHasBlockingPrerequisites({ ...run, prerequisites }) ? "blocked" : "ready",
+                        blockers: goalHasBlockingPrerequisites({ ...run, prerequisites }) ? run.blockers : [],
+                    };
+                    const setupBlockers = setupBlockersForRun(prerequisiteRun);
+                    const updated = await upsertGoalRun(cwd, {
+                        ...prerequisiteRun,
+                        status: statusAfterSetupCheck(prerequisiteRun, setupBlockers),
+                        blockers: blockersAfterSetupCheck(prerequisiteRun, setupBlockers),
                     });
                     await appendGoalDecision(cwd, updated.id, {
                         kind: "prerequisites",
@@ -333,6 +541,10 @@ export function createGoalsTool(cwd) {
                     if (!taskExisted && (!args.task_title || !args.task_prompt)) {
                         return "Error: task_title and task_prompt are required when adding a task.";
                     }
+                    if (!taskExisted &&
+                        !referencesAcknowledged(run.references, [args.task_title ?? "", args.task_prompt ?? ""])) {
+                        return "Error: task_prompt must explicitly include each non-prompt Goal reference id, label, URL, or path so workers cannot silently ignore the user's references.";
+                    }
                     const taskStatus = asTaskStatus(args.task_status);
                     const updated = await updateGoalTask(cwd, run.id, taskId, {
                         id: taskId,
@@ -344,10 +556,18 @@ export function createGoalsTool(cwd) {
                         ...(args.summary ? { lastSummary: args.summary } : {}),
                     });
                     const recovered = updated
-                        ? await upsertGoalRun(updated.projectPath, {
-                            ...updated,
-                            status: statusAfterTaskPatch(updated, taskStatus),
-                        })
+                        ? await (async () => {
+                            const taskPatchedRun = {
+                                ...updated,
+                                status: statusAfterTaskPatch(updated, taskStatus),
+                            };
+                            const setupBlockers = setupBlockersForRun(taskPatchedRun);
+                            return upsertGoalRun(updated.projectPath, {
+                                ...taskPatchedRun,
+                                status: statusAfterSetupCheck(taskPatchedRun, setupBlockers),
+                                blockers: blockersAfterSetupCheck(taskPatchedRun, setupBlockers),
+                            });
+                        })()
                         : null;
                     if (!recovered)
                         return `Error: no task found matching id "${taskId}".`;
@@ -372,6 +592,48 @@ export function createGoalsTool(cwd) {
                         return "Error: failed to append evidence.";
                     return `Evidence added to "${updated.title}".`;
                 }
+                case "evidence_plan": {
+                    const run = await resolveRun(cwd, args.run_id);
+                    if (!run)
+                        return "Error: no active goal run found.";
+                    const evidencePlanItemId = args.evidence_plan_item_id;
+                    if (!evidencePlanItemId)
+                        return "Error: evidence_plan_item_id is required.";
+                    const evidencePlan = [...run.evidencePlan];
+                    const index = evidencePlan.findIndex((item) => item.id === evidencePlanItemId || item.id.startsWith(evidencePlanItemId));
+                    if (index < 0) {
+                        return `Error: no evidence-plan item found matching id "${args.evidence_plan_item_id}".`;
+                    }
+                    const existing = evidencePlan[index];
+                    const status = asEvidencePlanStatus(args.evidence_plan_status);
+                    evidencePlan[index] = {
+                        ...existing,
+                        status,
+                        ...(args.instructions ? { instructions: args.instructions } : {}),
+                        ...(args.evidence_content || args.summary
+                            ? { evidence: args.evidence_content ?? args.summary }
+                            : {}),
+                        ...(args.evidence_path ? { path: args.evidence_path } : {}),
+                    };
+                    const canRecoverBlockedRun = run.status === "blocked" && status === "ready" && !goalHasBlockingPrerequisites(run);
+                    const evidencePlanRun = {
+                        ...run,
+                        evidencePlan,
+                        status: canRecoverBlockedRun ? "ready" : run.status,
+                        blockers: canRecoverBlockedRun ? [] : run.blockers,
+                    };
+                    const setupBlockers = setupBlockersForRun(evidencePlanRun);
+                    const updated = await upsertGoalRun(cwd, {
+                        ...evidencePlanRun,
+                        status: statusAfterSetupCheck(evidencePlanRun, setupBlockers),
+                        blockers: blockersAfterSetupCheck(evidencePlanRun, setupBlockers),
+                    });
+                    await appendGoalDecision(cwd, updated.id, {
+                        kind: "evidence_plan",
+                        reason: `Evidence-plan item ${existing.label} is ${status}.`,
+                    });
+                    return `Evidence-plan item updated for "${updated.title}": "${existing.label}" is ${status}.`;
+                }
                 case "verify": {
                     const run = await resolveRun(cwd, args.run_id);
                     if (!run)
@@ -395,6 +657,17 @@ export function createGoalsTool(cwd) {
                                 : {}),
                             lastResult: result,
                         },
+                        ...(result.status === "pass"
+                            ? {
+                                completionAudit: {
+                                    status: "unknown",
+                                    summary: "Final completion audit pending for latest verifier result.",
+                                    checkedAt: result.checkedAt,
+                                    verifierCheckedAt: result.checkedAt,
+                                    ...(result.outputPath ? { outputPath: result.outputPath } : {}),
+                                },
+                            }
+                            : {}),
                         evidence: [
                             ...run.evidence,
                             createGoalEvidence({
@@ -424,6 +697,61 @@ export function createGoalsTool(cwd) {
                     });
                     return `Verifier recorded for "${updated.title}": ${result.status}.`;
                 }
+                case "audit": {
+                    const run = await resolveRun(cwd, args.run_id);
+                    if (!run)
+                        return "Error: no active goal run found.";
+                    const verifierResult = run.verifier?.lastResult;
+                    if (!verifierResult || verifierResult.status !== "pass") {
+                        return "Error: cannot audit completion before a passing verifier result exists.";
+                    }
+                    const auditStatus = asVerificationStatus(args.verification_status);
+                    const auditSummary = args.summary ?? "Final completion audit recorded.";
+                    const auditOutputPath = args.output_path ?? verifierResult.outputPath;
+                    if (auditStatus === "pass") {
+                        const contractError = validatePassAuditContract(run, auditSummary, auditOutputPath);
+                        if (contractError)
+                            return `Error: invalid final completion audit pass contract: ${contractError}`;
+                    }
+                    const completionAudit = {
+                        status: auditStatus,
+                        summary: auditSummary,
+                        checkedAt: new Date().toISOString(),
+                        verifierCheckedAt: verifierResult.checkedAt,
+                        ...(auditOutputPath ? { outputPath: auditOutputPath } : {}),
+                    };
+                    const runWithAudit = {
+                        ...run,
+                        completionAudit,
+                        evidence: [
+                            ...run.evidence,
+                            createGoalEvidence({
+                                kind: "summary",
+                                label: `Final completion audit ${completionAudit.status}`,
+                                content: completionAudit.summary,
+                                ...(completionAudit.outputPath ? { path: completionAudit.outputPath } : {}),
+                            }),
+                        ],
+                    };
+                    const auditCheck = hasFreshGoalCompletionAudit(runWithAudit);
+                    const completion = canCompleteGoalRun(runWithAudit);
+                    const updated = await upsertGoalRun(cwd, {
+                        ...runWithAudit,
+                        status: completionAudit.status === "pass" && auditCheck.ok && completion.ok
+                            ? "passed"
+                            : goalHasBlockingPrerequisites(runWithAudit)
+                                ? "blocked"
+                                : "ready",
+                        blockers: completionAudit.status === "pass" && auditCheck.ok ? [] : run.blockers,
+                        activeWorkerId: undefined,
+                    });
+                    await appendGoalDecision(cwd, updated.id, {
+                        kind: "completion_audit",
+                        reason: auditCheck.reason,
+                        content: `status=${completionAudit.status}; verifierCheckedAt=${completionAudit.verifierCheckedAt ?? ""}; outputPath=${completionAudit.outputPath ?? ""}`,
+                    });
+                    return `Completion audit recorded for "${updated.title}": ${completionAudit.status}.`;
+                }
                 case "pause":
                 case "resume":
                 case "complete": {
@@ -431,8 +759,12 @@ export function createGoalsTool(cwd) {
                     if (!run)
                         return "Error: no active goal run found.";
                     let status;
-                    if (args.action === "pause")
+                    if (args.action === "pause") {
+                        if (run.activeWorkerId || run.tasks.some((task) => task.status === "running")) {
+                            return `Error: cannot pause goal while worker ${run.activeWorkerId ?? "task"} is active. Stop the worker first or wait for it to finish.`;
+                        }
                         status = "paused";
+                    }
                     else if (args.action === "resume") {
                         const missing = goalHasBlockingPrerequisites(run)
                             ? formatGoalBlockingPrerequisites(run)
@@ -441,7 +773,7 @@ export function createGoalsTool(cwd) {
                             const updated = await upsertGoalRun(cwd, {
                                 ...run,
                                 status: "blocked",
-                                blockers: Array.from(new Set([...run.blockers, missing])),
+                                blockers: appendGoalBlockers(run.blockers, missing),
                                 evidence: [
                                     ...run.evidence,
                                     createGoalEvidence({
@@ -469,7 +801,25 @@ export function createGoalsTool(cwd) {
                             ],
                         };
                         const decision = decideGoalNextAction(resumed);
-                        const updated = await upsertGoalRun(cwd, resumed);
+                        const blockedReason = decision.kind === "blocked" ? decision.reason : undefined;
+                        const updated = await upsertGoalRun(cwd, {
+                            ...resumed,
+                            ...(blockedReason
+                                ? {
+                                    status: "blocked",
+                                    continueRequestedAt: undefined,
+                                    blockers: appendGoalBlockers(run.blockers, blockedReason),
+                                    evidence: [
+                                        ...resumed.evidence,
+                                        createGoalEvidence({
+                                            kind: "summary",
+                                            label: "Goal resume blocked",
+                                            content: blockedReason,
+                                        }),
+                                    ],
+                                }
+                                : {}),
+                        });
                         await appendGoalDecision(cwd, updated.id, {
                             kind: "resume",
                             reason: decision.kind === "wait" ||