@voybio/ace-swarm 0.2.4 → 2.4.0

package/dist/tools-files.js

@@ -1,18 +1,66 @@
 /**
  * File operation tool registrations + new safe-edit and diff tools.
  */
-import { readdirSync } from "node:fs";
-import { isAbsolute, relative } from "node:path";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWrite, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
-import { looksLikeSwarmHandoffPath } from "./shared.js";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, 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";
-import { validateRuntimeProfileContent } from "./runtime-profile.js";
 import { shouldAutoRefreshKanbanForPath, refreshKanbanArtifacts, } from "./kanban.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
-import { safeEditFile, diffContents } from "./safe-edit.js";
+import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
+import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
+import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
+export function planAstgrepRewriteTargets(files) {
+    const affected = [...new Set(files.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+    if (affected.length > 1) {
+        return {
+            ok: false,
+            affected_files: affected,
+            error: `astgrep_rewrite refuses multi-file rewrites (${affected.length} files): ${affected.slice(0, 5).join(", ")}`,
+        };
+    }
+    return {
+        ok: true,
+        affected_files: affected,
+        target_file: affected[0],
+    };
+}
+async function appendAstgrepRewriteTransition(sessionId, to, reason, evidenceRefs) {
+    if (!sessionId)
+        return;
+    await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => {
+        await repo.appendTransitionRecord({
+            subject_kind: "plan_step",
+            subject_id: `${sessionId}/astgrep_rewrite`,
+            from: "staged",
+            to,
+            reason,
+            reason_code: to === "promoted" ? "surgical_rewrite" : "surgical_rewrite_failed",
+            evidence_refs: evidenceRefs,
+        });
+    }).catch(() => undefined);
+}
+function astgrepFileToWorkspaceRel(file) {
+    const abs = isAbsolute(file) ? file : resolve(WORKSPACE_ROOT, file);
+    if (!isInside(WORKSPACE_ROOT, abs))
+        return undefined;
+    return normalizeRelPath(relative(WORKSPACE_ROOT, abs));
+}
+async function resolveReadFileLinesBudget() {
+    let modelClass;
+    const statuses = await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => repo.listRuntimeStatuses()).catch(() => undefined);
+    modelClass = statuses?.[0]?.model_class;
+    const profile = readRuntimeProfile();
+    const resolved = resolveEffectiveSurgicalReadBudget(profile, modelClass);
+    return {
+        ...resolved,
+        source: modelClass ? "runtime-status" : "runtime-profile",
+    };
+}
 export function registerFileTools(server) {
     // ── Append-only artifact protection ───────────────────────────────
     // These files must only grow; overwrites from the generic write tool
@@ -26,12 +74,12 @@ export function registerFileTools(server) {
         "agent-state/PROVENANCE_LOG.md",
     ]);
     // ── Core file operations ──────────────────────────────────────────
