@wrongstack/wrongtrace 0.317.0 → 0.317.2

package/dist/adapters/mcp.d.ts

@@ -20,7 +20,20 @@ export interface McpTransport {
     readonly availableTools: McpToolName[];
     invoke<T = unknown>(tool: McpToolName, args: Record<string, unknown>): Promise<T | null>;
 }
-export declare function createMcpTransport(tools?: McpToolBag): McpTransport;
+/**
+ * Per-call bound — shared with httpJson via constants.ts so every transport
+ * surface in this adapter carries the same latency ceiling: a hung MCP
+ * bridge can never block the edit path (see hooks.ts failure philosophy:
+ * coordination is an optimization, never a hard dependency).
+ *
+ * Cancellation note: the bound limits CALLER settlement only. When the
+ * timeout branch wins, the underlying handler promise is not aborted — the
+ * MCP tool contract has no abort channel, so a never-settling handler keeps
+ * running (and any resources it captured stay alive) until it settles on its
+ * own. Callers are bounded regardless; the outlived promise is garbage once
+ * nothing references it.
+ */
+export declare function createMcpTransport(tools?: McpToolBag, timeoutMs?: number): McpTransport;
 export declare const mcp: {
     health(_health: WrongTraceHealth | null): McpToolName | null;
     lockResult(result: WrongTraceLockResult | null): WrongTraceLockResult | null;

package/dist/adapters/mcp.js

@@ -11,7 +11,21 @@
  * are provided, every call resolves with `null`, same as HTTP/IPC
  * failure paths.
  */
-export function createMcpTransport(tools = {}) {
+import { DEFAULT_TRANSPORT_TIMEOUT_MS } from "../constants.js";
+/**
+ * Per-call bound — shared with httpJson via constants.ts so every transport
+ * surface in this adapter carries the same latency ceiling: a hung MCP
+ * bridge can never block the edit path (see hooks.ts failure philosophy:
+ * coordination is an optimization, never a hard dependency).
+ *
+ * Cancellation note: the bound limits CALLER settlement only. When the
+ * timeout branch wins, the underlying handler promise is not aborted — the
+ * MCP tool contract has no abort channel, so a never-settling handler keeps
+ * running (and any resources it captured stay alive) until it settles on its
+ * own. Callers are bounded regardless; the outlived promise is garbage once
+ * nothing references it.
+ */
+export function createMcpTransport(tools = {}, timeoutMs = DEFAULT_TRANSPORT_TIMEOUT_MS) {
     const entries = Object.entries(tools).filter(([, v]) => typeof v === "function");
     return {
         isWired: entries.length > 0,
@@ -20,12 +34,30 @@ export function createMcpTransport(tools = {}) {
             const handler = tools[tool];
             if (!handler)
                 return null;
+            let timer;
             try {
-                return (await handler(args));
+                // Bound the await: a handler that never settles must resolve null
+                // after timeoutMs instead of leaving the caller pending forever.
+                // Promise.race consumes both settlement paths, so a late rejection
+                // of the underlying handler cannot surface as an unhandled rejection.
+                return (await Promise.race([
+                    handler(args),
+                    new Promise((resolve) => {
+                        timer = setTimeout(() => resolve(null), timeoutMs);
+                    }),
+                ]));
             }
             catch {
                 return null;
             }
+            finally {
+                // Never leave the race timer dangling: when the handler wins the
+                // race, a ref'ed setTimeout would hold the event loop open for the
+                // remaining timeoutMs (and abandoned timers stack at higher call
+                // rates). Clear it on every settlement path.
+                if (timer !== undefined)
+                    clearTimeout(timer);
+            }
         },
     };
 }

package/dist/agent-helpers.js

@@ -134,10 +134,28 @@ export function summarizeFriction(friction) {
     }
     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;
+    // Ratio units must match. `total` is a COLLISION count when the report
+    // carries `total_collisions`, so self-thrash must be weighted by each
+    // edge's conflict_count (falling back to one collision per edge when the
+    // count is missing) — the old per-EDGE count inflated the cross-agent
+    // share (99% instead of the true 50/50) and went NEGATIVE when
+    // self-thrash edges outnumbered total_collisions. When the report omits
+    // total_collisions, `total` is an edge count and per-edge counting is the
+    // correct unit. Percentages are clamped to [0,100] so a self-thrash
+    // collision sum bigger than the daemon's windowed total renders 100%,
+    // never 1433%.
+    const collisionUnits = typeof r.total_collisions === "number";
+    const selfThrash = edges.reduce((acc, e) => {
+        if (!e.is_self_thrash)
+            return acc;
+        if (!collisionUnits)
+            return acc + 1;
+        const raw = e.conflict_count;
+        return acc + (typeof raw === "number" ? raw : 1);
+    }, 0);
+    const crossAgent = Math.max(0, total - selfThrash);
+    const crossAgentRatioPct = total > 0 ? Math.min(100, Math.round((crossAgent / total) * 100)) : 0;
+    const selfThrashRatioPct = total > 0 ? Math.min(100, Math.round((selfThrash / total) * 100)) : 0;
     const prose = (topPair ? `Top friction pair: ${topPair}. ` : "") +
         `Cross-agent ratio: ${crossAgentRatioPct}% of ${total} collisions. ` +
         `Self-thrash: ${selfThrashRatioPct}%.`;

package/dist/client.js

@@ -32,8 +32,8 @@
  */
 import { createMcpTransport } from "./adapters/mcp.js";
 import { createIpcTransport } from "./adapters/ipc.js";
+import { DEFAULT_TRANSPORT_TIMEOUT_MS } from "./constants.js";
 import { discover } from "./discovery.js";
-const DEFAULT_TIMEOUT_MS = 4_000;
 class HttpError extends Error {
     status;
     constructor(status, message) {
@@ -47,7 +47,7 @@ async function httpJson(baseUrl, path, init) {
     if (typeof fetchImpl !== "function")
         return null;
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), init?.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const timer = setTimeout(() => controller.abort(), init?.timeoutMs ?? DEFAULT_TRANSPORT_TIMEOUT_MS);
     try {
         const headers = { Accept: "application/json" };
         if (init?.body !== undefined)
@@ -193,11 +193,14 @@ export async function createWrongTraceClient(opts = {}) {
             return httpJson(base, `/api/atlas${qs}`);
         },
         async lockFile(path, reason, opts) {
-            // Deliberately HTTP-first — the ONE IPC exception; see the strategy
-            // header. Live probe 2026-08-24: IPC guardrail/lock ignores conflicts
-            // (silently takes over even with force:false), so routing lock calls
-            // through the pipe would break the 409-conflict semantics the
-            // production guardrail depends on.
+            // Deliberately HTTP-first — the ONE exception to the transport
+            // preference order; see the strategy header. Live probe 2026-08-24:
+            // the daemon's non-HTTP lock surface ignores conflicts (IPC silently
+            // takes over another owner's lock even with force:false), and the MCP
+            // lock_file tool mirrors the pipe — so routing lock calls through
+            // either surface BEFORE HTTP would break the 409-conflict semantics
+            // the production guardrail depends on. MCP is consulted only when the
+            // HTTP path is unavailable.
             const body = { path, reason };
             if (opts?.owner !== undefined)
                 body.owner = opts.owner;
@@ -207,22 +210,35 @@ export async function createWrongTraceClient(opts = {}) {
                 body.ttl_seconds = opts.ttlSeconds;
             if (opts?.force === true)
                 body.force = true;
+            const base = requireBaseUrl();
+            if (base) {
+                // 409 = lock conflict: the daemon returns {ok:false, owner, owner_run_id,
+                // locked_at, expires_at, error, message} — exactly what the caller needs
+                // to decide whether to wait or take over, so pass the body through.
+                const viaHttp = await httpJson(base, "/api/guardrail/lock", {
+                    method: "POST",
+                    body,
+                    acceptStatus: [409],
+                });
+                if (viaHttp !== null)
+                    return viaHttp;
+                // httpJson collapses timeout / 5xx / unreadable-409-body into null —
+                // the POST's outcome is AMBIGUOUS: it may have been processed and may
+                // have conflicted. Consulting the conflict-unsafe MCP lock surface now
+                // could silently take over a peer's lock (live-probed daemon behavior,
+                // see header). Fail closed instead: report no lock; the caller's
+                // fail-open/TTL philosophy covers the coordination gap.
+                return null;
+            }
+            // No HTTP route exists at all (daemon undiscoverable over HTTP) — MCP
+            // is the only remaining surface. Best-effort coordination, and any
+            // conflict the MCP tool does report (ok:false) reaches the caller.
             if (mcp.isWired) {
                 const viaMcp = await mcp.invoke("lock_file", { ...body });
                 if (viaMcp)
                     return viaMcp;
             }
-            const base = requireBaseUrl();
-            if (!base)
-                return notAvailable();
-            // 409 = lock conflict: the daemon returns {ok:false, owner, owner_run_id,
-            // locked_at, expires_at, error, message} — exactly what the caller needs
-            // to decide whether to wait or take over, so pass the body through.
-            return httpJson(base, "/api/guardrail/lock", {
-                method: "POST",
-                body,
-                acceptStatus: [409],
-            });
+            return null;
         },
         async unlockFile(path) {
             // IPC-first since daemon v0.3.3 (live-verified 2026-08-24): the pipe

package/dist/constants.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Default per-call transport timeout (ms) shared by every request surface in
+ * this adapter. `httpJson` (client.ts) and `createMcpTransport` (mcp.ts) both
+ * default their per-call bound to this single value, so a slow daemon can
+ * never add latency surprises to the edit path (see the hooks.ts failure
+ * philosophy: coordination is an optimization, never a hard dependency).
+ *
+ * One source of truth instead of mirroring literals that can drift apart —
+ * tuning the ceiling once adjusts every transport surface.
+ */
+export declare const DEFAULT_TRANSPORT_TIMEOUT_MS = 4000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -0,0 +1,12 @@
+/**
+ * Default per-call transport timeout (ms) shared by every request surface in
+ * this adapter. `httpJson` (client.ts) and `createMcpTransport` (mcp.ts) both
+ * default their per-call bound to this single value, so a slow daemon can
+ * never add latency surprises to the edit path (see the hooks.ts failure
+ * philosophy: coordination is an optimization, never a hard dependency).
+ *
+ * One source of truth instead of mirroring literals that can drift apart —
+ * tuning the ceiling once adjusts every transport surface.
+ */
+export const DEFAULT_TRANSPORT_TIMEOUT_MS = 4_000;
+//# sourceMappingURL=constants.js.map

package/dist/discovery.js

@@ -19,7 +19,7 @@ import { join } from "node:path";
 /** Default IPC paths per platform — only consulted when `/api/health` did not return `socket_path`. */
 export function defaultSocketPath(home = process.env['HOME'] ?? process.env['USERPROFILE'] ?? "") {
     if (platform() === "win32")
-        return "\\\\.\\pipe\\wrongtrace.sock";
+        return "\\\\.\\pipe\\wrongtrace";
     if (home)
         return join(home, ".wrongtrace", "ipc.sock");
     return "/tmp/wrongtrace.sock";

package/dist/hooks.js

@@ -104,10 +104,43 @@ function emitSafe(emit, event) {
  * same path increment the count and the daemon lock is only released when
  * the LAST finisher's postToolUse decrements it to zero — a sibling finishing
  * early can never unlock a path another in-flight edit still holds.
+ *
+ * Counts PARTICIPANTS, not just acquirers: a lock-conflict-race preToolUse
+ * (claim failed but the edit proceeds) also increments, so the racer's own
+ * postToolUse decrements its own entry instead of a sibling's claim. The
+ * final release is owner-guarded: when a race touched the path, count-zero
+ * does not prove the lock is ours, so the daemon's file-health is consulted
+ * before unlocking (a peer's lock is never released).
  */
 function newWrongTraceLockCounter() {
     return new Map();
 }
+// Race-flag ledger keyed by the counters map identity, so pairs AND the
+// legacy factories (which share the module-level `legacyLocks` map) see the
+// same "did a race touch this path" state for the same map.
+const racedByCounters = new WeakMap();
+function racedSetFor(counters) {
+    let set = racedByCounters.get(counters);
+    if (!set) {
+        set = new Set();
+        racedByCounters.set(counters, set);
+    }
+    return set;
+}
+// Acquiring identity per path, keyed by the counters map identity. The
+// owner-guard at release compares the daemon's lock_owner against the owner
+// the claim was ACTUALLY acquired with — not re-derived from sessionId() —
+// so legacy post hooks (which are built with an empty session identity) can
+// still verify and release locks their paired pre hook acquired.
+const claimedOwnerByCounters = new WeakMap();
+function claimedOwnerSetFor(counters) {
+    let map = claimedOwnerByCounters.get(counters);
+    if (!map) {
+        map = new Map();
+        claimedOwnerByCounters.set(counters, map);
+    }
+    return map;
+}
 function acquireLock(counters, path) {
     counters.set(path, (counters.get(path) ?? 0) + 1);
 }
@@ -158,13 +191,23 @@ export function createWrongTraceHookPair(sessionId, opts = {}, counters = newWro
                     });
                     if (res?.ok === true) {
                         acquireLock(counters, path);
+                        // Remember the identity this claim was actually acquired with —
+                        // the release-side owner-guard needs it (legacy post hooks are
+                        // built with an empty session identity and cannot re-derive it).
+                        claimedOwnerSetFor(counters).set(path, owner);
                         emitSafe(emit, { kind: "lock-acquired", path, owner });
                     }
                     else {
                         // Peer grabbed it between the pre-flight and the claim (or our
                         // own earlier leak still holds it — the exemption let us through).
                         // Either way the file is being edited by someone: we proceed
-                        // without re-claiming; coordination stays advisory.
+                        // without re-claiming; coordination stays advisory. The edit is
+                        // STILL an in-flight participant on this path, so count it —
+                        // otherwise this racer's postToolUse would decrement a sibling's
+                        // claim and release the daemon lock mid-edit (the refcount
+                        // contract: only the LAST finisher releases).
+                        acquireLock(counters, path);
+                        racedSetFor(counters).add(path);
                         emitSafe(emit, { kind: "lock-conflict-race", path });
                     }
                 }
@@ -197,11 +240,39 @@ export function createWrongTraceHookPair(sessionId, opts = {}, counters = newWro
             });
             if (!shouldUnlock)
                 return; // a sibling still holds this path
-            emitSafe(emit, { kind: "lock-released", path });
             try {
                 const wt = await getWrongTrace();
-                if (wt.isAvailable)
-                    await wt.unlockFile(path);
+                if (wt.isAvailable) {
+                    // If a lock-conflict-race ever touched this path, count-zero does
+                    // NOT prove the daemon lock is ours — the claim went to a peer (or
+                    // never landed). Verify ownership against the daemon's file-health
+                    // before releasing, and never unlock a peer's lock. The expected
+                    // owner is the identity the claim was ACTUALLY acquired with
+                    // (recorded on acquire) — legacy post hooks are built with an
+                    // empty session identity and cannot re-derive it; only when no
+                    // acquisition was recorded do we fall back to the pair's session
+                    // id (pure self-leak cleanup).
+                    let racerInvolved = false;
+                    if (racedSetFor(counters).has(path)) {
+                        racerInvolved = true;
+                        const recordedOwner = claimedOwnerSetFor(counters).get(path);
+                        const expectedOwner = recordedOwner ?? `wrongstack:${sessionId()}`;
+                        const health = await wt.getFileHealth(path);
+                        if (health?.lock_owner !== expectedOwner)
+                            return; // not ours — TTL reaps
+                    }
+                    const released = await wt.unlockFile(path);
+                    if (released !== null && released.ok !== false) {
+                        // Emit lock-released only on a CONFIRMED daemon response —
+                        // mirroring lock-acquired's confirmed-emission rule. A failed
+                        // unlock (daemon offline mid-flight, HTTP 5xx/4xx, IPC
+                        // unreachable → null) must not record a release the daemon never
+                        // performed; the TTL backstop reaps the lock instead.
+                        emitSafe(emit, { kind: "lock-released", path });
+                    }
+                    if (racerInvolved)
+                        racedSetFor(counters).delete(path);
+                }
             }
             catch {
                 // TTL backstop will reap it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/wrongtrace",
-  "version": "0.317.0",
+  "version": "0.317.2",
   "license": "MIT",
   "description": "Optional client adapter for the external WrongTrace AI Observability daemon. Discovers the daemon over HTTP/IPC/MCP at runtime; returns isAvailable:false when it is not reachable, so callers degrade gracefully. Not coupled to any runtime inside WrongStack — this is the 'sibling' integration protocol.",
   "repository": {