@thehammer/danx-dashboard-mcp 0.1.276 → 0.1.277

package/dist/index.js

@@ -86,7 +86,7 @@ import { PlanEventRelay, WAIT_MAX_MS, WAIT_MIN_MS } from "./plan-events-relay.js
 import { READ_IDLE_TIMEOUT_MS } from "./listen.js";
 import { REQUEST_TIMEOUT_MS, realScheduleInterval, realSleep } from "./session-stream.js";
 import { servePlanEventsWait } from "./plan-events-tool.js";
-import { lookupRestartNotice } from "./restart-notice.js";
+import { lookupRestartNotice, RESTART_NOTICE_ARGS } from "./restart-notice.js";
 import { stopWhenSessionEnds } from "./shutdown.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
 import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
@@ -788,8 +788,10 @@ async (args, extra) => jsonResult(await servePlanEventsWait(planEventRelay, args
 strictTool("restart_notice", 
 // DX-4632 - for the danxbot plugin's session-start hook, not for a model to call. General-audience text (DX-4550).
 "Which plan the session this one replaced was working, and what waits there. For the danxbot plugin's session start: " +
-    "a model never calls it. Works before sign-in. Answers `{notice: text}` (tell the session), `{notice: null}` (nothing " +
-    "to say) or `{stopped: {reason, detail, fix}}`.", {}, async () => jsonResult(await lookupRestartNotice({
+    "a model never calls it. Works before sign-in. Answers " +
+    "`{notice: text}` (tell the session), `{notice: null}` (nothing to say) or `{stopped: {reason, detail, fix}}`.", RESTART_NOTICE_ARGS, async (args) => jsonResult(await lookupRestartNotice({
+    predecessorId: args.predecessor_id,
+    transcriptPath: args.transcript_path,
     sessionId: config.session?.id,
     cwd: process.cwd(),
     env: process.env,

package/dist/restart-notice.js

@@ -17,17 +17,35 @@
  *   - `{notice: null}` - nothing to say: no earlier session of this project connected a plan, or the plan is archived or
  *     deleted, or the record is stale, or every predecessor is still live. The plugin stays silent, as PLN-11 R-10 requires of
  *     a project that never connected a plan.
- *   - `{stopped: {reason, detail, fix}}` - the lookup could not answer: no session id, NO candidate answered (credential,
- *     network, non-2xx, bad shape, for every one), or the one deadline passed. Never a silent null. (A failure that is not
+ *   - `{stopped: {reason, detail, fix}}` - the lookup could not answer: no session id, an unreadable transcript, a named predecessor
+ *     with no usable record, NO candidate answered (credential, network, non-2xx, bad shape, for every one), or the one deadline
+ *     passed. Never a silent null. (A failure that is not
  *     one of these, a bug in the credential resolver, is rethrown: fail loud, never dressed as a lookup failure.)
  *
- * ONE DEADLINE over the whole lookup (`RESTART_NOTICE_DEADLINE_MS`): every candidate's request shares it (and each keeps its own
- * shorter bound), so a hung dashboard cannot wedge a session start however many candidates there are. READ-ONLY: it advances
+ * WHO THE PREDECESSOR IS (DX-4234). The project scan is a GUESS (the newest non-self record of the project): another session
+ * of the same checkout can win it, so a forked session was told about a stranger's plan. The caller can name the predecessor
+ * instead, in this precedence (`choosePredecessors`):
+ *   1. `predecessor_id` (a Claude Code session id): ask ONLY that session's record. No usable record for it is a `stopped`
+ *      (`no_predecessor_record`), never a fall back to the guess.
+ *   2. `transcript_path` (this session's own transcript, absolute `.jsonl`): the transcript says whether this session was forked
+ *      and from which session (`readTranscriptLineage`: the nearest ancestor, which for a fork of a fork is not the first row's
+ *      session). A fork's parent is asked as in (1), except that a parent with no record (it never connected a plan) is
+ *      `{notice: null}`. A transcript that proves this is NOT a fork (a plain resume) is `{notice: null}` too. One that cannot be
+ *      read (a bad path, a missing or malformed file, an over-cap row) is a `stopped` (`transcript_unreadable`): never the guess.
+ *   3. neither argument: the project scan (a bare startup).
+ * A predecessor the caller NAMED is asked with `?named=1`, which tells the dashboard to skip its "that session's stream is still
+ * open, so it is a live sibling" check: a fork's parent is usually still live, and the fork still needs to hear its plan.
+ *
+ * ONE DEADLINE over the whole lookup (`RESTART_NOTICE_DEADLINE_MS`): the transcript read and every candidate's request share it
+ * (each request keeps its own shorter bound), so a hung dashboard or a stalled disk cannot wedge a session start. READ-ONLY: it advances
  * no cursor on the server.
  */
+import { z } from "zod";
 import { sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
 import { resolveDashboardAuth, SessionStartError } from "./session-options.js";
-import { findPredecessorCandidates, projectKeyOf } from "./session-connection.js";
+import { findPredecessorCandidates, projectKeyOf, readSessionConnection } from "./session-connection.js";
+import { checkedTranscriptPath } from "./session-stats.js";
+import { readTranscriptLineage, TranscriptReadAborted, TranscriptUnreadable } from "./transcript-lineage.js";
 import { fixForStop } from "./stop-fixes.js";
 export const RESTART_NOTICE_REQUEST_TIMEOUT_MS = 5_000;
 /** DX-4632: the whole lookup, every candidate included (the old hook's `timeout 8s`). */
@@ -44,7 +62,7 @@ export const RESTART_NOTICE_REMINDER_KEY = "plan_restart.waiting_events";
 export async function fetchRestartNotice(target, deps) {
     // The bearer is the predecessor's; the session id header names the ASKING session.
     const auth = { dashboardUrl: target.dashboardUrl, token: target.token, sessionId: target.askingSessionId };
-    const sent = await sendSessionRequest(auth, `/api/plan-sessions/${encodeURIComponent(target.predecessorId)}/restart-notice`, { method: "GET" }, deps);
+    const sent = await sendSessionRequest(auth, `/api/plan-sessions/${encodeURIComponent(target.predecessorId)}/restart-notice${target.named === true ? "?named=1" : ""}`, { method: "GET" }, deps);
     if ("ok" in sent)
         return { ok: false, reason: sent.reason };
     const { status, text } = sent;
@@ -68,20 +86,94 @@ export async function fetchRestartNotice(target, deps) {
         return { ok: false, reason: "bad_response" };
     return { ok: true, text: notice.text };
 }
+/** The tool's arguments (`index.ts` registers exactly this shape). */
+export const RESTART_NOTICE_ARGS = {
+    predecessor_id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Session id of the session this one replaced, when known. Asked alone, and wins over transcript_path. With neither argument the newest earlier session of the project is guessed."),
+    transcript_path: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Absolute path of this session's transcript (.jsonl file): a forked session's copied rows name the session it was forked from."),
+};
 const stop = (reason, detail) => ({ stopped: { reason, detail, fix: fixForStop(reason) } });
+/**
+ * DX-4234 - the module docblock's precedence: a named id, else the transcript's lineage, else the project scan. Throws
+ * `TranscriptReadAborted` when the deadline fires mid-read; every other failure is an answer.
+ */
+async function choosePredecessors(lookup, ownId, signal) {
+    let namedId = lookup.predecessorId;
+    let namedBy = "predecessor_id";
+    if (namedId === undefined && lookup.transcriptPath !== undefined) {
+        let path;
+        try {
+            path = checkedTranscriptPath(lookup.transcriptPath, "restart_notice transcript_path");
+        }
+        catch (err) {
+            return { answer: stop("transcript_unreadable", err.message) };
+        }
+        let lineage;
+        try {
+            lineage = await readTranscriptLineage(path, ownId, { signal, open: lookup.openTranscript });
+        }
+        catch (err) {
+            if (err instanceof TranscriptUnreadable)
+                return { answer: stop("transcript_unreadable", err.message) };
+            throw err;
+        }
+        if (lineage.kind === "not_fork")
+            return { answer: { notice: null } };
+        namedId = lineage.parent;
+        namedBy = "transcript_path";
+    }
+    if (namedId === undefined) {
+        const found = findPredecessorCandidates(projectKeyOf(lookup.cwd), ownId, { home: lookup.home, now: lookup.now });
+        return { candidates: found.slice(0, RESTART_NOTICE_MAX_CANDIDATES), named: false };
+    }
+    let record;
+    try {
+        record = readSessionConnection(namedId, { home: lookup.home });
+    }
+    catch (err) {
+        return { answer: stop("no_predecessor_record", `session ${namedId} (${namedBy}) has no usable dashboard connection record: ${err.message}`) };
+    }
+    if (record === null) {
+        // A parent found through the transcript that never connected a plan has nothing to tell; an id the caller NAMED that has
+        // no record is something the caller must hear about.
+        if (namedBy === "transcript_path")
+            return { answer: { notice: null } };
+        return { answer: stop("no_predecessor_record", `session ${namedId} (${namedBy}) has no dashboard connection record on this machine`) };
+    }
+    return { candidates: [record], named: true };
+}
 /** The tool's whole body: see the module docblock for the contract. Throws only on a bug, never on a lookup failure. */
 export async function lookupRestartNotice(lookup) {
-    if (lookup.sessionId === undefined || lookup.sessionId === "") {
+    const ownId = lookup.sessionId;
+    if (ownId === undefined || ownId === "") {
         return stop("no_session_id", "this server has no CLAUDE_CODE_SESSION_ID, so it cannot tell which session it replaced");
     }
     const resolveFrom = { home: lookup.home, now: lookup.now };
-    const candidates = findPredecessorCandidates(projectKeyOf(lookup.cwd), lookup.sessionId, resolveFrom).slice(0, RESTART_NOTICE_MAX_CANDIDATES);
-    // DX-4632: ONE deadline for every candidate read. It is not unref'd: the lookup is awaited, and a pending request holds the
-    // process anyway.
+    // DX-4632: ONE deadline for the transcript read and every candidate read. It is not unref'd: the lookup is awaited, and a
+    // pending request holds the process anyway.
     const deadline = new AbortController();
     const deadlineMs = lookup.deadlineMs ?? RESTART_NOTICE_DEADLINE_MS;
     const timer = setTimeout(() => deadline.abort(), deadlineMs);
     try {
+        let choice;
+        try {
+            choice = await choosePredecessors(lookup, ownId, deadline.signal);
+        }
+        catch (err) {
+            if (!(err instanceof TranscriptReadAborted))
+                throw err;
+            return stop("lookup_timeout", `the lookup did not finish within ${deadlineMs} ms (it was still reading the transcript)`);
+        }
+        if ("answer" in choice)
+            return choice.answer;
+        const { candidates, named } = choice;
         // One candidate failing (its credential moved, its dashboard is down) must not hide a LATER candidate that
         // would answer: keep going, and report failure only when no candidate answered at all.
         const failures = [];
@@ -101,7 +193,8 @@ export async function lookupRestartNotice(lookup) {
                 dashboardUrl: options.dashboardUrl,
                 token: options.token,
                 predecessorId: predecessor.sessionId,
-                askingSessionId: lookup.sessionId,
+                askingSessionId: ownId,
+                named,
             }, { fetch: lookup.fetch, requestTimeoutMs: lookup.requestTimeoutMs ?? RESTART_NOTICE_REQUEST_TIMEOUT_MS, signal: deadline.signal });
             // A notice the dashboard fully answered is kept even when the deadline fired right after it; every other outcome of a
             // deadline that passed is the stop below (this is the lookup's one deadline check).

package/dist/stop-fixes.js

@@ -37,6 +37,8 @@ export const STOP_FIXES = {
     // DX-4632: `restart_notice` only tells a restarted session which plan its predecessor was on; none of its stops blocks anything.
     no_session_id: `${RESTART_NOTICE_STOP_LEAD}: this server was started without a session id, so it cannot tell which session it replaced; ${RESTART_NOTICE_STOP_TAIL}`,
     lookup_timeout: `${RESTART_NOTICE_STOP_LEAD}: the dashboard did not answer in time; ${RESTART_NOTICE_STOP_TAIL}`,
+    no_predecessor_record: `${RESTART_NOTICE_STOP_LEAD}: this machine holds no usable record of the named earlier session, so there is nothing to carry over; ${RESTART_NOTICE_STOP_TAIL}`,
+    transcript_unreadable: `${RESTART_NOTICE_STOP_LEAD}: this session's transcript could not be read to find the session it replaced (the detail says why); ${RESTART_NOTICE_STOP_TAIL}`,
     lookup_failed: `${RESTART_NOTICE_STOP_LEAD}: no earlier session's record could be checked (the detail says why); ${RESTART_NOTICE_STOP_TAIL}`,
     relay_failed: "the event relay inside this session's danx-dashboard MCP server failed (the detail says why); the next call tries again, and if it keeps failing restart this Claude Code session",
 };

package/dist/transcript-lineage.js

@@ -0,0 +1,105 @@
+/**
+ * DX-4234 - who a session was FORKED from, read from its own transcript. For the `restart_notice` tool.
+ *
+ * A desktop fork copies its parent's rows into the new transcript, then appends its own. The copied rows carry the session
+ * ids of the ancestors that wrote them, so a transcript runs `root ... parent ... own`: for a fork of a fork the FIRST row
+ * names the ROOT ancestor, not the parent. The parent is the LAST session id before the first row carrying this session's own
+ * id, so the read goes forward and stops at that row (it reads the copied prefix, never the rest of a file that can be tens
+ * of MB).
+ *
+ * ANSWERS:
+ *   - `{kind: "fork", parent}` - the nearest earlier session id.
+ *   - `{kind: "not_fork"}` - the first row naming a session is this session's own (a plain resume or a fresh start): it was
+ *     not forked from anything.
+ *   - throws `TranscriptUnreadable` - the file cannot say (missing, unreadable, a row that is not JSON, a row or prefix over
+ *     the caps below, no row names a session). The caller must be told; it is never a "not a fork".
+ *   - throws `TranscriptReadAborted` - the caller's deadline signal fired mid-read.
+ *
+ * BOUNDED: one row may be at most `TRANSCRIPT_MAX_LINE_BYTES` (a first row can be 428 KB or more) and the prefix read at most
+ * `TRANSCRIPT_MAX_PREFIX_BYTES`; over either is `TranscriptUnreadable`, never a quiet truncation.
+ */
+import { createReadStream } from "node:fs";
+export const TRANSCRIPT_MAX_LINE_BYTES = 4 * 1024 * 1024;
+export const TRANSCRIPT_MAX_PREFIX_BYTES = 64 * 1024 * 1024;
+export class TranscriptUnreadable extends Error {
+}
+export class TranscriptReadAborted extends Error {
+}
+const NEWLINE = 0x0a;
+export async function readTranscriptLineage(path, ownSessionId, options = {}) {
+    const source = options.open?.(path) ?? createReadStream(path);
+    const stop = () => {
+        source.destroy?.();
+    };
+    options.signal?.addEventListener("abort", stop, { once: true });
+    let carry = Buffer.alloc(0);
+    let total = 0;
+    let row = 0;
+    const seen = { nearest: null };
+    /** One complete line: the lineage when it settles the answer, else `undefined` to keep reading. */
+    const settle = (line) => {
+        if (line.toString("utf-8").trim() === "")
+            return undefined;
+        row += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(line.toString("utf-8"));
+        }
+        catch (err) {
+            throw new TranscriptUnreadable(`row ${row} of ${path} is not JSON: ${err.message}`);
+        }
+        const id = parsed?.sessionId;
+        if (typeof id !== "string" || id === "")
+            return undefined;
+        if (id !== ownSessionId) {
+            seen.nearest = id;
+            return undefined;
+        }
+        return seen.nearest === null ? { kind: "not_fork" } : { kind: "fork", parent: seen.nearest };
+    };
+    try {
+        for await (const chunk of source) {
+            if (options.signal?.aborted === true)
+                throw new TranscriptReadAborted("the deadline passed");
+            total += chunk.length;
+            if (total > TRANSCRIPT_MAX_PREFIX_BYTES) {
+                throw new TranscriptUnreadable(`${path} has no row of this session within its first ${TRANSCRIPT_MAX_PREFIX_BYTES} bytes`);
+            }
+            let start = 0;
+            for (let end = chunk.indexOf(NEWLINE, start); end !== -1; end = chunk.indexOf(NEWLINE, start)) {
+                const piece = chunk.subarray(start, end);
+                if (carry.length + piece.length > TRANSCRIPT_MAX_LINE_BYTES) {
+                    throw new TranscriptUnreadable(`row ${row + 1} of ${path} is over ${TRANSCRIPT_MAX_LINE_BYTES} bytes`);
+                }
+                const settled = settle(Buffer.concat([carry, piece]));
+                carry = Buffer.alloc(0);
+                if (settled !== undefined)
+                    return settled;
+                start = end + 1;
+            }
+            const rest = chunk.subarray(start);
+            if (carry.length + rest.length > TRANSCRIPT_MAX_LINE_BYTES) {
+                throw new TranscriptUnreadable(`row ${row + 1} of ${path} is over ${TRANSCRIPT_MAX_LINE_BYTES} bytes`);
+            }
+            carry = Buffer.concat([carry, rest]);
+        }
+    }
+    catch (err) {
+        if (options.signal?.aborted === true)
+            throw new TranscriptReadAborted("the deadline passed");
+        if (err instanceof TranscriptUnreadable || err instanceof TranscriptReadAborted)
+            throw err;
+        throw new TranscriptUnreadable(`cannot read ${path}: ${err.message}`);
+    }
+    finally {
+        options.signal?.removeEventListener("abort", stop);
+        stop();
+    }
+    const settled = settle(carry);
+    if (settled !== undefined)
+        return settled;
+    if (seen.nearest === null)
+        throw new TranscriptUnreadable(`no row of ${path} names a session`);
+    // The file ends before any row of this session: everything in it was copied from an earlier one.
+    return { kind: "fork", parent: seen.nearest };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.276",
+  "version": "0.1.277",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",