@frmwrkd/snag-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,1074 @@
+/**
+ * Talking to `snagd`, and reading `.snag/` when `snagd` is not there.
+ *
+ * ## Two sources, deliberately
+ *
+ * CLAUDE.md non-negotiable 3: **`.snag/` files are the API.** SQLite is a
+ * rebuildable index and MCP is "for actions and filtered queries, never bulk
+ * transfer". That cuts two ways here:
+ *
+ *  - **Reads prefer the daemon** (`GET /tasks`, `GET /plan`, `GET /map`),
+ *    because the SQLite index carries live status, and `.snag/plan.json` is a
+ *    snapshot whose `status` fields go stale the moment a task is claimed.
+ *  - **Reads fall back to `.snag/` on disk** when the daemon is unreachable, so
+ *    a developer with no daemon running still gets a queue instead of an error.
+ *    The fallback is labelled `source: 'files'` in every response — a stale
+ *    status the agent knows is stale is useful; one it thinks is live is not.
+ *  - **Writes require the daemon.** `snag_claim` and `snag_resolve` change
+ *    status, and status changes have to go through doc 02 §5.3's transition
+ *    table, the markdown writer and the event log all at once. Writing
+ *    `.snag/tasks/*.md` from here would race the daemon's file watcher and
+ *    desynchronise the index. When the daemon is down these tools fail with an
+ *    actionable error naming the exact command that fixes it.
+ *
+ * ## Port discovery
+ *
+ * doc 02 §7.3: the daemon binds the first free port in **7654–7664** and writes
+ * it to `.snag/.port`. **"Hard-coding 7654 anywhere will strand the user the
+ * first time anything else takes that port."** Unlike the extension, this
+ * process has a filesystem, so it reads `.snag/.port` first and only probes the
+ * range if that file is missing or points at a dead port.
+ *
+ * ## Which snagd
+ *
+ * One snagd per checkout, all sharing 7654–7664 and one token, so the first
+ * daemon to answer is not necessarily ours. `GET /health` reports the `root` it
+ * serves; a daemon for the same root is taken at once. A daemon for another
+ * root is still ours when both roots are checkouts of **one repository** — a
+ * `git worktree` next to the main checkout shares its git common dir — but only
+ * if no daemon for the exact root answered. Anything else is skipped, and
+ * remembered, so a write fails with "snagd on :7654 serves <that root>" rather
+ * than the misleading "snagd is not running".
+ *
+ * Before every write the cached handle's `/health` is asked again: a snagd that
+ * restarted may have left its port to another project's daemon, and a status
+ * change through that port would move someone else's task.
+ *
+ * ## Auth
+ *
+ * doc 02 §7.1: every route except `GET /health` requires the token from
+ * `~/.snag/token`, presented as `Authorization: Bearer <token>`.
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PlanSchema, RepoMapSchema, SnagConfigSchema, TaskSchema, defaultConfig, taskFileName, } from '@frmwrkd/snag-core';
+/* --------------------------------------------------------------- constants */
+export const DAEMON_HOST = '127.0.0.1';
+/** doc 02 §7.3 — the probe range, inclusive at both ends. */
+export const DAEMON_PORT_START = 7654;
+export const DAEMON_PORT_END = 7664;
+/** `.snag/` — the contract directory (doc 02 §6.1). */
+export const SNAG_DIR = '.snag';
+const DEFAULT_TIMEOUT_MS = 4_000;
+const PROBE_TIMEOUT_MS = 400;
+/**
+ * `git rev-parse` answers in tens of milliseconds. It runs only when a snagd
+ * serves a different root, and a hung git (a network drive, a credential
+ * prompt) must not hold up a tool call for longer than this.
+ */
+const GIT_TIMEOUT_MS = 1_500;
+/* ------------------------------------------------------------------ errors */
+/**
+ * The command that starts snagd, for whoever is running *this* build.
+ *
+ * `snagd` is not published, so `npx snagd` cannot start it today. Until it is, the MCP
+ * server runs from a Snag checkout (`scripts/install-claude-code.mjs`), and
+ * the daemon's build sits beside it at `apps/daemon/dist/cli.js` — so when that
+ * file exists, name it. `npx snagd` remains the answer for a published install.
+ */
+export function snagdCommand(moduleUrl = import.meta.url) {
+    try {
+        const cli = fileURLToPath(new URL('../../daemon/dist/cli.js', moduleUrl));
+        if (fs.existsSync(cli))
+            return `node "${cli.split(path.sep).join('/')}"`;
+    }
+    catch {
+        /* not a file: URL — fall through */
+    }
+    return 'npx snagd';
+}
+/**
+ * The daemon could not be reached at all. The message is written to be read by
+ * an agent: it names the command that fixes it and the files that work without
+ * it.
+ */
+export class DaemonUnavailableError extends Error {
+    root;
+    /** The underlying failure (`fetch failed`, a timeout), kept so it can be re-thrown against the project root. */
+    detail;
+    constructor(root, detail) {
+        super(`snagd is not running (probed http://${DAEMON_HOST}:${DAEMON_PORT_START}-${DAEMON_PORT_END} and ${path.join(root, SNAG_DIR, '.port')})` +
+            `${detail === undefined ? '' : `: ${detail}`}. ` +
+            `Start it with \`${snagdCommand()}\` in ${root}. ` +
+            `Until then the queue is still readable without me — Read/Grep ${SNAG_DIR}/tasks/*.md and ${SNAG_DIR}/plan.json.`);
+        this.name = 'DaemonUnavailableError';
+        this.root = root;
+        this.detail = detail;
+    }
+}
+/** A path as a shell argument: quoted when it has whitespace (`L:\Open Source\app`). */
+function shellPath(p) {
+    return /\s/.test(p) ? `"${p}"` : p;
+}
+/**
+ * A snagd answered — for a different checkout.
+ *
+ * Reported instead of "snagd is not running", which is false and sends the
+ * agent to start a second daemon that then fights the first for the port
+ * range. A subclass of `DaemonUnavailableError` because it means the same thing
+ * to every caller: there is no daemon *for this project* to write through.
+ */
+export class DaemonRootMismatchError extends DaemonUnavailableError {
+    /** The port the other daemon answered on, or `null` if the URL had none. */
+    port;
+    /** The root that daemon serves, exactly as its `/health` reported it. */
+    daemonRoot;
+    constructor(root, daemonRoot, baseUrl) {
+        super(root);
+        let port = null;
+        try {
+            const parsed = Number.parseInt(new URL(baseUrl).port, 10);
+            port = Number.isInteger(parsed) ? parsed : null;
+        }
+        catch {
+            /* not a URL — leave the port unnamed */
+        }
+        this.name = 'DaemonRootMismatchError';
+        this.port = port;
+        this.daemonRoot = daemonRoot;
+        this.message =
+            `snagd on :${port ?? '?'} serves ${daemonRoot}, not ${root} — ` +
+                `open Claude Code in ${daemonRoot}, or start snagd with --root ${shellPath(root)}`;
+    }
+}
+/** The daemon answered, and said no. `code` is its machine-readable error id. */
+export class DaemonRequestError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'DaemonRequestError';
+        this.status = status;
+        this.code = code;
+    }
+}
+const globalFetch = () => {
+    const f = globalThis.fetch;
+    if (typeof f !== 'function') {
+        throw new Error('global fetch is unavailable — @frmwrkd/snag-mcp requires Node 22+');
+    }
+    return f;
+};
+/* ------------------------------------------------------------- discovery */
+/**
+ * Whether two paths name the same directory.
+ *
+ * `path.resolve` on both, case-folded on win32 — NTFS is case-insensitive, and
+ * `git rev-parse --show-toplevel` (which is where snagd's `root` comes from)
+ * and `process.cwd()` do not agree on drive-letter case. The realpath
+ * comparison is the fallback for symlinked temp directories (macOS `/var` →
+ * `/private/var`) and 8.3 short names.
+ */
+export function samePath(a, b) {
+    const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+    if (fold(path.resolve(a)) === fold(path.resolve(b)))
+        return true;
+    try {
+        return fold(fs.realpathSync.native(a)) === fold(fs.realpathSync.native(b));
+    }
+    catch {
+        return false;
+    }
+}
+/** `git` from `PATH`, bounded by `GIT_TIMEOUT_MS`. Rejects when git is missing. */
+export const runGit = (args, cwd) => new Promise((resolve, reject) => {
+    execFile('git', [...args], { cwd, timeout: GIT_TIMEOUT_MS, windowsHide: true, encoding: 'utf8' }, (error, stdout) => (error === null ? resolve(stdout) : reject(error)));
+});
+/**
+ * `git rev-parse --git-common-dir`, resolved against `dir` and cached.
+ *
+ * The common dir is what a linked worktree shares with the checkout it was
+ * added from (`git worktree add`), so two roots with the same common dir are
+ * one repository and one queue. git prints it relative to the cwd in a main
+ * checkout (`.git`) and absolute in a linked worktree, hence the resolve.
+ * `--path-format=absolute` would save that, but needs git 2.31.
+ *
+ * Only answers are cached. A failure — git not installed, not a repository, a
+ * timeout — returns `null`, which only ever means "not proven to be the same
+ * repository", and is asked again next time: `git init` can happen mid-session.
+ */
+export function createGitCommonDirLookup(run = runGit) {
+    const cache = new Map();
+    return async (dir) => {
+        const resolved = path.resolve(dir);
+        const key = process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+        const hit = cache.get(key);
+        if (hit !== undefined)
+            return hit;
+        let out;
+        try {
+            out = (await run(['rev-parse', '--git-common-dir'], resolved)).trim();
+        }
+        catch {
+            return null;
+        }
+        if (out.length === 0)
+            return null;
+        const common = path.resolve(resolved, out);
+        cache.set(key, common);
+        return common;
+    };
+}
+/** The process-wide lookup, so the cache outlives any one discovery. */
+export const defaultGitCommonDir = createGitCommonDirLookup();
+/** Whether `a` and `b` are checkouts of one repository (same git common dir). */
+export async function sameRepository(a, b, lookup = defaultGitCommonDir) {
+    const [left, right] = await Promise.all([lookup(a), lookup(b)]);
+    return left !== null && right !== null && samePath(left, right);
+}
+function homeDir() {
+    try {
+        return os.homedir();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk up from `startDir` looking for a directory containing `.snag/`.
+ *
+ * Claude Code spawns a stdio MCP server with the project directory as its cwd,
+ * so this normally hits on the first try. Walking up covers the case where the
+ * server is spawned from a subdirectory of the repo.
+ *
+ * **`~/.snag` is not a project.** It is snagd's token directory (doc 02 §7.1),
+ * so every directory under the user's home has a `.snag/` somewhere above it.
+ * Without this skip, an MCP server started in an app that has never run snagd
+ * adopts the home directory as its root, and every read and write goes to the
+ * wrong place with no error at all.
+ */
+export function findProjectRoot(startDir = process.cwd(), home = homeDir()) {
+    let current = path.resolve(startDir);
+    for (;;) {
+        if (fs.existsSync(path.join(current, SNAG_DIR)) &&
+            (home === null || !samePath(current, home))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/** `~/.snag/token`, or `null` on first run before `snagd` has generated one. */
+export function readToken(home = os.homedir()) {
+    const file = path.join(home, SNAG_DIR, 'token');
+    try {
+        const contents = fs.readFileSync(file, 'utf8').trim();
+        return contents.length > 0 ? contents : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `.snag/.port` — the port `snagd` actually bound (doc 02 §7.3). */
+export function readPortFile(root) {
+    try {
+        const raw = fs.readFileSync(path.join(root, SNAG_DIR, '.port'), 'utf8').trim();
+        const port = Number.parseInt(raw, 10);
+        return Number.isInteger(port) && port > 0 && port < 65_536 ? port : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `.snag/` half of the contract. Pure reads — nothing here ever writes,
+ * because the daemon owns the directory and watches it.
+ */
+export class FileStore {
+    root;
+    constructor(root) {
+        this.root = path.resolve(root);
+    }
+    get dir() {
+        return path.join(this.root, SNAG_DIR);
+    }
+    /** Absolute path for a repo-relative path, or `null` if it escapes the root. */
+    resolveInsideRoot(relative) {
+        const absolute = path.resolve(this.root, relative);
+        const prefix = this.root.endsWith(path.sep) ? this.root : `${this.root}${path.sep}`;
+        return absolute === this.root || absolute.startsWith(prefix) ? absolute : null;
+    }
+    readJson(file) {
+        try {
+            return JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    /** `.snag/config.json`. Falls back to `defaultConfig()` — it is committed, but optional. */
+    readConfig() {
+        const parsed = SnagConfigSchema.safeParse(this.readJson(path.join(this.dir, 'config.json')));
+        return parsed.success ? parsed.data : defaultConfig();
+    }
+    /**
+     * `.snag/plan.json`, distinguishing "no plan yet" from "the plan is broken".
+     *
+     * Collapsing both to `null` is how 53 unreadable tasks came out of `snag_list`
+     * as "the queue is clear" — an agent was told there was no work when in fact
+     * the work could not be read. A file that exists and fails validation must
+     * never be reported as absence.
+     */
+    readPlanResult() {
+        const file = path.join(this.dir, 'plan.json');
+        if (!fs.existsSync(file))
+            return { state: 'missing' };
+        const raw = this.readJson(file);
+        if (raw === null) {
+            return { state: 'invalid', issues: ['plan.json is not readable as JSON'] };
+        }
+        const parsed = PlanSchema.safeParse(raw);
+        if (parsed.success)
+            return { state: 'ok', plan: parsed.data };
+        return {
+            state: 'invalid',
+            issues: parsed.error.issues.map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`),
+        };
+    }
+    /** `.snag/plan.json`, or `null` when there is no *usable* plan. */
+    readPlan() {
+        const result = this.readPlanResult();
+        return result.state === 'ok' ? result.plan : null;
+    }
+    /** `.snag/map.json`, or `null` when the repo map has not been built. */
+    readMap() {
+        const parsed = RepoMapSchema.safeParse(this.readJson(path.join(this.dir, 'map.json')));
+        return parsed.success ? parsed.data : null;
+    }
+    /**
+     * Tasks from `.snag/plan.json`. This is the offline fallback for
+     * `snag_list`/`snag_get`: `plan.tasks` is plain JSON validated by
+     * `TaskSchema`, so no YAML parser is needed to read the queue without the
+     * daemon. Statuses here are a snapshot and may lag the index.
+     */
+    tasks() {
+        const plan = this.readPlan();
+        if (plan === null)
+            return [];
+        return plan.tasks;
+    }
+    /**
+     * Why the offline task list is empty, when it is empty. `null` means it is
+     * not empty, or is legitimately so.
+     *
+     * `tasks()` has to keep returning `Task[]` — every caller expects an array —
+     * so the reason travels alongside it rather than inside it.
+     */
+    emptyTasksReason() {
+        const result = this.readPlanResult();
+        if (result.state === 'ok')
+            return null;
+        if (result.state === 'missing')
+            return null;
+        const shown = result.issues.slice(0, 8);
+        const more = result.issues.length - shown.length;
+        return (`.snag/plan.json exists but does not match @frmwrkd/snag-core's schema, so no tasks could be read ` +
+            `(${result.issues.length} problem(s)):\n` +
+            shown.map((issue) => `  - ${issue}`).join('\n') +
+            (more > 0 ? `\n  … and ${more} more` : '') +
+            '\nThis is a broken plan, not an empty queue. Regenerate it, or fix the file.');
+    }
+    /**
+     * The task's markdown file, repo-relative, or `null` if it is not on disk.
+     * The name is derived by `taskFileName` from `@frmwrkd/snag-core`, which is the same
+     * function the daemon's writer uses, so the two cannot drift.
+     */
+    taskMarkdownPath(task) {
+        const relative = path.posix.join(SNAG_DIR, 'tasks', taskFileName(task.id, task.title));
+        const absolute = this.resolveInsideRoot(relative);
+        if (absolute === null || !fs.existsSync(absolute))
+            return null;
+        return relative;
+    }
+    readTextFile(relative) {
+        const absolute = this.resolveInsideRoot(relative);
+        if (absolute === null)
+            return null;
+        try {
+            return fs.readFileSync(absolute, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+    readBytes(relative) {
+        const absolute = this.resolveInsideRoot(relative);
+        if (absolute === null)
+            return null;
+        try {
+            return fs.readFileSync(absolute);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export class DaemonClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    timeoutMs;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.token = options.token;
+        this.fetchImpl = options.fetchImpl ?? globalFetch();
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    headers() {
+        const headers = { accept: 'application/json' };
+        if (this.token !== null)
+            headers['authorization'] = `Bearer ${this.token}`;
+        return headers;
+    }
+    async raw(method, pathname, body, timeoutMs) {
+        const headers = this.headers();
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        return this.fetchImpl(`${this.baseUrl}${pathname}`, {
+            method,
+            headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            signal: AbortSignal.timeout(timeoutMs ?? this.timeoutMs),
+        });
+    }
+    /**
+     * A JSON request. Throws `DaemonRequestError` on a non-2xx, preserving the
+     * daemon's own `error` code and `message` — those messages are written to be
+     * actionable (`verify_only`, `illegal_transition`, …) and paraphrasing them
+     * would throw away the only explanation the agent gets.
+     */
+    async request(method, pathname, body) {
+        let response;
+        try {
+            response = await this.raw(method, pathname, body);
+        }
+        catch (error) {
+            throw new DaemonUnavailableError(this.baseUrl, error instanceof Error ? error.message : String(error));
+        }
+        const text = await response.text();
+        if (!response.ok) {
+            let code = `http_${response.status}`;
+            let message = text;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed.error === 'string')
+                    code = parsed.error;
+                if (typeof parsed.message === 'string')
+                    message = parsed.message;
+            }
+            catch {
+                /* leave the raw body as the message */
+            }
+            throw new DaemonRequestError(response.status, code, message);
+        }
+        return JSON.parse(text);
+    }
+    health() {
+        return this.request('GET', '/health');
+    }
+    async listTasks(query = {}) {
+        const search = new URLSearchParams();
+        if (query.status !== undefined)
+            search.set('status', query.status);
+        if (query.wave !== undefined)
+            search.set('wave', String(query.wave));
+        if (query.severity !== undefined)
+            search.set('severity', query.severity);
+        if (query.limit !== undefined)
+            search.set('limit', String(query.limit));
+        const suffix = search.size > 0 ? `?${search.toString()}` : '';
+        const body = await this.request('GET', `/tasks${suffix}`);
+        return parseTasks(body.tasks);
+    }
+    async getTask(id) {
+        try {
+            const body = await this.request('GET', `/tasks/${encodeURIComponent(id)}`);
+            const task = TaskSchema.parse(body.task);
+            return { task, file: typeof body.file === 'string' ? body.file : null };
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * `POST /git/commit` — snagd stages the named files and commits them.
+     *
+     * The daemon does it, not this server: it owns the project root and
+     * `.snag/config.json`'s `git` block, and one implementation means the rails
+     * (named paths only, never a push, never a protected branch) cannot differ
+     * between an MCP call and the commit at the end of a headless run.
+     */
+    async commit(body) {
+        return this.request('POST', '/git/commit', body);
+    }
+    async setStatus(id, status) {
+        const body = await this.request('PATCH', `/tasks/${encodeURIComponent(id)}`, {
+            status,
+            actor: 'agent',
+        });
+        return TaskSchema.parse(body.task);
+    }
+    async plan() {
+        try {
+            const body = await this.request('GET', '/plan');
+            return PlanSchema.parse(body.plan);
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+    async map() {
+        try {
+            const body = await this.request('GET', '/map');
+            return RepoMapSchema.parse(body.map);
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError && error.status === 404)
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * `POST /verify/:taskId` with `dry_run: true` — the daemon's preflight and
+     * nothing else. It starts no run and changes no status, so it can be asked
+     * *before* `snag_resolve` moves the task: a task that Verify can never judge
+     * must not be parked in `verifying`, where nothing will ever move it again.
+     *
+     * The refusals are the daemon's own, verbatim: 404 `not_found`, 409
+     * `verify_disabled`, 409 `no_capture_url`, 503 `verify_unavailable`.
+     */
+    async verifyPreflight(taskId) {
+        try {
+            await this.request('POST', `/verify/${encodeURIComponent(taskId)}`, {
+                dry_run: true,
+            });
+            return { ok: true };
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError) {
+                return { ok: false, status: error.status, code: error.code, message: error.message };
+            }
+            throw error;
+        }
+    }
+    /**
+     * `GET /verify/:taskId` — whether a run is in flight, and how the last one
+     * ended. The daemon keeps only the last report per task, in memory, so
+     * `last: null` after a snagd restart means "not since it started", not
+     * "never". `null` when the daemon has no such task, or no such route.
+     */
+    async verifyStatus(taskId) {
+        let body;
+        try {
+            body = await this.request('GET', `/verify/${encodeURIComponent(taskId)}`);
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError && error.status === 404)
+                return null;
+            throw error;
+        }
+        const last = typeof body.last === 'object' && body.last !== null
+            ? body.last
+            : null;
+        return {
+            running: body.running === true,
+            outcome: typeof last?.outcome === 'string' ? last.outcome : null,
+            reason: typeof last?.reason === 'string' ? last.reason : null,
+            last_at: typeof body.last_at === 'string' ? body.last_at : null,
+        };
+    }
+    /**
+     * `POST /verify/:taskId` (doc 02 §7.1 / §10). Returns a result rather than
+     * throwing when the daemon refuses: a task that reached `verifying` but could
+     * not queue a run is a partial success, and reporting it as a total failure
+     * would make the agent retry a transition that already happened.
+     *
+     * The daemon answers **202 `{ queued, task_uid, already_running }`** and runs
+     * the loop in the background — Verify drives a real Chrome tab, which takes
+     * far longer than this client's timeout, so waiting on it here would turn
+     * every resolve into a timeout. `wait: true` is never sent.
+     *
+     * **503 `verify_unavailable`** means no extension is attached. The daemon's
+     * message says exactly how to fix that, so it is passed through verbatim.
+     *
+     * `DaemonUnavailableError` propagates: the caller owns the connection cache
+     * and has to forget a daemon that stopped answering.
+     */
+    async queueVerify(taskId, body) {
+        let response;
+        try {
+            response = await this.request('POST', `/verify/${encodeURIComponent(taskId)}`, body);
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError) {
+                return {
+                    queued: false,
+                    code: error.code,
+                    detail: error.code === 'verify_unavailable'
+                        ? error.message
+                        : `snagd declined the verify run (${error.code}: ${error.message})`,
+                };
+            }
+            throw error;
+        }
+        if (response.queued === true) {
+            const alreadyRunning = response.already_running === true;
+            return {
+                queued: true,
+                already_running: alreadyRunning,
+                detail: alreadyRunning
+                    ? `A verify run for this task was already in progress, so no second one was started. ${VERIFY_QUEUED_DETAIL}`
+                    : VERIFY_QUEUED_DETAIL,
+            };
+        }
+        // A daemon that ran the loop synchronously (`200 { report }`). The run is
+        // already over, so the task's status has moved on from what we hold.
+        const outcome = response.report?.outcome;
+        return {
+            queued: true,
+            detail: typeof outcome === 'string'
+                ? `Verify already ran (outcome: ${outcome}); snag_get the task for its current status`
+                : VERIFY_QUEUED_DETAIL,
+        };
+    }
+}
+/**
+ * doc 02 §10 as it runs today. No pixel comparison happens yet, so this must
+ * not claim one: a capture with no console error gives Verify nothing to judge
+ * by, and the task goes to `needs_review` rather than to `resolved`.
+ */
+export const VERIFY_QUEUED_DETAIL = 'Verify runs in Chrome, not here: it re-opens the page, re-resolves the anchor and checks that the console errors the capture recorded are gone; a task it cannot judge goes to needs_review. ' +
+    'snag_get the task in ~30 s for the outcome';
+function parseTasks(value) {
+    if (!Array.isArray(value))
+        return [];
+    const tasks = [];
+    for (const entry of value) {
+        const parsed = TaskSchema.safeParse(entry);
+        if (parsed.success)
+            tasks.push(parsed.data);
+    }
+    return tasks;
+}
+/**
+ * The identity rule, shared by discovery and by the re-check before a write.
+ *
+ * `root` absent means a daemon too old to say; that is not evidence of a
+ * mismatch. A different root is accepted only when git says both are
+ * checkouts of one repository — see "Which snagd" above.
+ */
+export async function daemonIdentity(health, root, lookup = defaultGitCommonDir) {
+    if (health.name !== undefined && health.name !== 'snagd')
+        return { ok: false, reason: 'not_snagd' };
+    if (typeof health.root !== 'string' || samePath(health.root, root))
+        return { ok: true };
+    if (await sameRepository(health.root, root, lookup))
+        return { ok: true };
+    return { ok: false, reason: 'other_root', daemonRoot: health.root };
+}
+/**
+ * Find the daemon: `.snag/.port` first, then a bounded probe of 7654–7664.
+ *
+ * `GET /health` is unauthenticated by design (doc 02 §7.1) and reports
+ * `name: 'snagd'`, which is what tells us a stray service on 7655 is not the
+ * daemon — the appendix is explicit that the probe must be able to make that
+ * distinction.
+ *
+ * A daemon serving exactly this root wins outright. Failing that, the first
+ * daemon serving another worktree of the same repository is taken. Failing
+ * that, if any snagd answered for a different project this **throws**
+ * `DaemonRootMismatchError` naming it, and resolves `null` only when no snagd
+ * answered at all.
+ */
+export async function connectToDaemon(options) {
+    const token = options.token === undefined ? readToken() : options.token;
+    const fetchImpl = options.fetchImpl ?? globalFetch();
+    const lookup = options.gitCommonDir ?? defaultGitCommonDir;
+    const candidates = [];
+    if (options.baseUrl !== undefined) {
+        candidates.push(options.baseUrl);
+    }
+    else {
+        const fromFile = readPortFile(options.root);
+        if (fromFile !== null)
+            candidates.push(`http://${DAEMON_HOST}:${fromFile}`);
+        const range = options.portRange ?? { start: DAEMON_PORT_START, end: DAEMON_PORT_END };
+        for (let port = range.start; port <= range.end; port += 1) {
+            const url = `http://${DAEMON_HOST}:${port}`;
+            if (!candidates.includes(url))
+                candidates.push(url);
+        }
+    }
+    /** snagds serving some other root, in probe order: `git` is asked about them only if needed. */
+    const elsewhere = [];
+    for (const baseUrl of candidates) {
+        const client = new DaemonClient({
+            baseUrl,
+            token,
+            fetchImpl,
+            timeoutMs: PROBE_TIMEOUT_MS,
+        });
+        let health;
+        try {
+            health = await client.health();
+        }
+        catch {
+            continue;
+        }
+        if (health.name !== undefined && health.name !== 'snagd')
+            continue;
+        // One snagd per project, all sharing 7654–7664 and one token. A daemon
+        // serving a different repo answers every route correctly — for the wrong
+        // queue — so a claim here would move someone else's task.
+        if (typeof health.root === 'string' && !samePath(health.root, options.root)) {
+            elsewhere.push({ baseUrl, daemonRoot: health.root });
+            continue;
+        }
+        return new DaemonClient({ baseUrl, token, fetchImpl });
+    }
+    // No daemon for this exact root. A worktree's daemon is the next best —
+    // the same repository, the same queue — but never ahead of an exact match,
+    // or two worktrees each running their own snagd would share one.
+    for (const { baseUrl, daemonRoot } of elsewhere) {
+        if (await sameRepository(daemonRoot, options.root, lookup)) {
+            return new DaemonClient({ baseUrl, token, fetchImpl });
+        }
+    }
+    const first = elsewhere[0];
+    if (first !== undefined) {
+        throw new DaemonRootMismatchError(path.resolve(options.root), first.daemonRoot, first.baseUrl);
+    }
+    return null;
+}
+/**
+ * The real backend: daemon when it answers, `.snag/` when it does not.
+ *
+ * The daemon handle is resolved once, lazily, and re-resolved after a failure
+ * so a daemon started mid-session is picked up without restarting the MCP
+ * server (Claude Code keeps a stdio server alive for the whole session).
+ */
+/**
+ * How long a failed discovery is remembered before probing again.
+ *
+ * Without this, every tool call in a burst re-probes all eleven ports. The
+ * probe is cheap on a healthy machine (a closed loopback port refuses
+ * immediately) but not free, and a black-holed port costs the full timeout
+ * each time. Two seconds is long enough to cover one agent turn and short
+ * enough that a daemon started mid-session is picked up almost at once —
+ * Claude Code keeps a stdio server alive for the whole session, so
+ * "restart the MCP server" must never be the fix for "I started snagd".
+ */
+export const DAEMON_RETRY_AFTER_MS = 2_000;
+export class SnagClient {
+    root;
+    files;
+    connect;
+    daemonPromise = null;
+    /** The handle `daemonPromise` last resolved to, so a stale failure can be told apart. */
+    connected = null;
+    /**
+     * `-Infinity`, not `0`: "no failure yet" must never look like "failed at time
+     * zero", or the very first call is swallowed by the backoff window.
+     */
+    lastFailureAt = Number.NEGATIVE_INFINITY;
+    cachedConfig = null;
+    now;
+    gitCommonDir;
+    /**
+     * The snagd the last discovery skipped because it serves another project.
+     * Kept through the backoff window, so every write in it can say where the
+     * daemon actually is instead of claiming there is none.
+     */
+    mismatch = null;
+    constructor(root, connect, now = Date.now, gitCommonDir = defaultGitCommonDir) {
+        this.root = path.resolve(root);
+        this.files = new FileStore(this.root);
+        this.gitCommonDir = gitCommonDir;
+        this.connect = connect ?? (() => connectToDaemon({ root: this.root, gitCommonDir }));
+        this.now = now;
+    }
+    /** `null` when the daemon is unreachable. Never throws. */
+    async daemon() {
+        if (this.daemonPromise === null) {
+            if (this.now() - this.lastFailureAt < DAEMON_RETRY_AFTER_MS)
+                return null;
+            this.daemonPromise = this.connect().then((client) => {
+                this.mismatch = null;
+                return client;
+            }, (error) => {
+                this.mismatch = error instanceof DaemonRootMismatchError ? error : null;
+                return null;
+            });
+        }
+        const client = await this.daemonPromise;
+        if (client === null)
+            this.forgetDaemon(null);
+        else
+            this.connected = client;
+        return client;
+    }
+    /**
+     * Drop the cached handle after the daemon stopped answering.
+     *
+     * A handle that resolved once used to be kept for the life of the MCP
+     * server, so a snagd that was stopped and restarted — which picks the first
+     * free port and may not get the old one back — was never found again: every
+     * call went to the dead port and fell back to files. Forgetting it makes the
+     * next call re-probe, after the same backoff window a failed probe gets.
+     *
+     * `stale` is the handle that failed. Claude Code can run tool calls in
+     * parallel, so a failure on a handle another call has already replaced must
+     * not throw away the replacement.
+     *
+     * `backoff: false` is for a handle that answered but is no longer ours: the
+     * port is alive, so waiting out the window would only delay finding where
+     * our snagd went. The next call re-probes at once.
+     */
+    forgetDaemon(stale, { backoff = true } = {}) {
+        if (stale !== null && this.connected !== stale)
+            return;
+        this.connected = null;
+        this.daemonPromise = null;
+        this.lastFailureAt = backoff ? this.now() : Number.NEGATIVE_INFINITY;
+    }
+    /**
+     * The daemon, or a thrown `DaemonUnavailableError` — the root-mismatch
+     * subclass when the only snagd that answered serves another project.
+     */
+    async requireDaemon() {
+        const client = await this.daemon();
+        if (client === null)
+            throw this.mismatch ?? new DaemonUnavailableError(this.root);
+        return client;
+    }
+    /**
+     * The daemon for a write, with its identity asked again first.
+     *
+     * The handle is cached for the life of the MCP server, and a snagd that
+     * restarted binds the first free port — which another project's snagd may
+     * since have taken. That daemon answers `PATCH /tasks/SNAG-3` perfectly well,
+     * for its own SNAG-3. Reads tolerate the risk (they are labelled and cheap to
+     * repeat); a status change does not, so `/health` is asked before every one,
+     * and a handle that now answers for another root is dropped and discovery
+     * runs again on the spot.
+     */
+    async writableDaemon() {
+        const client = await this.requireDaemon();
+        let identity;
+        try {
+            identity = await daemonIdentity(await client.health(), this.root, this.gitCommonDir);
+        }
+        catch (error) {
+            if (error instanceof DaemonUnavailableError)
+                throw this.unavailable(client, error);
+            if (!(error instanceof DaemonRequestError))
+                throw error;
+            // `/health` is unauthenticated on every snagd; a non-2xx is not one.
+            identity = { ok: false, reason: 'not_snagd' };
+        }
+        if (identity.ok)
+            return client;
+        this.forgetDaemon(client, { backoff: false });
+        return this.requireDaemon();
+    }
+    /**
+     * Forget the daemon if `error` says it is gone, and return the error to throw.
+     * The request-level error names the base URL where the project root belongs,
+     * so it is rebuilt against the root — its message tells the agent where to
+     * start snagd.
+     */
+    unavailable(client, error) {
+        this.forgetDaemon(client);
+        return new DaemonUnavailableError(this.root, error.detail);
+    }
+    config() {
+        this.cachedConfig ??= this.files.readConfig();
+        return this.cachedConfig;
+    }
+    async listTasks(query) {
+        const client = await this.daemon();
+        if (client !== null) {
+            try {
+                const daemonQuery = {};
+                if (query.status !== undefined)
+                    daemonQuery.status = query.status;
+                if (query.wave !== undefined)
+                    daemonQuery.wave = query.wave;
+                if (query.limit !== undefined)
+                    daemonQuery.limit = query.limit;
+                return { tasks: await client.listTasks(daemonQuery), source: 'daemon' };
+            }
+            catch (error) {
+                if (!(error instanceof DaemonUnavailableError))
+                    throw error;
+                this.forgetDaemon(client);
+            }
+        }
+        let tasks = this.files.tasks();
+        if (query.status !== undefined)
+            tasks = tasks.filter((t) => t.status === query.status);
+        if (query.wave !== undefined)
+            tasks = tasks.filter((t) => t.wave === query.wave);
+        tasks = [...tasks].sort((a, b) => a.wave - b.wave || a.order - b.order);
+        if (query.limit !== undefined)
+            tasks = tasks.slice(0, query.limit);
+        return { tasks, source: 'files' };
+    }
+    async getTask(id) {
+        const client = await this.daemon();
+        if (client !== null) {
+            try {
+                const found = await client.getTask(id);
+                if (found === null)
+                    return null;
+                return {
+                    task: found.task,
+                    file: found.file ?? this.files.taskMarkdownPath(found.task),
+                    source: 'daemon',
+                };
+            }
+            catch (error) {
+                if (!(error instanceof DaemonUnavailableError))
+                    throw error;
+                this.forgetDaemon(client);
+            }
+        }
+        const task = this.files.tasks().find((t) => t.uid === id || t.id === id);
+        if (task === undefined)
+            return null;
+        return { task, file: this.files.taskMarkdownPath(task), source: 'files' };
+    }
+    async commit(body) {
+        const client = await this.writableDaemon();
+        try {
+            return await client.commit(body);
+        }
+        catch (error) {
+            if (error instanceof DaemonUnavailableError)
+                throw this.unavailable(client, error);
+            throw error;
+        }
+    }
+    async setStatus(id, status) {
+        const client = await this.writableDaemon();
+        try {
+            return await client.setStatus(id, status);
+        }
+        catch (error) {
+            if (error instanceof DaemonUnavailableError)
+                throw this.unavailable(client, error);
+            throw error;
+        }
+    }
+    async verifyPreflight(taskId) {
+        const client = await this.writableDaemon();
+        try {
+            return await client.verifyPreflight(taskId);
+        }
+        catch (error) {
+            if (error instanceof DaemonUnavailableError)
+                throw this.unavailable(client, error);
+            throw error;
+        }
+    }
+    async verifyStatus(taskId) {
+        const client = await this.daemon();
+        if (client === null)
+            return null;
+        try {
+            return await client.verifyStatus(taskId);
+        }
+        catch (error) {
+            if (error instanceof DaemonUnavailableError)
+                this.forgetDaemon(client);
+            // A verify summary is garnish on snag_get; its absence must not fail the read.
+            return null;
+        }
+    }
+    async queueVerify(taskId, body) {
+        let client;
+        try {
+            client = await this.writableDaemon();
+        }
+        catch (error) {
+            if (!(error instanceof DaemonUnavailableError))
+                throw error;
+            return {
+                queued: false,
+                detail: error instanceof DaemonRootMismatchError
+                    ? `no verify run was queued: ${error.message}`
+                    : 'snagd is not running, so no verify run was queued',
+            };
+        }
+        try {
+            return await client.queueVerify(taskId, body);
+        }
+        catch (error) {
+            if (!(error instanceof DaemonUnavailableError))
+                throw error;
+            this.forgetDaemon(client);
+            return { queued: false, detail: 'snagd went away before the verify run was queued' };
+        }
+    }
+    async plan() {
+        const client = await this.daemon();
+        if (client !== null) {
+            try {
+                return { plan: await client.plan(), source: 'daemon' };
+            }
+            catch (error) {
+                if (!(error instanceof DaemonUnavailableError))
+                    throw error;
+                this.forgetDaemon(client);
+            }
+        }
+        return { plan: this.files.readPlan(), source: 'files' };
+    }
+    async map() {
+        const client = await this.daemon();
+        if (client !== null) {
+            try {
+                return { map: await client.map(), source: 'daemon' };
+            }
+            catch (error) {
+                if (!(error instanceof DaemonUnavailableError))
+                    throw error;
+                this.forgetDaemon(client);
+            }
+        }
+        return { map: this.files.readMap(), source: 'files' };
+    }
+    async health() {
+        const client = await this.daemon();
+        if (client === null)
+            return null;
+        try {
+            return await client.health();
+        }
+        catch (error) {
+            if (error instanceof DaemonUnavailableError)
+                this.forgetDaemon(client);
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map