frontier-mcp 0.1.0

package/dist/tools/update-ticket.js

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+import { STATUSES, TRIAGE_ROLES } from '../domain.js';
+import { cycleThrough, renderCycle } from '../edges.js';
+import { indexById } from '../frontier.js';
+export const updateTicketInputSchema = {
+    id: z.string().describe('Ticket id, or the <effort>#<order> handle of a Legacy Ticket.'),
+    claim: z
+        .object({ by: z.string().min(1).describe('Who is taking it.') })
+        .optional()
+        .describe('Take the Ticket. Fails if another holder already has it.'),
+    resolve: z
+        .object({
+        answer_gist: z.string().min(1).describe('One line: what landed, or what was decided.'),
+        answer: z.string().optional().describe('The full answer, written into the body verbatim.'),
+    })
+        .optional()
+        .describe('Close the Ticket as a step on the route.'),
+    drop: z
+        .object({ reason: z.string().min(1).describe('Why it is beyond the destination.') })
+        .optional()
+        .describe('Close the Ticket as work ruled out of scope.'),
+    status: z
+        .enum(STATUSES)
+        .optional()
+        .describe('Not settable directly — use claim, resolve, or drop. Named here to say so.'),
+    triage: z
+        .enum(TRIAGE_ROLES)
+        .optional()
+        .describe('Set the triage role. A separate field from status; neither touches the other.'),
+    blocked_by: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Replace the Edges outright, each a plain Ticket id resolved repo-wide. An empty list ' +
+        'clears them. A cycle is refused.'),
+    comment: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Append to the comment log, stored exactly as written.'),
+    tick: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('Acceptance criteria to check off, matched on their text. Wrapped criteria match both ' +
+        'as get_tickets returns them and re-joined onto one line. All references resolve before ' +
+        'anything is written — one unmatched name fails the whole call and leaves the file untouched.'),
+    root: z.string().optional().describe('Workspace directory. Defaults to the session workspace.'),
+};
+export const updateTicketDescription = 'Change one Ticket. Lifecycle: claim, resolve with a one-line gist, or drop with a reason — at ' +
+    'most one of those per call. Graph: replace the Edges, refused if they close a cycle. ' +
+    'Annotations: triage role, a comment, ticking acceptance criteria; these touch no part of the ' +
+    'graph. Any of the three groups may accompany the others or stand alone.';
+/**
+ * Turn a request into the edit the driver applies, refusing anything the Status
+ * model or the Edge graph does not allow. Validation lives here rather than in
+ * the driver because it is a rule about the domain, not about storage.
+ *
+ * `all` is every Ticket in the workspace, because Edges resolve repo-wide and a
+ * cycle can run through an Effort this call never names.
+ */
+export function editFor(ticket, all, request, now) {
+    // Annotations are not graph operations. They carry no lifecycle meaning, so
+    // they ride along with a transition or stand on their own. An Edge change is a
+    // graph operation and rides along the same way, having been validated first.
+    const annotations = {
+        ...(request.triage === undefined ? {} : { triage: request.triage }),
+        ...(request.comment === undefined ? {} : { comment: request.comment }),
+        ...(request.tick === undefined ? {} : { tick: request.tick }),
+        ...(request.blocked_by === undefined ? {} : { blockedBy: edgesFor(ticket, all, request) }),
+    };
+    // Status is derived from the transition, never assigned. Saying so beats
+    // silently dropping the field — and `wontfix` is a Triage role, so it is not
+    // a Status this would have accepted either way.
+    if (request.status !== undefined) {
+        throw new Error(`status is not set directly. Use claim, resolve, or drop; '${request.status}' ` +
+            'is a lifecycle position the server derives.');
+    }
+    const actions = [request.claim, request.resolve, request.drop].filter(action => action !== undefined);
+    if (actions.length > 1)
+        throw new Error('Pass at most one of claim, resolve, or drop.');
+    if (actions.length === 0) {
+        if (Object.keys(annotations).length === 0) {
+            throw new Error('Nothing to do: pass a lifecycle change, or blocked_by, triage, comment, or tick.');
+        }
+        return annotations;
+    }
+    if (request.claim !== undefined) {
+        return { ...annotations, ...claimEdit(ticket, request.claim.by, now) };
+    }
+    if (request.resolve !== undefined) {
+        // Required on every kind, build included: a build Ticket's one line of what
+        // landed is what makes a Board of finished work readable.
+        return {
+            ...annotations,
+            status: 'resolved',
+            answerGist: request.resolve.answer_gist,
+            claimedBy: null,
+            claimedAt: null,
+            ...(request.resolve.answer === undefined ? {} : { answer: request.resolve.answer }),
+        };
+    }
+    if (request.drop !== undefined) {
+        return {
+            ...annotations,
+            status: 'dropped',
+            droppedReason: request.drop.reason,
+            claimedBy: null,
+            claimedAt: null,
+        };
+    }
+    throw new Error('Unreachable: an action was counted but none matched.');
+}
+/**
+ * The new Edge list, refused if it closes a cycle. This is the same check
+ * `create_tickets` runs and the easier of the two ways to close a loop — a
+ * breakdown published in one call is at least written down in one place, where
+ * an Edge added later is not.
+ *
+ * A dangling Edge is not refused: it is a Board warning, and pointing at a
+ * Ticket that has not been written yet is how a breakdown gets built up.
+ */
+function edgesFor(ticket, all, request) {
+    const blockedBy = request.blocked_by ?? [];
+    // Nothing can name an id-less Legacy Ticket, so no path leads back to it.
+    if (ticket.id === undefined)
+        return blockedBy;
+    const byId = indexById(all);
+    const edgesOf = id => (id === ticket.id ? blockedBy : (byId.get(id)?.blockedBy ?? []));
+    const cycle = cycleThrough(ticket.id, edgesOf);
+    if (cycle !== undefined) {
+        throw new Error(`Those Edges would close a cycle: ${renderCycle(cycle)}. Nothing in a cycle is ever ` +
+            'takeable, so nothing was written.');
+    }
+    return blockedBy;
+}
+/**
+ * Claiming is compare-and-set. A Ticket someone else holds is refused rather
+ * than taken, so two parallel sessions can never both believe they hold it.
+ * Re-claiming your own is allowed — it refreshes the timestamp.
+ */
+function claimEdit(ticket, by, now) {
+    if (ticket.claimedBy !== undefined && ticket.claimedBy !== by) {
+        throw new Error(`${ticket.handle} is already claimed by ${ticket.claimedBy}` +
+            `${ticket.claimedAt === undefined ? '' : ` since ${ticket.claimedAt}`}. ` +
+            'Claims are never auto-released; take it up with the holder.');
+    }
+    if (ticket.status === 'resolved' || ticket.status === 'dropped') {
+        throw new Error(`${ticket.handle} is already ${ticket.status}, so there is nothing to claim.`);
+    }
+    return { status: 'claimed', claimedBy: by, claimedAt: now };
+}
+export function renderUpdate(ticket, warnings = []) {
+    const fields = [
+        `status=${ticket.status}`,
+        ticket.claimedBy === undefined ? undefined : `claimed_by=${ticket.claimedBy}`,
+        ticket.claimedAt === undefined ? undefined : `claimed_at=${ticket.claimedAt}`,
+        ticket.answerGist === undefined ? undefined : `answer_gist=${ticket.answerGist}`,
+        ticket.droppedReason === undefined ? undefined : `dropped_reason=${ticket.droppedReason}`,
+    ].filter(field => field !== undefined);
+    const body = `${ticket.handle} updated\n${fields.join('  ')}`;
+    if (warnings.length === 0)
+        return body;
+    return `${body}\nwarnings:\n${warnings.map(warning => `- ${warning}`).join('\n')}`;
+}
+//# sourceMappingURL=update-ticket.js.map

