@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.920

package/dist/heart/tool-approval.js

@@ -0,0 +1,382 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalExecutionFailedError = exports.ApprovalExecutionIndeterminateError = void 0;
+exports.coordinateApprovalDecision = coordinateApprovalDecision;
+exports.digestApprovalSuspensionCheckpointPayload = digestApprovalSuspensionCheckpointPayload;
+exports.commitApprovalProposal = commitApprovalProposal;
+exports.recoverApprovalProposals = recoverApprovalProposals;
+exports.digestApprovalToolDefinition = digestApprovalToolDefinition;
+exports.executeApprovalDecision = executeApprovalDecision;
+exports.recoverClaimedApproval = recoverClaimedApproval;
+exports.recoverAttemptedApproval = recoverAttemptedApproval;
+const node_crypto_1 = require("node:crypto");
+const approval_store_1 = require("./approval-store");
+const runtime_1 = require("../nerves/runtime");
+const tool_arguments_1 = require("../repertoire/tool-arguments");
+class ApprovalExecutionIndeterminateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApprovalExecutionIndeterminateError";
+    }
+}
+exports.ApprovalExecutionIndeterminateError = ApprovalExecutionIndeterminateError;
+class ApprovalExecutionFailedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ApprovalExecutionFailedError";
+    }
+}
+exports.ApprovalExecutionFailedError = ApprovalExecutionFailedError;
+async function coordinateApprovalDecision(options) {
+    return options.withSessionLease(async (lease) => {
+        let currentSessionRevision = options.readCurrentRevision();
+        const record = await options.decideAndExecute({
+            currentSessionRevision,
+            lease,
+            hooks: {
+                afterClaim: async () => {
+                    currentSessionRevision = options.readCurrentRevision();
+                },
+            },
+        });
+        await options.persist?.(record);
+        await options.resume(record);
+        (0, runtime_1.emitNervesEvent)({
+            component: "engine",
+            event: "engine.approval_decision_coordinated",
+            message: "approval decision coordinated under session turn lease",
+            meta: { approvalId: record.approvalId, state: record.state },
+        });
+        return { record };
+    });
+}
+function checkpointMatches(record, checkpoint) {
+    return checkpoint.approvalId === record.approvalId
+        && checkpoint.checkpointDigest === record.checkpointDigest
+        && checkpoint.baseSessionRevision === record.baseSessionRevision
+        && (record.state === "preparing" || checkpoint.suspendedSessionRevision === record.suspendedSessionRevision)
+        && checkpoint.argumentDigest === record.argumentDigest
+        && checkpoint.schemaDigest === record.schemaDigest
+        && checkpoint.toolDigest === record.toolDigest
+        && checkpoint.policyDigest === record.policyDigest
+        && checkpoint.preCallDigest === digestTranscript(checkpoint.preCallMessages)
+        && record.checkpointDigest === digestApprovalSuspensionCheckpointPayload(checkpoint)
+        && JSON.stringify(checkpoint.frozenAssistantMessage) === JSON.stringify(record.frozenAssistantMessage);
+}
+function frozenCallMatches(record, checkpoint) {
+    const message = checkpoint.frozenAssistantMessage;
+    if (message.role !== "assistant")
+        return false;
+    if (!Array.isArray(message.tool_calls) || message.tool_calls.length !== 1)
+        return false;
+    const call = message.tool_calls[0];
+    if (!call || typeof call !== "object" || Array.isArray(call))
+        return false;
+    const callRecord = call;
+    if (callRecord.type !== "function")
+        return false;
+    const fn = callRecord.function;
+    if (!fn || typeof fn !== "object" || Array.isArray(fn))
+        return false;
+    const functionRecord = fn;
+    if (callRecord.id !== record.toolCallId || functionRecord.name !== record.toolName || typeof functionRecord.arguments !== "string")
+        return false;
+    try {
+        const parsed = JSON.parse(functionRecord.arguments);
+        return JSON.stringify(parsed) === JSON.stringify(record.arguments);
+    }
+    catch {
+        return false;
+    }
+}
+function digestTranscript(messages) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify(messages), "utf8").digest("hex");
+}
+function digestApprovalSuspensionCheckpointPayload(checkpoint) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify({
+        baseSessionRevision: checkpoint.baseSessionRevision,
+        argumentDigest: checkpoint.argumentDigest,
+        schemaDigest: checkpoint.schemaDigest,
+        toolDigest: checkpoint.toolDigest,
+        policyDigest: checkpoint.policyDigest,
+        preCallDigest: checkpoint.preCallDigest,
+        preCallMessages: checkpoint.preCallMessages,
+        frozenAssistantMessage: checkpoint.frozenAssistantMessage,
+    }), "utf8").digest("hex");
+}
+function digestDecisionToken(token) {
+    return (0, node_crypto_1.createHash)("sha256").update(token, "utf8").digest("hex");
+}
+function commitApprovalProposal(options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.approval_proposal_commit_start",
+        message: "approval proposal commit started",
+        meta: { toolName: options.proposal.toolName, toolCallId: options.proposal.toolCallId },
+    });
+    const preCallDigest = digestTranscript(options.preCallMessages);
+    const checkpointDigest = digestApprovalSuspensionCheckpointPayload({
+        baseSessionRevision: options.proposal.baseSessionRevision,
+        argumentDigest: (0, approval_store_1.canonicalApprovalArguments)(options.proposal.arguments).digest,
+        schemaDigest: options.proposal.schemaDigest,
+        toolDigest: options.proposal.toolDigest,
+        policyDigest: options.proposal.policyDigest,
+        preCallDigest,
+        preCallMessages: options.preCallMessages,
+        frozenAssistantMessage: options.proposal.frozenAssistantMessage,
+    });
+    const prepared = options.approvalStore.prepare({ ...options.proposal, checkpointDigest });
+    options.hooks?.afterJournalPrepare?.();
+    options.tokenStore.put(prepared.record.approvalId, prepared.decisionToken);
+    options.hooks?.afterTokenPersist?.();
+    const attestation = options.checkpointStore.write({
+        approvalId: prepared.record.approvalId,
+        baseSessionRevision: prepared.record.baseSessionRevision,
+        argumentDigest: prepared.record.argumentDigest,
+        schemaDigest: prepared.record.schemaDigest,
+        toolDigest: prepared.record.toolDigest,
+        policyDigest: prepared.record.policyDigest,
+        preCallDigest,
+        preCallMessages: structuredClone(options.preCallMessages),
+        frozenAssistantMessage: structuredClone(prepared.record.frozenAssistantMessage),
+    });
+    options.hooks?.afterCheckpointWrite?.();
+    if (attestation.checkpointDigest !== prepared.record.checkpointDigest) {
+        options.tokenStore.remove(prepared.record.approvalId);
+        options.checkpointStore.remove(prepared.record.approvalId);
+        options.approvalStore.recoverPreparing({
+            approvalId: prepared.record.approvalId,
+            state: "drifted",
+            reason: "checkpoint attestation digest mismatch",
+        });
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "engine",
+            event: "engine.approval_checkpoint_attestation_mismatch",
+            message: "approval checkpoint durability attestation did not match proposal",
+            meta: { approvalId: prepared.record.approvalId },
+        });
+        throw new approval_store_1.ApprovalStoreError("checkpoint_attestation_mismatch");
+    }
+    const record = options.approvalStore.activate({
+        approvalId: prepared.record.approvalId,
+        checkpointDigest: attestation.checkpointDigest,
+        suspendedSessionRevision: attestation.suspendedSessionRevision,
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.approval_proposal_commit_end",
+        message: "approval proposal checkpoint activated",
+        meta: { approvalId: record.approvalId },
+    });
+    return { record, decisionToken: prepared.decisionToken };
+}
+function recoverApprovalProposals(options) {
+    const recovered = [];
+    const preparing = options.approvalStore.listPreparing();
+    const preparingIds = new Set(preparing.map((record) => record.approvalId));
+    for (const checkpoint of options.checkpointStore.list()) {
+        if (preparingIds.has(checkpoint.approvalId) || options.approvalStore.read(checkpoint.approvalId))
+            continue;
+        options.checkpointStore.remove(checkpoint.approvalId);
+        recovered.push({ approvalId: checkpoint.approvalId, state: "orphan_checkpoint_removed" });
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "engine",
+            event: "engine.approval_orphan_checkpoint_removed",
+            message: "removed approval checkpoint with no journal authority",
+            meta: { approvalId: checkpoint.approvalId },
+        });
+    }
+    for (const record of preparing) {
+        const checkpoint = options.checkpointStore.read(record.approvalId);
+        const token = options.tokenStore.get(record.approvalId);
+        const hasToken = token !== null;
+        const tokenMatches = token !== null && digestDecisionToken(token) === record.decisionTokenDigest;
+        if (checkpoint && tokenMatches && checkpointMatches(record, checkpoint)) {
+            const activated = options.approvalStore.activate({
+                approvalId: record.approvalId,
+                checkpointDigest: checkpoint.checkpointDigest,
+                suspendedSessionRevision: checkpoint.suspendedSessionRevision,
+            });
+            recovered.push({ approvalId: record.approvalId, state: activated.state });
+            continue;
+        }
+        options.tokenStore.remove(record.approvalId);
+        if (checkpoint)
+            options.checkpointStore.remove(record.approvalId);
+        const checkpointMismatch = checkpoint !== null && !checkpointMatches(record, checkpoint);
+        const tokenMismatch = hasToken && !tokenMatches;
+        const mismatch = checkpointMismatch || tokenMismatch;
+        const terminal = options.approvalStore.recoverPreparing({
+            approvalId: record.approvalId,
+            state: mismatch ? "drifted" : "abandoned_before_attempt",
+            reason: tokenMismatch ? "decision token evidence mismatch" : mismatch ? "checkpoint evidence mismatch" : "incomplete proposal commit",
+        });
+        recovered.push({ approvalId: record.approvalId, state: terminal.state });
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.approval_proposal_recovery",
+        message: "approval proposal recovery scan completed",
+        meta: { recoveredCount: recovered.length },
+    });
+    return recovered;
+}
+function terminalizeClaimed(store, claimed, state, reason) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "engine",
+        event: "engine.approval_pre_attempt_terminalized",
+        message: "approval stopped during live revalidation",
+        meta: { approvalId: claimed.approvalId, state, reason },
+    });
+    return store.terminalizeBeforeAttempt({
+        approvalId: claimed.approvalId,
+        ownerId: claimed.ownerId,
+        epoch: claimed.epoch,
+        state,
+        reason,
+    });
+}
+function digestApprovalToolDefinition(definition, schemaDigest, policyId) {
+    const binding = definition.mcpBinding;
+    return (0, tool_arguments_1.digestJson)({
+        name: definition.tool.function.name, schemaDigest, policyId, advertisedTool: JSON.parse(JSON.stringify(definition.tool)),
+        ...(binding ? { mcp: {
+                agentName: binding.agentName, agentRoot: binding.agentRoot,
+                server: binding.server, rawName: binding.rawName, surfacedName: binding.surfacedName,
+                source: binding.source, pluginId: binding.pluginId ?? null,
+                configDigest: binding.configDigest,
+            } } : {}),
+    });
+}
+async function resolveApprovalTool(options, decided) {
+    const definition = await options.resolveTool(decided.toolName);
+    if (!definition || definition.tool.function.name !== decided.toolName) {
+        return { ok: false, reason: "tool identity drift" };
+    }
+    const schema = definition.tool.function.parameters;
+    if (!schema || typeof schema !== "object") {
+        return { ok: false, reason: "advertised schema missing" };
+    }
+    const validated = (0, tool_arguments_1.validateAdvertisedToolArguments)(JSON.stringify(decided.arguments), schema);
+    if (!validated.ok || validated.value.argumentDigest !== decided.argumentDigest
+        || validated.value.schemaDigest !== decided.schemaDigest) {
+        return { ok: false, reason: "tool arguments or schema drift" };
+    }
+    const policy = await options.resolveApprovalPolicy?.(decided.toolName, validated.value.arguments)
+        ?? definition.approvalPolicy?.(validated.value.arguments)
+        ?? { kind: "not_required" };
+    if (policy.kind !== "required") {
+        return { ok: false, reason: "approval policy no longer requires approval" };
+    }
+    const toolDigest = digestApprovalToolDefinition(definition, validated.value.schemaDigest, policy.policyId);
+    const policyDigest = (0, tool_arguments_1.digestJson)({ policyId: policy.policyId, actionClass: policy.actionClass, classification: "required" });
+    if (policy.policyId !== decided.policyId || toolDigest !== decided.toolDigest || policyDigest !== decided.policyDigest) {
+        return { ok: false, reason: "approval policy or tool digest drift" };
+    }
+    return { ok: true, definition, arguments: validated.value.arguments };
+}
+async function executeApprovalDecision(options) {
+    const decided = options.approvalStore.decide({ ...options.decision, ownerId: options.ownerId });
+    if (decided.state !== "claimed")
+        return decided;
+    await options.hooks?.afterClaim?.();
+    let currentSessionRevision;
+    try {
+        currentSessionRevision = typeof options.currentSessionRevision === "function" ? options.currentSessionRevision() : options.currentSessionRevision;
+    }
+    catch {
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", "current session revision is unavailable");
+    }
+    if (currentSessionRevision !== decided.suspendedSessionRevision) {
+        return terminalizeClaimed(options.approvalStore, decided, "session_head_changed", "suspended session revision changed");
+    }
+    const checkpoint = options.checkpointStore.read(decided.approvalId);
+    if (!checkpoint || !checkpointMatches(decided, checkpoint) || !frozenCallMatches(decided, checkpoint)) {
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", "checkpoint evidence drift");
+    }
+    const current = await resolveApprovalTool(options, decided);
+    if (!current.ok)
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", current.reason);
+    const context = {
+        record: structuredClone(decided),
+        checkpoint: structuredClone(checkpoint),
+        definition: current.definition,
+        arguments: structuredClone(current.arguments),
+    };
+    const guard = await options.liveGuard(context);
+    if (!guard.ok)
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", guard.reason);
+    const risk = await options.liveRisk(context);
+    if (!risk.ok)
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", risk.reason);
+    const fresh = await resolveApprovalTool(options, decided);
+    if (!fresh.ok)
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", fresh.reason);
+    const preflight = options.preflight
+        ? await options.preflight({ ...context, definition: fresh.definition, arguments: structuredClone(fresh.arguments) })
+        : { ok: false, reason: "canonical tool preflight is unavailable" };
+    if (!preflight.ok)
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", preflight.reason);
+    const attempted = options.approvalStore.markAttempted({
+        approvalId: decided.approvalId,
+        ownerId: decided.ownerId,
+        epoch: decided.epoch,
+    });
+    await options.hooks?.afterAttempt?.();
+    let result;
+    try {
+        result = await options.execute(attempted.toolName, structuredClone(attempted.arguments));
+    }
+    catch (error) {
+        if (!(error instanceof ApprovalExecutionFailedError))
+            throw error;
+        result = { kind: "handler_failed", text: `error: ${error.message}`, error };
+    }
+    if (!result || typeof result.text !== "string"
+        || !["rejected_before_handler", "handler_succeeded", "handler_failed", "handler_indeterminate"].includes(result.kind)) {
+        throw new ApprovalExecutionIndeterminateError("executor returned an invalid typed outcome; action was not retried");
+    }
+    const state = result.kind === "handler_succeeded" ? "succeeded"
+        : result.kind === "handler_indeterminate" ? "attempted_indeterminate" : "failed";
+    const emptyText = {
+        rejected_before_handler: "tool preflight rejected execution",
+        handler_succeeded: "action completed without output",
+        handler_failed: "action failed without details",
+        handler_indeterminate: "execution outcome is indeterminate; action was not retried",
+    };
+    const text = result.text.trim() ? result.text : emptyText[result.kind];
+    await options.hooks?.afterHandler?.();
+    return options.approvalStore.complete({
+        approvalId: attempted.approvalId,
+        ownerId: attempted.ownerId,
+        epoch: attempted.epoch,
+        state,
+        result: result.kind === "rejected_before_handler" ? `no action was taken: ${text}` : text,
+    });
+}
+function recoverClaimedApproval(options) {
+    const record = options.approvalStore.read(options.approvalId);
+    if (!record || record.state !== "claimed" || !record.ownerId)
+        throw new approval_store_1.ApprovalStoreError("claimed_recovery_not_eligible");
+    return options.approvalStore.abandonBeforeAttempt({
+        approvalId: record.approvalId,
+        ownerId: record.ownerId,
+        epoch: record.epoch,
+        reason: options.reason,
+    });
+}
+function recoverAttemptedApproval(options) {
+    const record = options.approvalStore.read(options.approvalId);
+    if (!record || record.state !== "attempted" || !record.ownerId)
+        throw new approval_store_1.ApprovalStoreError("attempted_recovery_not_eligible");
+    return options.approvalStore.complete({
+        approvalId: record.approvalId,
+        ownerId: record.ownerId,
+        epoch: record.epoch,
+        state: "attempted_indeterminate",
+        result: "execution outcome is indeterminate after restart; action was not retried",
+    });
+}

