@voybio/ace-swarm 2.4.4 → 2.4.6

package/dist/model-bridge.js

@@ -1,5 +1,5 @@
-import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync, realpathSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, 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";
@@ -8,6 +8,11 @@ import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
 import { normalizeRelPath } from "./helpers.js";
 import { sanitizeJsonLikeText } from "./json-sanitizer.js";
+const MUTATION_INTENT = /\b(write|create|mutate|edit|persist|save|generate|implement|fix|update|modify|patch|delete|remove)\b/i;
+/** Keep completion-evidence policy identical across direct and Hermes execution. */
+export function isMutationIntent(task) {
+    return MUTATION_INTENT.test(task);
+}
 /**
  * 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.
@@ -15,6 +20,33 @@ import { sanitizeJsonLikeText } from "./json-sanitizer.js";
  * marking the run as failed with status "role_contract_violation".
  */
 const ROLES_REQUIRING_JSON_ENVELOPE = new Set(["coders", "builder", "qa"]);
+/**
+ * JSON Schema for the ACE response envelope. Passed as `format` (Ollama ≥ 0.5) or
+ * `response_format.json_schema` (OpenAI-compatible) to enable schema-constrained
+ * generation. Falls back to plain json-mode if the provider rejects it with a 400.
+ */
+export const ACE_ENVELOPE_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        status: { type: "string", enum: ["tool", "message", "complete", "need_input"] },
+        thinking: { type: "string" },
+        message: { type: "string" },
+        summary: { type: "string" },
+        tool_calls: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    tool: { type: "string" },
+                    input: { type: "object" },
+                },
+                required: ["tool"],
+            },
+        },
+        evidence_refs: { type: "array", items: { type: "string" } },
+    },
+    required: ["status"],
+};
 const VALID_ENVELOPE_STATUSES = new Set(["tool", "message", "complete", "need_input"]);
 const MAX_PARSE_REPAIR_ATTEMPTS = 2;
 const MAX_OUTPUT_DRIFT_REPAIRS = 1;
@@ -93,6 +125,15 @@ function parseEnvelope(raw) {
                 .map((ref) => ref.trim())
                 .filter(Boolean);
         }
