@reposkein/mcp 0.3.0 → 0.4.0

package/dist/store/sessionLog.d.ts

@@ -0,0 +1,98 @@
+/** One JSONL record per tool invocation, appended to the active repo's
+ *  `.reposkein/local/sessions/<session-id>.jsonl` (REP-20). Never contains
+ *  argument or result VALUES — only shapes/sizes — so it's safe to leave
+ *  lying around on disk (though it's git-ignored regardless, see
+ *  `.reposkein/.gitignore` written by the indexer: `local/`). */
+export interface SessionLogRecord {
+    /** ISO-8601 timestamp of the call. */
+    ts: string;
+    /** MCP tool name, e.g. "get_context_profile". */
+    tool: string;
+    /** Argument KEY NAMES only, sorted — never values (may contain code/user text). */
+    argsShape: string[];
+    /** Byte size of the text content returned to the agent. */
+    resultBytes: number;
+    /** Node ids / file paths the call touched, when the result exposes them
+     *  (best-effort — see `extractTouchedIds`). Omitted when none found. */
+    nodeIds?: string[];
+    /** False when the handler threw or returned `isError: true`. */
+    ok: boolean;
+}
+export interface ToolResultLike {
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    isError?: boolean;
+}
+/** `<repoPath>/.reposkein/local/sessions` — where per-session JSONL logs
+ *  live for this repo. Git-ignored via `.reposkein/.gitignore`'s `local/`
+ *  entry (written by the indexer at index time). */
+export declare function sessionsDir(repoPath: string): string;
+export declare function sessionLogPath(repoPath: string, sessionId: string): string;
+/** Session id = server process lifetime: start-timestamp + pid. Filesystem-
+ *  safe (no colons) and lexicographically sortable = chronological. */
+export declare function defaultSessionId(now?: Date, pid?: number): string;
+/** Resolves this process's session id: `REPOSKEIN_SESSION_ID` override, else
+ *  `defaultSessionId()`. Computed once per server process and reused for
+ *  every call and every repo it touches during the connection's lifetime. */
+export declare function resolveSessionId(env?: NodeJS.ProcessEnv, now?: Date, pid?: number): string;
+/** Appends one record. Best-effort: a write failure (unwritable dir, full
+ *  disk, permission error) is swallowed — logging must never fail or slow a
+ *  tool call. Creates `local/sessions/` if needed. */
+export declare function appendSessionLog(repoPath: string, sessionId: string, record: SessionLogRecord): void;
+export interface PruneOptions {
+    /** Keep at most this many session files (newest first, by mtime). */
+    keep: number;
+    /** Drop any session file older than this many days, even if under `keep`. */
+    maxAgeDays: number;
+}
+export declare const DEFAULT_RETENTION: PruneOptions;
+/** Prunes `local/sessions/` for one repo: a file survives only if it is both
+ *  among the `keep` most-recently-modified files AND newer than
+ *  `maxAgeDays`. Deleting one file's read/stat failure never aborts the
+ *  sweep. Silently no-ops if the dir doesn't exist or isn't readable —
+ *  pruning must never fail server startup. */
+export declare function pruneSessions(repoPath: string, opts?: PruneOptions, now?: number): void;
+/** Best-effort extraction of node ids / file paths a tool call touched, from
+ *  its JSON-text result content — used for the "top queried nodes/files"
+ *  stat. Generic (one implementation for all tools, not per-tool logic):
+ *  parses each text block as JSON and walks it for a small allowlist of
+ *  id-shaped keys (`node_id`, `id`, `decision_id`, `node_ids`,
+ *  `anchor_node_ids`, `file_path`, `path`). Non-JSON or unparseable content
+ *  contributes nothing — never throws. */
+export declare function extractTouchedIds(result: ToolResultLike | undefined): string[];
+/** Byte size of the text an agent would actually read from a tool result
+ *  (sum of `content[].text`), the basis for "context tokens saved". Falls
+ *  back to the full JSON envelope size only when there's no text content AT
+ *  ALL (no `content` array, or no block of type "text") — a result whose
+ *  text blocks exist but are empty strings correctly reports 0, it does not
+ *  fall back to stringifying the envelope. */
+export declare function resultByteSize(result: ToolResultLike | undefined): number;
+/** Argument KEY NAMES only, sorted, never values. */
+export declare function argsShapeOf(args: unknown): string[];
+/** The single per-process instrumentation sink: one instance is created in
+ *  `main()` and shared by the tool-dispatch wrapper for every registered
+ *  tool (see `createToolLogger`/`withLog` in instrumentTool.ts) — the one
+ *  place tool calls get logged, so individual tool handlers never contain
+ *  logging code.
+ *
+ *  Retention is enforced lazily, per repo, the first time this process logs
+ *  a call for that repo — equivalent to "prune on server start" for the
+ *  common single-repo case, and the only sound definition of "start" once a
+ *  session can touch more than one repo (zero-config workspace mode). */
+export declare class SessionLogger {
+    private readonly sessionId;
+    private readonly retention;
+    private readonly prunedRepos;
+    constructor(sessionId: string, retention?: PruneOptions);
+    getSessionId(): string;
+    log(repoPath: string, entry: Omit<SessionLogRecord, "ts">): void;
+    /** Same as `log`, but with `ts` supplied by the caller instead of stamped
+     *  here — for the deferred-write path (see `instrumentTool.ts`), where the
+     *  call's completion time is captured synchronously on the hot path and
+     *  the actual write happens later (setImmediate); using that captured
+     *  `ts` keeps the record's timestamp accurate to when the call finished,
+     *  not to whenever the deferred write got scheduled. */
+    logAt(ts: string, repoPath: string, entry: Omit<SessionLogRecord, "ts">): void;
+}