package/dist/heart/tool-description.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.humanReadableToolDescription = humanReadableToolDescription;
+const runtime_1 = require("../nerves/runtime");
+function basename(filePath) {
+    const idx = filePath.lastIndexOf("/");
+    return idx >= 0 ? filePath.slice(idx + 1) : filePath;
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    // Cut at last space before maxLen to avoid mid-word truncation
+    const slice = text.slice(0, max - 1);
+    const lastSpace = slice.lastIndexOf(" ");
+    if (lastSpace > 0)
+        return text.slice(0, lastSpace) + "\u2026";
+    // No space found (single long word) — hard truncate
+    return slice + "\u2026";
+}
+const TOOL_DESCRIPTIONS = {
+    // File operations
+    shell: (args) => {
+        const cmd = args.command;
+        if (!cmd)
+            return "running a command...";
+        return `running ${truncate(cmd, 50)}...`;
+    },
+    read_file: (args) => {
+        const fp = args.path || args.file_path;
+        if (!fp)
+            return "reading a file...";
+        return `reading ${basename(fp)}...`;
+    },
+    write_file: (args) => {
+        const fp = args.path || args.file_path;
+        if (!fp)
+            return "writing a file...";
+        return `writing ${basename(fp)}...`;
+    },
+    edit_file: (args) => {
+        const fp = args.path || args.file_path;
+        if (!fp)
+            return "editing a file...";
+        return `editing ${basename(fp)}...`;
+    },
+    glob: (args) => {
+        const p = args.pattern;
+        if (!p)
+            return "searching for files...";
+        return `searching for ${truncate(p, 40)}...`;
+    },
+    grep: (args) => {
+        const p = args.pattern;
+        if (!p)
+            return "searching code...";
+        return `searching code for '${truncate(p, 40)}'...`;
+    },
+    // Notes and knowledge
+    search_facts: (args) => {
+        const q = args.query;
+        if (!q)
+            return "searching facts...";
+        return `searching facts for '${truncate(q, 40)}'...`;
+    },
+    consult_diary: (args) => {
+        const q = args.query;
+        if (!q)
+            return "checking recent diary facts...";
+        return `consulting diary facts for '${truncate(q, 40)}'...`;
+    },
+    consult_notes: (args) => {
+        const q = args.query;
+        if (!q)
+            return "checking Desk record notes...";
+        return `consulting Desk record notes for '${truncate(q, 40)}'...`;
+    },
+    diary_write: (args) => {
+        const about = args.about;
+        return about ? `noting something about ${truncate(about, 30)}...` : "noting something down...";
+    },
+    save_friend_note: () => "making a note about you...",
+    get_friend_note: () => "checking my notes...",
+    load_skill: (args) => {
+        const name = args.name || args.skill;
+        return name ? `loading ${name} skill...` : "loading a skill...";
+    },
+    // Session and context
+    query_session: (args) => {
+        const mode = args.mode;
+        if (mode === "search")
+            return `searching session for '${truncate(args.query || "", 30)}'...`;
+        if (mode === "status")
+            return "checking private-runtime turn status...";
+        return "checking session history...";
+    },
+    web_search: (args) => {
+        const q = args.query;
+        return q ? `searching the web for '${truncate(q, 35)}'...` : "searching the web...";
+    },
+    coding_spawn: (args) => {
+        const runner = args.runner;
+        return runner ? `starting ${runner} coding session...` : "starting coding session...";
+    },
+    coding_status: () => "checking coding sessions...",
+    coding_tail: () => "reading coding output...",
+    coding_kill: () => "stopping coding session...",
+    bridge_manage: () => "managing conversation bridge...",
+    // Communication
+    send_message: (args) => {
+        const to = args.to || args.friendId;
+        /* v8 ignore next 3 -- voice-send status wording is exercised by outbound voice tool tests; this generic renderer keeps a defensive fallback @preserve */
+        if (args.channel === "voice") {
+            return to ? `placing a voice call to ${to}...` : "placing a voice call...";
+        }
+        return to ? `sending a message to ${to}...` : "sending a message...";
+    },
+    surface: () => "sharing a thought...",
+    // Metacognitive (private runtime)
+    ponder: (args) => {
+        const objective = args.objective || args.thought;
+        return objective ? `bookmarking ${truncate(objective, 40)}...` : "bookmarking deeper work...";
+    },
+    observe: () => null,
+    claude: () => "reasoning...",
+    set_reasoning_effort: (args) => {
+        const level = args.level;
+        return level ? `setting thinking depth to ${level}...` : "adjusting thinking depth...";
+    },
+    // Hidden — these ARE the response or end-of-turn
+    settle: () => null,
+    rest: () => null,
+    descend: () => null,
+    // speak's visible output is the message itself, delivered via onTextChunk +
+    // flushNow. The shared tool-activity callbacks must skip it so no per-sense
+    // tool-status text precedes the actual message.
+    speak: () => null,
+};
+function humanReadableToolDescription(name, args) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.tool_description",
+        message: "generated human-readable tool description",
+        meta: { tool: name },
+    });
+    const builder = TOOL_DESCRIPTIONS[name];
+    if (builder)
+        return builder(args);
+    // MCP tools: mcp__server__toolname — extract last segment
+    if (name.startsWith("mcp__")) {
+        const parts = name.split("__");
+        const toolName = parts[parts.length - 1];
+        return `using ${toolName}...`;
+    }
+    return `using ${name}...`;
+}

