@reposkein/mcp 0.3.0 → 0.4.0

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"}

package/dist/store/repoSession.d.ts

@@ -0,0 +1,63 @@
+import { type RepoResolution } from "./resolveRepoPath.js";
+export interface RepoInfo {
+    path: string;
+    /** From <path>/.reposkein/meta.json, when present. */
+    repo_id?: string;
+    /** Display name: repo_id if meta.json resolved one, else the directory's
+     *  basename — always present so `select_repo` has something to match on
+     *  even before the repo has been indexed (no meta.json yet). */
+    name: string;
+    /** Cheap line counts (not full parses) — omitted where the file is absent. */
+    nodes?: number;
+    edges?: number;
+}
+export declare function describeRepo(path: string): RepoInfo;
+/** Every repo `list_repos` should report. Deliberately broader than
+ *  `resolveRepoPath`'s own short-circuiting precedence: discovery always
+ *  walks the filesystem (nearest ancestor with `.reposkein/`, else
+ *  subdirectories) so a workspace's sibling repos are visible — and thus
+ *  selectable via `select_repo` — even in a session where REPOSKEIN_REPO_PATH
+ *  happens to pin one of them. That env pin is unioned in (deduped) so it's
+ *  never missing from the list, but it does not suppress the others; only
+ *  `resolveRepoPath`'s actual *default* pick (used by `resolve()` below)
+ *  gives it priority over the walk. Sorted for deterministic output. */
+export declare function discoverRepoPaths(opts: {
+    cwd: string;
+    envRepoPath?: string;
+}): string[];
+/** Tracks the MCP session's active repo across tool calls.
+ *
+ *  Resolution precedence: `select_repo` (session-only; sticky for the rest of
+ *  the connection) > REPOSKEIN_REPO_PATH > walk-up > walk-down. `select_repo`
+ *  is deliberately allowed to override REPOSKEIN_REPO_PATH once called — it's
+ *  the more specific, more recent signal, and it's how a workspace-mode
+ *  session (multiple sibling repos, walk-down ambiguous) picks one to work
+ *  with instead of restarting the server with a different env var. */
+export declare class RepoSession {
+    private readonly cwd;
+    private readonly envRepoPath;
+    private selectedPath;
+    constructor(opts: {
+        cwd: string;
+        envRepoPath: string | undefined;
+    });
+    /** Current resolution, honoring an active `select_repo` pick first. */
+    resolve(): RepoResolution;
+    /** Every candidate repo for this session — see `discoverRepoPaths`. Each
+     *  entry is flagged `selected` for whichever one `resolve()` currently
+     *  returns, so an agent can see the effect of a prior `select_repo` call. */
+    list(): (RepoInfo & {
+        selected: boolean;
+    })[];
+    /** Sets the session-active repo by path, by its meta.json `repo_id`, or by
+     *  display `name` (as returned by `list()`/`list_repos`) — never an
+     *  arbitrary filesystem path, so this can't be used to point outside what
+     *  resolution actually discovered. */
+    select(pathOrName: string): {
+        ok: true;
+        repo: RepoInfo;
+    } | {
+        ok: false;
+        error: string;
+    };
+}

