@wrongstack/wrongtrace 0.313.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ECOSTACK TECHNOLOGY OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapters/ipc.d.ts

@@ -0,0 +1,49 @@
+/**
+ * IPC transport adapter for WrongTrace — JSON-RPC 2.0 over Named Pipe / UDS.
+ *
+ * Wire format (daemon 2026-08-24+):
+ *   request:  {"jsonrpc":"2.0","id":N,"method":"telemetry/file_health","params":{...}}\n
+ *   response: {"jsonrpc":"2.0","id":N,"result":{...}}\n
+ *            |{"jsonrpc":"2.0","id":N,"error":{"code":-32601,"message":"..."}}\n
+ *
+ * Live-verified (2026-08-24, both \\.\pipe\wrongtrace and \\.\pipe\wrongtrace-int):
+ * only `telemetry/file_health` and `telemetry/report_run` answer on the pipe;
+ * guardrail/atlas exist solely as HTTP routes. The legacy REST-over-pipe
+ * framing ({"method":"GET","path":...}) is GONE from the daemon — it now
+ * replies -32601 "method not found: GET", so this adapter no longer sends it.
+ *
+ * Degradation contract (mirrors the HTTP client): `call()` NEVER throws.
+ * Transport failures (connect refused, timeout, malformed frames) resolve
+ * `{ result: null }`; daemon error envelopes resolve `{ result: null, error }`.
+ * Callers fall back to HTTP instead of mistaking an envelope for a result —
+ * the exact bug the legacy framing produced in `getAtlas()`.
+ */
+export interface IpcTimeouts {
+    connectTimeoutMs?: number;
+    readTimeoutMs?: number;
+}
+export interface IpcCallResult<T = unknown> {
+    /** JSON-RPC `result` body when the call succeeded, else `null`. */
+    result: T | null;
+    /** Present only when the daemon replied with a JSON-RPC error envelope. */
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface IpcTransport {
+    /** Always `false` when constructed without a socketPath. */
+    readonly isWired: boolean;
+    /**
+     * Round-trips one JSON-RPC 2.0 call over a fresh connection. One request
+     * per connection means any error envelope on the wire is unambiguously
+     * ours — no cross-connection id confusion at these latencies (~0.3ms).
+     */
+    call<T = unknown>(method: string, params: Record<string, unknown>): Promise<IpcCallResult<T>>;
+}
+declare class TimeoutError extends Error {
+    constructor(ms: number);
+}
+export declare function createIpcTransport(socketPath?: string, timeouts?: IpcTimeouts): IpcTransport;
+export { TimeoutError as IpcTimeoutError };
+//# sourceMappingURL=ipc.d.ts.map

package/dist/adapters/ipc.js

@@ -0,0 +1,127 @@
+/**
+ * IPC transport adapter for WrongTrace — JSON-RPC 2.0 over Named Pipe / UDS.
+ *
+ * Wire format (daemon 2026-08-24+):
+ *   request:  {"jsonrpc":"2.0","id":N,"method":"telemetry/file_health","params":{...}}\n
+ *   response: {"jsonrpc":"2.0","id":N,"result":{...}}\n
+ *            |{"jsonrpc":"2.0","id":N,"error":{"code":-32601,"message":"..."}}\n
+ *
+ * Live-verified (2026-08-24, both \\.\pipe\wrongtrace and \\.\pipe\wrongtrace-int):
+ * only `telemetry/file_health` and `telemetry/report_run` answer on the pipe;
+ * guardrail/atlas exist solely as HTTP routes. The legacy REST-over-pipe
+ * framing ({"method":"GET","path":...}) is GONE from the daemon — it now
+ * replies -32601 "method not found: GET", so this adapter no longer sends it.
+ *
+ * Degradation contract (mirrors the HTTP client): `call()` NEVER throws.
+ * Transport failures (connect refused, timeout, malformed frames) resolve
+ * `{ result: null }`; daemon error envelopes resolve `{ result: null, error }`.
+ * Callers fall back to HTTP instead of mistaking an envelope for a result —
+ * the exact bug the legacy framing produced in `getAtlas()`.
+ */
+import { connect } from "node:net";
+const CONNECT_TIMEOUT_MS = 2_000;
+const READ_TIMEOUT_MS = 5_000;
+class TimeoutError extends Error {
+    constructor(ms) {
+        super(`IPC request exceeded ${ms}ms`);
+        this.name = "TimeoutError";
+    }
+}
+function once(emitter, event, predicate = () => true) {
+    return new Promise((resolve, reject) => {
+        const onAny = (...args) => {
+            if (predicate(...args)) {
+                emitter.removeListener("error", onError);
+                emitter.removeListener(event, onAny);
+                resolve(args);
+            }
+        };
+        const onError = (err) => {
+            emitter.removeListener(event, onAny);
+            reject(err);
+        };
+        emitter.once(event, onAny);
+        emitter.once("error", onError);
+    });
+}
+// JSON-RPC ids only need to be unique per connection, but a process-wide
+// counter costs nothing and makes correlation observable in logs/probes.
+let nextRequestId = 1;
+export function createIpcTransport(socketPath, timeouts) {
+    if (!socketPath) {
+        return {
+            isWired: false,
+            async call() {
+                return { result: null };
+            },
+        };
+    }
+    const connectTimeoutMs = timeouts?.connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
+    const readTimeoutMs = timeouts?.readTimeoutMs ?? READ_TIMEOUT_MS;
+    return {
+        isWired: true,
+        async call(method, params) {
+            const sock = connect(socketPath);
+            const id = nextRequestId++;
+            let timer;
+            const cleanup = () => {
+                if (timer)
+                    clearTimeout(timer);
+                sock.destroy();
+            };
+            try {
+                await Promise.race([
+                    once(sock, "connect"),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new TimeoutError(connectTimeoutMs)), connectTimeoutMs);
+                    }),
+                ]);
+                clearTimeout(timer);
+                timer = undefined;
+                const payload = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`;
+                sock.write(payload);
+                timer = setTimeout(() => sock.destroy(new TimeoutError(readTimeoutMs)), readTimeoutMs);
+                // Line-buffered frame reader: accumulate until the newline-delimited
+                // frame carrying our response arrives. Junk/partial lines are skipped,
+                // not fatal — the daemon is allowed to chatter before answering.
+                let buffer = "";
+                for await (const chunk of sock) {
+                    buffer += chunk.toString("utf8");
+                    let newlineAt = buffer.indexOf("\n");
+                    while (newlineAt !== -1) {
+                        const line = buffer.slice(0, newlineAt).trim();
+                        buffer = buffer.slice(newlineAt + 1);
+                        newlineAt = buffer.indexOf("\n");
+                        if (line.length === 0)
+                            continue;
+                        let envelope;
+                        try {
+                            envelope = JSON.parse(line);
+                        }
+                        catch {
+                            continue; // malformed line — tolerate, keep scanning
+                        }
+                        if (envelope.error) {
+                            return { result: null, error: envelope.error };
+                        }
+                        if (envelope.id === id || envelope.id === null) {
+                            return { result: (envelope.result ?? null) };
+                        }
+                        // Different id — a frame for someone else; keep scanning.
+                    }
+                }
+                // Socket closed without a usable frame.
+                return { result: null };
+            }
+            catch {
+                return { result: null };
+            }
+            finally {
+                cleanup();
+            }
+        },
+    };
+}
+// Re-exporting for tests / advanced consumers that want the underlying timeout error.
+export { TimeoutError as IpcTimeoutError };
+//# sourceMappingURL=ipc.js.map

package/dist/adapters/mcp.d.ts

@@ -0,0 +1,28 @@
+/**
+ * MCP transport adapter for WrongTrace.
+ *
+ * When the daemon is exposed as an MCP server (e.g. via `wrongtrace mcp`),
+ * the integration protocol can call its tools directly instead of HTTP.
+ * The adapter hides the lookup so `WrongTraceClient` can stay oblivious.
+ *
+ * MCP discovery is lazy: the adapter does NOT require the MCP SDK at
+ * construction time. We accept a `tools` bag from the caller — typically
+ * populated from `mcp_control.list()` in the host runtime. If no tools
+ * are provided, every call resolves with `null`, same as HTTP/IPC
+ * failure paths.
+ */
+import type { WrongTraceHealth, WrongTraceLockResult } from "../types.js";
+export type McpToolName = "check_guardrail" | "get_file_health_score" | "get_symbol_lineage" | "get_friction_matrix" | "get_atlas" | "lock_file" | "unlock_file" | "report_telemetry";
+export type McpToolHandler = (args: Record<string, unknown>) => Promise<unknown>;
+export type McpToolBag = Partial<Record<McpToolName, McpToolHandler>>;
+export interface McpTransport {
+    readonly isWired: boolean;
+    readonly availableTools: McpToolName[];
+    invoke<T = unknown>(tool: McpToolName, args: Record<string, unknown>): Promise<T | null>;
+}
+export declare function createMcpTransport(tools?: McpToolBag): McpTransport;
+export declare const mcp: {
+    health(_health: WrongTraceHealth | null): McpToolName | null;
+    lockResult(result: WrongTraceLockResult | null): WrongTraceLockResult | null;
+};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/adapters/mcp.js

@@ -0,0 +1,42 @@
+/**
+ * MCP transport adapter for WrongTrace.
+ *
+ * When the daemon is exposed as an MCP server (e.g. via `wrongtrace mcp`),
+ * the integration protocol can call its tools directly instead of HTTP.
+ * The adapter hides the lookup so `WrongTraceClient` can stay oblivious.
+ *
+ * MCP discovery is lazy: the adapter does NOT require the MCP SDK at
+ * construction time. We accept a `tools` bag from the caller — typically
+ * populated from `mcp_control.list()` in the host runtime. If no tools
+ * are provided, every call resolves with `null`, same as HTTP/IPC
+ * failure paths.
+ */
+export function createMcpTransport(tools = {}) {
+    const entries = Object.entries(tools).filter(([, v]) => typeof v === "function");
+    return {
+        isWired: entries.length > 0,
+        availableTools: entries.map(([k]) => k),
+        async invoke(tool, args) {
+            const handler = tools[tool];
+            if (!handler)
+                return null;
+            try {
+                return (await handler(args));
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+// Convenience mappers — keep the spec endpoints ↔ MCP tool names in one place
+// so future renames only need to touch this file.
+export const mcp = {
+    health(_health) {
+        return null; // `/api/health` is HTTP-only by spec
+    },
+    lockResult(result) {
+        return result;
+    },
+};
+//# sourceMappingURL=mcp.js.map

package/dist/agent-helpers.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent-facing helpers — opinionated wrappers over the raw WrongTrace
+ * client that turn multi-call queries into single, decision-ready values.
+ *
+ * Why this file exists:
+ *   The base client returns rich-but-unopinionated JSON (friction edges,
+ *   atlas nodes, file health rows). An agent deciding whether to edit a
+ *   file should not have to fuse those three calls by hand. These helpers
+ *   produce ONE number, ONE sentence, ONE list — the things an agent or a
+ *   prompt actually consumes.
+ *
+ * Every helper degrades gracefully when WrongTrace is offline: it returns
+ * a typed "no-op" shape that the caller can wire unconditionally.
+ */
+import type { WrongTraceAtlasSummary, WrongTraceClient } from "./types.js";
+/**
+ * Combines `getFileHealth(path)` + `getFrictionMatrix()` into one
+ * decision-ready score. Returns:
+ *   - `risk`: 0..100 — how dangerous editing this file is RIGHT NOW
+ *   - `band`: "safe" | "caution" | "fragile" | "locked" | "unknown"
+ *   - `reasons`: human-readable bullet list for prompt injection
+ *
+ * Heuristic (documented so the numbers don't drift silently):
+ *   - file.is_locked         → 100, "locked"
+ *   - file.health_score <40  → base 80, "fragile"
+ *   - file.recent_thrashing  → +5 per event above 3, cap at +25
+ *   - friction: this file's
+ *     author_model vs top
+ *     overwriter_model      → +20 if conflict_count >= 3
+ *   - all multipliers cap at 100.
+ *
+ * The `path` → friction join is intentionally fuzzy: the daemon's
+ * friction matrix does not always carry a per-file field, so when no
+ * row mentions `path`, we attribute only the file-health signals. This
+ * keeps the helper robust against daemon schema drift.
+ */
+export interface CrossAgentRisk {
+    path: string;
+    risk: number;
+    band: "safe" | "caution" | "fragile" | "locked" | "unknown";
+    reasons: string[];
+}
+export declare function getCrossAgentRisk(wt: WrongTraceClient, path: string, frictionLimit?: number, 
+/** Caller's lock-owner identity (`wrongstack:<sessionId>`). A lock the
+ *  caller itself holds (e.g. leaked by an interrupted earlier edit) is
+ *  exempted — it must not deny the session's own retry. */
+selfOwner?: string): Promise<CrossAgentRisk>;
+/**
+ * Condenses `getFrictionMatrix()` into a short, prompt-ready string:
+ *
+ *   "Top friction pair: MiniMax-M3 ↔ gemini-3.7-flash (3 conflicts).
+ *    Cross-agent ratio: 40% of 10 collisions. Self-thrash: 60%."
+ *
+ * Returns "" when no signal is available — the caller can drop the
+ * block from the prompt without branching.
+ */
+export interface FrictionSummary {
+    topPair: string | null;
+    crossAgentRatioPct: number;
+    selfThrashRatioPct: number;
+    totalCollisions: number;
+    prose: string;
+}
+export declare function summarizeFriction(friction: unknown): FrictionSummary;
+export interface RecentActivityEntry {
+    at: string;
+    actor: string;
+    action: string;
+    runId?: string | undefined;
+}
+/**
+ * Returns a chronological list of recent activity events for a file,
+ * sourcing from both the friction matrix's `recent_collisions` and any
+ * dedicated events endpoint exposed by the daemon.
+ *
+ * Returns [] when no events are available or the daemon is offline —
+ * the caller can treat an empty result as "no history known".
+ */
+export declare function getRecentActivity(wt: WrongTraceClient, filePath: string, limit?: number): Promise<RecentActivityEntry[]>;
+/**
+ * Summarizes `getAtlas()` for boot prompts:
+ *   - workspace count
+ *   - fragile-file count (health_score < 40 OR is_fragile)
+ *   - self-thrash-heavy workspaces (those with >5 recent_thrashing files)
+ *
+ * Returns null when no atlas is available — the caller can skip
+ * the prompt block.
+ */
+export interface AtlasDigest {
+    workspaceCount: number;
+    fragileFileCount: number;
+    selfThrashWorkspaces: string[];
+    prose: string;
+}
+interface AtlasPackage {
+    name: string;
+    files?: Array<{
+        health_score?: number;
+        is_fragile?: boolean;
+        recent_thrashing_count?: number;
+    }>;
+}
+interface AtlasShape {
+    workspaces?: string[];
+    packages?: AtlasPackage[];
+}
+export declare function digestAtlas(atlas: WrongTraceAtlasSummary | AtlasShape | null): AtlasDigest | null;
+export {};
+//# sourceMappingURL=agent-helpers.d.ts.map

package/dist/agent-helpers.js

@@ -0,0 +1,226 @@
+/**
+ * Agent-facing helpers — opinionated wrappers over the raw WrongTrace
+ * client that turn multi-call queries into single, decision-ready values.
+ *
+ * Why this file exists:
+ *   The base client returns rich-but-unopinionated JSON (friction edges,
+ *   atlas nodes, file health rows). An agent deciding whether to edit a
+ *   file should not have to fuse those three calls by hand. These helpers
+ *   produce ONE number, ONE sentence, ONE list — the things an agent or a
+ *   prompt actually consumes.
+ *
+ * Every helper degrades gracefully when WrongTrace is offline: it returns
+ * a typed "no-op" shape that the caller can wire unconditionally.
+ */
+export async function getCrossAgentRisk(wt, path, frictionLimit = 50, 
+/** Caller's lock-owner identity (`wrongstack:<sessionId>`). A lock the
+ *  caller itself holds (e.g. leaked by an interrupted earlier edit) is
+ *  exempted — it must not deny the session's own retry. */
+selfOwner) {
+    if (!wt.isAvailable) {
+        return { path, risk: 0, band: "unknown", reasons: ["WrongTrace offline — no signal available"] };
+    }
+    const health = await wt.getFileHealth(path);
+    const friction = await wt.getFrictionMatrix(frictionLimit);
+    if (health?.is_locked) {
+        // Self-owner exemption: a live lock claimed by THIS session is not a
+        // foreign conflict. The acquire happens in preToolUse, so a retry or a
+        // leaked own lock must fall through to health scoring instead of
+        // hard-blocking the session's own edit path.
+        if (selfOwner !== undefined && health.lock_owner === selfOwner) {
+            const exempted = await scoreFromHealth(path, health, friction);
+            exempted.reasons.unshift(`own lock held (owner ${selfOwner}) — exempted`);
+            return exempted;
+        }
+        const expiresAt = health.lock_expires_at ? Date.parse(health.lock_expires_at) : Number.NaN;
+        const hasExpiry = !Number.isNaN(expiresAt);
+        // A lock whose TTL already elapsed is stale — the daemon may not have
+        // reaped it yet. Treat it as unlocked (fall through to health scoring)
+        // so a dead lock can never block an edit forever.
+        if (hasExpiry && expiresAt <= Date.now()) {
+            // fall through to normal scoring below; note the stale lock.
+            const staleReason = `stale lock ignored (expired at ${health.lock_expires_at})`;
+            const base = await scoreFromHealth(path, health, friction);
+            base.reasons.unshift(staleReason);
+            return base;
+        }
+        const ownerNote = health.lock_owner ? ` by ${health.lock_owner}` : "";
+        const reasonNote = health.lock_reason ? `: ${health.lock_reason}` : "";
+        const expiryNote = hasExpiry
+            ? `, expires ${new Date(expiresAt).toISOString()}`
+            : " (no expiry — daemon TTL missing, treat as held)";
+        return {
+            path,
+            risk: 100,
+            band: "locked",
+            reasons: [`file is locked${ownerNote}${reasonNote}${expiryNote}`],
+        };
+    }
+    if (health) {
+        return scoreFromHealth(path, health, friction);
+    }
+    return { path, risk: 50, band: "unknown", reasons: ["file health endpoint unreachable"] };
+}
+/** Shared scoring used both directly and after a stale-lock fallthrough. */
+async function scoreFromHealth(path, health, friction) {
+    const reasons = [];
+    let risk = 0;
+    if (health.is_fragile || health.health_score < 40) {
+        risk = Math.max(risk, 80);
+        reasons.push(`file is fragile (health_score=${health.health_score})`);
+    }
+    else if (health.health_score < 70) {
+        risk = Math.max(risk, 45);
+        reasons.push(`health_score below 70 (${health.health_score})`);
+    }
+    if (health.recent_thrashing_count > 3) {
+        const thrashPenalty = Math.min(25, (health.recent_thrashing_count - 3) * 5);
+        risk = Math.min(100, risk + thrashPenalty);
+        reasons.push(`${health.recent_thrashing_count} recent write/delete cycles in last 24h (+${thrashPenalty})`);
+    }
+    // Path-aware friction lookup: best-effort, daemon schema may not carry file_path.
+    const fileFriction = friction.filter((row) => {
+        const r = row;
+        if (typeof r.file_path === "string")
+            return r.file_path === path;
+        if (Array.isArray(r.files))
+            return r.files.includes(path);
+        return false;
+    });
+    if (fileFriction.length > 0) {
+        const totalConflicts = fileFriction.reduce((acc, r) => {
+            const raw = r.conflict_count;
+            return acc + (typeof raw === "number" ? raw : 0);
+        }, 0);
+        if (totalConflicts >= 3) {
+            risk = Math.min(100, risk + 20);
+            reasons.push(`${totalConflicts} cross-agent conflicts on this file in friction matrix (+20)`);
+        }
+    }
+    const band = risk >= 80 ? "fragile" :
+        risk >= 50 ? "caution" :
+            risk > 0 ? "safe" :
+                "safe";
+    if (reasons.length === 0)
+        reasons.push("no risk signals — file is healthy");
+    return { path, risk, band, reasons };
+}
+export function summarizeFriction(friction) {
+    const empty = {
+        topPair: null,
+        crossAgentRatioPct: 0,
+        selfThrashRatioPct: 0,
+        totalCollisions: 0,
+        prose: "",
+    };
+    if (!friction || typeof friction !== "object")
+        return empty;
+    const r = friction;
+    const edges = Array.isArray(r.edges) ? r.edges : [];
+    const total = typeof r.total_collisions === "number" ? r.total_collisions : edges.length;
+    if (total === 0)
+        return empty;
+    // Find top pair by total conflict_count across both directions.
+    const pairTotals = new Map();
+    for (const e of edges) {
+        const key = [e.author_model, e.overwriter_model].sort().join("|");
+        const raw = e.conflict_count;
+        const c = typeof raw === "number" ? raw : 0;
+        const cur = pairTotals.get(key);
+        if (cur)
+            cur.count = cur.count + c;
+        else
+            pairTotals.set(key, { count: c, a: e.author_model, b: e.overwriter_model });
+    }
+    const topEntry = [...pairTotals.values()].sort((x, y) => y.count - x.count)[0];
+    const topPair = topEntry ? `${topEntry.a} ↔ ${topEntry.b} (${topEntry.count} conflicts)` : null;
+    const selfThrash = edges.filter((e) => e.is_self_thrash).length;
+    const crossAgent = total - selfThrash;
+    const crossAgentRatioPct = total > 0 ? Math.round((crossAgent / total) * 100) : 0;
+    const selfThrashRatioPct = total > 0 ? Math.round((selfThrash / total) * 100) : 0;
+    const prose = (topPair ? `Top friction pair: ${topPair}. ` : "") +
+        `Cross-agent ratio: ${crossAgentRatioPct}% of ${total} collisions. ` +
+        `Self-thrash: ${selfThrashRatioPct}%.`;
+    return { topPair, crossAgentRatioPct, selfThrashRatioPct, totalCollisions: total, prose };
+}
+/**
+ * Returns a chronological list of recent activity events for a file,
+ * sourcing from both the friction matrix's `recent_collisions` and any
+ * dedicated events endpoint exposed by the daemon.
+ *
+ * Returns [] when no events are available or the daemon is offline —
+ * the caller can treat an empty result as "no history known".
+ */
+export async function getRecentActivity(wt, filePath, limit = 10) {
+    if (!wt.isAvailable)
+        return [];
+    // Friction's recent_collisions is the most reliable signal today.
+    // The daemon does not yet expose a per-file events endpoint (see
+    // Missing-Endpoints report), so this is our primary source.
+    const matrix = (await getFrictionRaw(wt, limit * 5));
+    const collisions = Array.isArray(matrix.recent_collisions) ? matrix.recent_collisions : [];
+    const events = Array.isArray(matrix.events) ? matrix.events : [];
+    const all = [...events, ...collisions];
+    const matched = [];
+    for (const ev of all) {
+        if (typeof ev.file_path !== "string" || ev.file_path !== filePath)
+            continue;
+        const at = ev.overwriter_time ?? ev.author_time ?? "";
+        if (!at)
+            continue;
+        const entry = {
+            at,
+            actor: ev.overwriter_model ?? ev.author_model ?? "unknown",
+            action: ev.action ?? "MODIFIED",
+        };
+        const runId = ev.overwriter_run_id ?? ev.author_run_id;
+        if (runId)
+            entry.runId = runId;
+        matched.push(entry);
+    }
+    matched.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : 0));
+    return matched.slice(0, limit);
+}
+async function getFrictionRaw(wt, limit) {
+    // We piggyback on getFrictionMatrix's underlying call by issuing one HTTP
+    // request. Since the client doesn't expose raw access, we read the
+    // matrix through a dedicated call. Reusing getFrictionMatrix keeps the
+    // helper testable without leaking transport details.
+    return wt.getFrictionMatrix(limit);
+}
+export function digestAtlas(atlas) {
+    if (!atlas)
+        return null;
+    const a = atlas;
+    const workspaces = Array.isArray(a.workspaces) ? a.workspaces : [];
+    const packages = Array.isArray(a.packages) ? a.packages : [];
+    let fragileFileCount = 0;
+    const thrashCounts = new Map();
+    for (const pkg of packages) {
+        const files = pkg.files ?? [];
+        for (const f of files) {
+            if ((f.health_score ?? 100) < 40 || f.is_fragile === true)
+                fragileFileCount++;
+            const thrash = f.recent_thrashing_count ?? 0;
+            if (thrash > 5)
+                thrashCounts.set(pkg.name, (thrashCounts.get(pkg.name) ?? 0) + 1);
+        }
+    }
+    const selfThrashWorkspaces = [...thrashCounts.entries()]
+        .filter(([, n]) => n > 0)
+        .sort((x, y) => y[1] - x[1])
+        .slice(0, 5)
+        .map(([name]) => name);
+    const prose = `Atlas: ${workspaces.length || packages.length} workspaces, ` +
+        `${fragileFileCount} fragile files, ` +
+        (selfThrashWorkspaces.length > 0
+            ? `self-thrash hotspots: ${selfThrashWorkspaces.join(", ")}.`
+            : "no self-thrash hotspots.");
+    return {
+        workspaceCount: workspaces.length || packages.length,
+        fragileFileCount,
+        selfThrashWorkspaces,
+        prose,
+    };
+}
+//# sourceMappingURL=agent-helpers.js.map

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The integrated WrongTrace client.
+ *
+ *  ┌────────────────┐    ┌────────────────┐    ┌──────────────────┐
+ *  │  HTTP / REST   │ ←→ │  WrongTrace    │ ←→ │  IPC / MCP opt.  │
+ *  │  (always)      │    │  Client        │    │  (if discovered) │
+ *  └────────────────┘    └────────────────┘    └──────────────────┘
+ *
+ * Strategy:
+ *   - IPC-first: when `/api/health` reports a `socket_path`, JSON-RPC 2.0
+ *     over the pipe is preferred for every method the daemon exposes there.
+ *     Daemon v0.3.3 (live-verified 2026-08-24) answers telemetry/file_health,
+ *     telemetry/report_run, guardrail/unlock and get_atlas on the pipe;
+ *     older daemons reply -32601, which the transport surfaces as
+ *     {result:null} → HTTP fallback, so routing is a no-op there.
+ *   - ONE exception: guardrail/lock answers on the pipe but does NOT enforce
+ *     conflicts — a live probe (2026-08-24) showed IPC lock with force:false
+ *     silently TAKES OVER another owner's lock instead of rejecting with the
+ *     -32009 envelope the integration letter promises. lockFile therefore
+ *     stays HTTP-first to preserve the 409 conflict semantics production
+ *     gates depend on. Flip it when the daemon enforces conflicts on IPC.
+ *   - HTTP is the universal substrate — every method has an HTTP path and
+ *     serves as the fallback when the pipe is absent or fails.
+ *   - MCP is used when the host runtime supplies an MCP tool bag. In that
+ *     mode we prefer IPC, then the named MCP tools (lock_file,
+ *     get_file_health_score, etc.), then HTTP.
+ *
+ * Every method returns `null` (or `[]` for list endpoints) when the
+ * underlying transport failed OR the daemon was never reachable. The
+ * protocol promises callers can wire this client unconditionally and
+ * "pass" when WrongTrace is offline.
+ */
+import { type McpToolBag } from "./adapters/mcp.js";
+import { type DiscoveryOptions, type DiscoveryResult } from "./discovery.js";
+import type { WrongTraceClient } from "./types.js";
+export interface WrongTraceClientOptions extends DiscoveryOptions {
+    /** Optional MCP tool bag — typically `mcp_control.list()` output. */
+    mcpTools?: McpToolBag;
+}
+export interface WrongTraceClientInternal extends WrongTraceClient {
+    /** Internal: lets tests + integrations verify what was actually discovered. */
+    readonly _discovery: DiscoveryResult;
+}
+export declare function createWrongTraceClient(opts?: WrongTraceClientOptions): Promise<WrongTraceClientInternal>;
+//# sourceMappingURL=client.d.ts.map