package/dist/store/sessionLog.js

@@ -0,0 +1,216 @@
+import { appendFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+/** `<repoPath>/.reposkein/local/sessions` — where per-session JSONL logs
+ *  live for this repo. Git-ignored via `.reposkein/.gitignore`'s `local/`
+ *  entry (written by the indexer at index time). */
+export function sessionsDir(repoPath) {
+    return join(repoPath, ".reposkein", "local", "sessions");
+}
+export function sessionLogPath(repoPath, sessionId) {
+    return join(sessionsDir(repoPath), `${sessionId}.jsonl`);
+}
+function pad(n, len = 2) {
+    return String(n).padStart(len, "0");
+}
+/** Session id = server process lifetime: start-timestamp + pid. Filesystem-
+ *  safe (no colons) and lexicographically sortable = chronological. */
+export function defaultSessionId(now = new Date(), pid = process.pid) {
+    const stamp = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}` +
+        `T${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}Z`;
+    return `${stamp}-${pid}`;
+}
+/** Resolves this process's session id: `REPOSKEIN_SESSION_ID` override, else
+ *  `defaultSessionId()`. Computed once per server process and reused for
+ *  every call and every repo it touches during the connection's lifetime. */
+export function resolveSessionId(env = process.env, now = new Date(), pid = process.pid) {
+    const override = env.REPOSKEIN_SESSION_ID?.trim();
+    return override ? override : defaultSessionId(now, pid);
+}
+/** Appends one record. Best-effort: a write failure (unwritable dir, full
+ *  disk, permission error) is swallowed — logging must never fail or slow a
+ *  tool call. Creates `local/sessions/` if needed. */
+export function appendSessionLog(repoPath, sessionId, record) {
+    try {
+        mkdirSync(sessionsDir(repoPath), { recursive: true });
+        appendFileSync(sessionLogPath(repoPath, sessionId), JSON.stringify(record) + "\n", "utf8");
+    }
+    catch {
+        // best-effort — see doc comment
+    }
+}
+export const DEFAULT_RETENTION = { keep: 50, maxAgeDays: 30 };
+/** Prunes `local/sessions/` for one repo: a file survives only if it is both
+ *  among the `keep` most-recently-modified files AND newer than
+ *  `maxAgeDays`. Deleting one file's read/stat failure never aborts the
+ *  sweep. Silently no-ops if the dir doesn't exist or isn't readable —
+ *  pruning must never fail server startup. */
+export function pruneSessions(repoPath, opts = DEFAULT_RETENTION, now = Date.now()) {
+    try {
+        const dir = sessionsDir(repoPath);
+        if (!existsSync(dir))
+            return;
+        const files = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+        const withStats = files
+            .map((f) => {
+            const path = join(dir, f);
+            try {
+                return { path, mtimeMs: statSync(path).mtimeMs };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((x) => x !== null)
+            .sort((a, b) => b.mtimeMs - a.mtimeMs); // newest first
+        const maxAgeMs = opts.maxAgeDays * 24 * 60 * 60 * 1000;
+        withStats.forEach((entry, idx) => {
+            const tooOld = now - entry.mtimeMs > maxAgeMs;
+            const overCount = idx >= opts.keep;
+            if (tooOld || overCount) {
+                try {
+                    unlinkSync(entry.path);
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        });
+    }
+    catch {
+        // best-effort — see doc comment
+    }
+}
+/** Keys whose STRING value is treated as an id/path a tool call touched. */
+const ID_KEYS = new Set(["node_id", "id", "decision_id"]);
+/** Keys whose ARRAY value holds ids/paths (each string element collected). */
+const ID_ARRAY_KEYS = new Set(["node_ids", "anchor_node_ids"]);
+/** Keys whose STRING value is a file path a tool call touched. */
+const PATH_KEYS = new Set(["file_path", "path"]);
+const MAX_TOUCHED_IDS = 25;
+const MAX_WALK_DEPTH = 6;
+function walkForIds(value, out, depth) {
+    if (out.size >= MAX_TOUCHED_IDS || depth > MAX_WALK_DEPTH || value == null)
+        return;
+    if (Array.isArray(value)) {
+        for (const v of value)
+            walkForIds(v, out, depth + 1);
+        return;
+    }
+    if (typeof value !== "object")
+        return;
+    for (const [key, v] of Object.entries(value)) {
+        if (out.size >= MAX_TOUCHED_IDS)
+            return;
+        if ((ID_KEYS.has(key) || PATH_KEYS.has(key)) && typeof v === "string") {
+            out.add(v);
+        }
+        else if (ID_ARRAY_KEYS.has(key) && Array.isArray(v)) {
+            for (const item of v) {
+                if (out.size >= MAX_TOUCHED_IDS)
+                    break;
+                if (typeof item === "string")
+                    out.add(item);
+            }
+        }
+        else {
+            walkForIds(v, out, depth + 1);
+        }
+    }
+}
+/** Best-effort extraction of node ids / file paths a tool call touched, from
+ *  its JSON-text result content — used for the "top queried nodes/files"
+ *  stat. Generic (one implementation for all tools, not per-tool logic):
+ *  parses each text block as JSON and walks it for a small allowlist of
+ *  id-shaped keys (`node_id`, `id`, `decision_id`, `node_ids`,
+ *  `anchor_node_ids`, `file_path`, `path`). Non-JSON or unparseable content
+ *  contributes nothing — never throws. */
+export function extractTouchedIds(result) {
+    if (!result)
+        return [];
+    const found = new Set();
+    for (const block of result.content ?? []) {
+        if (found.size >= MAX_TOUCHED_IDS)
+            break;
+        if (block.type !== "text" || typeof block.text !== "string")
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(block.text);
+        }
+        catch {
+            continue;
+        }
+        walkForIds(parsed, found, 0);
+    }
+    return [...found];
+}
+/** Byte size of the text an agent would actually read from a tool result
+ *  (sum of `content[].text`), the basis for "context tokens saved". Falls
+ *  back to the full JSON envelope size only when there's no text content AT
+ *  ALL (no `content` array, or no block of type "text") — a result whose
+ *  text blocks exist but are empty strings correctly reports 0, it does not
+ *  fall back to stringifying the envelope. */
+export function resultByteSize(result) {
+    if (!result)
+        return 0;
+    const blocks = result.content ?? [];
+    let bytes = 0;
+    let hasTextBlock = false;
+    for (const block of blocks) {
+        if (block.type === "text" && typeof block.text === "string") {
+            hasTextBlock = true;
+            bytes += Buffer.byteLength(block.text, "utf8");
+        }
+    }
+    return hasTextBlock ? bytes : Buffer.byteLength(JSON.stringify(result), "utf8");
+}
+/** Argument KEY NAMES only, sorted, never values. */
+export function argsShapeOf(args) {
+    if (!args || typeof args !== "object")
+        return [];
+    return Object.keys(args).sort();
+}
+/** The single per-process instrumentation sink: one instance is created in
+ *  `main()` and shared by the tool-dispatch wrapper for every registered
+ *  tool (see `createToolLogger`/`withLog` in instrumentTool.ts) — the one
+ *  place tool calls get logged, so individual tool handlers never contain
+ *  logging code.
+ *
+ *  Retention is enforced lazily, per repo, the first time this process logs
+ *  a call for that repo — equivalent to "prune on server start" for the
+ *  common single-repo case, and the only sound definition of "start" once a
+ *  session can touch more than one repo (zero-config workspace mode). */
+export class SessionLogger {
+    sessionId;
+    retention;
+    prunedRepos = new Set();
+    constructor(sessionId, retention = DEFAULT_RETENTION) {
+        this.sessionId = sessionId;
+        this.retention = retention;
+    }
+    getSessionId() {
+        return this.sessionId;
+    }
+    log(repoPath, entry) {
+        this.logAt(new Date().toISOString(), repoPath, entry);
+    }
+    /** Same as `log`, but with `ts` supplied by the caller instead of stamped
+     *  here — for the deferred-write path (see `instrumentTool.ts`), where the
+     *  call's completion time is captured synchronously on the hot path and
+     *  the actual write happens later (setImmediate); using that captured
+     *  `ts` keeps the record's timestamp accurate to when the call finished,
+     *  not to whenever the deferred write got scheduled. */
+    logAt(ts, repoPath, entry) {
+        try {
+            if (!this.prunedRepos.has(repoPath)) {
+                this.prunedRepos.add(repoPath);
+                pruneSessions(repoPath, this.retention);
+            }
+            appendSessionLog(repoPath, this.sessionId, { ts, ...entry });
+        }
+        catch {
+            // never fail/slow the tool call — see appendSessionLog's own try/catch too
+        }
+    }
+}
+//# sourceMappingURL=sessionLog.js.map

package/dist/store/sessionLog.js.map

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

package/dist/store/sessionStats.d.ts

@@ -0,0 +1,55 @@
+import { type SessionLogRecord } from "./sessionLog.js";
+/** grep-baseline token-ratio multiplier used for the "estimated context
+ *  tokens saved" stat. Sourced from `mcp/bench/README.md`'s Track 1 retrieval
+ *  benchmark ("Mean token ratio on structural tasks: 8.4x (grep / RepoSkein,
+ *  generous-to-grep)") — a measured, repo-local number, not invented here.
+ *  Always LABEL output built from this as an estimate: it's one repo's
+ *  5-task mean, generalized to every call in a session. */
+export declare const GREP_BASELINE_MULTIPLIER = 8.4;
+export interface SessionSummary {
+    sessionId: string;
+    /** Absolute path to the session's .jsonl file. */
+    file: string;
+    recordCount: number;
+    callsByTool: Record<string, number>;
+    /** Top node ids / file paths touched, most-referenced first. */
+    topTouched: Array<{
+        id: string;
+        count: number;
+    }>;
+    /** Count of ADRs recorded this session (record_decision calls). */
+    decisionsWritten: number;
+    /** Count of semantic summaries written this session (write_semantic_summary calls). */
+    summariesWritten: number;
+    /** ms between the first and last record's `ts`. 0 for a single-record session. */
+    durationMs: number;
+    totalResultBytes: number;
+    /** GREP_BASELINE_MULTIPLIER * totalResultBytes / 4 (≈4 bytes/token), i.e.
+     *  the estimated token cost an equivalent grep-based approach would have
+     *  paid for what RepoSkein returned in `totalResultBytes`. Labeled an
+     *  estimate everywhere it's rendered — see GREP_BASELINE_MULTIPLIER. */
+    estimatedGrepTokens: number;
+    estimatedRepoSkeinTokens: number;
+    estimatedTokensSaved: number;
+    failedCalls: number;
+}
+/** Reads and parses one session's JSONL file. Malformed lines are skipped
+ *  (never thrown) — a session log is best-effort telemetry, not a source of
+ *  truth that must be pristine. */
+export declare function readSessionLog(file: string): SessionLogRecord[];
+/** Every session file for a repo, sorted newest-first (by mtime). */
+export declare function listSessionFiles(repoPath: string): Array<{
+    sessionId: string;
+    file: string;
+    mtimeMs: number;
+}>;
+/** Aggregates one session's records into the report shape rendered by
+ *  `reposkein-mcp stats`. Pure function over already-parsed records so it's
+ *  cheap to unit test independent of the filesystem. */
+export declare function summarizeSession(sessionId: string, file: string, records: SessionLogRecord[]): SessionSummary;
+/** Merges several sessions' records into one combined summary (`--all`) —
+ *  same aggregation, over the union of records, with a synthetic id. */
+export declare function summarizeSessions(sessions: Array<{
+    sessionId: string;
+    file: string;
+}>): SessionSummary;

package/dist/store/sessionStats.js

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { sessionsDir } from "./sessionLog.js";
+/** grep-baseline token-ratio multiplier used for the "estimated context
+ *  tokens saved" stat. Sourced from `mcp/bench/README.md`'s Track 1 retrieval
+ *  benchmark ("Mean token ratio on structural tasks: 8.4x (grep / RepoSkein,
+ *  generous-to-grep)") — a measured, repo-local number, not invented here.
+ *  Always LABEL output built from this as an estimate: it's one repo's
+ *  5-task mean, generalized to every call in a session. */
+export const GREP_BASELINE_MULTIPLIER = 8.4;
+/** Reads and parses one session's JSONL file. Malformed lines are skipped
+ *  (never thrown) — a session log is best-effort telemetry, not a source of
+ *  truth that must be pristine. */
+export function readSessionLog(file) {
+    if (!existsSync(file))
+        return [];
+    let text;
+    try {
+        text = readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const rec = JSON.parse(line);
+            if (typeof rec.tool === "string" && typeof rec.ts === "string") {
+                out.push({
+                    ts: rec.ts,
+                    tool: rec.tool,
+                    argsShape: Array.isArray(rec.argsShape) ? rec.argsShape : [],
+                    resultBytes: typeof rec.resultBytes === "number" ? rec.resultBytes : 0,
+                    ...(Array.isArray(rec.nodeIds) && rec.nodeIds.length ? { nodeIds: rec.nodeIds } : {}),
+                    ok: rec.ok !== false,
+                });
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return out;
+}
+/** Every session file for a repo, sorted newest-first (by mtime). */
+export function listSessionFiles(repoPath) {
+    const dir = sessionsDir(repoPath);
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = readdirSync(dir).filter((f) => f.endsWith(".jsonl"));
+    }
+    catch {
+        return [];
+    }
+    return names
+        .map((name) => {
+        const file = join(dir, name);
+        let mtimeMs = 0;
+        try {
+            mtimeMs = statSync(file).mtimeMs;
+        }
+        catch {
+            /* keep 0 — still listed, just sorts last */
+        }
+        return { sessionId: name.replace(/\.jsonl$/, ""), file, mtimeMs };
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/** Tools whose calls count as "summaries/ADRs written this session". */
+const DECISION_TOOLS = new Set(["record_decision"]);
+const SUMMARY_TOOLS = new Set(["write_semantic_summary"]);
+/** Aggregates one session's records into the report shape rendered by
+ *  `reposkein-mcp stats`. Pure function over already-parsed records so it's
+ *  cheap to unit test independent of the filesystem. */
+export function summarizeSession(sessionId, file, records) {
+    const callsByTool = {};
+    const touchedCounts = new Map();
+    let decisionsWritten = 0;
+    let summariesWritten = 0;
+    let totalResultBytes = 0;
+    let failedCalls = 0;
+    let minTs = Infinity;
+    let maxTs = -Infinity;
+    for (const rec of records) {
+        callsByTool[rec.tool] = (callsByTool[rec.tool] ?? 0) + 1;
+        totalResultBytes += rec.resultBytes;
+        if (!rec.ok)
+            failedCalls++;
+        if (DECISION_TOOLS.has(rec.tool))
+            decisionsWritten++;
+        if (SUMMARY_TOOLS.has(rec.tool))
+            summariesWritten++;
+        for (const id of rec.nodeIds ?? [])
+            touchedCounts.set(id, (touchedCounts.get(id) ?? 0) + 1);
+        const t = Date.parse(rec.ts);
+        if (!Number.isNaN(t)) {
+            if (t < minTs)
+                minTs = t;
+            if (t > maxTs)
+                maxTs = t;
+        }
+    }
+    const topTouched = [...touchedCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 10)
+        .map(([id, count]) => ({ id, count }));
+    const durationMs = Number.isFinite(minTs) && Number.isFinite(maxTs) && maxTs > minTs ? maxTs - minTs : 0;
+    // ~4 bytes/token is the common rough estimator (also used by mcp/bench —
+    // see its token cost model) — deliberately simple and labeled an estimate.
+    const estimatedRepoSkeinTokens = Math.round(totalResultBytes / 4);
+    const estimatedGrepTokens = Math.round(estimatedRepoSkeinTokens * GREP_BASELINE_MULTIPLIER);
+    const estimatedTokensSaved = estimatedGrepTokens - estimatedRepoSkeinTokens;
+    return {
+        sessionId,
+        file,
+        recordCount: records.length,
+        callsByTool,
+        topTouched,
+        decisionsWritten,
+        summariesWritten,
+        durationMs,
+        totalResultBytes,
+        estimatedGrepTokens,
+        estimatedRepoSkeinTokens,
+        estimatedTokensSaved,
+        failedCalls,
+    };
+}
+/** Merges several sessions' records into one combined summary (`--all`) —
+ *  same aggregation, over the union of records, with a synthetic id. */
+export function summarizeSessions(sessions) {
+    const allRecords = sessions.flatMap((s) => readSessionLog(s.file));
+    const label = sessions.length === 1 ? sessions[0].sessionId : `${sessions.length} sessions`;
+    return summarizeSession(label, sessions.map((s) => s.file).join(","), allRecords);
+}
+//# sourceMappingURL=sessionStats.js.map

package/dist/store/sessionStats.js.map

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

package/dist/store/sidecar.d.ts

@@ -1,4 +1,5 @@
-/** A persisted summary record (git-ignored .reposkein/local/summaries.jsonl). */
+import { type SummaryAccumulator } from "./summaryShards.js";
+/** A persisted summary record (git-ignored .reposkein/local/summaries-<agent>.jsonl). */
 export interface SidecarSummary {
     id: string;
     semantic_summary: string;
@@ -7,10 +8,45 @@ export interface SidecarSummary {
     summary_at: string;
     summary_by: string;
 }
-export declare function sidecarPath(repoPath: string): string;
+/** Directory holding every agent's sidecar. Git-ignored in full. */
+export declare function sidecarDir(repoPath: string): string;
+/** Filesystem-safe slug for the writing agent.
+ *
+ *  Untrusted input: REPOSKEIN_AGENT comes from whatever launched the server, so
+ *  it is reduced to `[a-z0-9._-]` and capped. A value that reduces to nothing
+ *  (or is absent) falls back to "agent", which is also the pre-multi-agent
+ *  name — so a single-agent setup keeps one stable file. */
+export declare function agentSlug(agent?: string | undefined): string;
+/** THIS process's sidecar: one file per agent.
+ *
+ *  A single shared `local/summaries.jsonl` meant two agents running against the
+ *  same checkout silently overwrote each other — `upsertSidecar` rewrites the
+ *  whole file, so the slower writer's prose vanished with no error anywhere.
+ *  One file per writer removes the shared mutable state; the indexer folds
+ *  every `local/summaries*.jsonl` into the committed shards. */
+export declare function sidecarPath(repoPath: string, agent?: string): string;
+/** Every agent's sidecar in this repo, sorted, so reads are deterministic and
+ *  independent of directory order. Includes the pre-split
+ *  `local/summaries.jsonl` an older client may still be writing. */
+export declare function sidecarPaths(repoPath: string): string[];
 /** Reads the sidecar into a map keyed by node id. Missing file → empty map.
  *  Best-effort: malformed lines / read errors are skipped. */
 export declare function readSidecar(path: string): Map<string, SidecarSummary>;
+/** Every agent's sidecar records, folded through the SAME rules the Rust
+ *  indexer applies — `beats` within the sidecar set, losers preserved — so the
+ *  server serves exactly the record the next `index` is going to write.
+ *
+ *  This used to be a plain last-file-wins merge, which disagreed with the
+ *  indexer whenever two agents summarised the same node, and dropped the loser
+ *  with no trace. Callers should hand `conflicts` to `recordSummaryConflicts`. */
+export declare function loadAllSidecars(repoPath: string): SummaryAccumulator;
+/** Convenience view of `loadAllSidecars` for callers that only want the
+ *  winning record per node id. Divergence losers are dropped on the floor
+ *  here, so prefer `loadAllSidecars` anywhere they can be recorded. */
+export declare function readAllSidecars(repoPath: string): Map<string, SidecarSummary>;
 /** Upserts one record and rewrites the sidecar sorted by id (deterministic, no
- *  duplicate lines). Creates the local/ dir if needed. Best-effort. */
+ *  duplicate lines). Creates the local/ dir if needed. Best-effort.
+ *
+ *  Rewriting the whole file is safe only because `path` belongs to one agent:
+ *  see `sidecarPath`. */
 export declare function upsertSidecar(path: string, rec: SidecarSummary): void;