package/dist/store/repoSession.js

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { resolveRepoPath, walkUp, walkDown } from "./resolveRepoPath.js";
+function countLines(text) {
+    let n = 0;
+    for (const line of text.split("\n"))
+        if (line.trim())
+            n++;
+    return n;
+}
+function readMetaRepoId(path) {
+    try {
+        const meta = JSON.parse(readFileSync(join(path, ".reposkein", "meta.json"), "utf8"));
+        return typeof meta.repo_id === "string" ? meta.repo_id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Line counts for nodes.jsonl / edges.jsonl if they exist — the same cheap
+ *  "count non-empty lines" approach `cli/doctor.ts` uses, not a full parse. */
+function cheapCounts(path) {
+    const out = {};
+    const nodesFile = join(path, ".reposkein", "nodes.jsonl");
+    const edgesFile = join(path, ".reposkein", "edges.jsonl");
+    try {
+        if (existsSync(nodesFile))
+            out.nodes = countLines(readFileSync(nodesFile, "utf8"));
+    }
+    catch {
+        /* unreadable — omit rather than fail list_repos over one repo */
+    }
+    try {
+        if (existsSync(edgesFile))
+            out.edges = countLines(readFileSync(edgesFile, "utf8"));
+    }
+    catch {
+        /* unreadable — omit */
+    }
+    return out;
+}
+export function describeRepo(path) {
+    const repo_id = readMetaRepoId(path);
+    return {
+        path,
+        ...(repo_id ? { repo_id } : {}),
+        name: repo_id ?? basename(path),
+        ...cheapCounts(path),
+    };
+}
+/** Every repo `list_repos` should report. Deliberately broader than
+ *  `resolveRepoPath`'s own short-circuiting precedence: discovery always
+ *  walks the filesystem (nearest ancestor with `.reposkein/`, else
+ *  subdirectories) so a workspace's sibling repos are visible — and thus
+ *  selectable via `select_repo` — even in a session where REPOSKEIN_REPO_PATH
+ *  happens to pin one of them. That env pin is unioned in (deduped) so it's
+ *  never missing from the list, but it does not suppress the others; only
+ *  `resolveRepoPath`'s actual *default* pick (used by `resolve()` below)
+ *  gives it priority over the walk. Sorted for deterministic output. */
+export function discoverRepoPaths(opts) {
+    const up = walkUp(opts.cwd);
+    const physical = up ? [up] : walkDown(opts.cwd);
+    if (opts.envRepoPath && !physical.includes(opts.envRepoPath)) {
+        return [...physical, opts.envRepoPath].sort();
+    }
+    return physical;
+}
+/** Tracks the MCP session's active repo across tool calls.
+ *
+ *  Resolution precedence: `select_repo` (session-only; sticky for the rest of
+ *  the connection) > REPOSKEIN_REPO_PATH > walk-up > walk-down. `select_repo`
+ *  is deliberately allowed to override REPOSKEIN_REPO_PATH once called — it's
+ *  the more specific, more recent signal, and it's how a workspace-mode
+ *  session (multiple sibling repos, walk-down ambiguous) picks one to work
+ *  with instead of restarting the server with a different env var. */
+export class RepoSession {
+    cwd;
+    envRepoPath;
+    selectedPath;
+    constructor(opts) {
+        this.cwd = opts.cwd;
+        this.envRepoPath = opts.envRepoPath;
+    }
+    /** Current resolution, honoring an active `select_repo` pick first. */
+    resolve() {
+        if (this.selectedPath)
+            return { repoPath: this.selectedPath, source: "explicit" };
+        return resolveRepoPath({ cwd: this.cwd, envRepoPath: this.envRepoPath });
+    }
+    /** Every candidate repo for this session — see `discoverRepoPaths`. Each
+     *  entry is flagged `selected` for whichever one `resolve()` currently
+     *  returns, so an agent can see the effect of a prior `select_repo` call. */
+    list() {
+        const active = this.resolve().repoPath;
+        return discoverRepoPaths({ cwd: this.cwd, envRepoPath: this.envRepoPath }).map((path) => ({
+            ...describeRepo(path),
+            selected: path === active,
+        }));
+    }
+    /** Sets the session-active repo by path, by its meta.json `repo_id`, or by
+     *  display `name` (as returned by `list()`/`list_repos`) — never an
+     *  arbitrary filesystem path, so this can't be used to point outside what
+     *  resolution actually discovered. */
+    select(pathOrName) {
+        const candidates = discoverRepoPaths({ cwd: this.cwd, envRepoPath: this.envRepoPath }).map(describeRepo);
+        const hit = candidates.find((c) => c.path === pathOrName) ??
+            candidates.find((c) => c.repo_id === pathOrName) ??
+            candidates.find((c) => c.name === pathOrName);
+        if (!hit) {
+            return {
+                ok: false,
+                error: `No repo matching "${pathOrName}" among the discovered candidates` +
+                    (candidates.length > 0
+                        ? `: ${candidates.map((c) => c.path).join(", ")}.`
+                        : " (none found).") +
+                    " Call list_repos first and pass one of its `path` or `name` values.",
+            };
+        }
+        this.selectedPath = hit.path;
+        return { ok: true, repo: hit };
+    }
+}
+//# sourceMappingURL=repoSession.js.map

package/dist/store/repoSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoSession.js","sourceRoot":"","sources":["../../src/store/repoSession.ts"],"names":[],"mappings":"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"}

package/dist/store/resolveRepoPath.d.ts

@@ -0,0 +1,31 @@
+export type RepoResolutionSource = "explicit" | "env" | "walk-up" | "walk-down" | "none";
+export interface RepoResolution {
+    /** Resolved repo root, or undefined if none could be determined. */
+    repoPath: string | undefined;
+    /** How repoPath was determined ("none" when nothing resolved). */
+    source: RepoResolutionSource;
+    /** Populated only when source is "none" because walk-down found 2+ hits
+     *  (workspace mode, ambiguous) — name them so the caller can pick one. */
+    candidates?: string[];
+}
+/** Nearest ancestor of `cwd` (inclusive) containing `.reposkein/`. */
+export declare function walkUp(cwd: string): string | undefined;
+/** Scans descendants of `cwd` (bounded to `maxDepth` levels, skipping
+ *  build/VCS/tool directories) for directories containing `.reposkein/`.
+ *  Does not recurse further into a hit — nested repos are a graph-federation
+ *  concern (see store/federation.ts), not a workspace-candidate one here.
+ *  Returns hits sorted for deterministic ambiguity-error output. */
+export declare function walkDown(cwd: string, maxDepth?: number): string[];
+/** Zero-config repo resolution.
+ *
+ *  Precedence: explicit tool arg > REPOSKEIN_REPO_PATH > walk-up > walk-down.
+ *  - Walk-up: nearest ancestor of `cwd` (inclusive) containing `.reposkein/`.
+ *  - Walk-down (workspace mode, only tried when no ancestor has one): scans
+ *    `cwd`'s children/grandchildren for `.reposkein/` dirs. One hit auto-
+ *    selects it. Zero or 2+ hits leave `repoPath` undefined ("none"); 2+
+ *    populates `candidates` so the caller can build an actionable error. */
+export declare function resolveRepoPath(opts: {
+    cwd: string;
+    envRepoPath?: string;
+    explicit?: string;
+}): RepoResolution;

package/dist/store/resolveRepoPath.js

@@ -0,0 +1,85 @@
+import { readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve as resolvePath } from "node:path";
+const REPOSKEIN_DIR = ".reposkein";
+/** Directories never treated as repo candidates while walking down: build
+ *  output, VCS internals, other worktrees/tool state — never real repo roots. */
+const SKIP_DIR_NAMES = new Set(["node_modules", ".git", "target", "dist", ".worktrees", ".claude"]);
+function hasReposkeinDir(dir) {
+    try {
+        return statSync(join(dir, REPOSKEIN_DIR)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Nearest ancestor of `cwd` (inclusive) containing `.reposkein/`. */
+export function walkUp(cwd) {
+    let dir = resolvePath(cwd);
+    for (;;) {
+        if (hasReposkeinDir(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined; // reached filesystem root
+        dir = parent;
+    }
+}
+/** Scans descendants of `cwd` (bounded to `maxDepth` levels, skipping
+ *  build/VCS/tool directories) for directories containing `.reposkein/`.
+ *  Does not recurse further into a hit — nested repos are a graph-federation
+ *  concern (see store/federation.ts), not a workspace-candidate one here.
+ *  Returns hits sorted for deterministic ambiguity-error output. */
+export function walkDown(cwd, maxDepth = 2) {
+    const root = resolvePath(cwd);
+    const hits = [];
+    function recurse(dir, depth) {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir (permissions, race) — skip, don't fail resolution
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === REPOSKEIN_DIR)
+                continue;
+            if (SKIP_DIR_NAMES.has(entry.name))
+                continue;
+            const full = join(dir, entry.name);
+            if (hasReposkeinDir(full)) {
+                hits.push(full);
+                continue;
+            }
+            if (depth < maxDepth)
+                recurse(full, depth + 1);
+        }
+    }
+    recurse(root, 1);
+    return hits.sort();
+}
+/** Zero-config repo resolution.
+ *
+ *  Precedence: explicit tool arg > REPOSKEIN_REPO_PATH > walk-up > walk-down.
+ *  - Walk-up: nearest ancestor of `cwd` (inclusive) containing `.reposkein/`.
+ *  - Walk-down (workspace mode, only tried when no ancestor has one): scans
+ *    `cwd`'s children/grandchildren for `.reposkein/` dirs. One hit auto-
+ *    selects it. Zero or 2+ hits leave `repoPath` undefined ("none"); 2+
+ *    populates `candidates` so the caller can build an actionable error. */
+export function resolveRepoPath(opts) {
+    if (opts.explicit)
+        return { repoPath: opts.explicit, source: "explicit" };
+    if (opts.envRepoPath)
+        return { repoPath: opts.envRepoPath, source: "env" };
+    const up = walkUp(opts.cwd);
+    if (up)
+        return { repoPath: up, source: "walk-up" };
+    const down = walkDown(opts.cwd);
+    if (down.length === 1)
+        return { repoPath: down[0], source: "walk-down" };
+    if (down.length > 1)
+        return { repoPath: undefined, source: "none", candidates: down };
+    return { repoPath: undefined, source: "none" };
+}
+//# sourceMappingURL=resolveRepoPath.js.map

package/dist/store/resolveRepoPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveRepoPath.js","sourceRoot":"","sources":["../../src/store/resolveRepoPath.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAe,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAElE,MAAM,aAAa,GAAG,YAAY,CAAC;AAEnC;iFACiF;AACjF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;AAcpG,SAAS,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,MAAM,CAAC,GAAW;IAChC,IAAI,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC3B,SAAS,CAAC;QACR,IAAI,eAAe,CAAC,GAAG,CAAC;YAAE,OAAO,GAAG,CAAC;QACrC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,SAAS,CAAC,CAAC,0BAA0B;QAChE,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;oEAIoE;AACpE,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,QAAQ,GAAG,CAAC;IAChD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAa,EAAE,CAAC;IAE1B,SAAS,OAAO,CAAC,GAAW,EAAE,KAAa;QACzC,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,CAAC,mEAAmE;QAC7E,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE;gBAAE,SAAS;YACnC,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa;gBAAE,SAAS;YAC3C,IAAI,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAChB,SAAS;YACX,CAAC;YACD,IAAI,KAAK,GAAG,QAAQ;gBAAE,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACjB,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;AACrB,CAAC;AAED;;;;;;;4EAO4E;AAC5E,MAAM,UAAU,eAAe,CAAC,IAI/B;IACC,IAAI,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC1E,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAE3E,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,EAAE;QAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAEnD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACzE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACtF,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACjD,CAAC"}