@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/tools-files.js

@@ -3,10 +3,10 @@
  */
 import { createHash, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, resolveWorkspaceWritePath, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, isReadError, safeRead, safeWriteAsync, safeWrite, resolveWorkspaceWritePath, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
 import { isInside, looksLikeSwarmHandoffPath, normalizeRelPath } from "./shared.js";
 import { validateAgentStateHandoffPayload, validateArtifactManifestPayload, validateProvenanceLogContent, validateStatusEventsNdjsonContent, validateSwarmHandoffPayload, validateTealConfigContent, validateRuntimeExecutorSessionRegistryPayload, validateRuntimeToolSpecRegistryPayload, validateTrackerSnapshotPayload, validateVericifyBridgeSnapshotPayload, validateVericifyProcessPostLogPayload, validateWorkspaceSessionRegistryPayload, lintHandoffPayload, } from "./schemas.js";
 import { syncTodoStateSafe } from "./todo-state.js";
@@ -14,9 +14,10 @@ import { shouldAutoRefreshKanbanForPath, refreshKanbanArtifacts, } from "./kanba
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
 import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
-import { detectAstgrepCommand, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
+import { detectAstgrepCommand, flattenMetaVariables, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
 import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
+import { listStoreKeysSync } from "./store/store-snapshot.js";
 function reasonCodeFromError(error) {
     return typeof error === "object" && error !== null && "reason_code" in error
         ? String(error.reason_code)
@@ -129,13 +130,22 @@ async function storeLocateArtifact(input, result) {
     });
 }
 function listStructuralEditArtifacts(prefix) {
+    const relPaths = new Set();
+    const storePrefix = `state/artifacts/${STRUCTURAL_EDIT_ARTIFACTS_REL}/${prefix}-`;
+    for (const key of listStoreKeysSync(WORKSPACE_ROOT, storePrefix)) {
+        if (key.endsWith(".json")) {
+            relPaths.add(key.slice("state/artifacts/".length));
+        }
+    }
     const dir = wsPath(STRUCTURAL_EDIT_ARTIFACTS_REL);
-    if (!existsSync(dir))
-        return [];
-    return readdirSync(dir)
-        .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith(".json"))
-        .sort((a, b) => b.localeCompare(a))
-        .map((name) => normalizeRelPath(relative(WORKSPACE_ROOT, resolve(dir, name))));
+    if (existsSync(dir)) {
+        for (const name of readdirSync(dir)) {
+            if (name.startsWith(`${prefix}-`) && name.endsWith(".json")) {
+                relPaths.add(normalizeRelPath(relative(WORKSPACE_ROOT, resolve(dir, name))));
+            }
+        }
+    }
+    return [...relPaths].sort((a, b) => b.localeCompare(a));
 }
 function findStoredMatch(matchId) {
     for (const relPath of listStructuralEditArtifacts("locate")) {
@@ -206,8 +216,12 @@ async function compileStructuralEditPlan(input) {
         },
         validation_command: input.validationCommand,
         test_command: input.testCommand,
+        allow_multi_match: input.allowMultiMatch,
     });
 }
+function renderStructuralRewrite(template, captures) {
+    return template.replace(/\$([A-Z][A-Z0-9_]*)/g, (full, name) => captures[name] ?? full);
+}
 function previewDiffText(diffText) {
     const lines = diffText.trimEnd().split("\n");
     const limited = lines.slice(0, 80).join("\n");
@@ -378,6 +392,24 @@ async function buildStructuralPreview(plan) {
             }),
         };
     }
