chesspal 0.2.3 → 0.3.0

package/dist/games/current-game.js

@@ -1,10 +1,10 @@
 // The player's current game on disk (D-27, D-41): game.json, its PGN and the talk on the board page inside, written whole at every change, and kept in
 // memory while nobody else changes it.
-import { readFileSync, rmSync, statSync } from "node:fs";
+import { readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { Game, readPgn, writePgn } from "../core/index.js";
-import { writeAtomically } from "./files.js";
+import { stampOf, whileLocked, writeAtomically } from "./files.js";
 /** The current game of a folder, as it is on disk, or undefined when there is none. A game.json Chesspal cannot read throws: nothing overwrites it. */
 export function loadGame(folder) {
     const path = join(folder, fileName);
@@ -21,27 +21,41 @@ export function loadGame(folder) {
     kept.set(path, { stamp, current });
     return current;
 }
-/** Writes the current game to game.json, whole or not at all; from then on it is the one kept in memory. */
+/**
+ * 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.
+ */
 export function saveGame(folder, current) {
     const path = join(folder, fileName);
-    const file = {
-        format: 1,
-        ai: current.ai,
-        started: current.started,
-        pgn: writePgn(current.game.record),
-        ...(current.talk.length === 0 ? {} : { talk: current.talk }),
-        ...(current.clock === undefined ? {} : { clock: savedClockOf(current.clock) }),
-        ...(drawOfferOf(current) === undefined ? {} : { drawOffer: current.drawOffer }),
+    whileLocked(path, () => {
+        if (stampOf(path) !== kept.get(path)?.stamp) {
+            kept.delete(path);
+            throw new GameChanged();
+        }
+        write(path, current);
+    });
+}
+/** 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 class GameChanged extends Error {
+    constructor() {
+        super("The game changed on disk while this call was changing it, in another chat or on the board page: call it again. Nothing changed.");
+    }
+}
+/** Runs a change of the game, and once more from the start when another process changed the game under it: a second refusal stands. */
+export function rerunIfChanged(run) {
+    const again = (error) => {
+        if (!(error instanceof GameChanged)) {
+            throw error;
+        }
+        return run();
     };
     try {
-        writeAtomically(path, `${JSON.stringify(file, null, 2)}\n`);
+        const result = run();
+        return result instanceof Promise ? result.catch(again) : result;
     }
     catch (error) {
-        // The live game may hold a move the file does not: the next call reads the file again.
-        kept.delete(path);
-        throw new Error(`Chesspal could not save the game: ${error.message} Nothing changed.`, { cause: error });
+        return again(error);
     }
-    kept.set(path, { stamp: stampOf(path) ?? "", current });
 }
 /** How the game ended, or undefined while it goes on: by the board, or by what the record says, such as a resignation. */
 export function endOf(game) {
@@ -73,7 +87,14 @@ export function removeGame(folder) {
 }
 const fileName = "game.json";
 /** A line of the talk as game.json and talk.json keep it. */
-export const savedLine = z.object({ who: z.enum(["player", "ai"]), text: z.string(), ply: z.int().min(0), at: z.iso.datetime(), agent: z.literal(true).optional() });
+export const savedLine = z.object({
+    who: z.enum(["player", "ai"]),
+    text: z.string(),
+    ply: z.int().min(0),
+    at: z.iso.datetime(),
+    agent: z.literal(true).optional(),
+    shown: z.object({ game: z.string(), at: z.int().min(0), move: z.string().optional() }).optional(),
+});
 const savedClock = z.object({
     base: z.int().positive(),
     increment: z.int().min(0),
@@ -93,10 +114,25 @@ const gameFile = z.object({
 });
 // The games read or written in this process, by their file, with the file's stamp then: a call reads a file again only when another process changed it.
 const kept = new Map();
-function stampOf(path) {
-    // The file's id changes at every rename: a write within the same tick of the clock, and of the same size, is seen too.
-    const stats = statSync(path, { bigint: true, throwIfNoEntry: false });
-    return stats === undefined ? undefined : `${stats.ino}:${stats.mtimeNs}:${stats.size}`;
+function write(path, current) {
+    const file = {
+        format: 1,
+        ai: current.ai,
+        started: current.started,
+        pgn: writePgn(current.game.record),
+        ...(current.talk.length === 0 ? {} : { talk: current.talk }),
+        ...(current.clock === undefined ? {} : { clock: savedClockOf(current.clock) }),
+        ...(drawOfferOf(current) === undefined ? {} : { drawOffer: current.drawOffer }),
+    };
+    try {
+        writeAtomically(path, `${JSON.stringify(file, null, 2)}\n`);
+    }
+    catch (error) {
+        // The live game may hold a move the file does not: the next call reads the file again.
+        kept.delete(path);
+        throw new Error(`Chesspal could not save the game: ${error.message} Nothing changed.`, { cause: error });
+    }
+    kept.set(path, { stamp: stampOf(path) ?? "", current });
 }
 function parsed(text, path) {
     try {

package/dist/games/files.d.ts

@@ -1,7 +1,14 @@
 /** Writes a file whole or not at all: a temporary file beside it, then renamed over it (D-27). A failure says what to do about it. */
 export declare function writeAtomically(path: string, text: string | Uint8Array): void;
+/**
+ * Runs `write` while this process alone holds the file's lock, a folder beside it made only if missing, cheaper than a file on Windows: another process
+ * waits, a second at most. A lock older than two seconds is of a process that stopped while it held it, and goes.
+ */
+export declare function whileLocked<T>(path: string, write: () => T): T;
 /** Makes a folder, and those above it, when missing. A failure says what to do about it. */
 export declare function makeFolder(path: string): void;
+/** A stamp of a file that changes whenever it is written, whoever writes it; undefined when there is none. */
+export declare function stampOf(path: string): string | undefined;
 /**
  * Renames a file or a folder. Windows refuses while another program holds a file in it open (an editor, an antivirus, a sync client): Chesspal waits a
  * little and tries again, half a second at most.

package/dist/games/files.js

@@ -1,5 +1,5 @@
 // Writing the player's files safely: whole or not at all, with failures that say what to do (D-27).
-import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 /** Writes a file whole or not at all: a temporary file beside it, then renamed over it (D-27). A failure says what to do about it. */
 export function writeAtomically(path, text) {
     const temporary = `${path}.${process.pid}.tmp`;
@@ -14,6 +14,40 @@ export function writeAtomically(path, text) {
         rmSync(temporary, { force: true });
     }
 }
+/**
+ * Runs `write` while this process alone holds the file's lock, a folder beside it made only if missing, cheaper than a file on Windows: another process
+ * waits, a second at most. A lock older than two seconds is of a process that stopped while it held it, and goes.
+ */
+export function whileLocked(path, write) {
+    const lock = `${path}.lock`;
+    for (let attempt = 1;; attempt++) {
+        try {
+            mkdirSync(lock);
+            break;
+        }
+        catch (error) {
+            // Windows refuses to make a folder another process is deleting: the lock is still held.
+            if (!["EEXIST", "EPERM", "EACCES"].includes(error.code ?? "")) {
+                throw new Error(`${lock} could not be made (${error.message}): check that its folder can be written.`, { cause: error });
+            }
+            if (isStale(lock)) {
+                rmSync(lock, { recursive: true, force: true });
+            }
+            else if (attempt === lockAttempts) {
+                throw new Error(`${lock} is held by another Chesspal writing the game: try again in a moment, or delete that folder when no Chesspal runs.`);
+            }
+            else {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5);
+            }
+        }
+    }
+    try {
+        return write();
+    }
+    finally {
+        rmdirSync(lock);
+    }
+}
 /** Makes a folder, and those above it, when missing. A failure says what to do about it. */
 export function makeFolder(path) {
     try {
@@ -23,7 +57,20 @@ export function makeFolder(path) {
         throw new Error(`${path} could not be made (${error.message}): check that it is a folder, and can be written.`, { cause: error });
     }
 }
+/** A stamp of a file that changes whenever it is written, whoever writes it; undefined when there is none. */
+export function stampOf(path) {
+    // The file's id changes at every rename: a write within the same tick of the clock, and of the same size, is seen too.
+    const stats = statSync(path, { bigint: true, throwIfNoEntry: false });
+    return stats === undefined ? undefined : `${stats.ino}:${stats.mtimeNs}:${stats.size}`;
+}
 const attempts = 10;
+// A lock is waited for 5 ms at a time, a second at most; one older than two seconds is of a process that stopped while it held it.
+const lockAttempts = 200;
+const staleLock = 2_000;
+function isStale(lock) {
+    const stats = statSync(lock, { throwIfNoEntry: false });
+    return stats !== undefined && Date.now() - stats.mtimeMs > staleLock;
+}
 /**
  * Renames a file or a folder. Windows refuses while another program holds a file in it open (an editor, an antivirus, a sync client): Chesspal waits a
  * little and tries again, half a second at most.

package/dist/games/index.d.ts

@@ -1,11 +1,11 @@
-export { aiHostOf, aiModelOf, noteAiHost, noteAiModel } from "./ai-model.ts";
-export { type Analysis, endAnalysis, gameInAnalysis, startAnalysis } from "./analysis.ts";
+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 { 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, type GameEnd, gameStamp, loadGame, removeGame, saveGame, type Speaker, type TalkLine } from "./current-game.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 { endTableTalk, loadTableTalk, saveTableTalk, type TableTalk } from "./table-talk.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";

package/dist/games/index.js

@@ -1,12 +1,12 @@
 // 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, noteAiHost, noteAiModel } from "./ai-model.js";
-export { endAnalysis, gameInAnalysis, startAnalysis } from "./analysis.js";
+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 { 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, gameStamp, loadGame, removeGame, saveGame } from "./current-game.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 { endTableTalk, loadTableTalk, saveTableTalk } from "./table-talk.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";

package/dist/games/table-talk.d.ts

@@ -8,5 +8,7 @@ export interface TableTalk {
 export declare function loadTableTalk(folder: string): TableTalk;
 /** Writes the talk with no game, whole or not at all. */
 export declare function saveTableTalk(folder: string, table: TableTalk): void;
+/** A stamp of talk.json that changes whenever it is written; undefined when there is none. */
+export declare function tableTalkStamp(folder: string): string | undefined;
 /** Forgets the talk with no game, when a game starts. */
 export declare function endTableTalk(folder: string): void;

package/dist/games/table-talk.js

@@ -3,7 +3,7 @@ import { readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { savedLine } from "./current-game.js";
-import { writeAtomically } from "./files.js";
+import { stampOf, writeAtomically } from "./files.js";
 /** The talk with no game: empty when there is none, or talk.json cannot be read, since it is only words. */
 export function loadTableTalk(folder) {
     try {
@@ -17,6 +17,10 @@ export function loadTableTalk(folder) {
 export function saveTableTalk(folder, table) {
     writeAtomically(join(folder, fileName), `${JSON.stringify(table, null, 2)}\n`);
 }
+/** A stamp of talk.json that changes whenever it is written; undefined when there is none. */
+export function tableTalkStamp(folder) {
+    return stampOf(join(folder, fileName));
+}
 /** Forgets the talk with no game, when a game starts. */
 export function endTableTalk(folder) {
     rmSync(join(folder, fileName), { force: true });

package/dist/games/talk.d.ts

@@ -1,4 +1,4 @@
-import { type CurrentGame, type Speaker, type TalkLine } from "./current-game.ts";
+import { type CurrentGame, type Shown, type Speaker, type TalkLine } from "./current-game.ts";
 import type { TableTalk } from "./table-talk.ts";
 /** The most the player may write in a move, in all their lines, and the most a line of the AI's may hold (D-54); with the helps on, as an analyst's note (D-78). */
 export declare const talkLimits: {
@@ -14,7 +14,7 @@ export type Talk = CurrentGame | TableTalk;
  * A new line of the talk, said when the game has `ply` moves: refused when it is empty or too long. The player writes 200 characters a move in all, the
  * words sent with the move included; the AI speaks once a move of theirs, on their time, and its agent's word leaves it an answer to what they write after (D-54, D-72).
  */
-export declare function talkLine(current: Talk, sayer: Sayer, text: string, at: Date, ply?: number, aiMost?: number): TalkLine;
+export declare function talkLine(current: Talk, sayer: Sayer, text: string, at: Date, ply?: number, aiMost?: number, shown?: Shown): TalkLine;
 /** Words refused, and why, for the page to say it in the player's language: none, the move's characters spent, more than a line or what is left holds. */
 export declare class WordsRefused extends Error {
     readonly reason: "empty" | "spent" | "long" | "longer-than-left";
@@ -23,10 +23,11 @@ export declare class WordsRefused extends Error {
 }
 /** Whether the player's last line wakes the chat: the first of a move, and between games the first since the AI last spoke (D-54, D-74). */
 export declare function wakesTheChat(current: Talk): boolean;
-/** Words of the player's, with the key that tells them apart across games. */
+/** Words of the player's, with the key that tells them apart across games, and in analysis the position the page showed (D-101). */
 export interface Words {
     readonly key: string;
     readonly text: string;
+    readonly shown?: Shown;
 }
 /** What the player said that the AI has not answered, but for the words whose keys are in `given`. */
 export declare function unheardWords(current: Talk, given: ReadonlySet<string>): Words[];

package/dist/games/talk.js

@@ -6,7 +6,7 @@ export const talkLimits = { player: 200, ai: 300, aiHelps: 700 };
  * A new line of the talk, said when the game has `ply` moves: refused when it is empty or too long. The player writes 200 characters a move in all, the
  * words sent with the move included; the AI speaks once a move of theirs, on their time, and its agent's word leaves it an answer to what they write after (D-54, D-72).
  */
-export function talkLine(current, sayer, text, at, ply = isGame(current) ? current.game.record.moves.length : 0, aiMost = talkLimits.ai) {
+export function talkLine(current, sayer, text, at, ply = isGame(current) ? current.game.record.moves.length : 0, aiMost = talkLimits.ai, shown) {
     const who = sayer === "agent" ? "ai" : sayer;
     const words = text.trim();
     const most = who === "player" ? wordsLeft(current) : aiMost;
@@ -23,7 +23,7 @@ export function talkLine(current, sayer, text, at, ply = isGame(current) ? curre
     if (who === "ai" && isGame(current)) {
         refuseAiWords(current, sayer === "agent");
     }
-    return { who, text: words, ply, at: at.toISOString(), ...(sayer === "agent" ? { agent: true } : {}) };
+    return { who, text: words, ply, at: at.toISOString(), ...(sayer === "agent" ? { agent: true } : {}), ...(shown === undefined ? {} : { shown }) };
 }
 /** Words refused, and why, for the page to say it in the player's language: none, the move's characters spent, more than a line or what is left holds. */
 export class WordsRefused extends Error {
@@ -41,7 +41,7 @@ export function wakesTheChat(current) {
 }
 /** What the player said that the AI has not answered, but for the words whose keys are in `given`. */
 export function unheardWords(current, given) {
-    return unanswered(current).filter(({ key }) => !given.has(key)).map(({ key, line }) => ({ key, text: line.text }));
+    return unanswered(current).filter(({ key }) => !given.has(key)).map(({ key, line }) => ({ key, text: line.text, ...(line.shown === undefined ? {} : { shown: line.shown }) }));
 }
 /** How far each line of the talk got: the player's by `Heard`, the AI's undefined (D-53). */
 export function heardLines(current, given) {

package/dist/home/data-folder.d.ts

@@ -10,3 +10,5 @@ export interface System {
 }
 /** The player's data folder: CHESSPAL_HOME when set, else the system's Documents with Chesspal's folder in it. */
 export declare function dataFolder(system?: System): string;
+/** The table's folder inside the data folder: one for every profile, where the chats the table opens start (D-104). */
+export declare function tableFolder(home: string): string;

package/dist/home/data-folder.js

@@ -3,7 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { posix, win32 } from "node:path";
+import { join, posix, win32 } from "node:path";
 /** The player's data folder: CHESSPAL_HOME when set, else the system's Documents with Chesspal's folder in it. */
 export function dataFolder(system = thisSystem()) {
     const chosen = system.env.CHESSPAL_HOME?.trim();
@@ -16,6 +16,10 @@ export function dataFolder(system = thisSystem()) {
     }
     return posix.join(system.platform === "darwin" ? posix.join(system.home, "Documents") : xdgDocuments(system), "Chesspal");
 }
+/** The table's folder inside the data folder: one for every profile, where the chats the table opens start (D-104). */
+export function tableFolder(home) {
+    return join(home, "table");
+}
 // Where Windows keeps Documents for this user, as Explorer's known folder does: the registry names it, with variables such as %USERPROFILE%.
 const shellFolders = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders";
 function thisSystem() {

package/dist/home/index.d.ts

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

package/dist/home/index.js

@@ -1,3 +1,3 @@
 // 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 } from "./data-folder.js";
+export { dataFolder, tableFolder } from "./data-folder.js";
 export { openFolder } from "./open-folder.js";

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

@@ -22,5 +22,5 @@ export declare function agentFiles(folder: string): {
     path: string;
     text: string;
 }[];
-/** Instructions for the AI, by their file's name in the package's instructions folder. */
-export declare function instructions(name: string): string;
+/** Instructions for the AI, by their file's name in the package's instructions folder: read once, as the version installed has them. */
+export declare function instructionsFile(name: string): string;

package/dist/host-files/agents.js

@@ -38,10 +38,16 @@ export function agentFiles(folder) {
     const agents = agentSpecs();
     return [...agents.map((agent) => claudeAgentFile(folder, agent)), ...agents.map((agent) => codexAgentFile(folder, agent))];
 }
-/** Instructions for the AI, by their file's name in the package's instructions folder. */
-export function instructions(name) {
-    return readFileSync(new URL(`../../instructions/${name}.md`, import.meta.url), "utf8").trim();
+/** Instructions for the AI, by their file's name in the package's instructions folder: read once, as the version installed has them. */
+export function instructionsFile(name) {
+    let text = instructionTexts.get(name);
+    if (text === undefined) {
+        text = readFileSync(new URL(`../../instructions/${name}.md`, import.meta.url), "utf8").trim();
+        instructionTexts.set(name, text);
+    }
+    return text;
 }
+const instructionTexts = new Map();
 const toolsOf = {
     [quickAgent]: ["ponder"],
     [ownAgent]: ["ponder"],
@@ -51,7 +57,7 @@ const toolsOf = {
 // Codex's quick model for the lower levels: written in its agent, since Codex ignores a model the chat names when it starts one that has it (Priya).
 const codexQuickModel = "gpt-6-luna";
 function agentSpecs() {
-    const ponder = instructions("ponder");
+    const ponder = instructionsFile("ponder");
     const thinking = "Chesspal's opponent thinking on the player's time. Started by the AI in the background after its move, as ai_move says.";
     return [
         { agent: quickAgent, claudeModel: "haiku", codexModel: codexQuickModel, description: thinking, text: ponder },
@@ -61,13 +67,13 @@ function agentSpecs() {
             agent: coachAgent,
             claudeModel: "inherit",
             description: "Chesspal's coach. Started only as Chesspal's answers say, in the background, never to answer the player.",
-            text: instructions("coach"),
+            text: instructionsFile("coach"),
         },
         {
             agent: analystAgent,
             claudeModel: "inherit",
             description: "Chesspal's analyst. Started only as Chesspal's answers say, in the background, to review a game over on the board page; never to answer the player.",
-            text: `${instructions("analyst-agent")}\n${instructions("analysis")}`,
+            text: `${instructionsFile("analyst-agent")}\n${instructionsFile("analysis")}`,
         },
     ];
 }

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

@@ -1,6 +1,6 @@
 /**
- * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the opponent's instructions between
- * Chesspal's marks, CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
+ * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the lines that start a chat between
+ * Chesspal's marks (D-102), CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
  * the files written.
  */
 export declare function setUpHosts(folder: string, platform: string): string[];
@@ -11,5 +11,7 @@ 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;
-/** The instructions of the AI opponent, read from the package wherever it is installed. */
+/** 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). */
+export declare function startInstructions(): string;

package/dist/host-files/host-files.js

@@ -1,11 +1,11 @@
-// What `chesspal init` writes in a player's folder for each AI host: the opponent's instructions, the MCP server, the hooks and the agents.
+// What `chesspal init` writes in a player's folder for each AI host: the lines that start a chat, the MCP server, the hooks and the agents.
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { makeFolder, writeAtomically } from "../games/index.js";
-import { agentFiles, instructions } from "./agents.js";
+import { agentFiles, instructionsFile } from "./agents.js";
 /**
- * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the opponent's instructions between
- * Chesspal's marks, CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
+ * Sets up the player's folder for Claude Code and Codex (D-31): .mcp.json with the chesspal server, AGENTS.md with the lines that start a chat between
+ * Chesspal's marks (D-102), CLAUDE.md importing it, the hosts' settings with the server approved, and their hooks. What the player wrote there stays; it returns
  * the files written.
  */
 export function setUpHosts(folder, platform) {
@@ -31,9 +31,13 @@ export function outdatedHostFiles(folder, platform) {
 export function codexHooksPath(folder) {
     return join(folder, ".codex", "hooks.json");
 }
-/** The instructions of the AI opponent, read from the package wherever it is installed. */
+/** 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 function opponentInstructions() {
-    return instructions("opponent");
+    return instructionsFile("opponent");
+}
+/** The lines that start a chat, in the MCP server's instructions and in AGENTS.md: call `instructions`, then `status` (D-102). */
+export function startInstructions() {
+    return instructionsFile("start");
 }
 // The marks around Chesspal's lines in AGENTS.md: init rewrites what lies between them, and the player's own text stays around them.
 const startMark = "<!-- chesspal: these lines up to the end mark are Chesspal's, and chesspal init rewrites them; write your own after it. -->";
@@ -60,11 +64,14 @@ function mcpFile(folder, platform) {
     const before = isObject(servers.chesspal) ? servers.chesspal : {};
     return changed(path, { ...config, mcpServers: { ...servers, chesspal: { ...chesspalServer(platform), ...(isObject(before.env) ? { env: before.env } : {}) } } });
 }
-/** AGENTS.md with the opponent's instructions between Chesspal's marks: rewritten when they changed, put first in a file that has none. */
+/**
+ * AGENTS.md with the lines that start a chat between Chesspal's marks, which Codex needs beside the server's instructions (D-31, D-102): rewritten when
+ * they changed, put first in a file that has none.
+ */
 function agentsFile(folder) {
     const path = join(folder, "AGENTS.md");
     const before = textOf(path);
-    const block = [startMark, opponentInstructions(), endMark].join("\n");
+    const block = [startMark, startInstructions(), endMark].join("\n");
     if (before === undefined) {
         return { path, text: `${block}\n` };
     }

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

@@ -1,2 +1,2 @@
-export { agentHosts, agentTools, analystAgent, coachAgent, hasAgent, instructions, isCodex, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.ts";
-export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts } from "./host-files.ts";
+export { agentHosts, agentTools, analystAgent, coachAgent, hasAgent, instructionsFile, isCodex, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.ts";
+export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts, startInstructions } from "./host-files.ts";

package/dist/host-files/index.js

@@ -1,3 +1,3 @@
 // The files through which an AI host finds Chesspal in the player's folder: the server, the opponent's instructions, the hosts' settings.
-export { agentHosts, agentTools, analystAgent, coachAgent, hasAgent, instructions, isCodex, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.js";
-export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts } from "./host-files.js";
+export { agentHosts, agentTools, analystAgent, coachAgent, hasAgent, instructionsFile, isCodex, onQuickModel, ponderAgentFor, ponderAgents } from "./agents.js";
+export { codexHooksPath, opponentInstructions, outdatedHostFiles, setUpHosts, startInstructions } from "./host-files.js";