@voybio/ace-swarm 2.4.4 → 2.4.6

package/dist/todo-state.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { ACE_TASKS_ROOT_REL, resolveWorkspaceRoot, safeRead, safeWrite, wsPath } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, resolveWorkspaceRoot, resolveWritableTaskPath, safeRead, safeWrite, safeWriteAsync, withFileLock, wsPath, } from "./helpers.js";
 import { openStore } from "./store/ace-packed-store.js";
 import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { TodoRepository } from "./store/repositories/todo-repository.js";
@@ -385,6 +385,49 @@ function setTodoCheckbox(todoRaw, line, checked) {
     lines[line - 1] = target.replace(/^- \[( |x|X)\]/, `- [${checked ? "x" : " "}]`);
     return lines.join("\n");
 }
+function insertTodoItem(todoRaw, section, title, id, dependsOn) {
+    const metaParts = [`id=${id}`];
+    if (dependsOn.length > 0)
+        metaParts.push(`depends_on=${dependsOn.join(",")}`);
+    const newLine = `- [ ] ${title} <!-- ace:${metaParts.join("; ")} -->`;
+    const lines = todoRaw.length > 0 ? todoRaw.split(/\r?\n/) : [];
+    let sectionStart = -1;
+    let sectionEnd = lines.length;
+    for (let i = 0; i < lines.length; i++) {
+        const header = lines[i]?.match(/^##\s+(.+)$/);
+        if (!header?.[1])
+            continue;
+        if (header[1].trim().toLowerCase() === section.toLowerCase()) {
+            sectionStart = i;
+            let j = i + 1;
+            while (j < lines.length && !/^##\s+/.test(lines[j] ?? ""))
+                j++;
+            sectionEnd = j;
+            break;
+        }
+    }
+    if (sectionStart === -1) {
+        const trimmed = todoRaw.replace(/\s+$/, "");
+        const prefix = trimmed.length > 0 ? `${trimmed}\n\n` : "";
+        return `${prefix}## ${section}\n${newLine}\n`;
+    }
+    let insertAt = sectionEnd;
+    while (insertAt > sectionStart + 1 && (lines[insertAt - 1] ?? "").trim() === "")
+        insertAt--;
+    lines.splice(insertAt, 0, newLine);
+    return lines.join("\n");
+}
+function uniqueTodoId(base, existingIds) {
+    if (!existingIds.has(base))
+        return base;
+    let n = 2;
+    let candidate = `${base}-${n}`;
+    while (existingIds.has(candidate)) {
+        n += 1;
+        candidate = `${base}-${n}`;
+    }
+    return candidate;
+}
 function getTodoPath() {
     return wsPath(TODO_MARKDOWN_REL);
 }
@@ -401,7 +444,10 @@ export function syncTodoState(todoContent) {
     const path = writeState(state);
     return { state, path };
 }
-export async function syncTodoStateSafe(todoContent) {
+// Lock-free core: callers that already hold the TODO_MARKDOWN_REL lock (e.g.
+// appendTodoItemSafe) must call this directly instead of syncTodoStateSafe,
+// since withFileLock is not reentrant and re-acquiring the same key deadlocks.
+async function syncTodoStateLocked(todoContent) {
     const root = workspaceRoot();
     if (storeExistsSync(root)) {
         const todoRaw = typeof todoContent === "string" ? todoContent : safeRead(TODO_MARKDOWN_REL);
@@ -418,6 +464,9 @@ export async function syncTodoStateSafe(todoContent) {
     await waitForTodoStoreMirror();
     return result;
 }
+export async function syncTodoStateSafe(todoContent) {
+    return withFileLock(TODO_MARKDOWN_REL, () => syncTodoStateLocked(todoContent));
+}
 export function readTodoState() {
     if (storeExistsSync(workspaceRoot())) {
         return readPersistedState();
@@ -495,73 +544,121 @@ export function transitionTodoNode(nodeId, targetStatus) {
     };
 }
 export async function transitionTodoNodeSafe(nodeId, targetStatus) {
-    const root = workspaceRoot();
-    if (storeExistsSync(root)) {
-        const todoRaw = safeRead(TODO_MARKDOWN_REL);
-        if (isReadError(todoRaw)) {
-            return {
-                ok: false,
-                path: getTodoStatePath(),
-                todo_path: getTodoPath(),
-                error: `${TODO_MARKDOWN_REL} not found; cannot apply transition.`,
-            };
-        }
-        const synced = syncStateWithTodo(todoRaw, readPersistedState());
-        const node = synced.nodes[nodeId];
-        if (!node) {
-            return {
-                ok: false,
-                path: getTodoStatePath(),
-                todo_path: getTodoPath(),
-                error: `Unknown node_id: ${nodeId}`,
-            };
-        }
-        const from = node.status;
-        if (from !== targetStatus) {
-            const allowed = TRANSITIONS[from];
-            if (!allowed.includes(targetStatus)) {
+    return withFileLock(TODO_MARKDOWN_REL, async () => {
+        const root = workspaceRoot();
+        if (storeExistsSync(root)) {
+            const todoRaw = safeRead(TODO_MARKDOWN_REL);
+            if (isReadError(todoRaw)) {
                 return {
                     ok: false,
                     path: getTodoStatePath(),
                     todo_path: getTodoPath(),
-                    node_id: nodeId,
-                    from,
-                    to: targetStatus,
-                    allowed,
-                    error: `Invalid transition ${from} -> ${targetStatus}`,
+                    error: `${TODO_MARKDOWN_REL} not found; cannot apply transition.`,
                 };
             }
-        }
-        if (targetStatus === "in_progress" ||
-            targetStatus === "gated" ||
-            targetStatus === "done") {
-            const unresolved = node.depends_on.filter((depId) => synced.nodes[depId]?.status !== "done");
-            if (unresolved.length > 0) {
+            const synced = syncStateWithTodo(todoRaw, readPersistedState());
+            const node = synced.nodes[nodeId];
+            if (!node) {
                 return {
                     ok: false,
                     path: getTodoStatePath(),
                     todo_path: getTodoPath(),
-                    node_id: nodeId,
-                    from,
-                    to: targetStatus,
-                    unresolved_dependencies: unresolved,
-                    error: `Dependencies not satisfied for ${nodeId}`,
+                    error: `Unknown node_id: ${nodeId}`,
                 };
             }
+            const from = node.status;
+            if (from !== targetStatus) {
+                const allowed = TRANSITIONS[from];
+                if (!allowed.includes(targetStatus)) {
+                    return {
+                        ok: false,
+                        path: getTodoStatePath(),
+                        todo_path: getTodoPath(),
+                        node_id: nodeId,
+                        from,
+                        to: targetStatus,
+                        allowed,
+                        error: `Invalid transition ${from} -> ${targetStatus}`,
+                    };
+                }
+            }
+            if (targetStatus === "in_progress" ||
+                targetStatus === "gated" ||
+                targetStatus === "done") {
+                const unresolved = node.depends_on.filter((depId) => synced.nodes[depId]?.status !== "done");
+                if (unresolved.length > 0) {
+                    return {
+                        ok: false,
+                        path: getTodoStatePath(),
+                        todo_path: getTodoPath(),
+                        node_id: nodeId,
+                        from,
+                        to: targetStatus,
+                        unresolved_dependencies: unresolved,
+                        error: `Dependencies not satisfied for ${nodeId}`,
+                    };
+                }
+            }
+            node.status = targetStatus;
+            const statePath = await writeStateStoreBacked(root, synced);
+            return {
+                ok: true,
+                path: statePath,
+                todo_path: getTodoPath(),
+                node_id: nodeId,
+                from,
+                to: targetStatus,
+            };
         }
-        node.status = targetStatus;
-        const statePath = await writeStateStoreBacked(root, synced);
+        const result = transitionTodoNode(nodeId, targetStatus);
+        await waitForTodoStoreMirror();
+        return result;
+    });
+}
+/**
+ * Atomically append a new TODO item under a section, without requiring the
+ * caller to read the whole board and resubmit it via update_todo(new_content).
+ * That read-modify-write dance is what let concurrent agents silently clobber
+ * each other's appended items: the read and write are separate MCP calls, so
+ * a lock around the write alone cannot close the race. Here the read, insert,
+ * and write all happen inside one TODO_MARKDOWN_REL lock acquisition.
+ */
+export async function appendTodoItemSafe(title, options) {
+    const trimmedTitle = title.trim();
+    if (!trimmedTitle) {
         return {
-            ok: true,
-            path: statePath,
+            ok: false,
+            path: getTodoStatePath(),
             todo_path: getTodoPath(),
-            node_id: nodeId,
-            from,
-            to: targetStatus,
+            error: "Todo item title must not be empty.",
         };
     }
-    const result = transitionTodoNode(nodeId, targetStatus);
-    await waitForTodoStoreMirror();
-    return result;
+    return withFileLock(TODO_MARKDOWN_REL, async () => {
+        const existingRaw = safeRead(TODO_MARKDOWN_REL);
+        const baseRaw = isReadError(existingRaw) ? "# Tasks\n" : existingRaw;
+        const section = options?.section?.trim() || "Active Work";
+        const dependsOn = (options?.depends_on ?? []).map((dep) => dep.trim()).filter(Boolean);
+        const existingIds = new Set(parseTodoMarkdown(baseRaw).map((entry) => entry.id));
+        const requestedId = options?.id?.trim();
+        if (requestedId && existingIds.has(requestedId)) {
+            return {
+                ok: false,
+                path: getTodoStatePath(),
+                todo_path: getTodoPath(),
+                error: `Todo id already exists: ${requestedId}`,
+            };
+        }
+        const id = requestedId || uniqueTodoId(`todo-${slugify(trimmedTitle)}`, existingIds);
+        const updatedRaw = insertTodoItem(baseRaw, section, trimmedTitle, id, dependsOn);
+        const synced = await syncTodoStateLocked(updatedRaw);
+        const mdPath = await safeWriteAsync(resolveWritableTaskPath("todo"), updatedRaw);
+        return {
+            ok: true,
+            path: synced.path,
+            todo_path: mdPath,
+            node_id: id,
+            section,
+        };
+    });
 }
 //# sourceMappingURL=todo-state.js.map

package/dist/tools-agent.js

@@ -2,9 +2,10 @@
  * Agent, skill, kernel, and task-pack tool registrations.
  */
 import { z } from "zod";
-import { ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, classifyPathSource, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, isSwarmRole, listAvailableSkills, readAgentInstructions, readAgentManifest, readKernelArtifact, readSkillInstructions, readTaskArtifact, resolveWorkspaceRoot, resolveWritableTaskPath, safeWriteAsync, } from "./helpers.js";
+import { ALL_AGENTS, COMPOSABLE_AGENTS, SWARM_AGENTS, SWARM_SUBAGENT_MAP, classifyPathSource, getAgentInstructionPath, getAgentManifestPath, getKernelArtifactPath, isSwarmRole, listAvailableSkills, readAgentInstructions, readAgentManifest, readKernelArtifact, readSkillInstructions, readTaskArtifact, resolveWorkspaceRoot, } from "./helpers.js";
 import { loadRuntimeProfile, readRuntimePromptTemplate, readRuntimeProfileState, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { getUnattendedSession, listUnattendedSessions, startUnattendedSession, stopUnattendedSession, validateRuntimeExecutorSessionRegistryContent, waitForUnattendedSession, } from "./runtime-executor.js";
+import { materializePlaybookMarkdown, PlaybookRepository, renderPlaybookMarkdown, } from "./store/repositories/playbook-repository.js";
 import { executeRuntimeTool, listRuntimeToolSpecs, loadRuntimeToolRegistry, validateRuntimeToolRegistryContent, } from "./runtime-tool-specs.js";
 import { createWorkspaceSessionAsync, listWorkspaceSessions, removeWorkspaceSession, resolveRuntimeWorkspaceRoot, validateManagedWorkspacePath, } from "./workspace-manager.js";
 import { getTrackerAdapter, listTrackerAdapterKinds, loadTrackerSnapshot, validateTrackerSnapshotContent, } from "./tracker-adapters.js";
@@ -350,8 +351,9 @@ function createToolOnlyBridgeResult(step, reason) {
     return {
         bridge_id: `tool-only-${step.step_id}-${Date.now()}`,
         role: step.role,
-        status: "completed",
-        summary: `Tool-only orchestrator completion for ${step.step_id} (${step.role}): ${step.task}. ${reason}`,
+        status: "blocked",
+        reason_code: "no_model_runtime",
+        summary: `Step blocked — no model runtime available for ${step.step_id} (${step.role}): ${step.task}. ${reason} Run \`ace connect\` or \`ace doctor --scan\`, or pass provider/model to resolve.`,
         turns: 0,
         tool_calls: [],
         child_results: [],
@@ -1369,7 +1371,11 @@ export function registerAgentTools(server) {
             .string()
             .optional()
             .describe("Optional workspace root override; defaults to the active workspace"),
-    }, async ({ task, steps, execution_mode, max_turns_per_step, provider, model, base_url, ollama_url, workspace_root }, extra) => {
+        mode: z
+            .enum(["execute", "plan_only"])
+            .optional()
+            .describe("'plan_only' compiles and validates the plan without executing any steps; 'execute' is the default"),
+    }, async ({ task, steps, execution_mode, max_turns_per_step, provider, model, base_url, ollama_url, workspace_root, mode }, extra) => {
         let runtime;
         const runtimeWarnings = [];
         try {
@@ -1406,6 +1412,32 @@ export function registerAgentTools(server) {
         const bridge = runtime
             ? new ModelBridge(createDefaultModelBridgeClients(runtime))
             : undefined;
+        // plan_only mode: return the compiled plan without executing anything
+        if (mode === "plan_only" || (!runtime && runtimeWarnings.length > 0)) {
+            const planOnly = mode === "plan_only";
+            const reasonCode = planOnly ? "plan_only_requested" : "no_model_runtime";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: planOnly,
+                            reason_code: reasonCode,
+                            execution_backend: "none",
+                            mode: planOnly ? "plan_only" : "execute",
+                            plan,
+                            runtime: runtime ?? null,
+                            runtime_warnings: runtimeWarnings,
+                            remediation: !runtime
+                                ? "Run `ace connect` or `ace doctor --scan`, or pass provider/model. Use mode:\"plan_only\" explicitly to compile a plan without a runtime."
+                                : undefined,
+                            acceptance_trace_map: traceArtifactPath,
+                            plan_source: planSource,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         const fallbackHandoffPrefix = `LOCAL-${plan.plan_id}-`;
         const vericifyWarnings = [];
         const appendSessionPlanTransition = async (stepId, from, to, reason, reasonCode) => {
@@ -1426,6 +1458,22 @@ export function registerAgentTools(server) {
                     evidence_refs: step.tool_scope ?? [],
                 });
             }).catch(() => undefined);
+            // WS-C item 5: emit a PLAN_UPDATE payload on the existing status-event pipe so
+            // consumers can follow "exactly one item in_progress" without a new transport.
+            const inProgressStep = plan.steps.find((candidate) => candidate.status === "running");
+            await executeAceInternalTool("emit_status_event", {
+                source_module: "capability-ops",
+                event_type: "PLAN_UPDATE",
+                status: to === "done" ? "done" : to === "blocked" || to === "failed" ? "blocked" : "in_progress",
+                summary: `Plan ${plan.plan_id} step ${stepId}: ${from} -> ${to}`,
+                payload_json: JSON.stringify({
+                    plan_id: plan.plan_id,
+                    step_id: stepId,
+                    from,
+                    to,
+                    in_progress_step_id: inProgressStep?.step_id ?? null,
+                }),
+            }, sessionId).catch(() => undefined);
         };
         const supervised = await superviseTaskPlan(plan, {
             async spawnStep(step) {
@@ -1439,6 +1487,8 @@ export function registerAgentTools(server) {
                         provider: runtime.provider,
                         model: runtime.model,
                         toolScope: step.tool_scope,
+                        expectedArtifacts: step.expected_artifacts,
+                        requiredEvidenceRefs: step.required_evidence_refs,
                     });
                 }
                 const reason = runtimeWarnings[0] ??
@@ -2287,31 +2337,45 @@ export function registerAgentTools(server) {
         };
     });
     // ── Lessons ───────────────────────────────────────────────────────
-    server.tool("get_lessons", "Read all accumulated lessons and guardrails", {}, async () => ({
-        content: [{ type: "text", text: readTaskArtifact("lessons") }],
-    }));
+    server.tool("get_lessons", "Read all accumulated playbook lessons and guardrails", {}, async () => {
+        const root = resolveWorkspaceRoot();
+        const repo = new PlaybookRepository(root);
+        const path = materializePlaybookMarkdown(root);
+        return {
+            content: [{ type: "text", text: `${renderPlaybookMarkdown(repo)}\nProjection: ${path}` }],
+        };
+    });
     server.tool("add_lesson", "Record a new lesson/guardrail after a correction or failure", {
         context: z.string().describe("What happened"),
         failure_pattern: z.string().describe("What went wrong"),
         guardrail: z.string().describe("Rule to prevent recurrence"),
         verification_check: z.string().describe("How to verify compliance"),
     }, async ({ context, failure_pattern, guardrail, verification_check }) => {
-        const date = new Date().toISOString().slice(0, 10);
-        const entry = [
-            "",
-            `## Lesson — ${date}`,
-            "",
-            `- **Date:** ${date}`,
-            `- **Context:** ${context}`,
-            `- **Failure Pattern:** ${failure_pattern}`,
-            `- **Guardrail:** ${guardrail}`,
-            `- **Verification Check:** ${verification_check}`,
-            "",
-        ].join("\n");
-        const existing = readTaskArtifact("lessons");
-        const path = await safeWriteAsync(resolveWritableTaskPath("lessons"), `${existing}${entry}`);
+        const knownReasonCodes = [
+            "false_completion_no_evidence",
+            "forward_pacing_incomplete",
+            "bridge_tool_doom_loop",
+            "bridge_text_doom_loop",
+            "context_overflow",
+            "tool_timeout",
+            "role_contract_violation",
+        ];
+        const scope = {};
+        const lowered = failure_pattern.toLowerCase();
+        const reason = knownReasonCodes.find((code) => lowered.includes(code));
+        if (reason)
+            scope.reason_code = reason;
+        const root = resolveWorkspaceRoot();
+        const bullet = new PlaybookRepository(root).createBullet({
+            section: "failure_modes",
+            scope,
+            content: `${guardrail} Verify: ${verification_check}`,
+            evidence_refs: [],
+            provenance: { source: "operator" },
+        });
+        const path = materializePlaybookMarkdown(root);
         return {
-            content: [{ type: "text", text: `✅ Lesson recorded in ${path}` }],
+            content: [{ type: "text", text: `✅ Lesson recorded as ${bullet.bullet_id} (${bullet.status}) in ${path}. Context: ${context}` }],
         };
     });
     // ── CLI Work Split ────────────────────────────────────────────────

package/dist/tools-discovery.js

@@ -217,7 +217,7 @@ export function registerDiscoveryTools(server) {
             },
         ],
     }));
-    server.tool("mcp_ingestion_probe", "Validate an external MCP server configuration, persist request/response artifacts, and expose bounded declared tool metadata without leaking shell env", {
+    server.tool("mcp_ingestion_probe", "Connect to an external MCP server with a bounded initialize handshake, list tools/resources/templates/prompts, and persist the probe artifacts", {
         name: z.string().min(1).describe("Logical MCP server name"),
         transport: z.enum(["stdio", "http"]).describe("MCP transport class"),
         command: z.string().optional().describe("Command for stdio MCP servers"),
@@ -231,8 +231,9 @@ export function registerDiscoveryTools(server) {
             input_schema: z.unknown().optional(),
         }))
             .optional()
-            .describe("Optional declared tool metadata discovered or provided by the server class"),
-    }, async ({ name, transport, command, args, url, env, declared_tools }) => ({
+            .describe("Deprecated compatibility input; live server catalogs are authoritative"),
+        timeout_ms: z.number().int().min(250).max(60000).optional().describe("Bound for connect and each catalog request (default 10000ms)"),
+    }, async ({ name, transport, command, args, url, env, declared_tools, timeout_ms }) => ({
         content: [
             {
                 type: "text",
@@ -244,6 +245,7 @@ export function registerDiscoveryTools(server) {
                     url,
                     env,
                     declared_tools,
+                    timeout_ms,
                 }), null, 2),
             },
         ],

package/dist/tools-files.js

@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
 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";
@@ -17,6 +17,7 @@ import { safeEditFile, diffContents, applyPatch } from "./safe-edit.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")) {
@@ -493,6 +503,7 @@ async function buildStructuralPreview(plan) {
         : diffProcess.status === 0
             ? ""
             : diff.diff_summary;
+    const hasUnifiedDiff = diffProcess.status === 1;
     return {
         artifact: await finalize({
             ok: true,
@@ -505,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,
@@ -1134,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,
@@ -1154,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,
             },
@@ -1215,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 {
@@ -1660,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,
         });
@@ -1707,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,8 @@ 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";
@@ -1199,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");
@@ -1368,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}`)),
@@ -1389,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);
@@ -1401,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}`,