@reposkein/mcp 0.2.7 → 0.4.0

package/dist/store/decisions.js

@@ -0,0 +1,321 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+const STATUSES = [
+    "proposed",
+    "accepted",
+    "rejected",
+    "deprecated",
+    "superseded",
+];
+/** Merge-damage tiebreak when the same id appears in two files: the more
+ *  terminal status wins (a lost supersede flip is worse than a lost flag). */
+const STATUS_PRECEDENCE = {
+    superseded: 4,
+    deprecated: 3,
+    rejected: 2,
+    accepted: 1,
+    proposed: 0,
+};
+export function decisionsDir(repoPath) {
+    return join(repoPath, ".reposkein", "decisions");
+}
+/** Kebab-cases a title into the id slug: lowercase [a-z0-9-], capped. */
+function slugify(title) {
+    const slug = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60)
+        .replace(/-+$/, "");
+    return slug || "decision";
+}
+/** The ordinal-free id a (date, title) pair maps to. */
+export function decisionBaseId(date, title) {
+    return `adr:${date}-${slugify(title)}`;
+}
+/** A short, content-derived salt for a colliding slug.
+ *
+ *  The old collision escape was an ordinal (`.1`, `.2`). That is exactly wrong
+ *  for the case it exists for: two branches recording a same-day decision with
+ *  the same title BOTH see `.1` free and both mint it, so both write the same
+ *  filename — reintroducing the merge conflict that file-per-decision exists to
+ *  remove, on a file whose bodies differ.
+ *
+ *  Salting from the body instead makes the id a function of the content: two
+ *  branches with genuinely different decisions get different files and merge
+ *  without touching each other, while two identical recordings collapse to one
+ *  id (which is the right answer — they are the same decision). */
+export function decisionSlugSalt(source) {
+    return createHash("sha256").update(source).digest("hex").slice(0, 6);
+}
+/** Mints `adr:<date>-<slug>`, salting the slug with content when taken.
+ *
+ *  `saltSource` should be something that differs between two decisions a person
+ *  would consider distinct — the body hash, or the prose itself. Omitting it
+ *  falls back to the old ordinal, which is fine for a single-writer context
+ *  (an import loop) but not for concurrent branches. */
+export function mintDecisionId(date, title, taken, saltSource) {
+    const base = decisionBaseId(date, title);
+    if (!taken.has(base))
+        return base;
+    if (saltSource !== undefined) {
+        const salted = `${base}-${decisionSlugSalt(saltSource)}`;
+        if (!taken.has(salted))
+            return salted;
+        // Same date, same title, same body, and the id is taken: the record is
+        // already there. Anything further is a genuine duplicate, so an ordinal is
+        // the honest fallback.
+        for (let i = 1;; i++) {
+            const candidate = `${salted}.${i}`;
+            if (!taken.has(candidate))
+                return candidate;
+        }
+    }
+    for (let i = 1;; i++) {
+        const candidate = `${base}.${i}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+}
+/** Every id that must not be minted again: parsed record ids PLUS ids implied
+ *  by existing filenames. The filename side matters when a file is damaged
+ *  (conflict markers): its record doesn't parse, but minting its id anyway
+ *  would let writeDecision rename over the hand-recoverable file — violating
+ *  "records are never machine-deleted". */
+export function takenDecisionIds(repoPath) {
+    const taken = new Set();
+    for (const { file, record } of loadDecisionFiles(repoPath)) {
+        if (record)
+            taken.add(record.id);
+        taken.add(`adr:${file.replace(/\.json$/, "")}`);
+    }
+    return taken;
+}
+/** SHA-256 over the immutable body. Excludes status/superseded_by (lifecycle)
+ *  and anchor hash values (re-stamped by reaffirm) — but covers WHICH nodes
+ *  and paths the decision governs, and every prose field. */
+export function computeBodyHash(rec) {
+    const body = {
+        alternatives: rec.alternatives ?? "",
+        anchor_node_ids: rec.anchors.map((a) => a.node_id),
+        consequences: rec.consequences ?? "",
+        context: rec.context,
+        decided_at: rec.decided_at,
+        decided_by: rec.decided_by,
+        decision: rec.decision,
+        paths: rec.paths,
+        supersedes: rec.supersedes,
+        title: rec.title,
+        trigger: rec.trigger.kind,
+    };
+    return createHash("sha256").update(JSON.stringify(body)).digest("hex");
+}
+/** File name for a decision id (`adr:` prefix stripped). */
+export function decisionFileName(id) {
+    return `${id.replace(/^adr:/, "")}.json`;
+}
+function sortedKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortedKeys);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const k of Object.keys(value).sort()) {
+            out[k] = sortedKeys(value[k]);
+        }
+        return out;
+    }
+    return value;
+}
+/** Canonical bytes: `id` first, then sorted keys, 2-space indent, trailing LF.
+ *  Pretty-printed (unlike the derived JSONL) because these files are authored
+ *  history that humans review in PR diffs. */
+export function canonicalizeDecision(rec) {
+    const { id, ...rest } = rec;
+    const sorted = sortedKeys(rest);
+    const withOptionalsDropped = {};
+    for (const [k, v] of Object.entries(sorted)) {
+        if (v === undefined)
+            continue;
+        withOptionalsDropped[k] = v;
+    }
+    return JSON.stringify({ id, ...withOptionalsDropped }, null, 2) + "\n";
+}
+/** Atomic write: temp file in the same dir, then rename. */
+export function writeDecision(repoPath, rec) {
+    const dir = decisionsDir(repoPath);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, decisionFileName(rec.id));
+    const tmp = join(dir, `.${decisionFileName(rec.id)}.tmp`);
+    writeFileSync(tmp, canonicalizeDecision(rec));
+    renameSync(tmp, file);
+}
+function parseDecision(obj) {
+    if (typeof obj.id !== "string" || !obj.id.startsWith("adr:"))
+        return null;
+    if (typeof obj.title !== "string" || typeof obj.context !== "string")
+        return null;
+    if (typeof obj.decision !== "string" || typeof obj.decided_at !== "string")
+        return null;
+    const status = obj.status;
+    if (typeof status !== "string" || !STATUSES.includes(status))
+        return null;
+    const anchorsRaw = Array.isArray(obj.anchors) ? obj.anchors : [];
+    const anchors = [];
+    for (const a of anchorsRaw) {
+        if (a === null || typeof a !== "object")
+            continue;
+        const o = a;
+        if (typeof o.node_id !== "string")
+            continue;
+        anchors.push({
+            node_id: o.node_id,
+            path: typeof o.path === "string" ? o.path : "",
+            name: typeof o.name === "string" ? o.name : "",
+            kind: typeof o.kind === "string" ? o.kind : "",
+            hash: typeof o.hash === "string" ? o.hash : null,
+        });
+    }
+    const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+    const triggerKind = obj.trigger !== null &&
+        typeof obj.trigger === "object" &&
+        typeof obj.trigger.kind === "string"
+        ? obj.trigger.kind
+        : "manual";
+    const rec = {
+        id: obj.id,
+        title: obj.title,
+        status: status,
+        context: obj.context,
+        decision: obj.decision,
+        anchors,
+        paths: strArray(obj.paths),
+        supersedes: strArray(obj.supersedes),
+        decided_at: obj.decided_at,
+        decided_by: typeof obj.decided_by === "string" ? obj.decided_by : "unknown",
+        trigger: {
+            kind: ["manual", "graph_delta", "drift"].includes(triggerKind)
+                ? triggerKind
+                : "manual",
+        },
+        body_hash: typeof obj.body_hash === "string" ? obj.body_hash : "",
+    };
+    if (typeof obj.consequences === "string")
+        rec.consequences = obj.consequences;
+    if (typeof obj.alternatives === "string")
+        rec.alternatives = obj.alternatives;
+    if (typeof obj.superseded_by === "string")
+        rec.superseded_by = obj.superseded_by;
+    return rec;
+}
+/** Raw per-file scan (no dedupe) — the substrate for loadDecisions and for
+ *  doctor's duplicate/integrity checks. */
+export function loadDecisionFiles(repoPath) {
+    const dir = decisionsDir(repoPath);
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith(".json") && !f.startsWith("."));
+    }
+    catch {
+        return [];
+    }
+    return files.sort().map((f) => {
+        let record = null;
+        try {
+            record = parseDecision(JSON.parse(readFileSync(join(dir, f), "utf8")));
+        }
+        catch {
+            record = null;
+        }
+        return { file: f, record };
+    });
+}
+/** Loads every decision file. Tolerant: malformed files (conflict markers,
+ *  bad JSON, missing fields) are skipped with a warning, never thrown — a
+ *  damaged file must not take recall down. */
+export function loadDecisions(repoPath) {
+    const warnings = [];
+    const byId = new Map();
+    for (const { file, record } of loadDecisionFiles(repoPath)) {
+        if (!record) {
+            warnings.push(`skipped malformed decision file: ${file}`);
+            continue;
+        }
+        const existing = byId.get(record.id);
+        if (!existing || STATUS_PRECEDENCE[record.status] > STATUS_PRECEDENCE[existing.status]) {
+            byId.set(record.id, record);
+        }
+    }
+    const decisions = [...byId.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { decisions, warnings };
+}
+/** Repo ids for anchor resolution: the root plus its federated children —
+ *  decisions live at the root but may govern nodes in nested repos. Falls
+ *  back to the root alone if federation lookup fails. */
+export async function anchorRepoIds(store, repoId) {
+    try {
+        return [repoId, ...(await store.federatedRepoIds(repoId))];
+    }
+    catch {
+        return [repoId];
+    }
+}
+/** The portion of a node id that survives repo_id drift: `:<kind>:<rest>`.
+ *  Shared by every decision surface — anchor resolution, profile governance,
+ *  list filtering, and drift cross-referencing must agree on tolerance. */
+export function nodeIdSuffix(nodeId) {
+    const m = /^rs1:[^:]+(:.+)$/.exec(nodeId);
+    return m ? m[1] : null;
+}
+/** The repo_id embedded in an rs1: node id, or null. */
+export function nodeIdRepo(nodeId) {
+    const m = /^rs1:([^:]+):.+$/.exec(nodeId);
+    return m ? m[1] : null;
+}
+const idSuffix = nodeIdSuffix;
+/** Resolves each anchor against the live graph:
+ *  - current:  node id live (exact or repo_id-suffix match), hash unchanged
+ *  - stale:    node id live, content differs since record time
+ *  - moved:    id dead, but the recorded content hash matches a live node —
+ *              the only signal that survives renames
+ *  - orphaned: nothing matches; kept and flagged, never deleted */
+export async function resolveAnchorStates(store, repoIds, anchors) {
+    const out = [];
+    for (const anchor of anchors) {
+        let live = await store.getNode(repoIds, anchor.node_id);
+        if (!live) {
+            // Fork tolerance: the anchor may carry a different repo_id than the
+            // local checkout computes. Retry with each live repo id + the suffix.
+            const suffix = idSuffix(anchor.node_id);
+            if (suffix) {
+                for (const repoId of repoIds) {
+                    const candidate = `rs1:${repoId}${suffix}`;
+                    if (candidate === anchor.node_id)
+                        continue;
+                    live = await store.getNode(repoIds, candidate);
+                    if (live)
+                        break;
+                }
+            }
+        }
+        if (live) {
+            const state = anchor.hash === null || live.content_hash === null || anchor.hash === live.content_hash
+                ? "current"
+                : "stale";
+            out.push({ ...anchor, state, resolved_node_id: live.id });
+            continue;
+        }
+        if (anchor.hash && store.findByContentHash) {
+            const matches = await store.findByContentHash(repoIds, anchor.hash);
+            if (matches.length > 0) {
+                out.push({ ...anchor, state: "moved", resolved_node_id: matches[0].id });
+                continue;
+            }
+        }
+        out.push({ ...anchor, state: "orphaned" });
+    }
+    return out;
+}
+//# sourceMappingURL=decisions.js.map

package/dist/store/decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.js","sourceRoot":"","sources":["../../src/store/decisions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,UAAU,EACV,SAAS,EACT,WAAW,EACX,YAAY,EACZ,UAAU,EACV,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAoEjC,MAAM,QAAQ,GAA8B;IAC1C,UAAU;IACV,UAAU;IACV,UAAU;IACV,YAAY;IACZ,YAAY;CACb,CAAC;AAEF;8EAC8E;AAC9E,MAAM,iBAAiB,GAAmC;IACxD,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;IACX,QAAQ,EAAE,CAAC;CACZ,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,OAAO,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;AACnD,CAAC;AAED,yEAAyE;AACzE,SAAS,OAAO,CAAC,KAAa;IAC5B,MAAM,IAAI,GAAG,KAAK;SACf,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;SACZ,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtB,OAAO,IAAI,IAAI,UAAU,CAAC;AAC5B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAa;IACxD,OAAO,OAAO,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;mEAWmE;AACnE,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;wDAKwD;AACxD,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,KAAa,EACb,KAA0B,EAC1B,UAAmB;IAEnB,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,gBAAgB,CAAC,UAAU,CAAC,EAAE,CAAC;QACzD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC;QACtC,uEAAuE;QACvE,2EAA2E;QAC3E,uBAAuB;QACvB,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QAC9C,CAAC;IACH,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAC;IAC9C,CAAC;AACH,CAAC;AAED;;;;2CAI2C;AAC3C,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,IAAI,MAAM;YAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACjC,KAAK,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;6DAE6D;AAC7D,MAAM,UAAU,eAAe,CAAC,GAAsC;IACpE,MAAM,IAAI,GAAG;QACX,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;QACpC,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAClD,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE;QACpC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI;KAC1B,CAAC;IACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC;AAC3C,CAAC;AAED,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACrE,GAAG,CAAC,CAAC,CAAC,GAAG,UAAU,CAAE,KAAiC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;8CAE8C;AAC9C,MAAM,UAAU,oBAAoB,CAAC,GAAmB;IACtD,MAAM,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,GAAG,GAAG,CAAC;IAC5B,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAA4B,CAAC;IAC3D,MAAM,oBAAoB,GAA4B,EAAE,CAAC;IACzD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,GAAG,oBAAoB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AACzE,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,GAAmB;IACjE,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC;IAC1D,aAAa,CAAC,GAAG,EAAE,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,aAAa,CAAC,GAA4B;IACjD,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAClF,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACxF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAwB,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5F,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,SAAS;QAClD,MAAM,CAAC,GAAG,CAA4B,CAAC;QACvC,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;YAAE,SAAS;QAC5C,OAAO,CAAC,IAAI,CAAC;YACX,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YAC9C,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YAC9C,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YAC9C,IAAI,EAAE,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;SACjD,CAAC,CAAC;IACL,CAAC;IACD,MAAM,QAAQ,GAAG,CAAC,CAAU,EAAY,EAAE,CACxC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,MAAM,WAAW,GACf,GAAG,CAAC,OAAO,KAAK,IAAI;QACpB,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAC/B,OAAQ,GAAG,CAAC,OAAmC,CAAC,IAAI,KAAK,QAAQ;QAC/D,CAAC,CAAG,GAAG,CAAC,OAAmC,CAAC,IAAe;QAC3D,CAAC,CAAC,QAAQ,CAAC;IACf,MAAM,GAAG,GAAmB;QAC1B,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,MAAwB;QAChC,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,OAAO;QACP,KAAK,EAAE,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC;QAC1B,UAAU,EAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;QACpC,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,UAAU,EAAE,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QAC3E,OAAO,EAAE;YACP,IAAI,EAAG,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAW,CAAC,QAAQ,CAC1D,WAAkC,CACnC;gBACC,CAAC,CAAE,WAAmC;gBACtC,CAAC,CAAC,QAAQ;SACb;QACD,SAAS,EAAE,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;KAClE,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAC9E,IAAI,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QAAE,GAAG,CAAC,YAAY,GAAG,GAAG,CAAC,YAAY,CAAC;IAC9E,IAAI,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ;QAAE,GAAG,CAAC,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC;IACjF,OAAO,GAAG,CAAC;AACb,CAAC;AAeD;2CAC2C;AAC3C,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC5B,IAAI,MAAM,GAA0B,IAAI,CAAC;QACzC,IAAI,CAAC;YACH,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAA4B,CAAC,CAAC;QACpG,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;8CAE8C;AAC9C,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC/C,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,iBAAiB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,QAAQ,CAAC,IAAI,CAAC,oCAAoC,IAAI,EAAE,CAAC,CAAC;YAC1D,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACvF,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9F,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACjC,CAAC;AAED;;yDAEyD;AACzD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAiB,EAAE,MAAc;IACnE,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED;;2EAE2E;AAC3E,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,CAAC,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1B,CAAC;AAED,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B;;;;;mEAKmE;AACnE,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAiB,EACjB,OAAiB,EACjB,OAAyB;IAEzB,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,IAAI,GAAqB,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,oEAAoE;YACpE,sEAAsE;YACtE,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxC,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;oBAC7B,MAAM,SAAS,GAAG,OAAO,MAAM,GAAG,MAAM,EAAE,CAAC;oBAC3C,IAAI,SAAS,KAAK,MAAM,CAAC,OAAO;wBAAE,SAAS;oBAC3C,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;oBAC/C,IAAI,IAAI;wBAAE,MAAM;gBAClB,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,KAAK,GACT,MAAM,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,YAAY;gBACrF,CAAC,CAAC,SAAS;gBACX,CAAC,CAAC,OAAO,CAAC;YACd,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1D,SAAS;QACX,CAAC;QACD,IAAI,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC3C,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YACpE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC1E,SAAS;YACX,CAAC;QACH,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/store/indexedAt.d.ts

@@ -0,0 +1,18 @@
+/** Path to the file recording the git commit SHA that was HEAD the last time
+ *  the mcp-side index invocation path (`reposkein-mcp index`, or `init`'s
+ *  initial index) completed successfully. Lives under `.reposkein/local/` —
+ *  per-machine scratch that's gitignored and never committed — so it never
+ *  survives a `git clone`. That's deliberate: a fresh clone has no idea what
+ *  commit (if any) its nonexistent graph was built from, which is exactly
+ *  the state `doctor --ci`'s `graph_stale` check should fail on. */
+export declare function indexedAtPath(repoPath: string): string;
+/** Records the current git HEAD as "the commit the graph was just built
+ *  from". Best-effort and silent: not a git repo / no HEAD yet / a read-only
+ *  filesystem all just skip the write — `graph_stale` degrades to "never
+ *  recorded" (fails, conservatively) rather than the index step itself
+ *  failing over a scratch-file write. */
+export declare function writeIndexedAtMarker(repoPath: string): void;
+/** Reads the recorded indexed-at SHA, or null when never recorded — never
+ *  indexed via the mcp-side path, or a fresh clone (local/ isn't committed,
+ *  so it never carries over). */
+export declare function readIndexedAtSha(repoPath: string): string | null;

package/dist/store/indexedAt.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+/** Path to the file recording the git commit SHA that was HEAD the last time
+ *  the mcp-side index invocation path (`reposkein-mcp index`, or `init`'s
+ *  initial index) completed successfully. Lives under `.reposkein/local/` —
+ *  per-machine scratch that's gitignored and never committed — so it never
+ *  survives a `git clone`. That's deliberate: a fresh clone has no idea what
+ *  commit (if any) its nonexistent graph was built from, which is exactly
+ *  the state `doctor --ci`'s `graph_stale` check should fail on. */
+export function indexedAtPath(repoPath) {
+    return join(repoPath, ".reposkein", "local", "indexed-at");
+}
+/** Records the current git HEAD as "the commit the graph was just built
+ *  from". Best-effort and silent: not a git repo / no HEAD yet / a read-only
+ *  filesystem all just skip the write — `graph_stale` degrades to "never
+ *  recorded" (fails, conservatively) rather than the index step itself
+ *  failing over a scratch-file write. */
+export function writeIndexedAtMarker(repoPath) {
+    let sha;
+    try {
+        sha = execFileSync("git", ["-C", repoPath, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return;
+    }
+    if (!sha)
+        return;
+    try {
+        const path = indexedAtPath(repoPath);
+        mkdirSync(join(path, ".."), { recursive: true });
+        writeFileSync(path, sha + "\n", "utf8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Reads the recorded indexed-at SHA, or null when never recorded — never
+ *  indexed via the mcp-side path, or a fresh clone (local/ isn't committed,
+ *  so it never carries over). */
+export function readIndexedAtSha(repoPath) {
+    const path = indexedAtPath(repoPath);
+    if (!existsSync(path))
+        return null;
+    try {
+        const sha = readFileSync(path, "utf8").trim();
+        return sha || null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=indexedAt.js.map

package/dist/store/indexedAt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedAt.js","sourceRoot":"","sources":["../../src/store/indexedAt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;oEAMoE;AACpE,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,OAAO,IAAI,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;AAC7D,CAAC;AAED;;;;yCAIyC;AACzC,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE;YAC/D,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;IACT,CAAC;IACD,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QACrC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,aAAa,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,iBAAiB;IACnB,CAAC;AACH,CAAC;AAED;;iCAEiC;AACjC,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,IAAI,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QAC9C,OAAO,GAAG,IAAI,IAAI,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/store/instrumentTool.d.ts

@@ -0,0 +1,40 @@
+import type { RepoResolution } from "./resolveRepoPath.js";
+import type { RepoSession } from "./repoSession.js";
+import { type SessionLogger, type ToolResultLike } from "./sessionLog.js";
+export interface ToolLogger {
+    /** `session.resolve()`, memoized for the lifetime of the CURRENT tool
+     *  call (see `withLog`) — a handler that calls this (directly, or via
+     *  `resolveActiveRepo`) and the logging wrapper both see the same
+     *  filesystem walk, not two. Isolated per call via AsyncLocalStorage, so
+     *  concurrent/overlapping tool calls never share a cached value. Falls
+     *  back to a plain, uncached `session.resolve()` when called outside any
+     *  `withLog`-wrapped call (e.g. server startup). */
+    cachedResolve(): RepoResolution;
+    /** Wraps a tool handler so its call is logged to the active repo's
+     *  session log — see sessionLog.ts. `Args`/result type are inferred from
+     *  the handler passed in, so call sites (`server.registerTool(name,
+     *  config, withLog(name, async (args) => {...}))`) need no extra typing. */
+    withLog<Args, R extends ToolResultLike>(name: string, cb: (args: Args) => Promise<R>): (args: Args) => Promise<R>;
+}
+/** Builds the tool-call instrumentation for one MCP server connection: one
+ *  `ToolLogger` shared across every `server.registerTool` call (REP-20).
+ *
+ *  Two hot-path fixes from review round 1, both scoped to this module so
+ *  they're covered without spinning up the whole server:
+ *
+ *  1. Single resolution per call — `cachedResolve()` memoizes
+ *     `session.resolve()` per call (AsyncLocalStorage-scoped), so a
+ *     handler's own resolution (via `resolveActiveRepo`, or a direct
+ *     `cachedResolve()` call for the couple of tools that don't gate on a
+ *     full repo context) and the logging wrapper's resolution are the same
+ *     filesystem walk, not two.
+ *  2. Deferred write — the `finally` block below only captures cheap,
+ *     already-computed references synchronously (tool name, argsShape, the
+ *     resolved repo path, the result object BY REFERENCE, ok, ts) and
+ *     returns immediately; JSON-parsing the result for `extractTouchedIds`
+ *     and the actual file write happen in a `schedule()`-deferred callback
+ *     (default `setImmediate`), which runs only after the response has
+ *     already been handed back to the MCP transport. The deferred callback
+ *     swallows every error itself — it must never surface as an unhandled
+ *     exception/rejection. */
+export declare function createToolLogger(session: RepoSession, sessionLogger: SessionLogger, schedule?: (fn: () => void) => void): ToolLogger;

package/dist/store/instrumentTool.js

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { argsShapeOf, extractTouchedIds, resultByteSize } from "./sessionLog.js";
+/** Builds the tool-call instrumentation for one MCP server connection: one
+ *  `ToolLogger` shared across every `server.registerTool` call (REP-20).
+ *
+ *  Two hot-path fixes from review round 1, both scoped to this module so
+ *  they're covered without spinning up the whole server:
+ *
+ *  1. Single resolution per call — `cachedResolve()` memoizes
+ *     `session.resolve()` per call (AsyncLocalStorage-scoped), so a
+ *     handler's own resolution (via `resolveActiveRepo`, or a direct
+ *     `cachedResolve()` call for the couple of tools that don't gate on a
+ *     full repo context) and the logging wrapper's resolution are the same
+ *     filesystem walk, not two.
+ *  2. Deferred write — the `finally` block below only captures cheap,
+ *     already-computed references synchronously (tool name, argsShape, the
+ *     resolved repo path, the result object BY REFERENCE, ok, ts) and
+ *     returns immediately; JSON-parsing the result for `extractTouchedIds`
+ *     and the actual file write happen in a `schedule()`-deferred callback
+ *     (default `setImmediate`), which runs only after the response has
+ *     already been handed back to the MCP transport. The deferred callback
+ *     swallows every error itself — it must never surface as an unhandled
+ *     exception/rejection. */
+export function createToolLogger(session, sessionLogger, schedule = setImmediate) {
+    const als = new AsyncLocalStorage();
+    function cachedResolve() {
+        const store = als.getStore();
+        if (!store)
+            return session.resolve();
+        if (!store.value)
+            store.value = session.resolve();
+        return store.value;
+    }
+    function deferredLog(ts, repoPath, tool, argsShape, ok, result) {
+        schedule(() => {
+            try {
+                const resultBytes = resultByteSize(result);
+                const nodeIds = extractTouchedIds(result);
+                sessionLogger.logAt(ts, repoPath, {
+                    tool,
+                    argsShape,
+                    resultBytes,
+                    ...(nodeIds.length ? { nodeIds } : {}),
+                    ok,
+                });
+            }
+            catch {
+                // deferred logging must never surface as an unhandled exception
+            }
+        });
+    }
+    function withLog(name, cb) {
+        return (args) => als.run({}, async () => {
+            let result;
+            let threw = false;
+            try {
+                result = await cb(args);
+                return result;
+            }
+            catch (err) {
+                threw = true;
+                throw err;
+            }
+            finally {
+                // Cheap, synchronous capture only — no JSON.parse, no fs calls on
+                // the hot path. `result` is captured BY REFERENCE; it isn't read
+                // until the deferred callback runs.
+                try {
+                    const resolution = cachedResolve();
+                    if (resolution.repoPath) {
+                        deferredLog(new Date().toISOString(), resolution.repoPath, name, argsShapeOf(args), !threw && result?.isError !== true, result);
+                    }
+                }
+                catch {
+                    // instrumentation must never affect the tool call
+                }
+            }
+        });
+    }
+    return { cachedResolve, withLog };
+}
+//# sourceMappingURL=instrumentTool.js.map

package/dist/store/instrumentTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentTool.js","sourceRoot":"","sources":["../../src/store/instrumentTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc,EAA2C,MAAM,iBAAiB,CAAC;AAsB1H;;;;;;;;;;;;;;;;;;;;8BAoB8B;AAC9B,MAAM,UAAU,gBAAgB,CAC9B,OAAoB,EACpB,aAA4B,EAC5B,WAAqC,YAAY;IAEjD,MAAM,GAAG,GAAG,IAAI,iBAAiB,EAAa,CAAC;IAE/C,SAAS,aAAa;QACpB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK;YAAE,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,SAAS,WAAW,CAClB,EAAU,EACV,QAAgB,EAChB,IAAY,EACZ,SAAmB,EACnB,EAAW,EACX,MAAkC;QAElC,QAAQ,CAAC,GAAG,EAAE;YACZ,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;gBAC3C,MAAM,OAAO,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;gBAC1C,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,QAAQ,EAAE;oBAChC,IAAI;oBACJ,SAAS;oBACT,WAAW;oBACX,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtC,EAAE;iBACH,CAAC,CAAC;YACL,CAAC;YAAC,MAAM,CAAC;gBACP,gEAAgE;YAClE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,SAAS,OAAO,CACd,IAAY,EACZ,EAA8B;QAE9B,OAAO,CAAC,IAAU,EAAc,EAAE,CAChC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE;YACrB,IAAI,MAAqB,CAAC;YAC1B,IAAI,KAAK,GAAG,KAAK,CAAC;YAClB,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;gBACxB,OAAO,MAAM,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,KAAK,GAAG,IAAI,CAAC;gBACb,MAAM,GAAG,CAAC;YACZ,CAAC;oBAAS,CAAC;gBACT,kEAAkE;gBAClE,iEAAiE;gBACjE,oCAAoC;gBACpC,IAAI,CAAC;oBACH,MAAM,UAAU,GAAG,aAAa,EAAE,CAAC;oBACnC,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;wBACxB,WAAW,CACT,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EACxB,UAAU,CAAC,QAAQ,EACnB,IAAI,EACJ,WAAW,CAAC,IAAI,CAAC,EACjB,CAAC,KAAK,IAAK,MAAqC,EAAE,OAAO,KAAK,IAAI,EAClE,MAAM,CACP,CAAC;oBACJ,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,kDAAkD;gBACpD,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;IACP,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC;AACpC,CAAC"}

package/dist/store/repoContextCache.d.ts

@@ -0,0 +1,15 @@
+/** A minimal memoizing cache with a caching decision left to the caller —
+ *  extracted so "never cache a failed/partial result" is one small, directly
+ *  testable primitive rather than inline logic in mcp/src/index.ts.
+ *
+ *  Context: index.ts's per-repoPath {repoId, store} cache used to cache
+ *  every resolution unconditionally, including a repo whose `.reposkein/`
+ *  exists but isn't indexed yet (no meta.json — `repoId` resolves to
+ *  `undefined`). That froze a session on the failure forever: an agent that
+ *  fixed the repo out-of-band (ran `reposkein-mcp index` in another
+ *  terminal) stayed stuck until the server restarted, which defeats
+ *  `select_repo`'s whole "no restart needed" point. `shouldCache` lets the
+ *  caller keep re-attempting `compute` for exactly the states worth
+ *  retrying, while still caching (and not repeatedly re-doing) real work
+ *  for a successful resolution. */
+export declare function makeCache<T>(compute: (key: string) => Promise<T>, shouldCache: (value: T) => boolean): (key: string) => Promise<T>;

package/dist/store/repoContextCache.js

@@ -0,0 +1,26 @@
+/** A minimal memoizing cache with a caching decision left to the caller —
+ *  extracted so "never cache a failed/partial result" is one small, directly
+ *  testable primitive rather than inline logic in mcp/src/index.ts.
+ *
+ *  Context: index.ts's per-repoPath {repoId, store} cache used to cache
+ *  every resolution unconditionally, including a repo whose `.reposkein/`
+ *  exists but isn't indexed yet (no meta.json — `repoId` resolves to
+ *  `undefined`). That froze a session on the failure forever: an agent that
+ *  fixed the repo out-of-band (ran `reposkein-mcp index` in another
+ *  terminal) stayed stuck until the server restarted, which defeats
+ *  `select_repo`'s whole "no restart needed" point. `shouldCache` lets the
+ *  caller keep re-attempting `compute` for exactly the states worth
+ *  retrying, while still caching (and not repeatedly re-doing) real work
+ *  for a successful resolution. */
+export function makeCache(compute, shouldCache) {
+    const cache = new Map();
+    return async (key) => {
+        if (cache.has(key))
+            return cache.get(key);
+        const value = await compute(key);
+        if (shouldCache(value))
+            cache.set(key, value);
+        return value;
+    };
+}
+//# sourceMappingURL=repoContextCache.js.map

package/dist/store/repoContextCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoContextCache.js","sourceRoot":"","sources":["../../src/store/repoContextCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;mCAamC;AACnC,MAAM,UAAU,SAAS,CACvB,OAAoC,EACpC,WAAkC;IAElC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAa,CAAC;IACnC,OAAO,KAAK,EAAE,GAAW,EAAc,EAAE;QACvC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,WAAW,CAAC,KAAK,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}