+    if (targetMatches.length > 1 && !plan.allow_multi_match) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "ambiguous_multi_match_in_file",
+                error: `Plan ${plan.plan_id} resolves to ${targetMatches.length} matches in ${plan.target.file}. Pass allow_multi_match=true at compile time to opt in, or narrow the pattern.`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: targetMatches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
     const astgrepCmd = detectAstgrepCommand();
     if (!astgrepCmd) {
         return {
@@ -403,7 +435,7 @@ async function buildStructuralPreview(plan) {
     mkdirSync(dirname(stagedOriginal), { recursive: true });
     writeFileSync(stagedOriginal, currentContent, "utf-8");
     writeFileSync(stagedRewrite, currentContent, "utf-8");
-    const rewriteResult = spawnSync(astgrepCmd, ["--pattern", plan.locator.pattern, "--rewrite", plan.rewrite.rewrite_template, "--lang", plan.locator.lang, stagedRewrite, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+    const rewriteResult = spawnSync(astgrepCmd, ["--pattern", plan.locator.pattern, "--rewrite", plan.rewrite.rewrite_template, "--lang", plan.locator.lang, "--json", stagedRewrite], { encoding: "utf8", cwd: WORKSPACE_ROOT });
     if (rewriteResult.status !== 0) {
         return {
             artifact: await finalize({
@@ -423,7 +455,46 @@ async function buildStructuralPreview(plan) {
             }),
         };
     }
-    const rewrittenContent = readFileSync(stagedRewrite, "utf-8");
+    let rawMatches = [];
+    try {
+        rawMatches = JSON.parse(rewriteResult.stdout || "[]");
+    }
+    catch {
+        rawMatches = [];
+    }
+    const selectedBytes = plan.target.selected_range?.byteOffset;
+    const targeted = rawMatches.find((match) => selectedBytes
+        && match.range?.byteOffset?.start === selectedBytes.start
+        && match.range?.byteOffset?.end === selectedBytes.end);
+    const replacement = targeted && (typeof targeted.replacement === "string"
+        ? targeted.replacement
+        : renderStructuralRewrite(plan.rewrite.rewrite_template, flattenMetaVariables(targeted.metaVariables)));
+    if (!selectedBytes || !targeted || typeof replacement !== "string") {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "target_byte_range_drift",
+                error: `No match at selected byte range [${selectedBytes?.start},${selectedBytes?.end}] for plan ${plan.plan_id}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: rawMatches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+                staging_path: stagingDir,
+            }),
+        };
+    }
+    const originalBuffer = Buffer.from(currentContent, "utf8");
+    const rewrittenContent = Buffer.concat([
+        originalBuffer.subarray(0, selectedBytes.start ?? 0),
+        Buffer.from(replacement, "utf8"),
+        originalBuffer.subarray(selectedBytes.end ?? 0),
+    ]).toString("utf8");
+    writeFileSync(stagedRewrite, rewrittenContent, "utf8");
     const rewriteHash = contentSha256(rewrittenContent);
     const diff = diffContents(currentContent, rewrittenContent);
     const diffProcess = spawnSync("diff", ["-u", "--label", `a/${plan.target.file}`, "--label", `b/${plan.target.file}`, stagedOriginal, stagedRewrite], { encoding: "utf8", cwd: WORKSPACE_ROOT });
@@ -432,6 +503,7 @@ async function buildStructuralPreview(plan) {
         : diffProcess.status === 0
             ? ""
             : diff.diff_summary;
+    const hasUnifiedDiff = diffProcess.status === 1;
     return {
         artifact: await finalize({
             ok: true,
@@ -444,7 +516,7 @@ async function buildStructuralPreview(plan) {
             changed_ranges: parseChangedRanges(diffText),
             diff_summary: diff.diff_summary,
             diff_preview: diffText ? previewDiffText(diffText) : diff.diff_summary,
-            promotable: diff.has_diff,
+            promotable: hasUnifiedDiff,
             staging_path: stagingDir,
         }),
         rewritten_content: rewrittenContent,
@@ -1073,10 +1145,15 @@ export function registerFileTools(server) {
             .boolean()
             .optional()
             .describe("Keep .ace-backup copy (default: true)"),
-    }, async ({ path, content, validation_command, test_command, backup }) => {
+        expected_base_hash: z
+            .string()
+            .optional()
+            .describe("Optional source precondition checked immediately before promotion; prefer full sha256:<hex>"),
+    }, async ({ path, content, validation_command, test_command, backup, expected_base_hash }) => {
         const result = safeEditFile({
             path,
             content,
+            expected_base_hash,
             validation_command,
             test_command,
             backup,
@@ -1093,6 +1170,9 @@ export function registerFileTools(server) {
                 original_hash: result.original_hash,
                 new_hash: result.new_hash,
                 restored: result.restored,
+                reason_code: result.reason_code,
+                expected_hash: result.expected_hash,
+                observed_hash: result.observed_hash,
                 validation_passed: result.validation_passed,
                 test_passed: result.test_passed,
             },
@@ -1154,19 +1234,19 @@ export function registerFileTools(server) {
         };
     });
     // ── Diff (new P2 tool) ────────────────────────────────────────────
-    server.tool("diff_files", "Compute a line-based diff between two file contents or file paths", {
+    server.tool("diff_files", "Produce a sequence-aware unified diff between two contents or two workspace paths", {
         original: z.string().describe("Original content or workspace-relative file path"),
         modified: z.string().describe("Modified content or workspace-relative file path"),
-        is_path: z
-            .boolean()
-            .optional()
-            .describe("If true, treat original/modified as file paths and read their contents"),
-    }, async ({ original, modified, is_path }) => {
+        mode: z.enum(["content", "path"]).default("content").describe("Explicitly interpret both inputs as literal content or workspace-relative paths"),
+    }, async ({ original, modified, mode }) => {
         let origContent = original;
         let modContent = modified;
-        if (is_path) {
+        if (mode === "path") {
             origContent = safeRead(original);
             modContent = safeRead(modified);
+            if (isReadError(origContent) || isReadError(modContent)) {
+                throw new Error(`Unable to read diff path: ${isReadError(origContent) ? origContent : modContent}`);
+            }
         }
         const diff = diffContents(origContent, modContent);
         return {
@@ -1344,9 +1424,10 @@ export function registerFileTools(server) {
         max_results: z.number().int().min(1).max(200).optional().describe("Max locator matches to keep (default: 50)"),
         desired_change: z.string().describe("Plain-language edit intent; used as rewrite_template when no explicit template is provided"),
         rewrite_template: z.string().optional().describe("Explicit ast-grep rewrite template; preferred when provided"),
+        allow_multi_match: z.boolean().optional().describe("Opt into selecting and rewriting only the chosen match when multiple matches exist in the target file"),
         validation_command: z.string().optional().describe("Shell command to validate before promotion"),
         test_command: z.string().optional().describe("Shell command to run before promotion"),
-    }, async ({ match_id, pattern, lang, scope, symbol_hint, max_results, desired_change, rewrite_template, validation_command, test_command, }) => {
+    }, async ({ match_id, pattern, lang, scope, symbol_hint, max_results, desired_change, rewrite_template, allow_multi_match, validation_command, test_command, }) => {
         if (!match_id && (!pattern || !lang)) {
             return jsonResponse({
                 ok: false,
@@ -1455,6 +1536,7 @@ export function registerFileTools(server) {
             selectedMatch,
             desiredChange: desired_change,
             rewriteTemplate: rewrite_template,
+            allowMultiMatch: allow_multi_match,
             validationCommand: validation_command,
             testCommand: test_command,
         }).catch((error) => {
@@ -1597,6 +1679,7 @@ export function registerFileTools(server) {
         const safeResult = safeEditFile({
             path: compiledPlan.target.file,
             content: preview.rewritten_content,
+            expected_base_hash: compiledPlan.target.file_hash,
             validation_command: validation_command ?? compiledPlan.validation_command,
             test_command: test_command ?? compiledPlan.test_command,
         });
@@ -1644,10 +1727,11 @@ export function registerFileTools(server) {
     server.tool("apply_patch", "Apply a unified diff patch to a workspace file. Applies the patch to staged content, runs optional validation/tests, and promotes to the target only on success. Cost: moderate.", {
         path: z.string().describe("Workspace-relative file path to patch"),
         patch: z.string().describe("Unified diff patch (output of diff -u or similar)"),
+        expected_base_hash: z.string().optional().describe("Optional source precondition checked immediately before promotion; prefer full sha256:<hex>"),
         validation_command: z.string().optional().describe("Shell command to validate after applying (e.g. 'npx tsc --noEmit')"),
         test_command: z.string().optional().describe("Shell command to run tests after applying"),
-    }, async ({ path: relPath, patch, validation_command, test_command }) => {
-        const result = applyPatch({ path: relPath, patch, validation_command, test_command });
+    }, async ({ path: relPath, patch, expected_base_hash, validation_command, test_command }) => {
+        const result = applyPatch({ path: relPath, patch, expected_base_hash, validation_command, test_command });
         if (!result.ok) {
             return {
                 content: [{ type: "text", text: `apply_patch failed: ${result.error ?? "unknown error"}\n${result.validation_output ?? ""}` }],

package/dist/tools-framework.js

@@ -18,6 +18,9 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { auditPublicSurface } from "./public-surface.js";
 import { auditStoreAuthority, writeStoreAuthorityAuditReport, } from "./store/store-authority-audit.js";
+import { openStore } from "./store/ace-packed-store.js";
+import { getWorkspaceStorePath } from "./store/store-snapshot.js";
+import { parseGateManifest, resolveGateSelection, } from "./gate-contract.js";
 import { PROVENANCE_CRITICAL_EVENT_TYPES, validateArtifactManifestPayload, validateProvenanceLogContent, validateTealConfigContent, } from "./schemas.js";
 import { readAceTaskContractAssessment } from "./ace-autonomy.js";
 import { listStoreKeysSync, readStoreBlobSync } from "./store/store-snapshot.js";
@@ -54,28 +57,6 @@ function getArtifactManifestEntries(payload) {
     }
     return [];
 }
-function parseGateManifest(raw, sourceRef) {
-    try {
-        const gate = JSON.parse(raw);
-        const id = typeof gate.id === "string" ? gate.id.trim() : "";
-        if (!id)
-            return undefined;
-        const type = gate.type === "executable" || gate.type === "artifact_scan" || gate.type === "manual_review"
-            ? gate.type
-            : "manual_review";
-        return {
-            id,
-            type,
-            invariant: typeof gate.invariant === "string" ? gate.invariant : "",
-            command: typeof gate.command === "string" ? gate.command : "",
-            evidence_requirement: typeof gate.evidence_requirement === "string" ? gate.evidence_requirement : "",
-            source_ref: sourceRef,
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
 function parseJsonForValidation(raw) {
     return parseJsonLikeText(raw);
 }
@@ -130,10 +111,14 @@ function hasArtifactEvidence(reference) {
     const normalized = reference.trim();
     if (!normalized)
         return false;
-    const candidates = [wsPath("agent-state", normalized), wsPath(normalized)];
-    if (candidates.some((candidate) => existsSync(candidate)))
+    const relativeCandidates = [
+        normalized,
+        normalized.startsWith("agent-state/") ? normalized : `agent-state/${normalized}`,
+    ];
+    const absoluteCandidates = relativeCandidates.map((candidate) => wsPath(candidate));
+    if (absoluteCandidates.some((candidate) => existsSync(candidate)))
         return true;
-    return candidates.some((candidate) => {
+    return relativeCandidates.some((candidate) => {
         const content = safeRead(candidate);
         return !content.startsWith("[FILE NOT FOUND]") && !content.startsWith("[ACCESS DENIED]");
     });
@@ -1216,6 +1201,27 @@ export function registerFrameworkTools(server) {
             ok: isGitRepo(),
             detail: isGitRepo() ? "initialized" : "NOT a git repo",
         });
+        // Check: malformed store events were not silently dropped.
+        const storePath = getWorkspaceStorePath(resolveWorkspaceRoot());
+        if (existsSync(storePath)) {
+            try {
+                const store = await openStore(storePath, { readOnly: true });
+                const skipped = store.skippedMalformedEventCount;
+                await store.close();
+                checks.push({
+                    name: "acepack:skipped-malformed-events",
+                    ok: skipped === 0,
+                    detail: skipped === 0 ? "0 skipped malformed events" : `${skipped} skipped malformed events`,
+                });
+            }
+            catch (error) {
+                checks.push({
+                    name: "acepack:skipped-malformed-events",
+                    ok: false,
+                    detail: `store validation failed: ${error instanceof Error ? error.message : String(error)}`,
+                });
+            }
+        }
         // ── Deep checks (P2 hardening) ─────────────────────────────────
         // Check: module registry role coverage vs event emitters
         const registryRaw = safeRead("agent-state/MODULES/registry.json");
@@ -1385,7 +1391,9 @@ export function registerFrameworkTools(server) {
                         result.ok
                             ? `✅ Public surface audit passed (${result.summary.tools} tools, ${result.summary.resources} resources, ${result.summary.prompts} prompts)`
                             : `❌ Public surface audit failed (${result.failures.length} failure${result.failures.length === 1 ? "" : "s"})`,
-                        `Report: ${result.report_path}`,
+                        `Artifact: ${result.artifact_path}`,
+                        `Read: ace read ${result.artifact_path}`,
+                        ...(result.written_path ? [`Store path: ${result.written_path}`] : []),
                         `Events: ${result.summary.emitted_events}`,
                         ...(result.failures.slice(0, 12).map((entry) => `- ${entry}`)),
                         ...(result.warnings.slice(0, 12).map((entry) => `- warning: ${entry}`)),
@@ -1406,8 +1414,9 @@ export function registerFrameworkTools(server) {
     }, async ({ write_artifact, artifact_path }) => {
         const result = auditStoreAuthority();
         const reportPath = artifact_path ?? result.report_path;
+        let writtenPath;
         if (write_artifact !== false) {
-            writeStoreAuthorityAuditReport({
+            writtenPath = writeStoreAuthorityAuditReport({
                 ...result,
                 report_path: reportPath,
             }, reportPath);
@@ -1418,7 +1427,9 @@ export function registerFrameworkTools(server) {
                     type: "text",
                     text: [
                         `✅ Store authority audit completed (${result.total_safe_write_sites} safeWrite users)`,
-                        `Report: ${reportPath}`,
+                        `Artifact: ${reportPath}`,
+                        `Read: ace read ${reportPath}`,
+                        ...(writtenPath ? [`Store path: ${writtenPath}`] : []),
                         `Bypassing ACEPACK: ${result.bypassing_sites.length}`,
                         `Runtime files without fallback keys: ${result.runtime_files_without_store_fallback_keys.length}`,
                         `Non-regenerable projections: ${result.non_regenerable_projections.length}`,
@@ -1436,7 +1447,7 @@ export function registerFrameworkTools(server) {
         gate_ids: z
             .array(z.string())
             .optional()
-            .describe("Specific gate IDs to run (e.g. ['gate-correctness']). Omit to run all registered gates."),
+            .describe("Specific gate IDs to run (e.g. ['gate-correctness']). Omit to run the active stage's stage-activated workspace gates."),
         review_mode: z
             .enum(["skeptic_adversarial"])
             .optional()
@@ -1449,25 +1460,102 @@ export function registerFrameworkTools(server) {
         const gatesDir = wsPath("agent-state", "MODULES", "gates");
         const resolved = resolveGateManifests(gatesDir);
         const allGates = resolved.gates;
-        const gateEvidenceRef = resolved.source === "store" ? "knowledge/gates/*" : "agent-state/MODULES/gates/";
-        // Filter to requested gates (or run all)
-        const targets = gate_ids
-            ? allGates.filter((g) => gate_ids.includes(g.id))
-            : allGates;
+        const manifestEvidenceRef = resolved.source === "store" ? "knowledge/gates/*" : "agent-state/MODULES/gates/";
+        const selection = resolveGateSelection({
+            gates: allGates,
+            manifestSource: resolved.source,
+            statusRaw: safeRead("agent-state/STATUS.md"),
+            tealRaw: safeRead("agent-state/TEAL_CONFIG.md"),
+            gateIds: gate_ids,
+        });
+        const targets = selection.selected;
         if (targets.length === 0) {
-            const noGateMessage = allGates.length === 0
-                ? "❌ No gate manifests found in agent-state/MODULES/gates/ or ace-state.ace knowledge/gates/*."
-                : `❌ No matching gates found. Available: ${allGates.map((g) => g.id).join(", ")}`;
+            if (allGates.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ No gate manifests found in agent-state/MODULES/gates/ or ace-state.ace knowledge/gates/*.",
+                        },
+                    ],
+                };
+            }
+            if (selection.selection_mode === "explicit") {
+                const noGateMessage = selection.missing_explicit_gate_ids.length > 0
+                    ? `❌ No matching gates found for: ${selection.missing_explicit_gate_ids.join(", ")}. Available: ${allGates.map((g) => g.id).join(", ")}`
+                    : `❌ No matching gates found. Available: ${allGates.map((g) => g.id).join(", ")}`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: noGateMessage,
+                        },
+                    ],
+                };
+            }
+            const message = selection.note ??
+                "No stage-activated workspace gates were selected for the active ACE stage. Use explicit gate_ids when needed.";
+            await appendStatusEventSafe({
+                source_module: "capability-framework",
+                event_type: "GATES_EXECUTED",
+                status: "pass",
+                summary: message,
+                payload: {
+                    gates_run: [],
+                    gate_results: [],
+                    passed: 0,
+                    failed: 0,
+                    selection_mode: selection.selection_mode,
+                    selected_gate_ids: [],
+                    skipped_gate_ids: selection.skipped_gate_ids,
+                    gate_manifest_source: resolved.source,
+                    active_role: selection.active_role ?? null,
+                    active_module: selection.active_module ?? null,
+                    active_pipeline: selection.active_pipeline ?? null,
+                    selection_note: message,
+                    evidence_ref: manifestEvidenceRef,
+                },
+                objective_id: "gate-execution",
+            });
+            const ledger = await appendRunLedgerEntrySafe({
+                tool: "execute_gates",
+                category: "info",
+                message,
+                artifacts: [],
+                metadata: {
+                    passed: 0,
+                    failed: 0,
+                    selection_mode: selection.selection_mode,
+                    selected_gate_ids: [],
+                    skipped_gate_ids: selection.skipped_gate_ids,
+                    gate_manifest_source: resolved.source,
+                    active_role: selection.active_role ?? null,
+                    active_module: selection.active_module ?? null,
+                    active_pipeline: selection.active_pipeline ?? null,
+                    selection_note: message,
+                },
+            });
             return {
                 content: [
                     {
                         type: "text",
-                        text: noGateMessage,
+                        text: [
+                            `ℹ️ ${message}`,
+                            `Selection mode: ${selection.selection_mode}`,
+                            `Active role/module: ${selection.active_role ?? "(unknown)"} / ${selection.active_module ?? "(unknown)"}`,
+                            `Active pipeline: ${selection.active_pipeline ?? "(unknown)"}`,
+                            `Selected gates: none`,
+                            `Skipped gates: ${selection.skipped_gate_ids.length > 0 ? selection.skipped_gate_ids.join(", ") : "none"}`,
+                            `Gate manifest source: ${resolved.source === "store"
+                                ? "ace-state.ace (knowledge/gates/*)"
+                                : "agent-state/MODULES/gates/"}`,
+                            `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                        ].join("\n"),
                     },
                 ],
             };
         }
-        const gateArtifactRefs = targets.map((gate) => gate.source_ref ?? gateEvidenceRef);
+        const gateArtifactRefs = targets.map((gate) => gate.source_ref ?? manifestEvidenceRef);
         const results = evaluateGateTargets(targets);
         const passed = results.filter((r) => r.ok).length;
         const failed = results.filter((r) => !r.ok).length;
@@ -1495,7 +1583,13 @@ export function registerFrameworkTools(server) {
                 })),
                 passed,
                 failed,