+        if (parsed.used_bullets !== undefined) {
+            if (!Array.isArray(parsed.used_bullets)) {
+                throw new Error("used_bullets must be an array");
+            }
+            parsed.used_bullets = parsed.used_bullets
+                .filter((id) => typeof id === "string")
+                .map((id) => id.trim())
+                .filter((id) => /^pb-[a-fA-F0-9]{8}$/.test(id));
+        }
         return parsed;
     }
     catch {
@@ -310,13 +351,14 @@ function mergeEvidenceRefs(...groups) {
     return merged.length > 0 ? [...new Set(merged)] : undefined;
 }
 async function appendFalseCompletionEvidence(input) {
+    const reasonCode = input.reason_code ?? "false_completion_no_evidence";
     await appendRunLedgerEntrySafe({
         tool: "model-bridge",
         category: "regression",
         message: input.summary,
         artifacts: input.evidence_refs ?? [],
         metadata: {
-            reason_code: "false_completion_no_evidence",
+            reason_code: reasonCode,
             role: input.role,
             workspace: input.workspace,
             evidence_refs: input.evidence_refs ?? [],
@@ -329,20 +371,23 @@ async function appendFalseCompletionEvidence(input) {
         summary: input.summary,
         objective_id: "model-bridge-completion-verification",
         payload: {
-            reason_code: "false_completion_no_evidence",
+            reason_code: reasonCode,
             role: input.role,
             workspace: input.workspace,
             evidence_refs: input.evidence_refs ?? [],
         },
     }).catch(() => undefined);
 }
-async function verifyCompletionArtifacts(result, context) {
+export 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) ||
+    const expectedArtifacts = (context.expectedArtifacts ?? []).filter((artifact) => artifact.required !== false);
+    const requiredEvidenceRefs = (context.requiredEvidenceRefs ?? []).filter((ref) => ref.trim().length > 0);
+    const mutationIntent = isMutationIntent(context.task);
+    const shouldVerify = context.forceCompletionVerification === true ||
+        ((context.role === "coders" || context.role === "builder") && mutationIntent) ||
         expectedArtifacts.length > 0 ||
+        requiredEvidenceRefs.length > 0 ||
         result.tool_calls.some((toolCall) => toolCall.tool === "write_workspace_file");
     if (!shouldVerify)
         return result;
@@ -351,10 +396,42 @@ async function verifyCompletionArtifacts(result, context) {
     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)
+        expectedArtifacts.every((artifact) => workspaceEvidenceExists(artifact.path, context.workspace));
+    const requiredEvidenceRefsOk = requiredEvidenceRefs.length > 0 &&
+        requiredEvidenceRefs.every((required) => (result.evidence_refs ?? []).some((ref) => ref.includes(required)));
+    if (expectedArtifacts.length > 0 && !expectedArtifactsOk) {
+        const summary = "Model claimed completion but declared expected artifacts are missing.";
+        await appendFalseCompletionEvidence({
+            role: context.role,
+            workspace: context.workspace,
+            summary,
+            evidence_refs: result.evidence_refs,
+            reason_code: "forward_pacing_incomplete",
+        });
+        return {
+            ...result,
+            status: "blocked",
+            reason_code: "forward_pacing_incomplete",
+            summary,
+        };
+    }
+    if (requiredEvidenceRefs.length > 0 && !requiredEvidenceRefsOk) {
+        const summary = "Model claimed completion but required evidence refs are missing.";
+        await appendFalseCompletionEvidence({
+            role: context.role,
+            workspace: context.workspace,
+            summary,
+            evidence_refs: result.evidence_refs,
+            reason_code: "forward_pacing_incomplete",
+        });
+        return {
+            ...result,
+            status: "blocked",
+            reason_code: "forward_pacing_incomplete",
+            summary,
+        };
+    }
+    if (expectedArtifactsOk || requiredEvidenceRefsOk || writeEvidenceOk || evidenceRefsOk)
         return result;
     const summary = "Model claimed completion but no persisted evidence or tool-calls found.";
     await appendFalseCompletionEvidence({
@@ -370,9 +447,34 @@ async function verifyCompletionArtifacts(result, context) {
         summary,
     };
 }
+/**
+ * Returns true when a provider rejected our schema-constrained format (400) and
+ * the bridge should retry with plain json-mode. Applies only when `jsonSchema` was
+ * set — any 400 from a schema request is treated as a format-rejection to degrade
+ * gracefully on older Ollama / backends that don't support json_schema yet.
+ */
+function isSchemaFormatRejectedError(error) {
+    const statusCode = typeof error?.statusCode === "number"
+        ? error.statusCode
+        : undefined;
+    return statusCode === 400;
+}
 function isRetryableProviderError(error) {
     const message = formatErrorMessage(error).toLowerCase();
-    return !/(abort|aborted|cancelled|canceled|interrupted)/.test(message);
+    if (/(abort|aborted|cancelled|canceled|interrupted)/.test(message))
+        return false;
+    const statusCode = typeof error?.statusCode === "number"
+        ? error.statusCode
+        : undefined;
+    if (statusCode !== undefined) {
+        if (statusCode >= 500)
+            return true;
+        if (statusCode === 408 || statusCode === 429)
+            return true;
+        if (statusCode >= 400 && statusCode < 500)
+            return false;
+    }
+    return /(econnreset|econnrefused|etimedout|timeout|timed out|socket|network|fetch failed)/.test(message);
 }
 function formatToolFeedback(results) {
     return [
@@ -381,20 +483,124 @@ function formatToolFeedback(results) {
         "Continue with another JSON response.",
     ].join("\n");
 }
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((entry) => stableJson(entry)).join(",")}]`;
+    const record = value;
+    const volatileKeys = new Set(["session_id", "sessionId", "timestamp", "updated_at", "created_at", "at"]);
+    return `{${Object.keys(record)
+        .filter((key) => !volatileKeys.has(key))
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+        .join(",")}}`;
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function toolDoomLoopKey(toolCall, result) {
+    return sha256Text([
+        toolCall.tool,
+        stableJson(toolCall.input ?? {}),
+        result.ok ? "ok" : "error",
+        sha256Text(result.summary),
+    ].join("\n"));
+}
+function defaultOutputTokenCap(numCtx) {
+    return Math.max(1, Math.min(2048, Math.floor(numCtx / 4)));
+}
+function addUsageTotals(total, usage) {
+    if (!usage)
+        return;
+    total.prompt_tokens += usage.prompt_tokens;
+    total.completion_tokens += usage.completion_tokens;
+}
+function withUsageTotals(result, usageTotals) {
+    if (usageTotals.prompt_tokens === 0 && usageTotals.completion_tokens === 0)
+        return result;
+    return {
+        ...result,
+        usage_totals: { ...usageTotals },
+    };
+}
+function contextOverflowSuspected(usage, numCtx) {
+    return Boolean(usage && usage.prompt_tokens >= Math.floor(numCtx * 0.98));
+}
+const DEFAULT_TOOL_DEADLINE_MS = 120_000;
+function toolDeadlineMs() {
+    const raw = Number(process.env.ACE_TOOL_DEADLINE_MS);
+    return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : DEFAULT_TOOL_DEADLINE_MS;
+}
+/**
+ * Per-tool-call deadline (E12). A hung validation/test subprocess must never
+ * wedge a turn indefinitely — and under Promise.all one stuck call also holds
+ * every parallel sibling's feedback hostage. On timeout we resolve a classified
+ * `tool_timeout` failure that then feeds the WS-C doom-loop brake.
+ */
+export async function executeToolWithDeadline(tool, args, sessionId, opts, deadlineMs, exec = executeAceInternalTool) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ rawToolResult: undefined, timedOut: true }), deadlineMs);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([
+            exec(tool, args, sessionId, opts).then((rawToolResult) => ({
+                rawToolResult,
+                timedOut: false,
+            })),
+            timeout,
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function appendBridgeTrace(input) {
+    const safeRunId = input.runId.replace(/[^a-zA-Z0-9_.-]/g, "_");
+    const traceDir = resolve(input.workspace, "agent-state", "bridge-traces");
+    mkdirSync(traceDir, { recursive: true });
+    appendFileSync(resolve(traceDir, `${safeRunId}.ndjson`), `${JSON.stringify({
+        turn: input.turn,
+        envelope_status: input.envelopeStatus,
+        parse_repairs: input.parseRepairAttempts,
+        drift_repairs: input.outputDriftRepairs,
+        tool_calls: (input.toolCalls ?? []).map((toolCall) => ({
+            tool: toolCall.tool,
+            ok: toolCall.ok,
+            reason_code: toolCall.reason_code ?? (toolCall.ok ? undefined : "tool_error"),
+        })),
+        usage: input.usage,
+        compressed: input.compressed,
+    })}\n`, "utf-8");
+}
 async function collectOllamaResponse(client, model, messages, options) {
     let combined = "";
+    let usage;
+    // Prefer schema-constrained (Ollama ≥ 0.5) over plain json-mode; caller degrades on 400.
+    const ollamaFormat = options?.jsonSchema ? options.jsonSchema : options?.jsonMode ? "json" : undefined;
     for await (const chunk of client.chat({
         model,
         messages,
         stream: true,
+        ...(ollamaFormat !== undefined ? { format: ollamaFormat } : {}),
         options: {
             temperature: 0.2,
             top_p: 0.9,
             num_ctx: options?.num_ctx ?? 8192,
+            num_predict: options?.num_predict ?? defaultOutputTokenCap(options?.num_ctx ?? 8192),
         },
     })) {
         const text = chunk.message?.content ?? "";
         combined += text;
+        if (typeof chunk.prompt_eval_count === "number" || typeof chunk.eval_count === "number") {
+            usage = {
+                prompt_tokens: chunk.prompt_eval_count ?? usage?.prompt_tokens ?? 0,
+                completion_tokens: chunk.eval_count ?? usage?.completion_tokens ?? 0,
+            };
+        }
         if (text || chunk.done) {
             options?.onProgress?.({
                 kind: "model_chunk",
@@ -405,16 +611,25 @@ async function collectOllamaResponse(client, model, messages, options) {
         if (chunk.done)
             break;
     }
-    return combined;
+    return { text: combined, usage };
 }
-async function collectOpenAiCompatibleResponse(client, provider, model, messages, onProgress) {
+async function collectOpenAiCompatibleResponse(client, provider, model, messages, maxTokens, jsonMode, jsonSchema, onProgress) {
     let combined = "";
+    let usage;
+    // Prefer schema-constrained (OpenAI json_schema) over json_object; caller degrades on 400.
+    const openAiResponseFormat = jsonSchema
+        ? { type: "json_schema", json_schema: { name: "ace_envelope", schema: jsonSchema, strict: false } }
+        : jsonMode
+            ? { type: "json_object" }
+            : undefined;
     for await (const chunk of client.chat({
         provider,
         model,
         messages,
         temperature: 0.2,
         topP: 0.9,
+        maxTokens,
+        ...(openAiResponseFormat ? { responseFormat: openAiResponseFormat } : {}),
         onProviderEvent: (event) => {
             onProgress?.({
                 kind: "thinking",
@@ -427,6 +642,12 @@ async function collectOpenAiCompatibleResponse(client, provider, model, messages
         },
     })) {
         combined += chunk.text;
+        if (typeof chunk.promptTokens === "number" || typeof chunk.completionTokens === "number") {
+            usage = {
+                prompt_tokens: chunk.promptTokens ?? usage?.prompt_tokens ?? 0,
+                completion_tokens: chunk.completionTokens ?? usage?.completion_tokens ?? 0,
+            };
+        }
         if (chunk.text || chunk.done) {
             onProgress?.({
                 kind: "model_chunk",
@@ -441,21 +662,37 @@ async function collectOpenAiCompatibleResponse(client, provider, model, messages
         if (chunk.done)
             break;
     }
-    return combined;
+    return { text: combined, usage };
 }
 async function collectProviderResponse(clients, provider, options) {
     return provider.client === "ollama"
         ? collectOllamaResponse(clients.ollama, options.model, options.messages, {
             num_ctx: options.numCtx,
+            num_predict: defaultOutputTokenCap(options.numCtx),
+            jsonMode: options.jsonMode,
+            jsonSchema: options.jsonSchema,
             onProgress: options.onProgress,
         })
-        : collectOpenAiCompatibleResponse(clients.openai, provider.display, options.model, options.messages, options.onProgress);
+        : collectOpenAiCompatibleResponse(clients.openai, provider.display, options.model, options.messages, defaultOutputTokenCap(options.numCtx), options.jsonMode, options.jsonSchema, options.onProgress);
 }
 async function collectProviderResponseWithRetry(clients, provider, options, onThinking) {
     try {
         return await collectProviderResponse(clients, provider, options);
     }
     catch (error) {
+        // Schema-constrained format rejected by provider → degrade to plain json-mode.
+        // Any 400 from a json_schema request is treated as a format-rejection; if the
+        // underlying issue is something else (bad model name, etc.) json-mode will also
+        // fail and propagate the error normally.
+        if (options.jsonSchema && isSchemaFormatRejectedError(error)) {
+            onThinking?.(`[schema-degrade] provider rejected schema-constrained format — retrying with json-mode`);
+            options.onProgress?.({
+                kind: "thinking",
+                at: Date.now(),
+                detail: { reason: "schema_format_degrade" },
+            });
+            return collectProviderResponse(clients, provider, { ...options, jsonSchema: undefined });
+        }
         if (!isRetryableProviderError(error)) {
             throw error;
         }
@@ -529,7 +766,7 @@ export class ModelBridge {
                 messages: selectionMessages,
                 numCtx: Math.min(input.numCtx, 8192),
             });
-            const parsed = parseToolPlan(rawSelection, plan.catalog);
+            const parsed = parseToolPlan(rawSelection.text, plan.catalog);
             const scoped = parsed.selected_tools.slice(0, plan.selection_limit);
             if (scoped.length === 0)
                 return undefined;
@@ -571,6 +808,8 @@ export class ModelBridge {
             workspace: options.workspace,
             tier: requestedTier,
             tools: selectedToolScope,
+            modelClass: options.modelClass,
+            model: options.model,
         });
         const promptBudget = calculateContextBudget(numCtx);
         for (const candidateTier of buildTierFallbackOrder(requestedTier)) {
@@ -580,6 +819,8 @@ export class ModelBridge {
                 workspace: options.workspace,
                 tier: candidateTier,
                 tools: selectedToolScope,
+                modelClass: options.modelClass,
+                model: options.model,
             });
             aceContext = candidateContext;
             if (candidateContext.tokenEstimate <= promptBudget || candidateTier === "brief") {
@@ -597,7 +838,18 @@ export class ModelBridge {
         const childResults = [];
         const touchedPaths = [];
         const declaredEvidenceRefs = [];
+        const usageTotals = { prompt_tokens: 0, completion_tokens: 0 };
         const evidenceRefs = () => mergeEvidenceRefs(touchedPaths, declaredEvidenceRefs);
+        const attachPlaybookMetadata = (result, usedBullets) => {
+            const cleanUsed = (usedBullets ?? []).filter((id) => aceContext.injected_ids.includes(id));
+            if (aceContext.injected_ids.length === 0 && cleanUsed.length === 0)
+                return result;
+            return {
+                ...result,
+                ...(aceContext.injected_ids.length > 0 ? { injected_bullets: [...aceContext.injected_ids] } : {}),
+                ...(cleanUsed.length > 0 ? { used_bullets: [...new Set(cleanUsed)] } : {}),
+            };
+        };
         const sessionId = this.bridgeId;
         const refs = deriveWorkspaceVericifyRunRef({
             session_id: this.bridgeId,
@@ -613,6 +865,11 @@ export class ModelBridge {
         let parseRepairAttempts = 0;
         // Tracks correction attempts for roles that produce semantically drifted output.
         let outputDriftRepairs = 0;
+        const toolDoomLoopCounts = new Map();
+        // Inter-turn text-loop brake (E2): catches a model that keeps emitting the same
+        // non-terminating output (repeated identical tool envelopes / parse errors). The
+        // intra-turn runaway is bounded separately by the num_predict output cap.
+        const textLoopCounts = new Map();
         try {
             await appendVericifyProcessPostSafe({
                 run_id: refs.run_id,
@@ -632,12 +889,17 @@ export class ModelBridge {
                     noteProgress("thinking", { reason: "context_compressed", turn });
                 }
                 this.activeProviderClient = provider.client;
-                const rawResponse = await collectProviderResponseWithRetry(this.clients, provider, {
+                const useJsonEnvelope = ROLES_REQUIRING_JSON_ENVELOPE.has(role);
+                const providerResponse = await collectProviderResponseWithRetry(this.clients, provider, {
                     model: options.model,
                     messages,
                     numCtx,
+                    jsonMode: useJsonEnvelope,
+                    jsonSchema: useJsonEnvelope ? ACE_ENVELOPE_JSON_SCHEMA : undefined,
                     onProgress: options.onProgress,
                 }, options.onThinking);
+                addUsageTotals(usageTotals, providerResponse.usage);
+                const rawResponse = providerResponse.text;
                 this.activeProviderClient = null;
                 const envelope = parseEnvelope(rawResponse);
                 if (envelope.status !== "parse_error") {
@@ -650,7 +912,108 @@ export class ModelBridge {
                     noteProgress("thinking", { turn });
                 }
                 messages.push({ role: "assistant", content: rawResponse });
+                // Text-loop brake (WS-C+, E2): a model stuck repeating the same non-terminating
+                // output. This fires only on turns that execute NO tool — turns that run tools are
+                // governed by the tool-doom-loop brake below (which exempts legitimate polling:
+                // same call, changing results). The gap this closes is an envelope loop that
+                // performs no work, e.g. repeated `{"status":"tool","tool_calls":[]}`, which the
+                // tool brake never sees. Terminal statuses (message/complete/need_input) return
+                // before a repeat can accumulate.
+                const turnExecutesTools = envelope.status === "tool" &&
+                    Array.isArray(envelope.tool_calls) &&
+                    envelope.tool_calls.length > 0;
+                if (!turnExecutesTools) {
+                    const textLoopKey = sha256Text(rawResponse.trim());
+                    const textLoopCount = (textLoopCounts.get(textLoopKey) ?? 0) + 1;
+                    textLoopCounts.set(textLoopKey, textLoopCount);
+                    if (textLoopCount === 3) {
+                        messages.push({
+                            role: "user",
+                            content: "You have produced the same response three times without making progress. " +
+                                "Change approach, call a tool, or report status:need_input — do not repeat yourself.",
+                        });
+                        noteProgress("thinking", { reason: "bridge_text_doom_loop_warning", count: textLoopCount });
+                    }
+                    if (textLoopCount >= 4) {
+                        const summary = "Bridge blocked after repeating an identical response four times without progress.";
+                        await appendVericifyProcessPostSafe({
+                            run_id: refs.run_id,
+                            branch_id: refs.branch_id,
+                            lane_id: refs.lane_id,
+                            agent_id: `agent-${role}`,
+                            kind: "blocker",
+                            summary,
+                            tool_refs: toolResults.map((entry) => entry.tool),
+                            blocker_category: "bridge_text_doom_loop",
+                        });
+                        noteProgress("process_post", { kind: "blocker", reason: "bridge_text_doom_loop" });
+                        return attachPlaybookMetadata(withUsageTotals({
+                            bridge_id: this.bridgeId,
+                            role,
+                            status: "blocked",
+                            reason_code: "bridge_text_doom_loop",
+                            summary,
+                            turns: turn,
+                            tool_calls: toolResults,
+                            child_results: childResults,
+                            evidence_refs: evidenceRefs(),
+                        }, usageTotals));
+                    }
+                }
+                if (contextOverflowSuspected(providerResponse.usage, numCtx)) {
+                    appendBridgeTrace({
+                        workspace: options.workspace,
+                        runId: refs.run_id,
+                        turn,
+                        envelopeStatus: envelope.status,
+                        parseRepairAttempts,
+                        outputDriftRepairs,
+                        compressed: compressed.compressed,
+                        usage: providerResponse.usage,
+                    });
+                    const summary = `Context overflow suspected: provider reported ${providerResponse.usage?.prompt_tokens ?? 0} ` +
+                        `prompt tokens for num_ctx ${numCtx}.`;
+                    await appendStatusEventSafe({
+                        source_module: "capability-qa",
+                        event_type: "MODEL_CONTEXT_OVERFLOW_SUSPECTED",
+                        status: "blocked",
+                        summary,
+                        objective_id: "model-bridge-context-overflow",
+                        payload: {
+                            reason_code: "context_overflow",
+                            role,
+                            provider: provider.display,
+                            model: options.model,
+                            prompt_tokens: providerResponse.usage?.prompt_tokens,
+                            completion_tokens: providerResponse.usage?.completion_tokens,
+                            num_ctx: numCtx,
+                            threshold_ratio: 0.98,
+                        },
+                    });
+                    noteProgress("output", { status: "blocked", reason: "context_overflow" });
+                    return attachPlaybookMetadata(withUsageTotals({
+                        bridge_id: this.bridgeId,
+                        role,
+                        status: "blocked",
+                        reason_code: "context_overflow",
+                        summary,
+                        turns: turn,
+                        tool_calls: toolResults,
+                        child_results: childResults,
+                        evidence_refs: evidenceRefs(),
+                    }, usageTotals));
+                }
                 if (envelope.status === "parse_error") {
+                    appendBridgeTrace({
+                        workspace: options.workspace,
+                        runId: refs.run_id,
+                        turn,
+                        envelopeStatus: envelope.status,
+                        parseRepairAttempts,
+                        outputDriftRepairs,
+                        compressed: compressed.compressed,
+                        usage: providerResponse.usage,
+                    });
                     // 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)) {
@@ -667,7 +1030,7 @@ export class ModelBridge {
                             tool_refs: [],
                         });
                         noteProgress("process_post", { kind: "completion", fallback: "plain_text" });
-                        return verifyCompletionArtifacts({
+                        return verifyCompletionArtifacts(attachPlaybookMetadata(withUsageTotals({
                             bridge_id: this.bridgeId,
                             role,
                             status: "completed",
@@ -676,12 +1039,13 @@ export class ModelBridge {
                             tool_calls: toolResults,
                             child_results: childResults,
                             evidence_refs: evidenceRefs(),
-                        }, {
+                        }, usageTotals)), {
                             role,
                             task: options.task,
                             workspace: options.workspace,
                             touchedPaths,
                             expectedArtifacts: options.expectedArtifacts,
+                            requiredEvidenceRefs: options.requiredEvidenceRefs,
                         });
                     }
                     // Repair path: roles that require a JSON envelope get up to MAX_PARSE_REPAIR_ATTEMPTS
@@ -723,7 +1087,7 @@ export class ModelBridge {
                         tool_refs: toolResults.map((entry) => entry.tool),
                     });
                     noteProgress("process_post", { kind: "blocker" });
-                    return {
+                    return attachPlaybookMetadata(withUsageTotals({
                         bridge_id: this.bridgeId,
                         role,
                         status: "failed",
@@ -732,7 +1096,7 @@ export class ModelBridge {
                         tool_calls: toolResults,
                         child_results: childResults,
                         evidence_refs: evidenceRefs(),
-                    };
+                    }, usageTotals));
                 }
                 if (envelope.status === "tool" &&
                     Array.isArray(envelope.tool_calls) &&
@@ -776,19 +1140,26 @@ export class ModelBridge {
                         });
                         continue;
                     }
-                    const executed = await Promise.all(envelope.tool_calls.map(async (toolCall) => {
+                    const executedPairs = await Promise.all(envelope.tool_calls.map(async (toolCall) => {
                         const args = toolCall.input ?? {};
                         options.onToolCall?.(toolCall.tool, args);
                         noteProgress("tool_start", { tool: toolCall.tool });
-                        const rawToolResult = await executeAceInternalTool(toolCall.tool, args, sessionId, {
-                            workspace_path: options.workspace,
-                        });
-                        const result = truncateToolResult({
-                            tool: toolCall.tool,
-                            ok: !Boolean(rawToolResult?.isError),
-                            isError: Boolean(rawToolResult?.isError),
-                            summary: summarizeToolText(rawToolResult),
-                        }, options.workspace);
+                        const deadlineMs = toolDeadlineMs();
+                        const outcome = await executeToolWithDeadline(toolCall.tool, args, sessionId, { workspace_path: options.workspace }, deadlineMs);
+                        const result = outcome.timedOut
+                            ? {
+                                tool: toolCall.tool,
+                                ok: false,
+                                isError: true,
+                                summary: `tool_timeout: ${toolCall.tool} exceeded ${deadlineMs}ms deadline`,
+                                reason_code: "tool_timeout",
+                            }
+                            : truncateToolResult({
+                                tool: toolCall.tool,
+                                ok: !Boolean(outcome.rawToolResult?.isError),
+                                isError: Boolean(outcome.rawToolResult?.isError),
+                                summary: summarizeToolText(outcome.rawToolResult),
+                            }, options.workspace);
                         options.onToolResult?.(toolCall.tool, result);
                         noteProgress("tool_finish", { tool: toolCall.tool, ok: result.ok });
                         toolResults.push(result);
@@ -801,8 +1172,63 @@ export class ModelBridge {
                             if (pathArg)
                                 touchedPaths.push(pathArg);
                         }
-                        return result;
+                        return { toolCall, result };
                     }));
+                    const executed = executedPairs.map((entry) => entry.result);
+                    appendBridgeTrace({
+                        workspace: options.workspace,
+                        runId: refs.run_id,
+                        turn,
+                        envelopeStatus: envelope.status,
+                        parseRepairAttempts,
+                        outputDriftRepairs,
+                        compressed: compressed.compressed,
+                        usage: providerResponse.usage,
+                        toolCalls: executed,
+                    });
+                    for (const { toolCall, result } of executedPairs) {
+                        const loopKey = toolDoomLoopKey(toolCall, result);
+                        const count = (toolDoomLoopCounts.get(loopKey) ?? 0) + 1;
+                        toolDoomLoopCounts.set(loopKey, count);
+                        if (count === 3) {
+                            messages.push({
+                                role: "user",
+                                content: "You have repeated the same tool call with the same result three times. " +
+                                    "Change approach or report blocked; do not repeat the same failing action.",
+                            });
+                            noteProgress("thinking", {
+                                reason: "bridge_tool_doom_loop_warning",
+                                tool: toolCall.tool,
+                                count,
+                            });
+                            options.onThinking?.(`[doom-loop] repeated ${toolCall.tool} with identical result three times; change approach or report blocked.`);
+                        }
+                        if (count >= 4) {
+                            const summary = `Bridge blocked after repeated identical tool result for ${toolCall.tool}.`;
+                            await appendVericifyProcessPostSafe({
+                                run_id: refs.run_id,
+                                branch_id: refs.branch_id,
+                                lane_id: refs.lane_id,
+                                agent_id: `agent-${role}`,
+                                kind: "blocker",
+                                summary,
+                                tool_refs: toolResults.map((entry) => entry.tool),
+                                blocker_category: "bridge_tool_doom_loop",
+                            });
+                            noteProgress("process_post", { kind: "blocker", reason: "bridge_tool_doom_loop" });
+                            return attachPlaybookMetadata(withUsageTotals({
+                                bridge_id: this.bridgeId,
+                                role,
+                                status: "blocked",
+                                reason_code: "bridge_tool_doom_loop",
+                                summary,
+                                turns: turn,
+                                tool_calls: toolResults,
+                                child_results: childResults,
+                                evidence_refs: evidenceRefs(),
+                            }, usageTotals));
+                        }
+                    }
                     messages.push({
                         role: "user",
                         content: amendedTools.length > 0
@@ -812,6 +1238,16 @@ export class ModelBridge {
                     continue;
                 }
                 if (envelope.status === "message") {
+                    appendBridgeTrace({
+                        workspace: options.workspace,
+                        runId: refs.run_id,
+                        turn,
+                        envelopeStatus: envelope.status,
+                        parseRepairAttempts,
+                        outputDriftRepairs,
+                        compressed: compressed.compressed,
+                        usage: providerResponse.usage,
+                    });
                     const message = readEnvelopeText(envelope.message) || rawResponse.trim();
                     options.onOutput?.(message);
                     noteProgress("output", { status: "message" });
@@ -825,7 +1261,7 @@ export class ModelBridge {
                         tool_refs: [],
                     });
                     noteProgress("process_post", { kind: "progress" });
-                    return verifyCompletionArtifacts({
+                    return verifyCompletionArtifacts(attachPlaybookMetadata(withUsageTotals({
                         bridge_id: this.bridgeId,
                         role,
                         status: "completed",
@@ -834,15 +1270,26 @@ export class ModelBridge {
                         tool_calls: toolResults,
                         child_results: childResults,
                         evidence_refs: evidenceRefs(),
-                    }, {
+                    }, usageTotals), envelope.used_bullets), {
                         role,
                         task: options.task,
                         workspace: options.workspace,
                         touchedPaths,
                         expectedArtifacts: options.expectedArtifacts,
+                        requiredEvidenceRefs: options.requiredEvidenceRefs,
                     });
                 }
                 if (envelope.status === "need_input") {
+                    appendBridgeTrace({
+                        workspace: options.workspace,
+                        runId: refs.run_id,
+                        turn,
+                        envelopeStatus: envelope.status,
+                        parseRepairAttempts,
+                        outputDriftRepairs,
+                        compressed: compressed.compressed,
+                        usage: providerResponse.usage,
+                    });
                     const message = readEnvelopeText(envelope.message) || "Additional operator input required.";
                     options.onOutput?.(message);
                     noteProgress("output", { status: "need_input" });
@@ -856,7 +1303,7 @@ export class ModelBridge {
                         tool_refs: [],
                     });
                     noteProgress("process_post", { kind: "blocker" });
-                    return {
+                    return attachPlaybookMetadata(withUsageTotals({
                         bridge_id: this.bridgeId,
                         role,
                         status: "needs_input",
@@ -865,10 +1312,20 @@ export class ModelBridge {
                         tool_calls: toolResults,
                         child_results: childResults,
                         evidence_refs: evidenceRefs(),
-                    };
+                    }, usageTotals));
                 }
                 if (envelope.status === "complete") {
                     const summary = readEnvelopeText(envelope.summary) || "Bridge completed.";
+                    appendBridgeTrace({
+                        workspace: options.workspace,
+                        runId: refs.run_id,
+                        turn,
+                        envelopeStatus: envelope.status,
+                        parseRepairAttempts,
+                        outputDriftRepairs,
+                        compressed: compressed.compressed,
+                        usage: providerResponse.usage,
+                    });
                     // Output shape drift check: detect semantic violations before accepting the result.
                     const driftViolation = checkOutputShapeDrift(role, summary, toolResults);
                     if (driftViolation) {
@@ -901,7 +1358,7 @@ export class ModelBridge {
                             tool_refs: toolResults.map((entry) => entry.tool),
                         });
                         noteProgress("process_post", { kind: "blocker" });
-                        return {
+                        return attachPlaybookMetadata(withUsageTotals({
                             bridge_id: this.bridgeId,
                             role,
                             status: "failed",
@@ -910,7 +1367,7 @@ export class ModelBridge {
                             tool_calls: toolResults,
                             child_results: childResults,
                             evidence_refs: evidenceRefs(),
-                        };
+                        }, usageTotals));
                     }
                     // Clean output — accept the completion.
                     options.onOutput?.(summary);
@@ -925,7 +1382,7 @@ export class ModelBridge {
                         tool_refs: toolResults.map((entry) => entry.tool),
                     });
                     noteProgress("process_post", { kind: "completion" });
-                    return verifyCompletionArtifacts({
+                    return verifyCompletionArtifacts(attachPlaybookMetadata(withUsageTotals({
                         bridge_id: this.bridgeId,
                         role,
                         status: "completed",
@@ -934,12 +1391,13 @@ export class ModelBridge {
                         tool_calls: toolResults,
                         child_results: childResults,
                         evidence_refs: evidenceRefs(),
-                    }, {
+                    }, usageTotals), envelope.used_bullets), {
                         role,
                         task: options.task,
                         workspace: options.workspace,
                         touchedPaths,
                         expectedArtifacts: options.expectedArtifacts,
+                        requiredEvidenceRefs: options.requiredEvidenceRefs,
                     });
                 }
             }
@@ -954,7 +1412,7 @@ export class ModelBridge {
                 tool_refs: toolResults.map((entry) => entry.tool),
             });
             noteProgress("process_post", { kind: "blocker" });
-            return {
+            return attachPlaybookMetadata(withUsageTotals({
                 bridge_id: this.bridgeId,
                 role,
                 status: "max_turns",
@@ -963,7 +1421,7 @@ export class ModelBridge {
                 tool_calls: toolResults,
                 child_results: childResults,
                 evidence_refs: evidenceRefs(),
-            };
+            }, usageTotals));
         }
         finally {
             this.activeProviderClient = null;