package/dist/tools/update-ticket.js.map

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

package/dist/tracker-doc.d.ts

@@ -0,0 +1,10 @@
+/** Stable URI for the tracker configuration document MCP resource. */
+export declare const TRACKER_DOC_URI = "frontier://tracker-doc";
+/**
+ * Read the shipped tracker configuration document. It sits beside `dist/` in
+ * the published package, which is why the path is resolved from this module
+ * rather than from the process working directory — the server is started from
+ * the user's repo, not from its own install.
+ */
+export declare function readTrackerDoc(): string;
+//# sourceMappingURL=tracker-doc.d.ts.map

package/dist/tracker-doc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker-doc.d.ts","sourceRoot":"","sources":["../src/tracker-doc.ts"],"names":[],"mappings":"AAIA,sEAAsE;AACtE,eAAO,MAAM,eAAe,2BAA2B,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC"}

package/dist/tracker-doc.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Stable URI for the tracker configuration document MCP resource. */
+export const TRACKER_DOC_URI = 'frontier://tracker-doc';
+/**
+ * Read the shipped tracker configuration document. It sits beside `dist/` in
+ * the published package, which is why the path is resolved from this module
+ * rather than from the process working directory — the server is started from
+ * the user's repo, not from its own install.
+ */
+export function readTrackerDoc() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return readFileSync(join(here, '..', 'docs', 'agents', 'issue-tracker.md'), 'utf8');
+}
+//# sourceMappingURL=tracker-doc.js.map

