@50arms/platform-mcp 0.0.0-stage → 0.1.437

package/dist/session-access.js

@@ -0,0 +1,322 @@
+/**
+ * DX-4390 (PLAN-17 section 96) - how this server gets, holds and loses its dashboard credential.
+ *
+ * Three states, none of them a process exit:
+ *
+ *   - `env`         a dispatch declared `DANX_DASHBOARD_CREDENTIAL`; this never signs out.
+ *   - `session-key` a user approved this session's access request; the key is stored per session
+ *                   (`session-key.ts`) and a 401 on it deletes the file (`dropKey`).
+ *   - signed out    no credential. Every tool but `plan_connect` halts; `plan_connect` asks.
+ *
+ * DX-4418: a fourth state, REVOKED, ends all three for good. The dashboard answers `401 key_revoked` to a key a person revoked
+ * (as opposed to one that lapsed); this object then remembers it for the life of the process, every dashboard tool (and
+ * `plan_connect`) returns the one stop halt (`key-revoked-halt.ts`), and no new access request is made. A session's key file is
+ * deleted; a dispatch's credential is left to its dispatch, but the halt is the same.
+ *
+ * ASKING NEVER BLOCKS FOR MINUTES. The first signed-out `plan_connect` posts the request and
+ * answers at once with the approval URL and confirm code. From then on THIS object polls claim in
+ * the background, so the key is stored the moment the user approves, and the next `plan_connect`
+ * waits at most `awaitMs` (about 45s) for it before answering `approval_pending`. The secret the
+ * poll needs lives only in this process's memory; a restarted session asks again.
+ *
+ * DX-4530: a request has no deadline. It stays open for as long as this process keeps polling it, so it waits for a person
+ * however long they take, and it expires once the session ends (its polls stop). A poll that cannot reach the dashboard is
+ * retried; the dashboard answers `expired` if they stopped arriving for longer than its requester-gone window.
+ */
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import { claimAccessRequest, createAccessRequest } from "./access-request.js";
+import { credentialFingerprint } from "./credential.js";
+import { keyRevocationOf, keyRevokedHalt } from "./key-revoked-halt.js";
+import { deleteSessionKey, writeSessionKey } from "./session-key.js";
+import { McpOutdatedError } from "./version-floor.js";
+/** Longest a `plan_connect` call waits for an approval already asked for. */
+export const AWAIT_APPROVAL_MS = 45_000;
+/** A live server rewrites its key file this often, so an in-use key never ages out of the 7-day prune. */
+const KEEP_KEY_FILE_EVERY_MS = 60 * 60 * 1000;
+/** DX-5882: longest dashboard answer body copied into a drop's log line. */
+const REFUSAL_LOG_LIMIT = 300;
+/** The request's title when the agent gave none: the session id's first characters. */
+const TITLE_FALLBACK_LENGTH = 8;
+export const SIGN_IN_HALT = "Not signed in to the 50 Arms dashboard. Call `plan_connect` (with `plan_id`) to request access; the user approves it in their browser, then this tool works.";
+/** DX-4418: the session's key lapsed (a day unused) or the dashboard does not know it; a PERSON's revoke is `keyRevokedHalt` instead. */
+export const KEY_LAPSED_HALT = "The dashboard no longer accepts this session's key (it lapsed after a day unused), so this session is signed out. " +
+    SIGN_IN_HALT;
+const APPROVAL_REQUIRED_INSTRUCTION = "Show the user the confirm code and open the approval URL in their browser; they check the code " +
+    "matches and approve. Then call `plan_connect` again: it waits up to about 45 seconds for the approval. " +
+    "The request stays open until this session ends, however long the user takes.";
+const APPROVAL_PENDING_INSTRUCTION = "Still waiting for the user to approve; the request stays open until this session ends. Remind them of the " +
+    "confirm code and the URL, then call `plan_connect` again.";
+const DENIED_INSTRUCTION = "The user denied the request. Do not retry unless they ask; a new `plan_connect` makes a new request.";
+const DASHBOARD_OUTDATED_ERROR = "this dashboard does not support request-and-approve yet (POST /api/access-requests answered 404): " +
+    "it must be updated before this session can sign in";
+const RATE_LIMITED_ERROR = "too many access requests from this address; wait, then call plan_connect again";
+const unknownTeamError = (team) => `the dashboard has no team "${team}" (DANXBOT_TEAM); fix DANXBOT_TEAM in this server's env (your shell, or a repo's committed .claude/settings.json env block) and restart the session`;
+const NO_SESSION_ID_ERROR = "this server has no CLAUDE_CODE_SESSION_ID, so it cannot request a session key";
+const CLAIMED_LOST_ERROR = "the dashboard says this request was already claimed, but this process never received the key; " +
+    "start a new request";
+const EXPIRED_NOTE = "The previous request expired before it was approved: the dashboard stopped hearing from this session. This is a new " +
+    "request: show the user its new confirm code and URL.";
+export const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+});
+const notReady = (answer, isError, halt) => ({
+    signedIn: false,
+    answer,
+    isError,
+    ...(halt === undefined ? {} : { halt }),
+});
+export class SessionAccess {
+    deps;
+    credential;
+    // DX-4418: set once the dashboard says a person revoked the key; never cleared (a restarted server is a new process).
+    revoked = null;
+    pending = null;
+    // DX-4390: two concurrent signed-out plan_connect calls must not each post a request.
+    ensureQueue = Promise.resolve();
+    lastKeyFileWrite = 0;
+    // DX-5882: why this server holds no credential (null while it holds one); logged with every "Not signed in" halt.
+    signedOutCause = null;
+    fetchImpl;
+    now;
+    sleep;
+    awaitMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.credential = deps.initial;
+        this.fetchImpl = deps.fetch ?? fetch;
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.awaitMs = deps.awaitMs ?? AWAIT_APPROVAL_MS;
+        deps.setToken(deps.initial?.token ?? "");
+        if (deps.initial === null) {
+            this.signedOutCause = `booted with no credential: no DANX_DASHBOARD_CREDENTIAL, no stored key for session ${deps.sessionId ?? "(none: CLAUDE_CODE_SESSION_ID is unset)"}`;
+            deps.log?.(`[platform-mcp] signed out: ${this.signedOutCause}`);
+        }
+    }
+    isSignedIn() {
+        return this.credential !== null && this.revoked === null;
+    }
+    /** DX-4523: the key this session holds now, or "" when it holds none (the permission stream opens with it). */
+    currentToken() {
+        return this.credential === null || this.revoked !== null ? "" : this.credential.token;
+    }
+    /** DX-4418: the stop halt once a person revoked the key, else null. */
+    revokedHalt() {
+        return this.revoked === null ? null : keyRevokedHalt(this.revoked.revocation, this.revoked.dispatched);
+    }
+    /**
+     * DX-4418: a dashboard answer that says a person revoked the key behind it: remembered for good (a session's key file is
+     * deleted, a dispatch's credential is left to its dispatch) and answered as the stop halt. Null for every other answer.
+     */
+    refusalHalt(result) {
+        const revocation = keyRevocationOf(result);
+        if (revocation === null)
+            return null;
+        this.revoked ??= { revocation, dispatched: this.credential?.source.kind === "env" };
+        this.dropKey(result);
+        return this.revokedHalt();
+    }
+    /** Where the current credential comes from and its fingerprint, for the relay's connection record. */
+    connection() {
+        if (this.credential === null || this.revoked !== null)
+            return null;
+        return {
+            dashboardUrl: this.deps.dashboardUrl.replace(/\/+$/, ""),
+            source: this.credential.source,
+            fingerprint: this.credential.fingerprint,
+        };
+    }
+    /**
+     * The dashboard answered 401 to this session's key: drop it. A dispatch credential is never
+     * dropped (the dispatch owns it). True when this signed the session out. DX-5882: `refusal` is the dashboard answer that
+     * caused it; one stderr line names the key's fingerprint, its file and that answer, and later halts repeat it.
+     */
+    dropKey(refusal) {
+        if (this.credential === null || this.credential.source.kind !== "session-key")
+            return false;
+        const { fingerprint, source } = this.credential;
+        this.signedOutCause = `dropped the session key ${fingerprint} (${source.path}): the dashboard answered ${refusal.status} ${JSON.stringify(refusal.body).slice(0, REFUSAL_LOG_LIMIT)}`;
+        this.deps.log?.(`[platform-mcp] ${this.signedOutCause}`);
+        deleteSessionKey(source.path);
+        this.credential = null;
+        this.pending = null; // DX-4390: a settled request of the dropped key must not read as "expired"
+        this.deps.setToken("");
+        return true;
+    }
+    /**
+     * Run a dashboard call for a tool: halted while signed out, and signed out (key file deleted)
+     * when the dashboard answers 401 to this session's key.
+     */
+    async guard(run) {
+        const revokedHalt = this.revokedHalt();
+        if (revokedHalt !== null)
+            return { halt: revokedHalt };
+        if (this.credential === null) {
+            this.deps.log?.(`[platform-mcp] halted a dashboard tool call with "Not signed in": ${this.signedOutCause}`);
+            return { halt: SIGN_IN_HALT };
+        }
+        const result = await run();
+        const refused = this.refusalHalt(result);
+        if (refused !== null)
+            return { halt: refused };
+        if (result.status === 401 && this.dropKey(result))
+            return { halt: KEY_LAPSED_HALT };
+        this.keepKeyFile();
+        return { result };
+    }
+    /**
+     * DX-4390: the stored file is the relay's only way to the key, and the 7-day prune ages out
+     * a file by when it was last written. A server in use rewrites it (atomically) at most hourly,
+     * which also restores a file someone deleted while this process still holds the key.
+     */
+    keepKeyFile() {
+        const credential = this.credential;
+        if (credential === null || credential.source.kind !== "session-key")
+            return;
+        const now = this.now();
+        if (now - this.lastKeyFileWrite < KEEP_KEY_FILE_EVERY_MS && existsSync(credential.source.path))
+            return;
+        try {
+            writeSessionKey({ dashboardUrl: this.deps.dashboardUrl, sessionId: this.deps.sessionId, apiKey: credential.token }, { home: this.deps.home, now });
+            this.lastKeyFileWrite = now;
+        }
+        catch (err) {
+            this.deps.log?.(`[platform-mcp] could not refresh the session key file: ${err.message}`);
+        }
+    }
+    /**
+     * Make sure this session holds a key. Signed in: `{signedIn: true}`. Otherwise the answer
+     * `plan_connect` returns: the request just made, the one still pending (after waiting up to
+     * `awaitMs` for it), or why there is none. Calls run one at a time.
+     */
+    ensureAccess(title) {
+        const run = this.ensureQueue.then(() => this.ensureAccessNow(title));
+        this.ensureQueue = run.catch(() => undefined);
+        return run;
+    }
+    async ensureAccessNow(title) {
+        // DX-4418: a person revoked this session's access; it never asks again.
+        const revokedHalt = this.revokedHalt();
+        if (revokedHalt !== null)
+            return notReady({ state: "access_revoked", instruction: revokedHalt }, true, revokedHalt);
+        if (this.credential !== null)
+            return { signedIn: true };
+        const sessionId = this.deps.sessionId;
+        if (sessionId === undefined || sessionId === "") {
+            return notReady({ state: "no_session_id", error: NO_SESSION_ID_ERROR }, true);
+        }
+        let note;
+        if (this.pending !== null) {
+            const pending = this.pending;
+            const outcome = await Promise.race([pending.settled, this.sleep(this.awaitMs).then(() => null)]);
+            if (outcome === null)
+                return notReady(this.requestAnswer("approval_pending", pending.request), false);
+            this.pending = null;
+            switch (outcome.kind) {
+                case "approved":
+                    return { signedIn: true };
+                case "denied":
+                    return notReady({ state: "denied", instruction: DENIED_INSTRUCTION }, false);
+                case "failed":
+                    return notReady({ state: "request_failed", error: outcome.error }, true);
+                case "expired":
+                    note = EXPIRED_NOTE;
+            }
+        }
+        return this.createRequest(sessionId, title, note);
+    }
+    async createRequest(sessionId, title, note) {
+        const created = await createAccessRequest(this.fetchImpl, this.deps.dashboardUrl, {
+            kind: "session",
+            labelId: sessionId,
+            title: title ?? sessionId.slice(0, TITLE_FALLBACK_LENGTH),
+            machine: this.deps.machine ?? hostname(),
+            clientVersion: this.deps.clientVersion,
+            ...(this.deps.team === undefined ? {} : { team: this.deps.team }),
+        });
+        switch (created.kind) {
+            case "dashboard_outdated":
+                return notReady({ state: "dashboard_outdated", error: DASHBOARD_OUTDATED_ERROR }, true);
+            case "unknown_team":
+                return notReady({ state: "unknown_team", team: created.team, error: unknownTeamError(created.team) }, true);
+            case "rate_limited":
+                return notReady({ state: "rate_limited", retryAfterSeconds: created.retryAfterSeconds, error: RATE_LIMITED_ERROR }, true);
+            case "refused":
+                return notReady({ state: "request_refused", status: created.status, body: created.body }, true);
+            case "created":
+                this.pending = { request: created.request, settled: this.pollUntilSettled(created.request) };
+                return notReady({ ...this.requestAnswer("approval_required", created.request), ...(note ? { note } : {}) }, false);
+        }
+    }
+    requestAnswer(state, request) {
+        return {
+            state,
+            approvalUrl: request.approvalUrl,
+            confirmCode: request.confirmCode,
+            instruction: state === "approval_required" ? APPROVAL_REQUIRED_INSTRUCTION : APPROVAL_PENDING_INSTRUCTION,
+        };
+    }
+    // DX-4530: no give-up time - the polls are what keep the request open, until the dashboard answers how it ended.
+    async pollUntilSettled(request) {
+        let waitMs = request.pollMs;
+        for (;;) {
+            await this.sleep(waitMs);
+            waitMs = request.pollMs;
+            let claim;
+            try {
+                claim = await claimAccessRequest(this.fetchImpl, this.deps.dashboardUrl, request.secret);
+            }
+            catch (err) {
+                // A claim the dashboard could not answer is retried until it answers how the request ended; an outdated
+                // MCP will never get a different answer, so that one ends it.
+                if (err instanceof McpOutdatedError)
+                    return { kind: "failed", error: err.message };
+                this.deps.log?.(`[platform-mcp] access request poll failed, retrying: ${err.message}`);
+                continue;
+            }
+            switch (claim.kind) {
+                case "pending":
+                    continue;
+                case "rate_limited":
+                    waitMs = Math.max(request.pollMs, claim.retryAfterSeconds * 1000);
+                    continue;
+                case "approved":
+                    return this.storeKey(claim.apiKey);
+                case "denied":
+                    return { kind: "denied" };
+                case "expired":
+                case "not_found":
+                    return { kind: "expired" };
+                case "claimed":
+                    return { kind: "failed", error: CLAIMED_LOST_ERROR };
+                case "refused":
+                    return {
+                        kind: "failed",
+                        error: `the dashboard refused the claim (${claim.status}): ${JSON.stringify(claim.body)}`,
+                    };
+            }
+        }
+    }
+    storeKey(apiKey) {
+        const now = this.now();
+        try {
+            const path = writeSessionKey({ dashboardUrl: this.deps.dashboardUrl, sessionId: this.deps.sessionId, apiKey }, { home: this.deps.home, now });
+            this.credential = {
+                source: { kind: "session-key", path },
+                token: apiKey,
+                fingerprint: credentialFingerprint(apiKey),
+            };
+            this.lastKeyFileWrite = now;
+            this.signedOutCause = null;
+            this.deps.setToken(apiKey);
+            return { kind: "approved" };
+        }
+        catch (err) {
+            return {
+                kind: "failed",
+                error: `the request was approved but storing the key failed: ${err.message}; start a new request`,
+            };
+        }
+    }
+}