package/dist/heart/tool-friction.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolFrictionLedger = createToolFrictionLedger;
+exports.rewriteToolResultForModel = rewriteToolResultForModel;
+const runtime_1 = require("../nerves/runtime");
+const tool_results_1 = require("../repertoire/tool-results");
+function createToolFrictionLedger() {
+    return { signatures: new Map() };
+}
+function parseFrictionResult(result) {
+    try {
+        const parsed = JSON.parse(result);
+        if (parsed.ok !== false || !parsed.tool || !parsed.friction || typeof parsed.friction !== "object") {
+            return null;
+        }
+        return { tool: parsed.tool, friction: parsed.friction };
+    }
+    catch {
+        return null;
+    }
+}
+function rewriteToolResultForModel(tool, result, ledger) {
+    const parsed = parseFrictionResult(result);
+    if (!parsed?.friction.signature)
+        return result;
+    const seen = ledger.signatures.get(parsed.friction.signature) ?? 0;
+    ledger.signatures.set(parsed.friction.signature, seen + 1);
+    if (seen === 0 || parsed.friction.kind === "systemic_harness_bug") {
+        return result;
+    }
+    const escalated = {
+        ...parsed.friction,
+        kind: "systemic_harness_bug",
+        summary: `${parsed.friction.summary} This looks like a harness-level gap now, not just a one-off repair.`,
+        suggested_next_actions: [
+            ...parsed.friction.suggested_next_actions,
+            {
+                kind: "tool",
+                tool: "ponder",
+                reason: "Create a harness_friction packet before asking the user to retry again.",
+            },
+        ],
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.tool_friction_escalated",
+        message: "tool friction escalated to harness bug",
+        meta: {
+            tool,
+            signature: parsed.friction.signature,
+            priorOccurrences: seen,
+        },
+    });
+    return (0, tool_results_1.frictionToolResult)(tool, escalated);
+}