-                evidence_ref: evidence?.evidenceRef ?? gateEvidenceRef,
+                evidence_ref: evidence?.evidenceRef ?? manifestEvidenceRef,
+                selection_mode: selection.selection_mode,
+                active_role: selection.active_role ?? null,
+                active_module: selection.active_module ?? null,
+                active_pipeline: selection.active_pipeline ?? null,
+                selected_gate_ids: results.map((r) => r.id),
+                skipped_gate_ids: selection.skipped_gate_ids,
                 gate_manifest_source: resolved.source,
                 ...(review
                     ? {
@@ -1530,6 +1624,13 @@ export function registerFrameworkTools(server) {
                 passed,
                 failed,
                 gate_ids: results.map((r) => r.id),
+                selection_mode: selection.selection_mode,
+                active_role: selection.active_role ?? null,
+                active_module: selection.active_module ?? null,
+                active_pipeline: selection.active_pipeline ?? null,
+                selected_gate_ids: results.map((r) => r.id),
+                skipped_gate_ids: selection.skipped_gate_ids,
+                missing_explicit_gate_ids: selection.missing_explicit_gate_ids,
                 gate_manifest_source: resolved.source,
                 ...(review
                     ? {
@@ -1559,6 +1660,11 @@ export function registerFrameworkTools(server) {
                         `Gate manifest source: ${resolved.source === "store"
                             ? "ace-state.ace (knowledge/gates/*)"
                             : "agent-state/MODULES/gates/"}`,
+                        `Selection mode: ${selection.selection_mode}`,
+                        `Active role/module: ${selection.active_role ?? "(unknown)"} / ${selection.active_module ?? "(unknown)"}`,
+                        `Active pipeline: ${selection.active_pipeline ?? "(unknown)"}`,
+                        `Selected gates: ${results.map((r) => r.id).join(", ")}`,
+                        `Skipped gates: ${selection.skipped_gate_ids.length > 0 ? selection.skipped_gate_ids.join(", ") : "none"}`,
                         `Run ledger: ${ledger.path} (${ledger.entry.id})`,
                         ...(evidence ? [`Evidence: ${evidence.path} (${evidence.evidenceRef})`] : []),
                         "",

package/dist/tools-goal.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ACE Goal Engine tool registrations (WS-F).
+ *
+ * These let a premium host delegate a long-running objective to ACE and poll
+ * it. `start_goal`/`resume_goal` never block the MCP server for the life of the
+ * goal: they compile/prepare, then hand execution to a detached `ace goal run`
+ * child and return immediately. The host polls `get_goal_status`.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGoalTools(server: McpServer): void;
+//# sourceMappingURL=tools-goal.d.ts.map

package/dist/tools-goal.js

@@ -0,0 +1,108 @@
+/**
+ * ACE Goal Engine tool registrations (WS-F).
+ *
+ * These let a premium host delegate a long-running objective to ACE and poll
+ * it. `start_goal`/`resume_goal` never block the MCP server for the life of the
+ * goal: they compile/prepare, then hand execution to a detached `ace goal run`
+ * child and return immediately. The host polls `get_goal_status`.
+ */
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { getGoalStatus, listGoals, startGoal, stopGoal, } from "./goal-engine.js";
+function asJsonBlock(value) {
+    return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
+function spawnDetachedRunner(goalId, verb) {
+    try {
+        // dist/cli.js is a sibling of this compiled module.
+        const cliPath = fileURLToPath(new URL("./cli.js", import.meta.url));
+        const child = spawn(process.execPath, [cliPath, "goal", verb, goalId], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+        return child.pid;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function registerGoalTools(server) {
+    server.tool("start_goal", "Compile and launch a long-running autonomous goal (ACE plans it, executes step-by-step under evidence-gated completion, and can never declare success by prose). Returns immediately; poll with get_goal_status.", {
+        objective: z.string().min(1).describe("What the goal should accomplish"),
+        budget_hours: z.number().positive().max(24).optional().describe("Wall-clock budget (default 4h)"),
+        max_replans: z.number().int().min(0).max(20).optional().describe("Max plan-level replans (default 3)"),
+        plan_only: z.boolean().optional().describe("Compile + validate the plan but do not execute"),
+        detach: z.boolean().optional().describe("Run in a detached background child (default true when not plan_only)"),
+    }, async ({ objective, budget_hours, max_replans, plan_only, detach }) => {
+        const started = await startGoal(objective, { budget_hours, max_replans, plan_only });
+        let runnerPid;
+        if (started.ok && !plan_only && detach !== false) {
+            runnerPid = spawnDetachedRunner(started.goal.goal_id, "run");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        started.ok ? "✅ Goal started" : "❌ Goal not started",
+                        `goal_id: ${started.goal.goal_id}`,
+                        `status: ${started.goal.status}`,
+                        started.reason_code ? `reason: ${started.reason_code}` : "",
+                        runnerPid ? `detached runner pid: ${runnerPid}` : "",
+                        asJsonBlock({ ...started, runner_pid: runnerPid }),
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("get_goal_status", "Get a goal's status (tick count, current step, last heartbeat, escalations, plan status), or list all goals when no goal_id is given.", {
+        goal_id: z.string().optional().describe("Goal id; omit to list all goals"),
+    }, async ({ goal_id }) => {
+        if (!goal_id) {
+            return {
+                content: [{ type: "text", text: asJsonBlock({ goals: listGoals() }) }],
+            };
+        }
+        const view = getGoalStatus(goal_id);
+        if (!view) {
+            return { content: [{ type: "text", text: `❌ Unknown goal: ${goal_id}` }] };
+        }
+        return { content: [{ type: "text", text: asJsonBlock(view) }] };
+    });
+    server.tool("stop_goal", "Request that a running goal stop at its next tick boundary.", { goal_id: z.string().describe("Goal id to stop") }, async ({ goal_id }) => {
+        try {
+            const goal = stopGoal(goal_id);
+            return {
+                content: [{ type: "text", text: `🛑 Stop requested for ${goal.goal_id} (status ${goal.status}).` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `❌ ${err instanceof Error ? err.message : String(err)}` }],
+            };
+        }
+    });
+    server.tool("resume_goal", "Resume a blocked/stopped goal: reset any step left running mid-crash and continue execution in a detached runner.", { goal_id: z.string().describe("Goal id to resume") }, async ({ goal_id }) => {
+        const view = getGoalStatus(goal_id);
+        if (!view) {
+            return { content: [{ type: "text", text: `❌ Unknown goal: ${goal_id}` }] };
+        }
+        const runnerPid = spawnDetachedRunner(goal_id, "resume");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `▶️ Resuming ${goal_id}`,
+                        runnerPid ? `detached runner pid: ${runnerPid}` : "runner spawn failed; run `ace goal resume` manually",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-goal.js.map