package/dist/session-connection.js

@@ -0,0 +1,264 @@
+/**
+ * DX-2862 — the record that hands ONE Claude Code session's dashboard
+ * connection from its MCP server to its other readers (`restart_notice`, the listener reminder).
+ *
+ * THE PROBLEM THIS SOLVES. A reader outside the server process runs in the SESSION's environment, not in the MCP server's, which is the only
+ * place the server's `.mcp.json` env block exists. So it cannot see what the server was configured with, and before this it
+ * simply used its own ambient env credential. When that was a different credential from the server's, its report was
+ * dropped silently (the card's incident). The plan event relay (`plan_events_wait`) needs none of this: it runs inside the
+ * server, with the server's own credential. The listener reminder reads this record too.
+ *
+ * WHAT IS WRITTEN, AND WHAT IS NOT. On a successful `plan_connect` the server
+ * writes the dashboard URL, the credential SOURCE (a session key file path, or the name of
+ * an env var — never a credential) and the credential's FINGERPRINT. A reader
+ * (`restart_notice`) reads that record, resolves the SAME source through the same resolver
+ * (`credential.ts`), and refuses to run unless what it resolved fingerprints
+ * identically. A rotated file or a session environment that disagrees with the
+ * server's therefore fails loud instead of reporting as somebody else.
+ *
+ * WHY `plan_connect` AND NOTHING ELSE WRITES IT. A session can have several
+ * dashboard MCP servers configured (gpt-manager has a deployed one and a local
+ * one). The server that CONNECTED the session to a plan is, by construction,
+ * the one whose credential owns that session's stream — so the connect is the
+ * only moment at which the right server is identifiable. Writing at boot would
+ * be a race between servers over the same file.
+ *
+ * The record is per session, tiny, and pruned after `STALE_RECORD_MS` — the
+ * dashboard keeps only a week of events, so an older session cannot resume
+ * anything anyway.
+ */
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { writeFileDurable } from "./durable-write.js";
+import { homedir } from "node:os";
+import { join, resolve, win32 } from "node:path";
+/** One canonical shape (CLAUDE.md Core Principle 1) — a record of any other version is refused, never adapted. */
+// DX-3928 — v2 adds `projectKey`, the directory the connecting session ran in, so a
+// restarted session (a NEW session id, no record of its own) can find which plan the
+// previous session of the same project was on (`findPredecessorCandidates`).
+export const SESSION_CONNECTION_SCHEMA_VERSION = 3;
+// DX-4390 — v3: the credential source is `session-key` (an approved per-session key file) or `env`;
+// the v2 `file` source (a hand-placed token file) no longer exists.
+export const STALE_RECORD_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * DX-3928 — the one definition of "the same project": the resolved working
+ * directory, normalised so the SAME directory reached two ways compares equal.
+ * A Windows path is written with forward slashes and a lower-case drive letter
+ * (`C:\Work\p` and `c:/Work/p` are one key), because the MCP server and the
+ * plugin's hook can each report the cwd in either spelling.
+ */
+export function projectKeyOf(cwd) {
+    if (!/^[A-Za-z]:[\\/]/.test(cwd))
+        return resolve(cwd);
+    const resolved = win32.resolve(cwd).replace(/\\/g, "/");
+    return resolved[0].toLowerCase() + resolved.slice(1);
+}
+export function sessionConnectionDir(home = homedir()) {
+    return join(home, ".config", "danxbot", "plan-sessions");
+}
+/**
+ * A session id is a path segment (here and in `session-key.ts`), so an odd one is refused rather than
+ * turned into a path.
+ */
+export function assertSessionIdSegment(sessionId) {
+    if (typeof sessionId !== "string" || !/^[A-Za-z0-9_-]+$/.test(sessionId)) {
+        throw new Error(`session id is missing or has unexpected characters: ${JSON.stringify(sessionId)}`);
+    }
+}
+export function sessionConnectionPath(sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
+    return join(sessionConnectionDir(home), `${sessionId}.json`);
+}
+/**
+ * Remove the per-session `.json` files in `dir` that nothing has touched for `STALE_RECORD_MS`, and the `.tmp` files a failed
+ * write-then-rename left beside them (DX-4993).
+ */
+export function pruneStaleSessionFiles(dir, now) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return; // nothing written yet
+    }
+    for (const name of names) {
+        if (!name.endsWith(".json") && !name.endsWith(".tmp"))
+            continue;
+        const file = join(dir, name);
+        try {
+            if (now - statSync(file).mtimeMs > STALE_RECORD_MS)
+                rmSync(file, { force: true });
+        }
+        catch {
+            /* removed by another process */
+        }
+    }
+}
+/**
+ * Record this session's connection. Write-then-rename, so a reader
+ * concurrently sees the old record or the new one, never a torn one.
+ */
+export function writeSessionConnection(record, options = {}) {
+    const home = options.home ?? homedir();
+    const now = options.now ?? Date.now();
+    const file = sessionConnectionPath(record.sessionId, home);
+    const dir = sessionConnectionDir(home);
+    mkdirSync(dir, { recursive: true });
+    pruneStaleSessionFiles(dir, now);
+    const full = {
+        schemaVersion: SESSION_CONNECTION_SCHEMA_VERSION,
+        ...record,
+        connectedAt: new Date(now).toISOString(),
+    };
+    writeFileDurable(file, JSON.stringify(full), { mode: 0o600 });
+    return full;
+}
+/**
+ * This session's record, or `null` when there is none (the session has never
+ * connected a plan from a server new enough to record one). A record that IS
+ * there but unreadable or of another shape throws — a connection we cannot
+ * understand is not the same thing as no connection, and quietly treating it as
+ * one is how a session goes deaf without a word.
+ */
+export function readSessionConnection(sessionId, options = {}) {
+    const file = sessionConnectionPath(sessionId, options.home ?? homedir());
+    let raw;
+    try {
+        raw = readFileSync(file, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw new Error(`cannot read the session connection record ${file}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`the session connection record ${file} is not JSON: ${err.message}`);
+    }
+    const invalid = invalidRecordReason(parsed);
+    if (invalid !== null)
+        throw new Error(`the session connection record ${file} is unusable: ${invalid}`);
+    return parsed;
+}
+/**
+ * Record the connection a successful `plan_connect` just made, and say so in
+ * that tool's own answer when it could not be recorded.
+ *
+ * FAIL LOUD, IN THE ONE PLACE THE AGENT IS LOOKING. A connect whose record is
+ * missing produces a session that is connected but whose `restart_notice` lookup and listener reminder cannot
+ * find its connection — so the failure belongs in the connect's answer, not only in a file
+ * nobody reads. It does NOT fail the connect itself: the session IS connected,
+ * and reporting otherwise would be a second lie on top of the first.
+ */
+export function recordSessionConnectionAfterConnect(result, inputs, write = writeSessionConnection) {
+    if (!result.ok)
+        return {};
+    if (inputs.sessionId === undefined || inputs.sessionId === "") {
+        return {
+            connection_record_error: "connected, but this server has no CLAUDE_CODE_SESSION_ID, so no connection record can be written — " +
+                "`restart_notice` and the listener reminder will not find this session's connection",
+        };
+    }
+    try {
+        write({
+            sessionId: inputs.sessionId,
+            projectKey: inputs.projectKey,
+            dashboardUrl: inputs.dashboardUrl,
+            source: inputs.source,
+            fingerprint: inputs.fingerprint,
+        });
+        return {};
+    }
+    catch (err) {
+        return {
+            connection_record_error: `connected, but recording this session's connection failed (${err.message}) — ` +
+                "`restart_notice` and the listener reminder will not find this session's connection until it succeeds",
+        };
+    }
+}
+/**
+ * DX-6556 — a manual pickup, which goes through the generic `50arms_api`, can connect the session as `card_connect` does; the dashboard marks that answer, and it is then
+ * handled as a connect, so no record or tool sync is missed.
+ */
+export function isPickupConnect(result) {
+    return result.ok && typeof result.body === "object" && result.body !== null && result.body.connectedByPickup === true;
+}
+/**
+ * DX-2985 — drop this session's local connection record after a successful leave (`plan_connect {disconnect: true}`), so
+ * nothing on this machine still treats the session as plan-connected (the listener-reminder reads this record). A refused
+ * leave keeps it: the session is still on its plan. Never throws for an absent record.
+ */
+export function removeSessionConnectionAfterLeave(result, sessionId, home = homedir()) {
+    if (!result.ok || sessionId === undefined || sessionId === "")
+        return;
+    rmSync(sessionConnectionPath(sessionId, home), { force: true });
+}
+/** Why a parsed record cannot be used, or `null` when it can. */
+export function invalidRecordReason(value) {
+    if (typeof value !== "object" || value === null)
+        return "it is not an object";
+    const r = value;
+    if (r.schemaVersion !== SESSION_CONNECTION_SCHEMA_VERSION) {
+        return (`schemaVersion is ${JSON.stringify(r.schemaVersion)}, not ${SESSION_CONNECTION_SCHEMA_VERSION} — ` +
+            "a session connected by an older MCP server wrote it; call plan_connect again to rewrite it");
+    }
+    for (const field of ["sessionId", "projectKey", "dashboardUrl", "fingerprint", "connectedAt"]) {
+        if (typeof r[field] !== "string" || r[field] === "")
+            return `${field} is not a non-empty string`;
+    }
+    const source = r.source;
+    if (typeof source !== "object" || source === null)
+        return "source is not an object";
+    if (source.kind === "session-key")
+        return typeof source.path === "string" && source.path !== "" ? null : "source.path is not a path";
+    if (source.kind === "env")
+        return typeof source.name === "string" && source.name !== "" ? null : "source.name is not a variable name";
+    return `source.kind is ${JSON.stringify(source.kind)}, which this version does not know`;
+}
+/**
+ * DX-3928 — the records of the sessions that ran in `projectKey` before
+ * `currentSessionId`, NEWEST FIRST: other sessions' records for that project,
+ * within `STALE_RECORD_MS`. Which of them is a real predecessor (not a live
+ * sibling in the same checkout) is the dashboard's call, not this reader's, so
+ * all candidates are returned; the caller asks about them in order.
+ *
+ * A record that cannot be understood (another schema version, not JSON) is
+ * SKIPPED here and nowhere else: this answers "was a plan being worked in this
+ * project", and a record from an older server cannot say. Every consumer of a
+ * session's OWN record (`readSessionConnection`) still fails loud.
+ */
+export function findPredecessorCandidates(projectKey, currentSessionId, options = {}) {
+    const dir = sessionConnectionDir(options.home ?? homedir());
+    const now = options.now ?? Date.now();
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return []; // nothing written yet
+    }
+    const found = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(join(dir, name), "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (invalidRecordReason(parsed) !== null)
+            continue;
+        const record = parsed;
+        if (record.projectKey !== projectKey || record.sessionId === currentSessionId)
+            continue;
+        const connectedAt = Date.parse(record.connectedAt);
+        if (!Number.isFinite(connectedAt) || now - connectedAt > STALE_RECORD_MS)
+            continue;
+        found.push({ record, connectedAt });
+    }
+    return found.sort((x, y) => y.connectedAt - x.connectedAt).map((f) => f.record);
+}