package/dist/tracker-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker-doc.js","sourceRoot":"","sources":["../src/tracker-doc.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG,wBAAwB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,OAAO,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC,CAAC;AACtF,CAAC"}

package/dist/workspace-index.d.ts

@@ -0,0 +1,39 @@
+import type { Effort, MapDocument, MapEdit, MigrateOptions, MigrationReport, SpecDocument, Ticket, TicketDraft } from './domain.ts';
+import type { CreateOptions, HeaderDocOptions, StorageDriver, TicketEdit, TicketWriteResult } from './storage/driver.ts';
+/**
+ * The in-memory index: a derived, rebuildable view of one workspace, built by a
+ * full scan. At the volumes involved a full scan is single-digit milliseconds,
+ * so the index rebuilds wholesale rather than tracking entries individually.
+ *
+ * A filesystem watcher invalidates the scan when `.scratch/` changes on disk,
+ * so the next read rebuilds without restarting the process.
+ */
+export interface WorkspaceIndex {
+    efforts(): Promise<readonly Effort[]>;
+    tickets(): Promise<readonly Ticket[]>;
+    /** Apply an edit and discard the scan, since the workspace has moved on. */
+    update(handle: string, edit: TicketEdit, expectedRevision: string): Promise<TicketWriteResult>;
+    /** Create a batch of Tickets and discard the scan, for the same reason. */
+    create(effort: string, drafts: readonly TicketDraft[], options: CreateOptions): Promise<readonly Ticket[]>;
+    readMap(effort: string): Promise<MapDocument>;
+    editMap(effort: string, edit: MapEdit, expectedRevision: string | undefined, options: HeaderDocOptions): Promise<MapDocument>;
+    readSpec(effort: string): Promise<SpecDocument>;
+    putSpec(effort: string, body: string, expectedRevision: string | undefined, options: HeaderDocOptions): Promise<SpecDocument>;
+    migrate(effort: string, options: MigrateOptions): Promise<MigrationReport>;
+    /** Discard cached scans so the next read rebuilds from disk. */
+    invalidate(): void;
+}
+export declare function createWorkspaceIndex(driver: StorageDriver): WorkspaceIndex;
+/**
+ * One index per workspace. A call carrying an explicit `root` reads a different
+ * workspace from the session's own, and each keeps its own scan.
+ */
+export interface IndexRegistry {
+    forWorkspace(root: string): WorkspaceIndex;
+    closeAll(): void;
+}
+export interface IndexRegistryOptions {
+    readonly watcherDebounceMs?: number;
+}
+export declare function createIndexRegistry(createDriver: (root: string) => StorageDriver, options?: IndexRegistryOptions): IndexRegistry;
+//# sourceMappingURL=workspace-index.d.ts.map

