chesspal 0.3.5 → 0.4.0

package/dist/games/analysis.js

@@ -8,7 +8,7 @@ import { writeAtomically } from "./files.js";
  * unless it starts afresh, in one write, so that the page never sees it leave the analysis; the analyst stays with the game it took, whichever the page
  * opens meanwhile (Federico), and goes when that game starts afresh.
  */
-export function startAnalysis(folder, game, now, { brought = false, corrected = [], analyst, afresh = false } = {}) {
+export function startAnalysis(folder, game, now, { brought = false, redo = false, corrected = [], analyst, afresh = false } = {}) {
     const before = gameInAnalysis(folder);
     const same = !afresh && before?.game === game;
     const kept = [...new Set([...(same ? before.corrected ?? [] : []), ...corrected])];
@@ -17,6 +17,7 @@ export function startAnalysis(folder, game, now, { brought = false, corrected =
         game,
         at: now.toISOString(),
         ...(brought ? { brought: true } : {}),
+        ...(brought && redo ? { redo: true } : {}),
         ...(kept.length === 0 ? {} : { corrected: kept }),
         ...withAnalyst(analyst ?? held),
     });
@@ -25,8 +26,8 @@ export function startAnalysis(folder, game, now, { brought = false, corrected =
 export function forgetAnalyst(folder) {
     const analysis = gameInAnalysis(folder);
     if (analysis?.analyst !== undefined) {
-        const { game, at, brought, corrected } = analysis;
-        writeAnalysis(folder, { game, at, ...(brought === undefined ? {} : { brought }), ...(corrected === undefined ? {} : { corrected }) });
+        const { game, at, brought, redo, corrected } = analysis;
+        writeAnalysis(folder, { game, at, ...(brought === undefined ? {} : { brought }), ...(redo === undefined ? {} : { redo }), ...(corrected === undefined ? {} : { corrected }) });
     }
 }
 /** The game in analysis, or none when there is none, or analysis.json cannot be read. */
@@ -39,6 +40,7 @@ export function gameInAnalysis(folder) {
                 game: analysis.game,
                 at: analysis.at,
                 ...(analysis.brought === true ? { brought: true } : {}),
+                ...(analysis.brought === true && analysis.redo === true ? { redo: true } : {}),
                 ...(corrected.length === 0 ? {} : { corrected }),
                 ...withAnalyst(isAnalystRun(analysis.analyst) ? analysis.analyst : undefined),
             }

package/dist/games/archive.d.ts

@@ -10,15 +10,15 @@ export declare function isOverOnTable(folder: string, name: string): boolean;
  */
 export declare function startOfNewGame(folder: string, now: Date, before?: CurrentGame): Date;
 /**
- * Writes the game to the archive, with the plans, how it ended and the AI's model and host last noted (D-82, D-97), and gives its name; the same game again rewrites the
- * same file. A game closed before any move is not kept, as Lichess aborts it: none.
+ * Writes the game to the archive, with the plans, how it ended, the AI's model and host last noted (D-82, D-97) and the opening's tags, and gives its name;
+ * the same game again rewrites the same file. A game closed before any move is not kept, as Lichess aborts it: none.
  */
-export declare function archiveGame(folder: string, current: CurrentGame): string | undefined;
+export declare function archiveGame(folder: string, current: CurrentGame, opening: OpeningTags): string | undefined;
 /**
  * Archives a game that has ended: its name in the archive, none for a game closed before any move, or, when that fails, a warning, since the game is saved in
  * game.json all the same.
  */
-export declare function archiveEnded(folder: string, current: CurrentGame): {
+export declare function archiveEnded(folder: string, current: CurrentGame, opening: OpeningTags): {
     archive?: string;
     warning?: string;
 };
@@ -26,16 +26,36 @@ export declare function archiveEnded(folder: string, current: CurrentGame): {
  * Writes the coach's judgments into a game over already in the archive, beside what the analyst may have written there since (Federico);
  * archives the game when it is not there.
  */
-export declare function archiveCoached(folder: string, current: CurrentGame): {
+export declare function archiveCoached(folder: string, current: CurrentGame, opening: OpeningTags): {
     archive?: string;
     warning?: string;
 };
 /** The name of a game over in the archive, when it is there. */
 export declare function archivedName(folder: string, current: CurrentGame): string | undefined;
+/**
+ * The opening a game reached, in its ECO and Opening tags, as the commands name it: none from another position or outside the book. With the PlyCount the
+ * archive adds, a game is listed from its tags alone.
+ */
+export interface OpeningTags {
+    readonly ECO?: string;
+    readonly Opening?: string;
+}
 /** The names of the games in the archive, the latest first: games/2026-11-02-153012.pgn. */
 export declare function archivedGames(folder: string): string[];
 /** A game of the archive by its name, as listed; refused when it is not there, or cannot be read. */
 export declare function archivedGame(folder: string, name: string): GameRecord;
+/** A game of the archive by its name, as listed, with its moves as written, neither checked nor played: for its tags and comments, quickly. */
+export declare function archivedGameUnplayed(folder: string, name: string): GameRecord;
+/** The tags of a game of the archive by its name, as listed, read without its moves; refused as archivedGame refuses. */
+export declare function archivedTags(folder: string, name: string): Readonly<Record<string, string>>;
+/**
+ * Whether the archive wrote a game's list tags, its PlyCount with its ECO and Opening, or none for a game that has no opening: a numeric PlyCount says so.
+ * A game an older Chesspal archived has none, and is read whole.
+ */
+export declare function hasListTags(tags: Readonly<Record<string, string>>): boolean;
+/** The refusal of a game asked by a name no game has, apart from a game that is there and cannot be read. */
+export declare class GameMissing extends Error {
+}
 /** The names of the games kept to study in a profile's folder, the latest kept first: study/2026-11-04-153012.pgn. */
 export declare function keptGames(root: string): string[];
 /** A game kept to study by its name, as listed; refused when it is not there, or cannot be read. */

package/dist/games/archive.js

@@ -1,7 +1,7 @@
 // The finished games, as PGN in games/ (D-9, D-41), with the AI's plans for the analyst (D-21); and the games played elsewhere, kept to study in study/ (D-68).
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { movesOnly, pgnDate, readPgn, unsigned, withAiHost, withAiModel, writePgn } from "../core/index.js";
+import { movesOnly, pgnDate, readPgn, readPgnTags, readPgnUnplayed, unsigned, withAiHost, withAiModel, writePgn } from "../core/index.js";
 import { aiHostOf, aiModelOf } from "./ai-model.js";
 import { coachWords, withCoach } from "./coach.js";
 import { endOf, loadGame } from "./current-game.js";
@@ -34,10 +34,10 @@ export function startOfNewGame(folder, now, before) {
     return start;
 }
 /**
- * Writes the game to the archive, with the plans, how it ended and the AI's model and host last noted (D-82, D-97), and gives its name; the same game again rewrites the
- * same file. A game closed before any move is not kept, as Lichess aborts it: none.
+ * Writes the game to the archive, with the plans, how it ended, the AI's model and host last noted (D-82, D-97) and the opening's tags, and gives its name;
+ * the same game again rewrites the same file. A game closed before any move is not kept, as Lichess aborts it: none.
  */
-export function archiveGame(folder, current) {
+export function archiveGame(folder, current, opening) {
     if (current.game.record.moves.length === 0) {
         return undefined;
     }
@@ -45,7 +45,7 @@ export function archiveGame(folder, current) {
     const path = join(folder, name);
     try {
         makeFolder(dirname(path));
-        writeAtomically(path, writePgn(withAiHost(withAiModel(endedRecord(folder, current), aiModelOf(folder)), aiHostOf(folder))));
+        writeAtomically(path, writePgn(withListTags(withAiHost(withAiModel(endedRecord(folder, current), aiModelOf(folder)), aiHostOf(folder)), opening)));
     }
     catch (error) {
         throw new Error(`Chesspal could not archive the game: ${error.message}`, { cause: error });
@@ -56,9 +56,9 @@ export function archiveGame(folder, current) {
  * Archives a game that has ended: its name in the archive, none for a game closed before any move, or, when that fails, a warning, since the game is saved in
  * game.json all the same.
  */
-export function archiveEnded(folder, current) {
+export function archiveEnded(folder, current, opening) {
     try {
-        const archive = archiveGame(folder, current);
+        const archive = archiveGame(folder, current, opening);
         return archive === undefined ? {} : { archive };
     }
     catch (error) {
@@ -69,10 +69,10 @@ export function archiveEnded(folder, current) {
  * Writes the coach's judgments into a game over already in the archive, beside what the analyst may have written there since (Federico);
  * archives the game when it is not there.
  */
-export function archiveCoached(folder, current) {
+export function archiveCoached(folder, current, opening) {
     const name = archivedName(folder, current);
     if (name === undefined) {
-        return archiveEnded(folder, current);
+        return archiveEnded(folder, current, opening);
     }
     try {
         writeAtomically(join(folder, name), writePgn(withCoach(archivedGame(folder, name), coachWords(folder, current))));
@@ -98,6 +98,28 @@ export function archivedGames(folder) {
 export function archivedGame(folder, name) {
     return gameNamed(folder, "games", name);
 }
+/** A game of the archive by its name, as listed, with its moves as written, neither checked nor played: for its tags and comments, quickly. */
+export function archivedGameUnplayed(folder, name) {
+    const [record] = readPgnUnplayed(gameText(folder, "games", name));
+    if (record === undefined) {
+        throw new Error(`${name} holds no game Chesspal can read.`);
+    }
+    return record;
+}
+/** The tags of a game of the archive by its name, as listed, read without its moves; refused as archivedGame refuses. */
+export function archivedTags(folder, name) {
+    return readPgnTags(gameText(folder, "games", name));
+}
+/**
+ * Whether the archive wrote a game's list tags, its PlyCount with its ECO and Opening, or none for a game that has no opening: a numeric PlyCount says so.
+ * A game an older Chesspal archived has none, and is read whole.
+ */
+export function hasListTags(tags) {
+    return /^\d+$/.test(tags.PlyCount ?? "");
+}
+/** The refusal of a game asked by a name no game has, apart from a game that is there and cannot be read. */
+export class GameMissing extends Error {
+}
 /** The names of the games kept to study in a profile's folder, the latest kept first: study/2026-11-04-153012.pgn. */
 export function keptGames(root) {
     return gameNames(root, "study");
@@ -211,24 +233,30 @@ function gameNames(folder, shelf) {
     }
 }
 function gameNamed(folder, shelf, name) {
+    const [record] = readPgn(gameText(folder, shelf, name));
+    if (record === undefined) {
+        throw new Error(`${name} holds no game Chesspal can read.`);
+    }
+    return record;
+}
+function gameText(folder, shelf, name) {
     // The name as listed, or without its folder or its .pgn.
     const file = `${(name.startsWith(`${shelf}/`) ? name.slice(shelf.length + 1) : name).trim().replace(/\.pgn$/, "")}.pgn`;
     const { what, list } = shelves[shelf];
     if (!namePattern.test(file)) {
-        throw new Error(`${name} is no game ${what}: give a name as ${list} writes it, such as ${shelf}/2026-11-02-153012.pgn.`);
+        throw new GameMissing(`${name} is no game ${what}: give a name as ${list} writes it, such as ${shelf}/2026-11-02-153012.pgn.`);
     }
-    let text;
     try {
-        text = readFileSync(join(folder, shelf, file), "utf8");
-    }
-    catch {
-        throw new Error(`There is no ${name} among the games ${what}: give a name as ${list} writes it.`);
+        return readFileSync(join(folder, shelf, file), "utf8");
     }
-    const [record] = readPgn(text);
-    if (record === undefined) {
-        throw new Error(`${name} holds no game Chesspal can read.`);
+    catch (error) {
+        const code = error.code;
+        // Only a file that is not there is a missing game: one busy or locked by another process is there, and may be read in a moment.
+        if (code === "ENOENT") {
+            throw new GameMissing(`There is no ${name} among the games ${what}: give a name as ${list} writes it.`);
+        }
+        throw new Error(`${name} could not be read (${code ?? error.message}): try again in a moment.`, { cause: error });
     }
-    return record;
 }
 /** Whether two records are the same game: the same tags and the same moves, whatever their comments say. */
 function sameGame(one, other) {
@@ -245,6 +273,11 @@ function endedRecord(folder, current) {
     const { record, outcome } = current.game;
     return withTermination(withCoach(record, coachWords(folder, current)), outcome);
 }
+/** The record with the tags past_games lists it from: the opening's, the commands' alone whatever the game brought, and how many plies it has. */
+function withListTags(record, opening) {
+    const tags = Object.fromEntries(Object.entries(record.tags).filter(([name]) => name !== "ECO" && name !== "Opening" && name !== "PlyCount"));
+    return { ...record, tags: { ...tags, ...opening, PlyCount: String(record.moves.length) } };
+}
 function withTermination(record, outcome) {
     return outcome.over && record.tags.Termination === undefined ? { ...record, tags: { ...record.tags, Termination: outcome.ending } } : record;
 }

package/dist/games/chat-start.d.ts

@@ -1,6 +1,6 @@
 /**
- * How a chat started, as the host's SessionStart hook says it: new, cleared, resumed or compacted; when, as an ISO date; its session, for the logs; and the
- * file where the host writes the chat, where Claude Code tells which model made each tool call (D-81).
+ * How a chat started, as the host's SessionStart hook says it: new, cleared, resumed or compacted; when, as an ISO date; its session, as the hooks have it;
+ * and the file where the host writes the chat, where Claude Code tells which model made each tool call (D-81).
  */
 export interface ChatStart {
     readonly source: string;

package/dist/games/chat-start.js

@@ -13,7 +13,12 @@ export function lastChatStart(folder) {
         if (typeof start.source !== "string" || typeof start.at !== "string") {
             return undefined;
         }
-        return { source: start.source, at: start.at, ...(typeof start.transcript === "string" ? { transcript: start.transcript } : {}) };
+        return {
+            source: start.source,
+            at: start.at,
+            ...(typeof start.session === "string" ? { session: start.session } : {}),
+            ...(typeof start.transcript === "string" ? { transcript: start.transcript } : {}),
+        };
     }
     catch {
         return undefined;

package/dist/games/current-game.d.ts

@@ -43,9 +43,9 @@ export interface GameEnd {
 export declare function loadGame(folder: string): CurrentGame | undefined;
 /**
  * Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. Refused with GameChanged when another process wrote
- * the file since this one read it: the change made on the game read before would lose theirs.
+ * the file since this one read it: the change made on the game read before would lose theirs. `first` runs just before the write, on the game read.
  */
-export declare function saveGame(folder: string, current: CurrentGame): void;
+export declare function saveGame(folder: string, current: CurrentGame, first?: () => void): void;
 /** The refusal of a save on a game another process changed since this one read it: what wrote it reads it again and starts over, once (rerunIfChanged). */
 export declare class GameChanged extends Error {
     constructor();

package/dist/games/current-game.js

@@ -23,15 +23,16 @@ export function loadGame(folder) {
 }
 /**
  * Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. Refused with GameChanged when another process wrote
- * the file since this one read it: the change made on the game read before would lose theirs.
+ * the file since this one read it: the change made on the game read before would lose theirs. `first` runs just before the write, on the game read.
  */
-export function saveGame(folder, current) {
+export function saveGame(folder, current, first) {
     const path = join(folder, fileName);
     whileLocked(path, () => {
         if (stampOf(path) !== kept.get(path)?.stamp) {
             kept.delete(path);
             throw new GameChanged();
         }
+        first?.();
         write(path, current);
     });
 }

package/dist/games/index.d.ts

@@ -1,11 +1,12 @@
 export { aiHostOf, aiModelOf, forgetTheAi, noteAiHost, noteAiModel } from "./ai-model.ts";
 export { type Analysis, type AnalysisStart, endAnalysis, forgetAnalyst, gameInAnalysis, startAnalysis } from "./analysis.ts";
-export { archiveCoached, archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, gameStemOf, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.ts";
+export { archiveCoached, archivedGame, archivedGames, archivedGameUnplayed, archivedName, archivedTags, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, GameMissing, gameStemOf, hasListTags, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, type OpeningTags, playerPgn, rewriteGame, startOfNewGame, } from "./archive.ts";
 export { type ChatStart, cleanSince, lastChatStart, saveChatStart } from "./chat-start.ts";
 export { type CoachHint, type CoachJudgment, type CoachLead, coachShown, coachStarted, coachWaitingSince, type CoachWords, coachWords, forgetCoach, keepHint, keepJudgment, keepLead, startCoach, withCoach } from "./coach.ts";
 export { bothSidesMoved, type CurrentGame, drawOfferOf, endOf, GameChanged, type GameEnd, gameStamp, loadGame, removeGame, rerunIfChanged, saveGame, type Shown, type Speaker, type TalkLine } from "./current-game.ts";
 export { makeFolder, renameOver, writeAtomically } from "./files.ts";
 export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.ts";
+export { forgetPositionShown, hostProcess, notePositionShown, type PositionShown, positionShownNote } from "./position-shown.ts";
 export { endTableTalk, loadTableTalk, saveTableTalk, type TableTalk, tableTalkStamp } from "./table-talk.ts";
 export { type Heard, heardLines, type Sayer, type Talk, talkLimits, talkLine, unheardWords, wakesTheChat, type Words, WordsRefused } from "./talk.ts";
-export { keepThought, notePondering, ponderingOn, type Thought, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.ts";
+export { keepThought, notePondering, ponderingOn, ponderingUntil, type Thought, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.ts";

package/dist/games/index.js

@@ -1,12 +1,13 @@
 // The player's games on disk: the current one in game.json, the finished ones in games/ (D-27, D-41), the games kept to study in study/ (D-68). Below the commands, above the core.
 export { aiHostOf, aiModelOf, forgetTheAi, noteAiHost, noteAiModel } from "./ai-model.js";
 export { endAnalysis, forgetAnalyst, gameInAnalysis, startAnalysis } from "./analysis.js";
-export { archiveCoached, archivedGame, archivedGames, archivedName, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, gameStemOf, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.js";
+export { archiveCoached, archivedGame, archivedGames, archivedGameUnplayed, archivedName, archivedTags, archivedWhen, archiveEnded, archiveGame, archiveName, deleteGame, GameMissing, gameStemOf, hasListTags, isGameName, isOverOnTable, keepToStudy, keptGame, keptGames, listedName, movesPgn, playerPgn, rewriteGame, startOfNewGame, } from "./archive.js";
 export { cleanSince, lastChatStart, saveChatStart } from "./chat-start.js";
 export { coachShown, coachStarted, coachWaitingSince, coachWords, forgetCoach, keepHint, keepJudgment, keepLead, startCoach, withCoach } from "./coach.js";
 export { bothSidesMoved, drawOfferOf, endOf, GameChanged, gameStamp, loadGame, removeGame, rerunIfChanged, saveGame } from "./current-game.js";
 export { makeFolder, renameOver, writeAtomically } from "./files.js";
 export { commentWithPlan, currentPlan, planOf, withoutPlans } from "./plans.js";
+export { forgetPositionShown, hostProcess, notePositionShown, positionShownNote } from "./position-shown.js";
 export { endTableTalk, loadTableTalk, saveTableTalk, tableTalkStamp } from "./table-talk.js";
 export { heardLines, talkLimits, talkLine, unheardWords, wakesTheChat, WordsRefused } from "./talk.js";
-export { keepThought, notePondering, ponderingOn, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.js";
+export { keepThought, notePondering, ponderingOn, ponderingUntil, thoughtForLastMove, thoughtKey, waitingSince } from "./thoughts.js";

package/dist/games/position-shown.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The position shown to a chat by its session, as the host names it to its hooks, and by the host's process, when it names one: the game by its start, none
+ * when there is none, its plies, the stamp of game.json after the move, when, and the keys of the player's words given with it.
+ */
+export interface PositionShown {
+    readonly session: string;
+    readonly process?: string;
+    readonly stamp?: string;
+    readonly started?: string;
+    readonly plies: number;
+    readonly at: string;
+    readonly given: readonly string[];
+}
+/**
+ * The Claude Code process this one runs in, as it names it to its hooks and to the MCP server alike, the same through /clear and /resume: none when it
+ * names none. Not documented: Priya measured it in Claude Code 2.1.323.
+ */
+export declare function hostProcess(): string | undefined;
+/** Notes the position shown to a chat, over the last one. */
+export declare function notePositionShown(folder: string, shown: PositionShown): void;
+/** The position a hook showed a chat of the folder, or undefined when there is no note, or it cannot be read. */
+export declare function positionShownNote(folder: string): PositionShown | undefined;
+/** Forgets the note; one that cannot go now is taken again, which changes nothing, or dropped once the game has moved on. */
+export declare function forgetPositionShown(folder: string): void;

package/dist/games/position-shown.js

@@ -0,0 +1,51 @@
+// The position a hook showed a chat outside its server (D-71), and the player's words on the board page it gave with it: `chesspal prompt` notes them
+// after playing the move the player wrote alone, and the chat's server takes them before its next tool, so that the AI moves without asking for status
+// and no tool gives those words again; the chat's doorbell does not ring for that move, which the chat hears from the prompt itself.
+import { readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeAtomically } from "./files.js";
+/**
+ * The Claude Code process this one runs in, as it names it to its hooks and to the MCP server alike, the same through /clear and /resume: none when it
+ * names none. Not documented: Priya measured it in Claude Code 2.1.323.
+ */
+export function hostProcess() {
+    const socket = process.env.CLAUDE_CODE_MESSAGING_SOCKET?.trim();
+    return socket === undefined || socket === "" ? undefined : socket;
+}
+/** Notes the position shown to a chat, over the last one. */
+export function notePositionShown(folder, shown) {
+    writeAtomically(join(folder, fileName), `${JSON.stringify(shown)}\n`);
+}
+/** The position a hook showed a chat of the folder, or undefined when there is no note, or it cannot be read. */
+export function positionShownNote(folder) {
+    try {
+        const shown = JSON.parse(readFileSync(join(folder, fileName), "utf8"));
+        if (typeof shown.session !== "string" || typeof shown.at !== "string" || !Number.isInteger(shown.plies)) {
+            return undefined;
+        }
+        // A note of an older Chesspal has no words.
+        const given = Array.isArray(shown.given) ? shown.given.filter((key) => typeof key === "string") : [];
+        return {
+            session: shown.session,
+            ...(typeof shown.process === "string" ? { process: shown.process } : {}),
+            ...(typeof shown.stamp === "string" ? { stamp: shown.stamp } : {}),
+            ...(typeof shown.started === "string" ? { started: shown.started } : {}),
+            plies: shown.plies,
+            at: shown.at,
+            given,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Forgets the note; one that cannot go now is taken again, which changes nothing, or dropped once the game has moved on. */
+export function forgetPositionShown(folder) {
+    try {
+        rmSync(join(folder, fileName), { force: true });
+    }
+    catch {
+        // Another process holds it for a moment.
+    }
+}
+const fileName = "position-shown.json";

package/dist/games/thoughts.d.ts

@@ -7,8 +7,11 @@ export interface Thought {
 }
 /** The key of the position the player is to move in: the game, by its start, and how many moves it has. */
 export declare function thoughtKey(current: CurrentGame, ply?: number): string;
-/** Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. */
-export declare function keepThought(folder: string, key: string, thought: Thought): Thought[];
+/**
+ * Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. A thought kept while the AI
+ * ponders shows it still at work.
+ */
+export declare function keepThought(folder: string, key: string, thought: Thought, now: Date): Thought[];
 /** The thought for the player's last move, when the AI is to move and thought of it on their time. */
 export declare function thoughtForLastMove(folder: string, current: CurrentGame): Thought | undefined;
 /** Since when the AI has waited for the player's move in a position: the first time it asked, `now` then, kept with its thoughts. */
@@ -17,6 +20,11 @@ export declare function waitingSince(folder: string, key: string, now: Date): Da
  * Notes whether the AI thinks on the player's time in a position now, from its first look until it waits for their move, for the page's sign: in the file,
  * since in Codex the agent that thinks has a process of its own (D-98).
  */
-export declare function notePondering(folder: string, key: string, pondering: boolean): void;
+export declare function notePondering(folder: string, key: string, pondering: boolean, now: Date): void;
+/**
+ * Until when the AI is seen thinking on the player's time in a position, as noted: a while after its last look or thought, so that an agent stopped before
+ * it waits (Esc, its host closed) does not leave the sign on until the player moves.
+ */
+export declare function ponderingUntil(folder: string, key: string): Date | undefined;
 /** Whether the AI thinks on the player's time in a position now, as noted. */
-export declare function ponderingOn(folder: string, key: string): boolean;
+export declare function ponderingOn(folder: string, key: string, now: Date): boolean;

package/dist/games/thoughts.js

@@ -8,14 +8,17 @@ import { writeAtomically } from "./files.js";
 export function thoughtKey(current, ply = current.game.record.moves.length) {
     return `${current.started}#${ply}`;
 }
-/** Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. */
-export function keepThought(folder, key, thought) {
+/**
+ * Keeps a thought for a position, in place of one for the same reply; thoughts of another position go. The thoughts kept now. A thought kept while the AI
+ * ponders shows it still at work.
+ */
+export function keepThought(folder, key, thought, now) {
     const kept = keptAt(folder, key);
     const thoughts = [...kept.thoughts.filter((one) => one.reply !== thought.reply), thought];
     if (thoughts.length > mostThoughts) {
         throw new Error(`You have ${mostThoughts} thoughts for this position already: they are enough. Nothing changed.`);
     }
-    write(folder, { ...kept, thoughts });
+    write(folder, { ...kept, thoughts, ...(kept.pondering === undefined ? {} : { pondering: now.toISOString() }) });
     return thoughts;
 }
 /** The thought for the player's last move, when the AI is to move and thought of it on their time. */
@@ -37,17 +40,30 @@ export function waitingSince(folder, key, now) {
  * Notes whether the AI thinks on the player's time in a position now, from its first look until it waits for their move, for the page's sign: in the file,
  * since in Codex the agent that thinks has a process of its own (D-98).
  */
-export function notePondering(folder, key, pondering) {
+export function notePondering(folder, key, pondering, now) {
     const { pondering: before, ...kept } = keptAt(folder, key);
-    if ((before === true) !== pondering) {
-        write(folder, pondering ? { ...kept, pondering: true } : kept);
+    if (pondering) {
+        write(folder, { ...kept, pondering: now.toISOString() });
+    }
+    else if (before !== undefined) {
+        write(folder, kept);
     }
 }
-/** Whether the AI thinks on the player's time in a position now, as noted. */
-export function ponderingOn(folder, key) {
+/**
+ * Until when the AI is seen thinking on the player's time in a position, as noted: a while after its last look or thought, so that an agent stopped before
+ * it waits (Esc, its host closed) does not leave the sign on until the player moves.
+ */
+export function ponderingUntil(folder, key) {
     const kept = read(folder);
-    return kept?.key === key && kept.pondering === true;
+    return kept?.key === key && typeof kept.pondering === "string" ? new Date(new Date(kept.pondering).getTime() + ponderSignFor) : undefined;
+}
+/** Whether the AI thinks on the player's time in a position now, as noted. */
+export function ponderingOn(folder, key, now) {
+    const until = ponderingUntil(folder, key);
+    return until !== undefined && now < until;
 }
+// An agent thinks on one reply in well under this; one silent for longer has stopped.
+const ponderSignFor = 5 * 60_000;
 /** The most thoughts kept for a position: a few likely replies, not every legal one. */
 const mostThoughts = 8;
 const fileName = "thoughts.json";
@@ -55,7 +71,8 @@ const thoughtsFile = z.object({
     key: z.string(),
     thoughts: z.array(z.object({ reply: z.string(), move: z.string(), why: z.string() })),
     since: z.iso.datetime().optional(),
-    pondering: z.boolean().optional(),
+    // The time of the AI's last look or thought while it ponders; true, from an older Chesspal, is a sign without its time, taken as gone.
+    pondering: z.union([z.iso.datetime(), z.boolean()]).optional(),
 });
 /** What is kept for a position: nothing yet when the file is for another, or missing. */
 function keptAt(folder, key) {

package/dist/home/index.d.ts

@@ -1,2 +1,3 @@
 export { dataFolder, type System, tableFolder } from "./data-folder.ts";
 export { openFolder } from "./open-folder.ts";
+export { realPath, samePath } from "./same-path.ts";

package/dist/home/index.js

@@ -1,3 +1,4 @@
 // Where the player's data is (D-71): one folder for every chat, apart from the host's folder. Below the commands, beside the games and the profiles.
 export { dataFolder, tableFolder } from "./data-folder.js";
 export { openFolder } from "./open-folder.js";
+export { realPath, samePath } from "./same-path.js";

package/dist/home/same-path.d.ts

@@ -0,0 +1,7 @@
+/** Whether two paths name the same folder: as written, or through the links and junctions on their way; without regard to case on Windows. */
+export declare function samePath(one: string, other: string): boolean;
+/**
+ * A path with the links and junctions on its way followed, as a page's ports are counted from it: two names of one folder give one path. Case, drive
+ * letters and short names stay as written, so a path with no link stays as it was. A folder not made yet keeps the rest of its path as written.
+ */
+export declare function realPath(path: string): string;

package/dist/home/same-path.js

@@ -0,0 +1,24 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+/** Whether two paths name the same folder: as written, or through the links and junctions on their way; without regard to case on Windows. */
+export function samePath(one, other) {
+    // The same path as written needs no disk: only two different names may be one folder.
+    return sameText(resolve(one), resolve(other)) || sameText(realPath(one), realPath(other));
+}
+/**
+ * A path with the links and junctions on its way followed, as a page's ports are counted from it: two names of one folder give one path. Case, drive
+ * letters and short names stay as written, so a path with no link stays as it was. A folder not made yet keeps the rest of its path as written.
+ */
+export function realPath(path) {
+    const written = resolve(path);
+    try {
+        return realpathSync(written);
+    }
+    catch {
+        const parent = dirname(written);
+        return parent === written ? written : join(realPath(parent), basename(written));
+    }
+}
+function sameText(one, other) {
+    return process.platform === "win32" ? one.toLowerCase() === other.toLowerCase() : one === other;
+}

package/dist/host-files/host-files.d.ts

@@ -11,6 +11,11 @@ export declare function setUpHosts(folder: string, platform: string): string[];
 export declare function outdatedHostFiles(folder: string, platform: string): string[];
 /** Where Codex reads a folder's hooks, which it runs only once the player trusts them. */
 export declare function codexHooksPath(folder: string): string;
+/**
+ * Whether the host runs the doorbell's hook init writes, Claude Code and Codex by the names they give the server, so the player's act on the page wakes
+ * the chat; the command line, which names no host, is taken as one. Elsewhere the player tells the chat in its window.
+ */
+export declare function hasDoorbell(host: string | undefined): boolean;
 /** The instructions of the AI opponent, read from the package wherever it is installed: the MCP server's `instructions` tool gives them (D-102). */
 export declare function opponentInstructions(): string;
 /** The lines that start a chat, in the MCP server's instructions and in AGENTS.md: call `instructions`, then `status` (D-102). */