package/dist/session-control-file.js

@@ -0,0 +1,58 @@
+/**
+ * DX-6692 - the ONE local store of a per-session control file the relay keeps for the plugin: the compaction control (`compaction-control.ts`, DX-4993) and the clear release
+ * (`clear-control.ts`). Each is `~/.config/danxbot/<dirName>/<sessionId>.json`, written atomically (a sibling then a rename: the plugin must never read half a file), read back through the
+ * kind's own parser, and pruned: every write removes the files nothing has touched for a week (`pruneStaleSessionFiles`). A live relay touches its session's files at every heartbeat, so only
+ * the files of sessions whose relay has gone are removed.
+ */
+import { mkdirSync, readFileSync, utimesSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { writeFileDurable } from "./durable-write.js";
+import { assertSessionIdSegment, pruneStaleSessionFiles } from "./session-connection.js";
+/** `~/.config/danxbot/<dirName>`, next to the plugin's other per-session records. */
+export function sessionControlDir(dirName, home = homedir()) {
+    return join(home, ".config", "danxbot", dirName);
+}
+/** `~/.config/danxbot/<dirName>/<sessionId>.json`; refuses a session id that is not a plain id. */
+export function sessionControlFilePath(dirName, sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
+    return join(sessionControlDir(dirName, home), `${sessionId}.json`);
+}
+/** The real store of `dirName`'s files under `home`. `parse` reads one file (naming `where` when it refuses it); a file written for another session is refused. */
+export function sessionControlFilesIn(dirName, parse, home = homedir(), now = Date.now) {
+    return {
+        read(sessionId) {
+            const path = sessionControlFilePath(dirName, sessionId, home);
+            let text;
+            try {
+                text = readFileSync(path, "utf-8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return null;
+                throw err;
+            }
+            const file = parse(text, path);
+            if (file.sessionId !== sessionId)
+                throw new Error(`${path} was written for session ${JSON.stringify(file.sessionId)}`);
+            return file;
+        },
+        write(sessionId, file) {
+            const path = sessionControlFilePath(dirName, sessionId, home);
+            mkdirSync(dirname(path), { recursive: true });
+            pruneStaleSessionFiles(dirname(path), now());
+            writeFileDurable(path, JSON.stringify(file));
+        },
+        touch(sessionId) {
+            const at = new Date(now());
+            try {
+                utimesSync(sessionControlFilePath(dirName, sessionId, home), at, at);
+            }
+            catch (err) {
+                // a session with no file has nothing to keep; any other failure is the caller's to report
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        },
+    };
+}