package/dist/workspace-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-index.d.ts","sourceRoot":"","sources":["../src/workspace-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,WAAW,EACX,OAAO,EACP,cAAc,EACd,eAAe,EACf,YAAY,EACZ,MAAM,EACN,WAAW,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAG7B;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IACtC,OAAO,IAAI,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IACtC,4EAA4E;IAC5E,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/F,2EAA2E;IAC3E,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9C,OAAO,CACL,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAChD,OAAO,CACL,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC3E,gEAAgE;IAChE,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CA2C1E;AAuBD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC;IAC3C,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,aAAa,EAC7C,OAAO,GAAE,oBAAyB,GACjC,aAAa,CAsBf"}

package/dist/workspace-index.js

@@ -0,0 +1,83 @@
+import { createWatcherRegistry } from './workspace-watcher.js';
+export function createWorkspaceIndex(driver) {
+    const efforts = cache(() => driver.listEfforts());
+    const tickets = cache(() => driver.listTickets());
+    const invalidate = () => {
+        efforts.invalidate();
+        tickets.invalidate();
+    };
+    /**
+     * A write moves the workspace on whether or not it succeeded partway, so the
+     * next read rebuilds rather than trusting a scan taken before it.
+     */
+    async function moved(operation) {
+        try {
+            return await operation();
+        }
+        finally {
+            invalidate();
+        }
+    }
+    return {
+        efforts: efforts.get,
+        tickets: tickets.get,
+        async update(handle, edit, expectedRevision) {
+            return moved(() => driver.updateTicket(handle, edit, expectedRevision));
+        },
+        async create(effort, drafts, options) {
+            return moved(() => driver.createTickets(effort, drafts, options));
+        },
+        readMap: effort => driver.readMap(effort),
+        async editMap(effort, edit, expectedRevision, options) {
+            return moved(() => driver.editMap(effort, edit, expectedRevision, options));
+        },
+        readSpec: effort => driver.readSpec(effort),
+        async putSpec(effort, body, expectedRevision, options) {
+            return moved(() => driver.putSpec(effort, body, expectedRevision, options));
+        },
+        async migrate(effort, options) {
+            return moved(() => driver.migrateEffort(effort, options));
+        },
+        invalidate,
+    };
+}
+/**
+ * Hold the in-flight scan, not just its result, so concurrent callers share one
+ * scan instead of racing several. A failed scan is never cached as the answer.
+ */
+function cache(scan) {
+    let pending;
+    return {
+        get: () => {
+            pending ??= scan().catch((error) => {
+                pending = undefined;
+                throw error;
+            });
+            return pending;
+        },
+        invalidate: () => {
+            pending = undefined;
+        },
+    };
+}
+export function createIndexRegistry(createDriver, options = {}) {
+    const indexes = new Map();
+    const watchers = createWatcherRegistry(options.watcherDebounceMs === undefined ? {} : { debounceMs: options.watcherDebounceMs });
+    return {
+        forWorkspace(root) {
+            let index = indexes.get(root);
+            if (index === undefined) {
+                const created = createWorkspaceIndex(createDriver(root));
+                indexes.set(root, created);
+                watchers.attach(root, () => created.invalidate());
+                index = created;
+            }
+            return index;
+        },
+        closeAll() {
+            watchers.closeAll();
+            indexes.clear();
+        },
+    };
+}
+//# sourceMappingURL=workspace-index.js.map

package/dist/workspace-index.js.map

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

package/dist/workspace-watcher.d.ts