-    server.tool("read_workspace_file", "Read any workspace file by relative path", {
+    server.tool("read_workspace_file", "Read any workspace file by relative path. Prefer outline_file for discovery, read_file_lines for known regions, astgrep_query for symbol lookup. For small_local runs, this is the fallback after surgical reads are insufficient. Cost: heavy for large files.", {
         path: z.string().describe("Relative path from workspace root"),
     }, async ({ path }) => ({
         content: [{ type: "text", text: safeRead(path) }],
     }));
-    server.tool("write_workspace_file", "Write or update a workspace file", {
+    server.tool("write_workspace_file", "Write or update a workspace file. Prefer apply_patch for targeted edits, astgrep_rewrite for structural rewrites. Cost: heavy.", {
         path: z.string().describe("Relative path from workspace root"),
         content: z.string().describe("File content"),
     }, async ({ path, content }) => {
@@ -475,8 +523,10 @@ export function registerFileTools(server) {
             const synced = await syncTodoStateSafe(content);
             todoStateSuffix = `\nTODO state synced: ${synced.path}`;
         }
+        const storeFallbackKeys = resolveStoreFallbackKeysForPath(normalizedPath);
+        const useAsyncStoreAdmission = storeFallbackKeys.length > 0;
         // Keep the file as a materialized projection after the canonical store update.
-        const abs = safeWrite(path, content);
+        const abs = useAsyncStoreAdmission ? await safeWriteAsync(path, content) : safeWrite(path, content);
         let kanbanSuffix = "";
         const shouldRefreshKanban = shouldAutoRefreshKanbanForPath(normalizedPath);
         if (shouldRefreshKanban) {
@@ -544,7 +594,7 @@ export function registerFileTools(server) {
         }
     });
     // ── Safe-edit (new P0 tool) ───────────────────────────────────────
-    server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail.", {
+    server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail. Prefer apply_patch for small targeted edits. Cost: heavy for large files.", {
         path: z.string().describe("Workspace-relative file path to edit"),
         content: z.string().describe("New file content"),
         validation_command: z
@@ -676,5 +726,244 @@ export function registerFileTools(server) {
             ],
         };
     });
+    // ── Surgical read / query / patch tools ──────────────────────────
+    server.tool("read_file_lines", "Read a specific line range from a workspace file. Prefer this over read_workspace_file for large files. Cost: moderate.", {
+        path: z.string().describe("Workspace-relative file path"),
+        start_line: z.number().int().min(1).describe("First line to read (1-indexed)"),
+        end_line: z.number().int().min(1).describe("Last line to read (inclusive)"),
+        symbol_anchor: z.string().optional().describe("Optional symbol name hint for context (informational only)"),
+    }, async ({ path: relPath, start_line, end_line, symbol_anchor }) => {
+        const budget = await resolveReadFileLinesBudget();
+        const requestedLines = end_line - start_line + 1;
+        const budgetText = budget.read_file_lines_max_lines === null
+            ? "unbounded"
+            : String(budget.read_file_lines_max_lines);
+        const headerLines = [
+            `# Budget: model_class=${budget.model_class}; read_file_lines_max_lines=${budgetText}`,
+            `# Budget source: ${budget.source}`,
+        ];
+        if (budget.read_file_lines_max_lines !== null &&
+            requestedLines > budget.read_file_lines_max_lines) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            ...headerLines,
+                            `Error: requested range (${requestedLines} lines) exceeds ${budget.model_class} budget of ${budgetText} lines.`,
+                            "Use outline_file for discovery or astgrep_query for symbol lookup.",
+                        ].join("\n"),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const content = safeRead(relPath);
+        const lines = content.split("\n");
+        const slice = lines.slice(start_line - 1, end_line);
+        const result = slice.map((l, i) => `${start_line + i}: ${l}`).join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        ...headerLines,
+                        `# ${relPath} (lines ${start_line}–${end_line})`,
+                        symbol_anchor ? `# Symbol context: ${symbol_anchor}` : "",
+                        "",
+                        result,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("outline_file", "Return symbol signatures and top-level structure of a file without bodies. Use for discovery before reading specific regions. Cost: cheap.", {
+        path: z.string().describe("Workspace-relative file path"),
+    }, async ({ path: relPath }) => {
+        const content = safeRead(relPath);
+        const lines = content.split("\n");
+        const outlinePatterns = [
+            /^export\s+(async\s+)?function\s+\w+/,
+            /^export\s+(class|interface|type|enum|const|abstract)\s+\w+/,
+            /^(export\s+)?default\s+/,
+            /^\s+(async\s+)?(\w+\s+)?\w+\s*\([^)]*\)\s*[:{]/,
+            /^(function|class|interface|type|enum|const|let|var)\s+\w+/,
+        ];
+        const outline = [];
+        lines.forEach((line, idx) => {
+            if (outlinePatterns.some(p => p.test(line))) {
+                outline.push(`${idx + 1}: ${line.trimEnd()}`);
+            }
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# Outline: ${relPath} (${lines.length} lines total)`,
+                        "",
+                        outline.length > 0 ? outline.join("\n") : "(no symbols found)",
+                    ].join("\n"),
+                }],
+        };
+    });
+    server.tool("astgrep_query", "Search for a structural pattern in workspace files using ast-grep. Returns matching ranges without reading whole files. Cost: cheap.", {
+        pattern: z.string().describe("ast-grep pattern, e.g. 'export function $NAME($$$)'"),
+        lang: z.string().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory to search (default: src)"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max results to return (default: 50)"),
+    }, async ({ pattern, lang, scope, max_results }) => {
+        const { runAstgrepQuery } = await import("./astgrep-index.js");
+        const root = wsPath(scope ?? "src");
+        const matches = runAstgrepQuery(pattern, lang, [root]);
+        const limited = matches.slice(0, max_results ?? 50);
+        const lines = limited.map((m) => `${m.file}:${m.line}: ${m.text}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# astgrep_query: ${pattern} (${lang})`,
+                        `# Found ${matches.length} matches, showing ${limited.length}`,
+                        "",
+                        ...lines,
+                    ].join("\n"),
+                }],
+        };
+    });
+    server.tool("astgrep_rewrite", "Apply a structural rewrite to one workspace file using ast-grep pattern + replacement. Multi-file rewrites are refused; staged through safe_edit_file. Emits transition-compatible result details. Cost: heavy.", {
+        pattern: z.string().describe("ast-grep pattern to match"),
+        rewrite: z.string().describe("Replacement template (use $NAME etc. from pattern)"),
+        lang: z.string().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src)"),
+        confirm_multi_file: z.boolean().optional().describe("Deprecated; multi-file rewrites are always refused"),
+        validation_command: z.string().optional().describe("Shell command to validate the staged rewrite before promotion"),
+        test_command: z.string().optional().describe("Shell command to test the staged rewrite before promotion"),
+        session_id: z.string().optional().describe("Optional runtime session id for transition-record emission"),
+    }, async ({ pattern, rewrite, lang, scope, validation_command, test_command, session_id }) => {
+        const { runAstgrepQuery } = await import("./astgrep-index.js");
+        const root = wsPath(scope ?? "src");
+        if (!isInside(WORKSPACE_ROOT, root)) {
+            return {
+                content: [{ type: "text", text: `astgrep_rewrite failed: scope escapes workspace root (${scope})` }],
+                isError: true,
+            };
+        }
+        const matches = runAstgrepQuery(pattern, lang, [root]);
+        const affectedFiles = [...new Set(matches.map(m => m.file))];
+        const plan = planAstgrepRewriteTargets(affectedFiles);
+        if (!plan.ok) {
+            await appendAstgrepRewriteTransition(session_id, "refused", plan.error ?? "astgrep_rewrite refused the requested rewrite", plan.affected_files);
+            return {
+                content: [{
+                        type: "text",
+                        text: plan.error ?? "astgrep_rewrite refused the requested rewrite",
+                    }],
+                isError: true,
+            };
+        }
+        if (matches.length === 0) {
+            return {
+                content: [{ type: "text", text: "No matches found for pattern. No files modified." }],
+            };
+        }
+        const targetRel = astgrepFileToWorkspaceRel(plan.target_file ?? "");
+        if (!targetRel) {
+            return {
+                content: [{ type: "text", text: `astgrep_rewrite failed: matched path escapes workspace root (${plan.target_file ?? ""})` }],
+                isError: true,
+            };
+        }
+        const originalContent = safeRead(targetRel);
+        if (originalContent.startsWith("[FILE NOT FOUND]") || originalContent.startsWith("[ACCESS DENIED]")) {
+            return {
+                content: [{ type: "text", text: `astgrep_rewrite failed: cannot read ${targetRel}\n${originalContent}` }],
+                isError: true,
+            };
+        }
+        const stagingDir = wsPath(".ace-staging", `astgrep-rewrite-${Date.now()}`);
+        const stagedFile = resolve(stagingDir, targetRel);
+        mkdirSync(dirname(stagedFile), { recursive: true });
+        writeFileSync(stagedFile, originalContent, "utf-8");
+        const { spawnSync } = await import("node:child_process");
+        const result = spawnSync("ast-grep", ["--pattern", pattern, "--rewrite", rewrite, "--lang", lang, stagedFile, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+        if (result.status !== 0) {
+            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed in staging: ${result.stderr || result.stdout || "unknown error"}`, [targetRel]);
+            return {
+                content: [{ type: "text", text: `astgrep rewrite failed:\n${result.stderr}` }],
+                isError: true,
+            };
+        }
+        const rewrittenContent = readFileSync(stagedFile, "utf-8");
+        const safeResult = safeEditFile({
+            path: targetRel,
+            content: rewrittenContent,
+            validation_command,
+            test_command,
+        });
+        if (!safeResult.ok) {
+            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed before promotion for ${targetRel}: ${safeResult.error ?? "unknown error"}`, [targetRel]);
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `astgrep_rewrite failed before promotion`,
+                            `Path: ${targetRel}`,
+                            `Error: ${safeResult.error ?? "unknown error"}`,
+                            safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "FAILED"}` : "Validation: not requested",
+                            safeResult.validation_output ? `Validation output:\n${safeResult.validation_output}` : "",
+                            safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "FAILED"}` : "Tests: not requested",
+                            safeResult.test_output ? `Test output:\n${safeResult.test_output}` : "",
+                            `Staging: ${safeResult.staging_path || stagingDir}`,
+                        ].filter(Boolean).join("\n"),
+                    }],
+                isError: true,
+            };
+        }
+        await appendAstgrepRewriteTransition(session_id, "promoted", `astgrep_rewrite promoted staged rewrite for ${targetRel}`, [targetRel]);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# astgrep_rewrite completed`,
+                        `Pattern: ${pattern}`,
+                        `Rewrite: ${rewrite}`,
+                        `Files affected: ${affectedFiles.length}`,
+                        `Path: ${targetRel}`,
+                        `Hash: ${safeResult.original_hash} → ${safeResult.new_hash}`,
+                        safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "failed"}` : "Validation: not requested",
+                        safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "failed"}` : "Tests: not requested",
+                        `Staging: ${safeResult.staging_path}`,
+                        result.stdout ? `\nOutput:\n${result.stdout}` : "",
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    });
+    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)"),
+        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 });
+        if (!result.ok) {
+            return {
+                content: [{ type: "text", text: `apply_patch failed: ${result.error ?? "unknown error"}\n${result.validation_output ?? ""}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# apply_patch: ${relPath}`,
+                        `Status: success`,
+                        result.validation_passed !== undefined ? `Validation: ${result.validation_passed ? "passed" : "failed"}` : "",
+                        result.test_passed !== undefined ? `Tests: ${result.test_passed ? "passed" : "failed"}` : "",
+                        `Staging: ${result.staging_path}`,
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    });
 }
 //# sourceMappingURL=tools-files.js.map

package/dist/tools-framework.js

@@ -4,7 +4,7 @@
  */
 import { z } from "zod";
 import { bootstrapStoreWorkspace } from "./store/bootstrap-store.js";
-import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, safeRead, safeWrite, withFileLock, wsPath, } from "./helpers.js";
+import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, ALL_MCP_CLIENTS, ALL_LLM_PROVIDERS, ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, WORKSPACE_ROOT, classifyPathSource, detectAssetDrift, getAllMcpServerConfigSnippets, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, getMcpClientInstallHint, getMcpServerConfigSnippet, getTaskArtifactPath, isSwarmRole, listAvailableSkills, normalizePathForValidation, resolveWorkspaceRoot, safeRead, safeWriteAsync, withFileLock, wsPath, } from "./helpers.js";
 import { getRoleTitle, MCP_CLIENT_ENUM, scoreDomains, } from "./shared.js";
 import { defaultModelForProvider, } from "./tui/provider-discovery.js";
 import { refreshAstgrepIndex } from "./astgrep-index.js";
