@voybio/ace-swarm 2.4.0 → 2.4.1

package/dist/model-bridge.js

@@ -1,9 +1,23 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { existsSync, mkdirSync, writeFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
 import { executeAceInternalTool, listAceInternalToolCatalog, } from "./ace-internal-tools.js";
 import { appendVericifyProcessPostSafe, deriveWorkspaceVericifyRunRef, } from "./vericify-bridge.js";
 import { buildToolPlan, renderAceContext } from "./ace-context.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { appendStatusEventSafe } from "./status-events.js";
+import { normalizeRelPath } from "./helpers.js";
+import { sanitizeJsonLikeText } from "./json-sanitizer.js";
+/**
+ * Roles that MUST produce a valid JSON envelope in every response.
+ * A parse_error from these roles is a contract failure, not a plain-text fallback.
+ * The bridge will inject a repair prompt (up to MAX_PARSE_REPAIR_ATTEMPTS) before
+ * marking the run as failed with status "role_contract_violation".
+ */
+const ROLES_REQUIRING_JSON_ENVELOPE = new Set(["coders", "builder", "qa"]);
+const VALID_ENVELOPE_STATUSES = new Set(["tool", "message", "complete", "need_input"]);
+const MAX_PARSE_REPAIR_ATTEMPTS = 2;
+const MAX_OUTPUT_DRIFT_REPAIRS = 1;
 function resolveProviderClient(input) {
     const display = input.trim() || "ollama";
     const normalized = display.toLowerCase();
@@ -11,8 +25,11 @@ function resolveProviderClient(input) {
         ? { display, client: "ollama" }
         : { display, client: "openai-compatible" };
 }
+function sanitizeModelOutput(raw) {
+    return sanitizeJsonLikeText(raw).text;
+}
 function extractJsonEnvelope(raw) {
-    const trimmed = raw.trim();
+    const trimmed = sanitizeModelOutput(raw).trim();
     if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
         return trimmed;
     }
@@ -29,11 +46,11 @@ function extractJsonEnvelope(raw) {
     let escape = false;
     for (let index = firstBrace; index < trimmed.length; index += 1) {
         const ch = trimmed[index];
-        if (escape) {
+        if (inString && escape) {
             escape = false;
             continue;
         }
-        if (ch === "\\") {
+        if (inString && ch === "\\") {
             escape = true;
             continue;
         }
@@ -61,18 +78,60 @@ function parseEnvelope(raw) {
         if (!parsed || typeof parsed !== "object") {
             throw new Error("response is not an object");
         }
-        if (!parsed.status) {
-            throw new Error("missing status");
+        if (typeof parsed.status !== "string" || !VALID_ENVELOPE_STATUSES.has(parsed.status)) {
+            throw new Error("missing or invalid status");
+        }
+        if (parsed.tool_calls !== undefined && !Array.isArray(parsed.tool_calls)) {
+            throw new Error("tool_calls must be an array");
+        }
+        if (parsed.evidence_refs !== undefined) {
+            if (!Array.isArray(parsed.evidence_refs)) {
+                throw new Error("evidence_refs must be an array");
+            }
+            parsed.evidence_refs = parsed.evidence_refs
+                .filter((ref) => typeof ref === "string")
+                .map((ref) => ref.trim())
+                .filter(Boolean);
         }
         return parsed;
     }
     catch {
         return {
             status: "parse_error",
-            message: summarizeSnippet(raw.trim() || "[empty response]", 240),
+            message: summarizeSnippet(sanitizeModelOutput(raw).trim() || "[empty response]", 240),
         };
     }
 }
+/**
+ * Validates the semantic shape of a completed bridge output against role-specific
+ * output contracts. Returns a violation description if drift is detected, or null
+ * if the output is clean.
+ *
+ * Thresholds are conservative to avoid false positives on legitimate inline snippets.
+ */
+function checkOutputShapeDrift(role, text, _toolResults) {
+    if (role === "qa") {
+        // qa must return a short structured verdict, not a rewritten artifact.
+        // Large code fences in the output strongly suggest artifact rewriting.
+        const codeBlocks = [...text.matchAll(/```[\s\S]*?```/g)];
+        const totalCodeChars = codeBlocks.reduce((sum, match) => sum + match[0].length, 0);
+        if (totalCodeChars > 800) {
+            return ("output contains large code blocks — qa must return a short structured verdict, " +
+                "not a rewritten artifact. Include a one-paragraph verdict and failure classification, " +
+                "not the full file content.");
+        }
+    }
+    if (role === "vos" || role === "ui") {
+        // vos/ui primary output is prose; high HTML-tag density indicates a full document
+        // was produced instead of planning prose.
+        const htmlTagCount = (text.match(/<[a-z][^>]*>/gi) ?? []).length;
+        if (htmlTagCount > 8) {
+            return (`${role} output contains ${htmlTagCount} HTML opening tags — primary output must be ` +
+                `prose. HTML authoring is the coders role's responsibility. Restate as plain prose.`);
+        }
+    }
+    return null;
+}
 function parseToolPlan(raw, catalog) {
     const candidate = extractJsonEnvelope(raw);
     const allowedTools = new Set(catalog.map((tool) => tool.name));
@@ -127,6 +186,9 @@ function summarizeSnippet(text, maxChars = 240) {
         return normalized;
     return `${normalized.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
 }
+function readEnvelopeText(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
 function buildHistorySummary(messages, maxChars) {
     const lines = messages.slice(-8).map((message) => {
         const content = summarizeSnippet(messageText(message).replace(/^Conversation summary:\s*/i, ""), 220);
@@ -209,6 +271,105 @@ function truncateToolResult(result, workspace, maxChars = 3000) {
 function formatErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function normalizeEvidenceRefPath(ref) {
+    const pathPart = ref.split("#", 1)[0]?.trim() ?? "";
+    if (!pathPart || pathPart.includes("\0") || pathPart.startsWith("~"))
+        return undefined;
+    if (isAbsolute(pathPart))
+        return undefined;
+    const normalized = normalizeRelPath(pathPart);
+    if (!normalized || normalized === ".." || normalized.startsWith("../"))
+        return undefined;
+    return normalized;
+}
+function workspaceEvidenceExists(ref, workspace) {
+    const normalized = normalizeEvidenceRefPath(ref);
+    if (!normalized)
+        return false;
+    try {
+        const root = resolve(workspace);
+        const candidate = resolve(root, normalized);
+        // Prevent symlink escape: compare real (resolved) filesystem paths
+        const realRoot = realpathSync(root);
+        const realCandidate = realpathSync(candidate);
+        // Accept candidate only if its real path is equal to the root or nested under it
+        if (realCandidate === realRoot || realCandidate.startsWith(realRoot + sep)) {
+            return existsSync(realCandidate);
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+function mergeEvidenceRefs(...groups) {
+    const merged = groups
+        .flatMap((group) => group ?? [])
+        .map((ref) => ref.trim())
+        .filter(Boolean);
+    return merged.length > 0 ? [...new Set(merged)] : undefined;
+}
+async function appendFalseCompletionEvidence(input) {
+    await appendRunLedgerEntrySafe({
+        tool: "model-bridge",
+        category: "regression",
+        message: input.summary,
+        artifacts: input.evidence_refs ?? [],
+        metadata: {
+            reason_code: "false_completion_no_evidence",
+            role: input.role,
+            workspace: input.workspace,
+            evidence_refs: input.evidence_refs ?? [],
+        },
+    }).catch(() => undefined);
+    await appendStatusEventSafe({
+        source_module: "capability-qa",
+        event_type: "MODEL_BRIDGE_COMPLETION_BLOCKED",
+        status: "blocked",
+        summary: input.summary,
+        objective_id: "model-bridge-completion-verification",
+        payload: {
+            reason_code: "false_completion_no_evidence",
+            role: input.role,
+            workspace: input.workspace,
+            evidence_refs: input.evidence_refs ?? [],
+        },
+    }).catch(() => undefined);
+}
+async function verifyCompletionArtifacts(result, context) {
+    if (result.status !== "completed")
+        return result;
+    const expectedArtifacts = context.expectedArtifacts ?? [];
+    const mutationIntent = /\b(write|create|mutate|edit|persist|save|generate)\b/i.test(context.task);
+    const shouldVerify = ((context.role === "coders" || context.role === "builder") && mutationIntent) ||
+        expectedArtifacts.length > 0 ||
+        result.tool_calls.some((toolCall) => toolCall.tool === "write_workspace_file");
+    if (!shouldVerify)
+        return result;
+    const writeEvidenceOk = result.tool_calls.some((toolCall) => toolCall.tool === "write_workspace_file" && toolCall.ok) &&
+        context.touchedPaths.some((path) => workspaceEvidenceExists(path, context.workspace));
+    const evidenceRefsOk = (result.evidence_refs ?? []).length > 0 &&
+        (result.evidence_refs ?? []).some((ref) => workspaceEvidenceExists(ref, context.workspace));
+    const expectedArtifactsOk = expectedArtifacts.length > 0 &&
+        expectedArtifacts
+            .filter((artifact) => artifact.required !== false)
+            .every((artifact) => workspaceEvidenceExists(artifact.path, context.workspace));
+    if (writeEvidenceOk || evidenceRefsOk || expectedArtifactsOk)
+        return result;
+    const summary = "Model claimed completion but no persisted evidence or tool-calls found.";
+    await appendFalseCompletionEvidence({
+        role: context.role,
+        workspace: context.workspace,
+        summary,
+        evidence_refs: result.evidence_refs,
+    });
+    return {
+        ...result,
+        status: "blocked",
+        reason_code: "false_completion_no_evidence",
+        summary,
+    };
+}
 function isRetryableProviderError(error) {
     const message = formatErrorMessage(error).toLowerCase();
     return !/(abort|aborted|cancelled|canceled|interrupted)/.test(message);
@@ -254,6 +415,16 @@ async function collectOpenAiCompatibleResponse(client, provider, model, messages
         messages,
         temperature: 0.2,
         topP: 0.9,
+        onProviderEvent: (event) => {
+            onProgress?.({
+                kind: "thinking",
+                at: Date.now(),
+                detail: {
+                    reason: "provider_adapter_event",
+                    ...event,
+                },
+            });
+        },
     })) {
         combined += chunk.text;
         if (chunk.text || chunk.done) {
@@ -378,9 +549,12 @@ export class ModelBridge {
         const provider = resolveProviderClient(options.provider);
         const numCtx = options.numCtx ??
             (requestedTier === "brief" ? 4096 : requestedTier === "compressed" ? 8192 : 16384);
-        const explicitToolScope = options.toolScope?.map((tool) => tool.trim()).filter((tool) => tool.length > 0) ?? [];
-        const toolScopeLocked = explicitToolScope.length > 0;
-        const selectedToolScope = explicitToolScope.length > 0
+        const toolScopeProvided = Array.isArray(options.toolScope);
+        const explicitToolScope = toolScopeProvided
+            ? options.toolScope.map((tool) => tool.trim()).filter((tool) => tool.length > 0)
+            : [];
+        const toolScopeLocked = toolScopeProvided;
+        const selectedToolScope = toolScopeProvided
             ? explicitToolScope
             : await this.selectToolScope({
                 task: options.task,
@@ -421,6 +595,9 @@ export class ModelBridge {
         ];
         const toolResults = [];
         const childResults = [];
+        const touchedPaths = [];
+        const declaredEvidenceRefs = [];
+        const evidenceRefs = () => mergeEvidenceRefs(touchedPaths, declaredEvidenceRefs);
         const sessionId = this.bridgeId;
         const refs = deriveWorkspaceVericifyRunRef({
             session_id: this.bridgeId,
@@ -432,6 +609,10 @@ export class ModelBridge {
         const noteProgress = (kind, detail) => {
             options.onProgress?.({ kind, at: Date.now(), detail });
         };
+        // Tracks repair attempts for roles that require a JSON envelope (coders, builder, qa).
+        let parseRepairAttempts = 0;
+        // Tracks correction attempts for roles that produce semantically drifted output.
+        let outputDriftRepairs = 0;
         try {
             await appendVericifyProcessPostSafe({
                 run_id: refs.run_id,
@@ -459,15 +640,79 @@ export class ModelBridge {
                 }, options.onThinking);
                 this.activeProviderClient = null;
                 const envelope = parseEnvelope(rawResponse);
+                if (envelope.status !== "parse_error") {
+                    const refs = mergeEvidenceRefs(envelope.evidence_refs);
+                    if (refs)
+                        declaredEvidenceRefs.push(...refs);
+                }
                 if (envelope.thinking) {
                     options.onThinking?.(envelope.thinking);
                     noteProgress("thinking", { turn });
                 }
                 messages.push({ role: "assistant", content: rawResponse });
                 if (envelope.status === "parse_error") {
-                    const summary = `Model bridge returned malformed or non-JSON output: ${envelope.message ?? "[empty response]"}`;
+                    // Plain-text fallback: accepted only for roles that do NOT require a JSON envelope
+                    // and only when they have no tool scope (i.e. they legitimately produce prose output).
+                    if ((selectedToolScope ?? []).length === 0 && !ROLES_REQUIRING_JSON_ENVELOPE.has(role)) {
+                        const summary = rawResponse.trim() || "Bridge completed.";
+                        options.onOutput?.(summary);
+                        noteProgress("output", { status: "complete", fallback: "plain_text" });
+                        await appendVericifyProcessPostSafe({
+                            run_id: refs.run_id,
+                            branch_id: refs.branch_id,
+                            lane_id: refs.lane_id,
+                            agent_id: `agent-${role}`,
+                            kind: "completion",
+                            summary,
+                            tool_refs: [],
+                        });
+                        noteProgress("process_post", { kind: "completion", fallback: "plain_text" });
+                        return verifyCompletionArtifacts({
+                            bridge_id: this.bridgeId,
+                            role,
+                            status: "completed",
+                            summary,
+                            turns: turn,
+                            tool_calls: toolResults,
+                            child_results: childResults,
+                            evidence_refs: evidenceRefs(),
+                        }, {
+                            role,
+                            task: options.task,
+                            workspace: options.workspace,
+                            touchedPaths,
+                            expectedArtifacts: options.expectedArtifacts,
+                        });
+                    }
+                    // Repair path: roles that require a JSON envelope get up to MAX_PARSE_REPAIR_ATTEMPTS
+                    // chances to emit a valid response before the run is marked as failed.
+                    if (ROLES_REQUIRING_JSON_ENVELOPE.has(role) && parseRepairAttempts < MAX_PARSE_REPAIR_ATTEMPTS) {
+                        parseRepairAttempts += 1;
+                        const repairPrompt = `Your previous response was not a valid JSON envelope and cannot be accepted. ` +
+                            `As the ${role} role, every response MUST be a JSON object with a "status" key. ` +
+                            `Valid response shapes:\n` +
+                            `  {"status":"tool","tool_calls":[{"tool":"name","input":{}}]}\n` +
+                            `  {"status":"complete","summary":"what you accomplished"}\n` +
+                            `Do NOT output plain text, HTML, markdown, or code outside a JSON envelope. ` +
+                            `Respond with valid JSON only. (repair attempt ${parseRepairAttempts}/${MAX_PARSE_REPAIR_ATTEMPTS})`;
+                        messages.push({ role: "user", content: repairPrompt });
+                        options.onThinking?.(`[drift-repair] ${role} parse_error — injecting repair prompt (attempt ${parseRepairAttempts}/${MAX_PARSE_REPAIR_ATTEMPTS})`);
+                        noteProgress("thinking", {
+                            reason: "role_contract_repair",
+                            role,
+                            attempt: parseRepairAttempts,
+                        });
+                        continue;
+                    }
+                    const isContractViolation = ROLES_REQUIRING_JSON_ENVELOPE.has(role);
+                    const summary = isContractViolation
+                        ? `[role_contract_violation] ${role} returned malformed JSON after ${parseRepairAttempts} repair attempt(s): ${envelope.message ?? "[empty response]"}`
+                        : `Model bridge returned malformed or non-JSON output: ${envelope.message ?? "[empty response]"}`;
                     options.onOutput?.(summary);
-                    noteProgress("output", { status: "parse_error" });
+                    noteProgress("output", {
+                        status: "parse_error",
+                        role_contract_violation: isContractViolation,
+                    });
                     await appendVericifyProcessPostSafe({
                         run_id: refs.run_id,
                         branch_id: refs.branch_id,
@@ -486,6 +731,7 @@ export class ModelBridge {
                         turns: turn,
                         tool_calls: toolResults,
                         child_results: childResults,
+                        evidence_refs: evidenceRefs(),
                     };
                 }
                 if (envelope.status === "tool" &&
@@ -534,7 +780,9 @@ export class ModelBridge {
                         const args = toolCall.input ?? {};
                         options.onToolCall?.(toolCall.tool, args);
                         noteProgress("tool_start", { tool: toolCall.tool });
-                        const rawToolResult = await executeAceInternalTool(toolCall.tool, args, sessionId);
+                        const rawToolResult = await executeAceInternalTool(toolCall.tool, args, sessionId, {
+                            workspace_path: options.workspace,
+                        });
                         const result = truncateToolResult({
                             tool: toolCall.tool,
                             ok: !Boolean(rawToolResult?.isError),
@@ -544,6 +792,15 @@ export class ModelBridge {
                         options.onToolResult?.(toolCall.tool, result);
                         noteProgress("tool_finish", { tool: toolCall.tool, ok: result.ok });
                         toolResults.push(result);
+                        if (result.ok) {
+                            const pathArg = typeof args.path === "string"
+                                ? args.path
+                                : typeof args.file_path === "string"
+                                    ? args.file_path
+                                    : undefined;
+                            if (pathArg)
+                                touchedPaths.push(pathArg);
+                        }
                         return result;
                     }));
                     messages.push({
@@ -555,7 +812,7 @@ export class ModelBridge {
                     continue;
                 }
                 if (envelope.status === "message") {
-                    const message = envelope.message?.trim() || rawResponse.trim();
+                    const message = readEnvelopeText(envelope.message) || rawResponse.trim();
                     options.onOutput?.(message);
                     noteProgress("output", { status: "message" });
                     await appendVericifyProcessPostSafe({
@@ -568,7 +825,7 @@ export class ModelBridge {
                         tool_refs: [],
                     });
                     noteProgress("process_post", { kind: "progress" });
-                    return {
+                    return verifyCompletionArtifacts({
                         bridge_id: this.bridgeId,
                         role,
                         status: "completed",
@@ -576,10 +833,17 @@ export class ModelBridge {
                         turns: turn,
                         tool_calls: toolResults,
                         child_results: childResults,
-                    };
+                        evidence_refs: evidenceRefs(),
+                    }, {
+                        role,
+                        task: options.task,
+                        workspace: options.workspace,
+                        touchedPaths,
+                        expectedArtifacts: options.expectedArtifacts,
+                    });
                 }
                 if (envelope.status === "need_input") {
-                    const message = envelope.message?.trim() || "Additional operator input required.";
+                    const message = readEnvelopeText(envelope.message) || "Additional operator input required.";
                     options.onOutput?.(message);
                     noteProgress("output", { status: "need_input" });
                     await appendVericifyProcessPostSafe({
@@ -600,10 +864,55 @@ export class ModelBridge {
                         turns: turn,
                         tool_calls: toolResults,
                         child_results: childResults,
+                        evidence_refs: evidenceRefs(),
                     };
                 }
                 if (envelope.status === "complete") {
-                    const summary = envelope.summary?.trim() || "Bridge completed.";
+                    const summary = readEnvelopeText(envelope.summary) || "Bridge completed.";
+                    // Output shape drift check: detect semantic violations before accepting the result.
+                    const driftViolation = checkOutputShapeDrift(role, summary, toolResults);
+                    if (driftViolation) {
+                        if (outputDriftRepairs < MAX_OUTPUT_DRIFT_REPAIRS) {
+                            outputDriftRepairs += 1;
+                            const correctionPrompt = `Your previous completion violated the output contract for the ${role} role: ` +
+                                `${driftViolation} Please restate your output, correcting the violation.`;
+                            messages.push({ role: "user", content: correctionPrompt });
+                            options.onThinking?.(`[drift-correction] ${role} output drift — injecting correction ` +
+                                `(attempt ${outputDriftRepairs}/${MAX_OUTPUT_DRIFT_REPAIRS}): ${driftViolation}`);
+                            noteProgress("thinking", {
+                                reason: "output_drift_correction",
+                                role,
+                                attempt: outputDriftRepairs,
+                                violation: driftViolation,
+                            });
+                            continue;
+                        }
+                        // Correction exhausted — reject the drifted output.
+                        const driftSummary = `[output_drift_violation] ${role}: ${driftViolation}`;
+                        options.onOutput?.(driftSummary);
+                        noteProgress("output", { status: "output_drift_violation" });
+                        await appendVericifyProcessPostSafe({
+                            run_id: refs.run_id,
+                            branch_id: refs.branch_id,
+                            lane_id: refs.lane_id,
+                            agent_id: `agent-${role}`,
+                            kind: "blocker",
+                            summary: driftSummary,
+                            tool_refs: toolResults.map((entry) => entry.tool),
+                        });
+                        noteProgress("process_post", { kind: "blocker" });
+                        return {
+                            bridge_id: this.bridgeId,
+                            role,
+                            status: "failed",
+                            summary: driftSummary,
+                            turns: turn,
+                            tool_calls: toolResults,
+                            child_results: childResults,
+                            evidence_refs: evidenceRefs(),
+                        };
+                    }
+                    // Clean output — accept the completion.
                     options.onOutput?.(summary);
                     noteProgress("output", { status: "complete" });
                     await appendVericifyProcessPostSafe({
@@ -616,7 +925,7 @@ export class ModelBridge {
                         tool_refs: toolResults.map((entry) => entry.tool),
                     });
                     noteProgress("process_post", { kind: "completion" });
-                    return {
+                    return verifyCompletionArtifacts({
                         bridge_id: this.bridgeId,
                         role,
                         status: "completed",
@@ -624,7 +933,14 @@ export class ModelBridge {
                         turns: turn,
                         tool_calls: toolResults,
                         child_results: childResults,
-                    };
+                        evidence_refs: evidenceRefs(),
+                    }, {
+                        role,
+                        task: options.task,
+                        workspace: options.workspace,
+                        touchedPaths,
+                        expectedArtifacts: options.expectedArtifacts,
+                    });
                 }
             }
             const summary = "Bridge stopped after reaching max turns.";
@@ -646,6 +962,7 @@ export class ModelBridge {
                 turns: options.maxTurns,
                 tool_calls: toolResults,
                 child_results: childResults,
+                evidence_refs: evidenceRefs(),
             };
         }
         finally {

package/dist/orchestrator-supervisor.d.ts

@@ -20,6 +20,20 @@ export interface TaskStep {
         result_summary: string;
         evidence_refs: string[];
     }[];
+    expected_output_class?: "plain_text_plan" | "tool_envelope" | "code_artifact" | "structural_edit_plan" | "qa_verdict";
+    expected_artifacts?: Array<{
+        path: string;
+        required?: boolean;
+        evidence_ref_kind?: "artifact" | "diff" | "hash" | "test" | "gate";
+    }>;
+    allowed_tools?: string[];
+    forbidden_patterns?: string[];
+    required_evidence_refs?: string[];
+    structural_edit_plan_required?: boolean;
+    structural_edit_waiver?: {
+        reason: string;
+        evidence_ref: string;
+    };
 }
 export interface TaskPlan {
     plan_id: string;
@@ -44,6 +58,13 @@ export interface TaskPlanAmendment {
     vcx_cursor?: string;
     evidence_refs?: string[];
 }
+export type IntentVerificationOutcome = "ok" | "revisit_step" | "replan_required";
+export interface IntentVerificationResult {
+    outcome: IntentVerificationOutcome;
+    reason: string;
+    reason_code?: string;
+    uncovered_clauses?: string[];
+}
 export interface SupervisorHooks {
     spawnStep: (step: TaskStep, plan: TaskPlan) => Promise<BridgeResult>;
     createHandoff?: (input: {
@@ -80,6 +101,26 @@ export interface SupervisorHooks {
         summary: string;
         step_id?: string;
     }) => Promise<void>;
+    verifyIntent?: (input: {
+        plan: TaskPlan;
+        step: TaskStep;
+        result: BridgeResult;
+        intent_contract: unknown;
+        vericify_delta?: unknown;
+    }) => Promise<IntentVerificationResult>;
+    recordIntentVerificationFailure?: (input: {
+        plan: TaskPlan;
+        step: TaskStep;
+        result: BridgeResult;
+        verification: IntentVerificationResult;
+        from: TaskStepStatus;
+        to: TaskStepStatus;
+    }) => Promise<void>;
+    /** Called when replan_required: returns an amendment to insert steps covering uncovered clauses. */
+    replanForClauses?: (input: {
+        plan: TaskPlan;
+        uncovered_clauses: string[];
+    }) => Promise<TaskPlanAmendment | undefined>;
 }
 export interface SupervisorRunResult {
     plan: TaskPlan;
@@ -87,6 +128,7 @@ export interface SupervisorRunResult {
     job_ids: string[];
     circuit_opened: boolean;
     final_gate?: unknown;
+    blocked_reason?: string;
 }
 export declare function deriveTaskPlanStatus(plan: TaskPlan): TaskPlanStatus;
 export declare function createTaskPlan(input: {