@@ -0,0 +1,24 @@
+export interface WorkspaceWatcher {
+    close(): void;
+}
+export interface WorkspaceWatcherOptions {
+    /** Debounce rapid events before invalidating. Defaults to 50ms. */
+    readonly debounceMs?: number;
+}
+/**
+ * Watch `.scratch/` under a resolved workspace and call `invalidate` when it
+ * changes. Never writes — only schedules invalidation after debouncing.
+ *
+ * If `.scratch/` does not exist yet, the workspace root is watched until the
+ * directory appears, then the recursive scratch watch is attached.
+ */
+export declare function watchWorkspace(root: string, invalidate: () => void, options?: WorkspaceWatcherOptions): WorkspaceWatcher;
+/**
+ * One watcher per workspace root. Started when an index is first opened.
+ */
+export interface WatcherRegistry {
+    attach(root: string, invalidate: () => void): void;
+    closeAll(): void;
+}
+export declare function createWatcherRegistry(options?: WorkspaceWatcherOptions): WatcherRegistry;
+//# sourceMappingURL=workspace-watcher.d.ts.map

package/dist/workspace-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-watcher.d.ts","sourceRoot":"","sources":["../src/workspace-watcher.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,IAAI,EACtB,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CA2DlB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACnD,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,uBAA4B,GAAG,eAAe,CAa5F"}

package/dist/workspace-watcher.js

@@ -0,0 +1,87 @@
+import { existsSync, watch } from 'node:fs';
+import { join } from 'node:path';
+const SCRATCH = '.scratch';
+/**
+ * Watch `.scratch/` under a resolved workspace and call `invalidate` when it
+ * changes. Never writes — only schedules invalidation after debouncing.
+ *
+ * If `.scratch/` does not exist yet, the workspace root is watched until the
+ * directory appears, then the recursive scratch watch is attached.
+ */
+export function watchWorkspace(root, invalidate, options = {}) {
+    const debounceMs = options.debounceMs ?? 50;
+    const scratchPath = join(root, SCRATCH);
+    let timer;
+    let scratchWatcher;
+    let rootWatcher;
+    const scheduleInvalidate = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            timer = undefined;
+            invalidate();
+        }, debounceMs);
+    };
+    const attachScratchWatcher = () => {
+        if (scratchWatcher !== undefined || !existsSync(scratchPath))
+            return;
+        try {
+            scratchWatcher = watch(scratchPath, { recursive: true }, () => {
+                scheduleInvalidate();
+            });
+            scratchWatcher.on('error', () => {
+                scratchWatcher?.close();
+                scratchWatcher = undefined;
+            });
+            rootWatcher?.close();
+            rootWatcher = undefined;
+        }
+        catch {
+            // `.scratch/` may have disappeared between the exists check and watch.
+        }
+    };
+    attachScratchWatcher();
+    if (scratchWatcher === undefined) {
+        try {
+            rootWatcher = watch(root, (_event, filename) => {
+                if (filename !== SCRATCH)
+                    return;
+                attachScratchWatcher();
+                scheduleInvalidate();
+            });
+            rootWatcher.on('error', () => {
+                rootWatcher?.close();
+                rootWatcher = undefined;
+            });
+        }
+        catch {
+            // Unusual, but a missing workspace root should not wedge the server.
+        }
+    }
+    return {
+        close() {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            scratchWatcher?.close();
+            rootWatcher?.close();
+            scratchWatcher = undefined;
+            rootWatcher = undefined;
+        },
+    };
+}
+export function createWatcherRegistry(options = {}) {
+    const watchers = new Map();
+    return {
+        attach(root, invalidate) {
+            if (watchers.has(root))
+                return;
+            watchers.set(root, watchWorkspace(root, invalidate, options));
+        },
+        closeAll() {
+            for (const watcher of watchers.values())
+                watcher.close();
+            watchers.clear();
+        },
+    };
+}
+//# sourceMappingURL=workspace-watcher.js.map

package/dist/workspace-watcher.js.map

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

package/dist/workspace.d.ts