@@ -20,6 +20,21 @@ import { auditPublicSurface } from "./public-surface.js";
 import { auditStoreAuthority, writeStoreAuthorityAuditReport, } from "./store/store-authority-audit.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";
+function executionRoleForDomain(domain) {
+    switch (domain) {
+        case "venture":
+            return "vos";
+        case "ux":
+            return "ui";
+        case "engineering":
+            return "coders";
+        case "research":
+            return "research";
+        default:
+            return "orchestrator";
+    }
+}
 function getArtifactManifestEntries(payload) {
     if (!payload || typeof payload !== "object" || Array.isArray(payload))
         return [];
@@ -38,15 +53,37 @@ 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 readGateManifests(gatesDir) {
     const files = readdirSync(gatesDir).filter((f) => f.endsWith(".json"));
     const allGates = [];
     for (const file of files) {
         try {
             const raw = readFileSync(resolve(gatesDir, file), "utf-8");
-            const gate = JSON.parse(raw);
-            if (gate.id)
-                allGates.push(gate);
+            const parsed = parseGateManifest(raw, `agent-state/MODULES/gates/${file}`);
+            if (parsed)
+                allGates.push(parsed);
         }
         catch {
             /* skip corrupt manifests */
@@ -54,6 +91,44 @@ function readGateManifests(gatesDir) {
     }
     return allGates;
 }
+function readStoreGateManifests(workspaceRoot) {
+    const gateKeys = listStoreKeysSync(workspaceRoot, "knowledge/gates/").filter((key) => key.endsWith(".json"));
+    const allGates = [];
+    for (const key of gateKeys) {
+        const raw = readStoreBlobSync(workspaceRoot, key);
+        if (typeof raw !== "string")
+            continue;
+        const parsed = parseGateManifest(raw, key);
+        if (parsed)
+            allGates.push(parsed);
+    }
+    return allGates;
+}
+function resolveGateManifests(gatesDir) {
+    if (existsSync(gatesDir)) {
+        const workspaceGates = readGateManifests(gatesDir);
+        if (workspaceGates.length > 0) {
+            return { gates: workspaceGates, source: "workspace" };
+        }
+    }
+    const storeGates = readStoreGateManifests(resolveWorkspaceRoot());
+    if (storeGates.length > 0) {
+        return { gates: storeGates, source: "store" };
+    }
+    return { gates: [], source: "none" };
+}
+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)))
+        return true;
+    return candidates.some((candidate) => {
+        const content = safeRead(candidate);
+        return !content.startsWith("[FILE NOT FOUND]") && !content.startsWith("[ACCESS DENIED]");
+    });
+}
 function evaluateGateTargets(targets) {
     const results = [];
     for (const gate of targets) {
@@ -97,7 +172,7 @@ function evaluateGateTargets(targets) {
                 }
                 else {
                     for (const artifact of relevantArtifacts) {
-                        if (!existsSync(wsPath("agent-state", artifact))) {
+                        if (!hasArtifactEvidence(artifact)) {
                             missing.push(artifact);
                         }
                     }
@@ -109,11 +184,9 @@ function evaluateGateTargets(targets) {
                     .map((s) => s.trim())
                     .filter(Boolean);
                 for (const ref of evidenceFiles) {
-                    const candidates = [wsPath("agent-state", ref), wsPath(ref)];
-                    const found = candidates.some((candidate) => existsSync(candidate));
-                    if (!found) {
+                    if (!hasArtifactEvidence(ref)) {
                         const asFile = ref.replace(/\s+/g, "_").replace(/[^a-zA-Z0-9_./-]/g, "");
-                        const fileFound = existsSync(wsPath("agent-state", asFile));
+                        const fileFound = hasArtifactEvidence(asFile);
                         if (!fileFound)
                             missing.push(ref);
                     }
@@ -228,7 +301,7 @@ async function appendEvidenceLogEntrySafe(review) {
     const timestamp = new Date().toISOString();
     const anchor = `#ts:${timestamp}`;
     const evidenceRef = `agent-state/EVIDENCE_LOG.md${anchor}`;
-    return withFileLock("agent-state/EVIDENCE_LOG.md", () => {
+    return withFileLock("agent-state/EVIDENCE_LOG.md", async () => {
         const existing = safeRead("agent-state/EVIDENCE_LOG.md");
         const seed = existing.startsWith("[FILE NOT FOUND]") || existing.startsWith("[ACCESS DENIED]")
             ? "# EVIDENCE LOG\n\nAppend-only validation evidence.\n\n## Entries\n"
@@ -260,7 +333,7 @@ async function appendEvidenceLogEntrySafe(review) {
                 })
                 : ["  - none"]),
         ];
-        const path = safeWrite("agent-state/EVIDENCE_LOG.md", `${seed}${lines.join("\n")}\n`);
+        const path = await safeWriteAsync("agent-state/EVIDENCE_LOG.md", `${seed}${lines.join("\n")}\n`);
         return { path, evidenceRef };
     });
 }
@@ -475,6 +548,12 @@ export function registerFrameworkTools(server) {
             recommendedSubagents.add("memory");
         }
         return {
+            structuredContent: {
+                detected_domain: detected,
+                suggested_execution_role: executionRoleForDomain(detected),
+                default_entry_agent: "orchestrator",
+                task_contract_ok: taskContract.ok,
+            },
             content: [
                 {
                     type: "text",
@@ -576,7 +655,7 @@ export function registerFrameworkTools(server) {
             model: resolvedLlmModel ?? undefined,
             baseUrl: resolvedLlmBaseUrl ?? undefined,
         });
-        const astIndex = refreshAstgrepIndex({
+        const astIndex = await refreshAstgrepIndex({
             scope: ".",
             append_evidence: true,
             emit_event: true,
@@ -603,7 +682,7 @@ export function registerFrameworkTools(server) {
             category: "major_update",
             message: "Bootstrapped ACE workspace state",
             artifacts: [
-                `${ACE_ROOT_REL}/ace-state.ace`,
+                storeResult.storePath,
                 `${ACE_TASKS_ROOT_REL}/todo.md`,
                 normalizePathForValidation(delta.index_path),
                 "agent-state/AST_GREP_INDEX.json",
@@ -1349,31 +1428,27 @@ export function registerFrameworkTools(server) {
             .describe("Optional short focus string persisted with skeptic adversarial review evidence."),
     }, async ({ gate_ids, review_mode, review_focus }) => {
         const gatesDir = wsPath("agent-state", "MODULES", "gates");
-        if (!existsSync(gatesDir)) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "❌ Gates directory not found: agent-state/MODULES/gates/",
-                    },
-                ],
-            };
-        }
-        const allGates = readGateManifests(gatesDir);
+        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;
         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(", ")}`;
             return {
                 content: [
                     {
                         type: "text",
-                        text: `❌ No matching gates found. Available: ${allGates.map((g) => g.id).join(", ")}`,
+                        text: noGateMessage,
                     },
                 ],
             };
         }
+        const gateArtifactRefs = targets.map((gate) => gate.source_ref ?? gateEvidenceRef);
         const results = evaluateGateTargets(targets);
         const passed = results.filter((r) => r.ok).length;
         const failed = results.filter((r) => !r.ok).length;
@@ -1401,7 +1476,8 @@ export function registerFrameworkTools(server) {
                 })),
                 passed,
                 failed,
-                evidence_ref: evidence?.evidenceRef ?? "agent-state/MODULES/gates/",
+                evidence_ref: evidence?.evidenceRef ?? gateEvidenceRef,
+                gate_manifest_source: resolved.source,
                 ...(review
                     ? {
                         review: {
@@ -1428,13 +1504,14 @@ export function registerFrameworkTools(server) {
                 ? `Gate execution with skeptic review: ${review.summary.confirmed_count} confirmed findings`
                 : `Gate execution: ${passed}/${results.length} passed`,
             artifacts: [
-                ...results.map((r) => `agent-state/MODULES/gates/${r.id}.json`),
+                ...gateArtifactRefs,
                 ...(evidence ? ["agent-state/EVIDENCE_LOG.md"] : []),
             ],
             metadata: {
                 passed,
                 failed,
                 gate_ids: results.map((r) => r.id),
+                gate_manifest_source: resolved.source,
                 ...(review
                     ? {
                         review_mode: review.mode,
@@ -1460,6 +1537,9 @@ export function registerFrameworkTools(server) {
                             : allOk
                                 ? `✅ All gates passed: ${passed}/${results.length}`
                                 : `❌ Gate failures: ${failed}/${results.length} failed`,
+                        `Gate manifest source: ${resolved.source === "store"
+                            ? "ace-state.ace (knowledge/gates/*)"
+                            : "agent-state/MODULES/gates/"}`,
                         `Run ledger: ${ledger.path} (${ledger.entry.id})`,
                         ...(evidence ? [`Evidence: ${evidence.path} (${evidence.evidenceRef})`] : []),
                         "",

package/dist/tools-handoff.js

@@ -3,7 +3,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, readTaskArtifact, safeWrite, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, readTaskArtifact, safeWriteAsync, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
 import { ROLE_ENUM, HANDOFF_VALIDATION_MODE, HANDOFF_LIFECYCLE_STATUS_ENUM, } from "./shared.js";
 import { validateHandoffPayload, validateSwarmHandoffPayload, lintHandoffPayload, } from "./schemas.js";
 import { acknowledgeHandoffSafe, getHandoffRegistryPath, readHandoffRegistry, registerHandoffSafe, } from "./handoff-registry.js";
@@ -247,7 +247,7 @@ export function registerHandoffTools(server) {
             .replace("T", "-")
             .slice(0, 15);
         const filePath = wsPath("tasks", `SWARM_HANDOFF.${from}_to_${to}_${timeStr}_${shortId}.json`);
-        safeWrite(filePath, JSON.stringify(handoff, null, 2));
+        await safeWriteAsync(filePath, JSON.stringify(handoff, null, 2));
         const registry = await registerHandoffSafe({
             handoff_id: handoff.handoff_id,
             from: handoff.router.from,

package/dist/tools-lifecycle.js

@@ -2,8 +2,8 @@
  * Lifecycle tool registrations: status events, circuit breaker, and kanban.
  */
 import { z } from "zod";
-import { safeRead, safeWrite } from "./helpers.js";
-import { appendStatusEventSafe, getStatusEventsPath, readStatusEvents, } from "./status-events.js";
+import { safeRead, safeWriteAsync } from "./helpers.js";
+import { appendStatusEventSafe, getStatusEventsPath, readStatusEvents } from "./status-events.js";
 import { refreshKanbanArtifacts } from "./kanban.js";
 export function registerLifecycleTools(server) {
     server.tool("emit_status_event", "Append a schema-valid lifecycle event into agent-state/STATUS_EVENTS.ndjson", {
@@ -119,7 +119,7 @@ export function registerLifecycleTools(server) {
             ? "# STATUS\n\n"
             : current.trimEnd();
         const next = `${seed}\n- [${timestamp}] CIRCUIT_BREAKER_OPENED: ${reason}${owner ? ` (owner: ${owner})` : ""}\n`;
-        const statusPath = safeWrite("agent-state/STATUS.md", next);
+        const statusPath = await safeWriteAsync("agent-state/STATUS.md", next);
         const event = await appendStatusEventSafe({
             source_module: "capability-ops",
             event_type: "CIRCUIT_BREAKER_OPENED",
@@ -158,7 +158,7 @@ export function registerLifecycleTools(server) {
             ? "# STATUS\n\n"
             : current.trimEnd();
         const next = `${seed}\n- [${timestamp}] CIRCUIT_BREAKER_CLOSED: ${reason}\n`;
-        const statusPath = safeWrite("agent-state/STATUS.md", next);
+        const statusPath = await safeWriteAsync("agent-state/STATUS.md", next);
         const event = await appendStatusEventSafe({
             source_module: "capability-ops",
             event_type: "CIRCUIT_BREAKER_CLOSED",