@@ -0,0 +1,23 @@
+/** The environment variable that overrides the workspace for a whole session. */
+export declare const WORKSPACE_ENV_VAR = "FRONTIER_ROOT";
+export interface WorkspaceContext {
+    /** The server process's working directory. */
+    readonly cwd: string;
+    readonly env: Readonly<Partial<Record<string, string>>>;
+}
+/**
+ * Resolve which workspace a call serves. First match wins:
+ *
+ *   1. an explicit `root` argument on the call,
+ *   2. the `FRONTIER_ROOT` environment variable,
+ *   3. the working directory, walked upward to the nearest `.scratch/` or `.git/`.
+ *
+ * MCP Roots is deliberately not used: it is deprecated as of protocol revision
+ * `2026-07-28` (SEP-2577), which directs implementations to pass directories
+ * through tool parameters or server configuration instead.
+ *
+ * An override that names nothing, or names a file, is a typo worth failing on.
+ * A workspace with no `.scratch/` is not — that is a fresh project.
+ */
+export declare function resolveWorkspace(root: string | undefined, context: WorkspaceContext): string;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAGA,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,kBAAkB,CAAC;AAKjD,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;CACzD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAY5F"}

package/dist/workspace.js

@@ -0,0 +1,70 @@
+import { statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** The environment variable that overrides the workspace for a whole session. */
+export const WORKSPACE_ENV_VAR = 'FRONTIER_ROOT';
+/** A directory holding either of these is the repository root we serve. */
+const ROOT_MARKERS = ['.scratch', '.git'];
+/**
+ * Resolve which workspace a call serves. First match wins:
+ *
+ *   1. an explicit `root` argument on the call,
+ *   2. the `FRONTIER_ROOT` environment variable,
+ *   3. the working directory, walked upward to the nearest `.scratch/` or `.git/`.
+ *
+ * MCP Roots is deliberately not used: it is deprecated as of protocol revision
+ * `2026-07-28` (SEP-2577), which directs implementations to pass directories
+ * through tool parameters or server configuration instead.
+ *
+ * An override that names nothing, or names a file, is a typo worth failing on.
+ * A workspace with no `.scratch/` is not — that is a fresh project.
+ */
+export function resolveWorkspace(root, context) {
+    const argument = given(root);
+    if (argument !== undefined) {
+        return requireDirectory(resolve(context.cwd, argument), 'root argument');
+    }
+    const fromEnv = given(context.env[WORKSPACE_ENV_VAR]);
+    if (fromEnv !== undefined) {
+        return requireDirectory(resolve(context.cwd, fromEnv), WORKSPACE_ENV_VAR);
+    }
+    return findRootMarker(resolve(context.cwd)) ?? resolve(context.cwd);
+}
+/**
+ * An empty override was not supplied. Falling through to the next source is the
+ * only reading that keeps the precedence intact — treating `''` as an answer
+ * would let `{ root: '' }` skip `FRONTIER_ROOT` and silently read another repo.
+ */
+function given(value) {
+    return value === undefined || value === '' ? undefined : value;
+}
+/**
+ * Walk upward for the nearest directory carrying a marker. Falls back to the
+ * working directory itself, so a session started outside any repository still
+ * resolves rather than failing.
+ */
+function findRootMarker(from) {
+    let dir = from;
+    for (;;) {
+        if (ROOT_MARKERS.some(marker => isDirectory(join(dir, marker))))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function requireDirectory(path, source) {
+    if (!isDirectory(path)) {
+        throw new Error(`Workspace from ${source} is not a directory: ${path}`);
+    }
+    return path;
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,iFAAiF;AACjF,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,YAAY,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;AAQ1C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAwB,EAAE,OAAyB;IAClF,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,eAAe,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACtD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,KAAyB;IACtC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,GAAG,GAAG,IAAI,CAAC;IAEf,SAAS,CAAC;QACR,IAAI,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAE5E,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,SAAS,CAAC;QACrC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,MAAc;IACpD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,kBAAkB,MAAM,wBAAwB,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}