@khorsheed/dsh-game 0.0.0-stage → 0.1.1

package/lib/types/store.js

@@ -0,0 +1,1383 @@
+/**
+ * The game service core (`ctx.gameStore`): the project registry, session
+ * binding, reading a project for the tools and the panel, the end-of-turn
+ * check flow, versions and the playtest log.
+ *
+ * Storage (proposal §3): a project is a plain directory in the session's
+ * workspace — `game.json`, `index.html`, `src/`, `assets/`, `elements/`,
+ * `design/`, `tests/` — and the plugin's own state lives inside it under
+ * `.game/` (versions, the last check, the playtest log), so the project moves
+ * as one folder. Only the registry (which projects exist, which session is
+ * bound to which) is deployment-level, at `$DSH_HOME/state/game/`.
+ *
+ * The agent writes project files with the ordinary fs tools; the plugin
+ * writes only the manifest and the first chapter at creation (through the
+ * mounted `ctx.fs` with the calling session's policy, so the fence applies)
+ * and its own `.game/` state. Version snapshots copy binary assets, which
+ * `ctx.fs` cannot write, so they go through node behind the same checks the
+ * canvas uses: the session's mode is not read-only and the target sits inside
+ * the project.
+ * @module @khorsheed/dsh-game
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { appendFile, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { ChromeChecker } from "./checks.js";
+import { kitOf, withKitRuntime } from "./kits/index.js";
+import { systemTrash } from "./trash.js";
+import { bundleOf, fingerprintOf, inside, readJson, readText, walk, writeAtomic } from "./fsutil.js";
+import { artStyleLabel, chapterStatus, elementsChapter, gate, loreChapter, isBuildFile, parseManifest, patchElementText, listOf, pillarNotes, resolveArtStyle, serializeManifest, slugOf, validateElements, } from "./project.js";
+import { CHAPTERS, LORE_MAX, MANIFEST_FILE, PANEL_CHANGES_MARK, STATE_DIR, } from "./types.js";
+/** Versions kept under `.game/versions/`; older ones are pruned. */
+const KEEP_VERSIONS = 10;
+/**
+ * Resolve the registry root: explicit value, then `$DSH_HOME/state/game`,
+ * then `<cwd>/.dsh-game` (the canvas precedent).
+ */
+export function resolveGameStateRoot(configured) {
+    if (configured !== undefined && configured !== '')
+        return configured;
+    const home = process.env.DSH_HOME;
+    if (home !== undefined && home !== '')
+        return join(home, 'state', 'game');
+    return join(process.cwd(), '.dsh-game');
+}
+/** Format a number the way the dock shows it (no float noise). */
+function num(value) {
+    return String(Math.round(value * 1000) / 1000);
+}
+/** A change this recent means someone is still writing (a CLI member gives no other sign). */
+const BUSY_QUIET_MS = 20_000;
+/** Build-file paths under a folder with their modification times (no contents read). */
+async function statWalk(root, keep) {
+    const out = [];
+    const visit = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            if (out.length >= 600 || entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(dir, entry.name);
+            const rel = relative(root, full).split(sep).join('/');
+            if (entry.isDirectory()) {
+                await visit(full);
+                continue;
+            }
+            if (!entry.isFile() || !keep(rel))
+                continue;
+            const info = await stat(full).catch(() => undefined);
+            if (info !== undefined)
+                out.push({ path: rel, mtimeMs: info.mtimeMs });
+        }
+    };
+    await visit(root);
+    return out;
+}
+/** The game service core. */
+export class GameService {
+    ctx;
+    static inject = ['fs'];
+    stateRoot;
+    sandboxPolicy;
+    checker;
+    /** Serializes registry read-modify-write cycles. */
+    registryLock = Promise.resolve();
+    listeners = new Set();
+    /**
+     * @param ctx - host context (the mounted `ctx.fs`; `sandboxPolicy` probed).
+     * @param config - plugin config.
+     * @param deps - seams the specs replace.
+     */
+    constructor(ctx, config = {}, deps = {}) {
+        this.ctx = ctx;
+        this.stateRoot = resolveGameStateRoot(config.stateRoot);
+        this.sandboxPolicy = ctx.fs?.sandboxMode === undefined ? undefined : ctx.get('sandboxPolicy');
+        this.checker = deps.checker ?? new ChromeChecker(config.chromePath);
+        if (deps.writer !== undefined)
+            this.writeFenced = deps.writer;
+        this.trash = deps.trash ?? systemTrash();
+    }
+    /** Where a deleted project folder goes (the system trash; specs swap a fake). */
+    trash;
+    /** Release the checker's browser. */
+    async dispose() {
+        await this.checker.dispose();
+    }
+    /** Subscribe to project changes (the Remote face forwards nothing yet; specs and hooks use it). */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    notify(projectId) {
+        for (const listener of this.listeners)
+            listener(projectId);
+    }
+    /** Default fenced write: the mounted fs, stamped with the caller's policy. */
+    writeFenced = async (path, content, session) => {
+        const policy = this.sandboxPolicy?.resolve({ session });
+        const target = await this.ctx.fs.resolve(path);
+        await this.ctx.fs.writeText(target, content, { kind: 'createIfAbsent' }, undefined, policy);
+    };
+    /** Whether the session may have the plugin write into its workspace. */
+    writable(session) {
+        if (session === undefined)
+            return true;
+        return this.sandboxPolicy?.resolve({ session })?.mode !== 'read-only';
+    }
+    // ---------------------------------------------------------------- registry
+    registryPath() {
+        return join(this.stateRoot, 'registry.json');
+    }
+    async readRegistry() {
+        const raw = await readJson(this.registryPath());
+        return {
+            projects: Array.isArray(raw?.projects) ? raw.projects.filter(p => typeof p?.id === 'string' && typeof p.root === 'string') : [],
+            bindings: raw?.bindings !== null && typeof raw?.bindings === 'object' ? { ...raw.bindings } : {},
+        };
+    }
+    /** Read-modify-write the registry under the lock. */
+    async updateRegistry(change) {
+        const run = this.registryLock.then(async () => {
+            const registry = await this.readRegistry();
+            const result = change(registry);
+            await writeAtomic(this.registryPath(), `${JSON.stringify(registry, null, 2)}\n`);
+            return result;
+        });
+        this.registryLock = run.catch(() => { });
+        return run;
+    }
+    /** Every registered project, most recently updated first. */
+    async listProjects() {
+        const { projects } = await this.readRegistry();
+        return [...projects].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+    /** Element files parsed per id, for turn diffs. */
+    async elementIndex(root) {
+        const out = new Map();
+        for (const f of await walk(join(root, 'elements'), p => p.endsWith('.json'))) {
+            let raw;
+            try {
+                raw = JSON.parse(f.data.toString('utf8'));
+            }
+            catch {
+                continue;
+            }
+            for (const item of Array.isArray(raw) ? raw : [raw]) {
+                if (item === null || typeof item !== 'object')
+                    continue;
+                const r = item;
+                if (typeof r.id !== 'string')
+                    continue;
+                const fields = {};
+                for (const [k, v] of Object.entries(r))
+                    if (k !== 'look' && k !== 'id')
+                        fields[k] = JSON.stringify(v);
+                out.set(r.id, { name: typeof r.name === 'string' ? r.name : r.id, json: JSON.stringify(r), look: JSON.stringify(r.look ?? null), fields });
+            }
+        }
+        return out;
+    }
+    /** Snapshot the bound project when a turn starts (undefined when unbound). */
+    async turnBaseline(sessionId) {
+        const row = await this.boundProject(sessionId);
+        if (row === undefined)
+            return undefined;
+        const files = new Map((await walk(row.root, () => true)).map(f => [f.path, createHash('sha1').update(f.data).digest('hex')]));
+        const manifest = await this.manifestOf(row.root);
+        return {
+            at: Date.now(), projectId: row.id, files, elements: await this.elementIndex(row.root),
+            params: Object.fromEntries((manifest?.params ?? []).map(p => [p.key, p.value])),
+            current: (await readJson(join(row.root, STATE_DIR, 'current.json')))?.version,
+            candidate: (await readJson(join(row.root, STATE_DIR, 'candidate.json')))?.version,
+        };
+    }
+    turnsPath(sessionId) {
+        return join(this.stateRoot, 'turns', `${sessionId.replace(/[^\w.-]/g, '_')}.json`);
+    }
+    /**
+     * Compare the project with its turn-start snapshot and store what the turn
+     * changed. Nothing is stored for a turn that changed nothing.
+     */
+    async recordTurn(sessionId, turn, base) {
+        const row = await this.row(base.projectId);
+        if (row === undefined)
+            return undefined;
+        const now = new Map((await walk(row.root, () => true)).map(f => [f.path, createHash('sha1').update(f.data).digest('hex')]));
+        const changed = [...now.keys()].filter(p => base.files.get(p) !== now.get(p));
+        const removed = [...base.files.keys()].filter(p => !now.has(p));
+        const elementsNow = await this.elementIndex(row.root);
+        const elements = [];
+        for (const [id, e] of elementsNow) {
+            const before = base.elements.get(id);
+            if (before === undefined) {
+                elements.push({ id, name: e.name, what: 'new' });
+                continue;
+            }
+            if (before.json === e.json)
+                continue;
+            const fields = [...new Set([...Object.keys(e.fields), ...Object.keys(before.fields)])].filter(k => e.fields[k] !== before.fields[k]);
+            if (before.look !== e.look) {
+                // 3D looks ride along (bounded) so the card can show both side by side; pixel looks have their own preview.
+                const is3d = /"kind":"(parts3d|gltf)"/.test(e.look);
+                const looks = is3d && e.look.length < 8000 && before.look.length < 8000 ? { looks: { before: before.look === 'null' ? null : before.look, after: e.look } } : {};
+                elements.push({ id, name: e.name, what: 'look', ...(fields.length > 0 ? { fields } : {}), ...looks });
+            }
+            else
+                elements.push({ id, name: e.name, what: 'fields', fields });
+        }
+        for (const [id, e] of base.elements)
+            if (!elementsNow.has(id))
+                elements.push({ id, name: e.name, what: 'removed' });
+        const manifest = await this.manifestOf(row.root);
+        const params = (manifest?.params ?? []).filter(p => base.params[p.key] !== p.value)
+            .map(p => ({ key: p.key, label: p.label, to: p.value, ...(base.params[p.key] === undefined ? {} : { from: base.params[p.key] }) }));
+        const chapters = CHAPTERS.filter(c => c.generated !== true && [...changed, ...removed].includes(c.file)).map(c => ({ id: c.id, title: c.title }));
+        const code = [...changed, ...removed].filter(p => isBuildFile(p) && !p.startsWith('elements/') && p !== MANIFEST_FILE);
+        const tests = changed.filter(p => p.startsWith('tests/'));
+        const current = (await readJson(join(row.root, STATE_DIR, 'current.json')))?.version;
+        const candidate = (await readJson(join(row.root, STATE_DIR, 'candidate.json')))?.version;
+        const version = candidate !== undefined && candidate !== base.candidate ? { kind: 'candidate', version: candidate }
+            : current !== undefined && current !== base.current ? { kind: 'deployed', version: current } : null;
+        const last = await readJson(join(row.root, STATE_DIR, 'checks.json'));
+        const check = last !== undefined && new Date(last.at).getTime() >= base.at
+            ? { ok: last.ok, fixes: last.attempt, gaveUp: last.gaveUp === true, passed: last.passed, failures: last.failures.length }
+            : null;
+        if (elements.length + params.length + chapters.length + code.length + tests.length === 0 && version === null && check === null)
+            return undefined;
+        const report = {
+            turn, projectId: row.id, title: manifest?.title ?? row.title, at: new Date().toISOString(),
+            version, check, elements, chapters, params, code: code.slice(0, 20), tests,
+        };
+        const path = this.turnsPath(sessionId);
+        const all = (await readJson(path)) ?? {};
+        all[String(turn)] = report;
+        const keys = Object.keys(all).map(Number).sort((a, b) => b - a);
+        for (const k of keys.slice(200))
+            delete all[String(k)];
+        await writeAtomic(path, `${JSON.stringify(all)}\n`);
+        this.notify(row.id);
+        return report;
+    }
+    /** A stored turn report. */
+    async turnReport(sessionId, turn) {
+        const all = await readJson(this.turnsPath(sessionId));
+        return all?.[String(turn)] ?? null;
+    }
+    /** Every project as a switcher card (manifest summary, live version, last screenshot), most recent first. */
+    async projectCards() {
+        const cards = [];
+        for (const row of await this.listProjects()) {
+            const manifest = await this.manifestOf(row.root);
+            const current = await readJson(join(row.root, STATE_DIR, 'current.json'));
+            const elementFiles = await walk(join(row.root, 'elements'), p => p.endsWith('.json'));
+            const { elements } = validateElements(Object.fromEntries(elementFiles.map(f => [`elements/${f.path}`, f.data.toString('utf8')])), [], kitOf(manifest?.runtime));
+            const thumb = await readFile(join(row.root, STATE_DIR, 'last-check.webp')).catch(() => undefined);
+            cards.push({
+                id: row.id, title: manifest?.title ?? row.title, root: row.root, updatedAt: row.updatedAt,
+                pitch: manifest?.pitch ?? '', artStyle: manifest?.artStyle ?? '', version: current?.version ?? null, elements: elements.length,
+                ...(thumb === undefined || thumb.length > 400_000 ? {} : { thumb: thumb.toString('base64') }),
+            });
+        }
+        return cards;
+    }
+    /** The project a session is bound to, if any. */
+    async boundProject(sessionId) {
+        const registry = await this.readRegistry();
+        const id = registry.bindings[sessionId];
+        return id === undefined ? undefined : registry.projects.find(p => p.id === id);
+    }
+    /** Bind a session to a project (or unbind with null). */
+    async bind(sessionId, projectId) {
+        return this.updateRegistry(registry => {
+            if (projectId === null) {
+                delete registry.bindings[sessionId];
+                return { ok: true };
+            }
+            if (!registry.projects.some(p => p.id === projectId))
+                return { ok: false, error: 'not-found' };
+            registry.bindings[sessionId] = projectId;
+            return { ok: true };
+        });
+    }
+    async touch(projectId) {
+        await this.updateRegistry(registry => {
+            const row = registry.projects.find(p => p.id === projectId);
+            if (row !== undefined)
+                Object.assign(row, { updatedAt: new Date().toISOString() });
+        }).catch(() => { });
+        this.notify(projectId);
+    }
+    /**
+     * Register an existing folder that holds a `game.json` (a project copied
+     * in, or one whose registry row was lost).
+     */
+    async adopt(root) {
+        const manifestText = await readText(join(root, MANIFEST_FILE));
+        if (manifestText === undefined)
+            return { ok: false, error: 'not-found' };
+        const parsed = parseManifest(manifestText);
+        if (!parsed.ok)
+            return { ok: false, error: 'invalid' };
+        return this.updateRegistry(registry => {
+            const existing = registry.projects.find(p => p.root === root || p.id === parsed.manifest.id);
+            if (existing !== undefined)
+                return { ok: true, project: existing };
+            const now = new Date().toISOString();
+            const row = { id: parsed.manifest.id, title: parsed.manifest.title, root, createdAt: parsed.manifest.createdAt || now, updatedAt: now };
+            registry.projects.push(row);
+            return { ok: true, project: row };
+        });
+    }
+    /**
+     * Delete a project from the panel. `trash` takes it out of the plugin
+     * (registry row and every session binding) AND moves its folder to the
+     * system trash — complete, yet recoverable; `forget` only takes it out of
+     * the plugin and leaves the folder (re-adopt with `game_open path`).
+     *
+     * Guards, checked before anything changes: the folder must still hold the
+     * project's own `game.json` (never trash an arbitrary directory a registry
+     * row happens to point at), must not be the calling session's workspace
+     * itself, and a read-only session may do neither. A failed move changes
+     * nothing, so the panel can offer `forget` instead.
+     */
+    async deleteProject(projectId, mode, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        let trashedTo;
+        if (mode === 'trash') {
+            const manifest = await this.manifestOf(row.root);
+            const cwd = session?.header?.cwd;
+            if (manifest === undefined || manifest.id !== projectId)
+                return { ok: false, error: 'not-a-project' };
+            if (cwd !== undefined && resolve(cwd) === resolve(row.root))
+                return { ok: false, error: 'is-workspace' };
+            try {
+                trashedTo = await this.trash(row.root);
+            }
+            catch (error) {
+                return { ok: false, error: 'trash-failed', reason: error.message.split('\n')[0] ?? '' };
+            }
+        }
+        await this.updateRegistry(registry => {
+            registry.projects = registry.projects.filter(p => p.id !== projectId);
+            for (const [sid, bound] of Object.entries(registry.bindings))
+                if (bound === projectId)
+                    delete registry.bindings[sid];
+        });
+        this.notify(projectId);
+        return { ok: true, ...(trashedTo === undefined ? {} : { trashedTo }) };
+    }
+    // ---------------------------------------------------------------- create
+    /**
+     * Create a project in the session's workspace behind the light gate, and
+     * bind the session to it.
+     * @param request - the gate's inputs.
+     * @param session - the calling session (its workspace and fence).
+     * @returns the new row, the gate's missing items, or a failure.
+     */
+    async create(request, session) {
+        const verdict = gate(request);
+        if (!verdict.ok)
+            return { ok: false, missing: verdict.missing };
+        const cwd = session.header?.cwd;
+        if (cwd === undefined || cwd === '')
+            return { ok: false, error: '这个会话没有工作区，项目没处放。请用户先给会话选一个工作区。' };
+        if (!this.writable(session))
+            return { ok: false, error: '这个会话是只读模式，不能新建项目。' };
+        const registry = await this.readRegistry();
+        const base = slugOf(verdict.manifest.title);
+        let folder = base;
+        for (let n = 2; registry.projects.some(p => p.root === join(cwd, folder)) || await stat(join(cwd, folder)).then(() => true, () => false); n++) {
+            folder = `${base}-${n}`;
+        }
+        const root = join(cwd, folder);
+        const id = `g_${randomBytes(4).toString('hex')}`;
+        const now = new Date().toISOString();
+        const manifest = { ...verdict.manifest, id, createdAt: now };
+        try {
+            await this.writeFenced(join(root, MANIFEST_FILE), serializeManifest(manifest), session);
+        }
+        catch (error) {
+            return { ok: false, error: `写不进工作区：${error.message.split('\n')[0]}` };
+        }
+        const row = { id, title: manifest.title, root, createdAt: now, updatedAt: now };
+        await this.updateRegistry(r => {
+            r.projects.push(row);
+            r.bindings[session.id] = id;
+        });
+        this.notify(id);
+        return { ok: true, project: row };
+    }
+    // ---------------------------------------------------------------- read
+    async row(projectId) {
+        return (await this.readRegistry()).projects.find(p => p.id === projectId);
+    }
+    /**
+     * Everything the panel and `game_read` show about one project.
+     * @param projectId - registry id.
+     * @returns the view, or undefined for an unknown id.
+     */
+    async view(projectId) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return undefined;
+        const manifestText = await readText(join(row.root, MANIFEST_FILE));
+        const parsed = manifestText === undefined ? undefined : parseManifest(manifestText);
+        const manifest = parsed?.ok === true ? parsed.manifest : null;
+        const elementFiles = await walk(join(row.root, 'elements'), p => p.endsWith('.json'));
+        const { elements, failures } = validateElements(Object.fromEntries(elementFiles.map(f => [`elements/${f.path}`, f.data.toString('utf8')])), manifest?.elementTypes ?? [], kitOf(manifest?.runtime));
+        const playtest = await this.playtestText(row.root);
+        const chapters = [];
+        for (const spec of CHAPTERS) {
+            const text = spec.id === 'elements'
+                ? elementsChapter(elements, manifest?.elementTypes ?? [])
+                : spec.id === 'lore' ? loreChapter(elements, manifest?.elementTypes ?? [])
+                    : spec.id === 'playtest' ? playtest
+                        : spec.id === 'pillars' ? pillarNotes((await readText(join(row.root, spec.file))) ?? '', manifest)
+                            : (await readText(join(row.root, spec.file))) ?? '';
+            const source = spec.id === 'playtest' ? join(row.root, STATE_DIR, 'playtest-log.jsonl') : spec.id === 'elements' || spec.id === 'lore' ? join(row.root, 'elements') : join(row.root, spec.file);
+            const mtime = await stat(source).then(info => info.mtimeMs, () => 0);
+            chapters.push({
+                id: spec.id, title: spec.title, file: spec.file, text, generated: spec.generated === true, mtime,
+                status: spec.generated === true ? (text === '' ? 'todo' : 'draft') : chapterStatus(text),
+            });
+        }
+        const state = join(row.root, STATE_DIR);
+        const user = await this.userLayer(row.root);
+        const params = manifest?.params ?? [];
+        const paramOverrides = Object.fromEntries(Object.entries(user.params).filter(([key, value]) => {
+            const param = params.find(p => p.key === key);
+            return param !== undefined && param.value !== value;
+        }));
+        return {
+            id: row.id,
+            title: manifest?.title ?? row.title,
+            root: row.root,
+            manifest,
+            ...(manifestText === undefined ? { manifestError: `${MANIFEST_FILE} 不见了` } : parsed?.ok === false ? { manifestError: parsed.error } : {}),
+            chapters,
+            // Each element carries its file's last change, so the panel can list the newest first.
+            elements: await Promise.all(elements.map(async (e) => {
+                const info = await stat(join(row.root, e.file)).catch(() => undefined);
+                return info === undefined ? e : { ...e, updatedAt: info.mtimeMs };
+            })),
+            elementErrors: failures,
+            current: (await readJson(join(state, 'current.json'))) ?? null,
+            candidate: (await readJson(join(state, 'candidate.json'))) ?? null,
+            lastCheck: (await readJson(join(state, 'checks.json'))) ?? null,
+            hasEntry: await stat(join(row.root, 'index.html')).then(() => true, () => false),
+            paramOverrides,
+            pending: user.pending,
+            uncommitted: user.edits,
+            proposals: await this.proposals(row.root),
+            versions: await this.versionRows(row.root),
+            log: await this.logEntries(row.root),
+            ...(user.restyleTo === undefined ? {} : { restyleTo: user.restyleTo }),
+            candidateDiff: await this.candidateDiff(row.root),
+        };
+    }
+    /** Elements the waiting candidate changed or added against the live version (null without both). */
+    async candidateDiff(root) {
+        const current = await readJson(join(root, STATE_DIR, 'current.json'));
+        const candidate = await readJson(join(root, STATE_DIR, 'candidate.json'));
+        if (current === undefined || candidate === undefined)
+            return null;
+        const before = await this.elementIndex(join(root, STATE_DIR, 'versions', String(current.version)));
+        const after = await this.elementIndex(join(root, STATE_DIR, 'versions', String(candidate.version)));
+        const changed = [], added = [];
+        for (const [id, e] of after) {
+            const was = before.get(id);
+            if (was === undefined)
+                added.push(id);
+            else if (was.json !== e.json)
+                changed.push(id);
+        }
+        return { changed, added };
+    }
+    /** The tab's state for one session. */
+    /**
+     * The bound project's newest version (the waiting candidate, else the live
+     * one), read from two small files: the page polls it to announce a version
+     * the moment it lands, whoever's turn cut it. Version 0 means none yet.
+     */
+    async liveVersion(sessionId) {
+        const row = await this.boundProject(sessionId);
+        if (row === undefined)
+            return null;
+        const state = join(row.root, STATE_DIR);
+        const candidate = await readJson(join(state, 'candidate.json'));
+        const record = candidate ?? (await readJson(join(state, 'current.json')));
+        const show = this.shows.get(row.id);
+        const extra = show === undefined ? {} : { show };
+        if (record === undefined)
+            return { projectId: row.id, version: 0, kind: 'none', at: null, ...extra };
+        return { projectId: row.id, version: record.version, kind: candidate !== undefined ? 'candidate' : 'deployed', at: record.at, ...(record.by === undefined ? {} : { by: record.by }), ...extra };
+    }
+    /** The agent's latest 「请用户看这里」 per project (in memory: a request is for the moment, not history). */
+    shows = new Map();
+    showSeq = 0;
+    /**
+     * After a passing `game_publish`: leave the pages showing this project a
+     * request to take their game tab to the result. `show` is the agent's choice
+     * (play, versions, elements, elements:<id or name>, design:<chapter>); left
+     * out — or not found — the version decides: the one element it changed, the
+     * grid when several, else the play area (a candidate always opens play,
+     * where it waits for the user's OK). Pages pick it up on their poll.
+     * @returns a line for the tool's answer.
+     */
+    async showAfterPublish(sessionId, version, candidate, show, note) {
+        const row = await this.boundProject(sessionId);
+        const project = row === undefined ? undefined : await this.view(row.id);
+        if (row === undefined || project === undefined)
+            return '';
+        let target = null;
+        let refused = '';
+        const asked = (show ?? '').trim();
+        if (asked !== '') {
+            const [view, ...rest] = asked.split(':');
+            const name = rest.join(':').trim();
+            if (view === 'play' || view === 'versions' || (view === 'elements' && name === ''))
+                target = { view };
+            else if (view === 'elements') {
+                const e = project.elements.find(x => x.id === name || x.name === name);
+                if (e !== undefined)
+                    target = { view, elementId: e.id };
+            }
+            else if (view === 'design') {
+                const c = project.chapters.find(x => x.id === name || x.title === name);
+                if (c !== undefined)
+                    target = { view, chapterId: c.id };
+            }
+            if (target === null)
+                refused = `（show「${asked}」找不到，改用默认位置）`;
+        }
+        let changedNames = [];
+        if (target === null) {
+            const decided = candidate ? { target: { view: 'play' }, names: [] } : await this.changedBy(row.root, version);
+            target = decided.target;
+            changedNames = decided.names;
+        }
+        const words = (note ?? '').trim();
+        const text = words !== '' ? words
+            : candidate ? `v${version} 等你确认上线`
+                : changedNames.length > 0 ? `v${version}：改了${changedNames.slice(0, 3).join('、')}${changedNames.length > 3 ? ` 等 ${changedNames.length} 个` : ''}`
+                    : `v${version} 已上线`;
+        this.shows.set(row.id, { seq: ++this.showSeq, target, note: text.slice(0, 120), at: new Date().toISOString() });
+        this.notify(row.id);
+        const where = target.view === 'play' ? '试玩' : target.view === 'versions' ? '版本' : target.view === 'design' ? `策划·${target.chapterId}` : target.elementId === undefined ? '元素列表' : `元素「${target.elementId}」`;
+        return `右栏会打开：${where}${refused}。`;
+    }
+    /** Where a version's change is: the one element it changed, the grid for several, else play (code, assets, a first version). */
+    async changedBy(root, version) {
+        const earlier = (await this.readVersions(root)).map(v => v.version).filter(v => v < version);
+        const play = { target: { view: 'play' }, names: [] };
+        if (earlier.length === 0)
+            return play;
+        const prev = Math.max(...earlier);
+        const dir = (v) => join(root, STATE_DIR, 'versions', String(v));
+        if (!await stat(dir(prev)).then(() => true, () => false))
+            return play;
+        const [before, after] = await Promise.all([this.elementIndex(dir(prev)), this.elementIndex(dir(version))]);
+        const changed = [...after].filter(([id, e]) => before.get(id)?.json !== e.json);
+        const others = async (v) => new Map((await walk(dir(v), p => !p.startsWith('elements/'))).map(f => [f.path, f.data.toString('base64')]));
+        const [a, b] = await Promise.all([others(prev), others(version)]);
+        const otherChanged = a.size !== b.size || [...b].some(([p, d]) => a.get(p) !== d);
+        const names = changed.map(([, e]) => e.name);
+        if (otherChanged || changed.length === 0)
+            return { target: { view: 'play' }, names };
+        if (changed.length === 1)
+            return { target: { view: 'elements', elementId: changed[0][0] }, names };
+        return { target: { view: 'elements' }, names };
+    }
+    async sessionState(sessionId) {
+        const bound = await this.boundProject(sessionId);
+        return {
+            bound: bound === undefined ? null : (await this.view(bound.id)) ?? null,
+            projects: await this.listProjects(),
+        };
+    }
+    /**
+     * One build file as it is in the working folder now (a model the user just
+     * exported, say), for a panel preview ahead of any version. Build files only,
+     * inside the project, 8 MB at most.
+     */
+    async workingFile(projectId, path) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const rel = path.replace(/^\.\//, '');
+        const full = resolve(row.root, rel);
+        if (!isBuildFile(rel) || !inside(row.root, full))
+            return { ok: false, error: 'invalid' };
+        const info = await stat(full).catch(() => undefined);
+        if (info === undefined || !info.isFile() || info.size > 8 * 1024 * 1024)
+            return { ok: false, error: 'not-found' };
+        const data = await readFile(full);
+        return { ok: true, file: bundleOf([{ path: rel, data }])[rel] };
+    }
+    /** The files of a deployed (or candidate) version, for the play area. */
+    async bundle(projectId, which = 'current') {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const record = await readJson(join(row.root, STATE_DIR, `${which}.json`));
+        if (record === undefined)
+            return { ok: false, error: 'no-version' };
+        const files = await walk(join(row.root, STATE_DIR, 'versions', String(record.version)), () => true);
+        if (files.length === 0)
+            return { ok: false, error: 'no-version' };
+        return { ok: true, bundle: { projectId, version: record.version, files: withKitRuntime(bundleOf(files), this.snapshotKit(files)) } };
+    }
+    /** One specific version's files. */
+    async versionBundle(projectId, version) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const files = await walk(join(row.root, STATE_DIR, 'versions', String(Math.floor(version))), () => true);
+        if (files.length === 0)
+            return { ok: false, error: 'no-version' };
+        return { ok: true, bundle: { projectId, version, files: withKitRuntime(bundleOf(files), this.snapshotKit(files)) } };
+    }
+    /** The kit a snapshot was built for: its own `game.json`'s runtime. */
+    snapshotKit(files) {
+        const manifest = files.find(f => f.path === MANIFEST_FILE);
+        const parsed = manifest === undefined ? undefined : parseManifest(manifest.data.toString('utf8'));
+        return kitOf(parsed?.ok === true ? parsed.manifest.runtime : undefined);
+    }
+    /** The kit a project runs on now (its working `game.json`). */
+    async kitFor(root) {
+        return kitOf((await this.manifestOf(root))?.runtime);
+    }
+    // ---------------------------------------------------------------- checks
+    /** The build and test files as they are on disk now, plus their fingerprint. */
+    async snapshot(root) {
+        const build = await walk(root, isBuildFile);
+        const tests = await walk(join(root, 'tests'), p => p.endsWith('.test.js'));
+        return { build, tests, fingerprint: fingerprintOf([...build, ...tests.map(t => ({ path: `tests/${t.path}`, data: t.data }))]) };
+    }
+    /**
+     * The end-of-turn evaluation for a bound session: skip when nothing
+     * playable changed since the last check, else run the checks, persist the
+     * record, and on a pass deploy (auto-confirm) or leave a candidate.
+     * @param session - the session whose turn is closing.
+     * @param attempt - which automatic fix round this is (0 = the turn's own work).
+     * @param cap - the fix-round cap (a failure at the cap is recorded as given up).
+     * @returns what the hook should do.
+     */
+    async checkTurn(session, attempt, cap, by = 'turn') {
+        const row = await this.boundProject(session.id);
+        if (row === undefined)
+            return { kind: 'skip' };
+        return this.checkRow(row, session, attempt, cap, by);
+    }
+    /**
+     * 提交为新版本: the user commits the panel edits sitting in the working
+     * files. Runs the same checks as the end of a turn (no fix cap — nothing
+     * is steered); a pass cuts the version, whose note lists the edits.
+     */
+    async commit(projectId, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const outcome = await this.checkRow(row, session, 0, Number.POSITIVE_INFINITY, 'user');
+        this.notify(projectId);
+        if (outcome.kind === 'fail')
+            return { ok: true, kind: 'failed', failures: outcome.record.failures.slice(0, 8).map(f => ({ where: f.where, message: f.message.slice(0, 300) })) };
+        if (outcome.kind === 'pass') {
+            if (outcome.deployed !== null)
+                return { ok: true, kind: 'deployed', version: outcome.deployed.version };
+            if (outcome.candidate !== null)
+                return { ok: true, kind: 'candidate', version: outcome.candidate.version };
+            return { ok: false, error: 'denied' };
+        }
+        if (!await stat(join(row.root, 'index.html')).then(() => true, () => false))
+            return { ok: true, kind: 'no-entry' };
+        // Same build as the last check: a passed one already carries the edits (edited back, say); a given-up one still fails.
+        const last = await readJson(join(row.root, STATE_DIR, 'checks.json'));
+        if (last !== undefined && !last.ok)
+            return { ok: true, kind: 'failed', failures: last.failures.slice(0, 8).map(f => ({ where: f.where, message: f.message.slice(0, 300) })) };
+        const user = await this.userLayer(row.root);
+        user.edits = [];
+        await this.saveUserLayer(row.root, user);
+        return { ok: true, kind: 'unchanged' };
+    }
+    async checkRow(row, session, attempt, cap, by) {
+        const root = row.root;
+        if (!await stat(join(root, 'index.html')).then(() => true, () => false))
+            return { kind: 'skip' };
+        const { build, tests, fingerprint } = await this.snapshot(root);
+        const last = await readJson(join(root, STATE_DIR, 'checks.json'));
+        if (last?.fingerprint === fingerprint && (last.ok || last.gaveUp === true))
+            return { kind: 'skip' };
+        const failures = [];
+        const manifestText = await readText(join(root, MANIFEST_FILE));
+        const parsed = manifestText === undefined ? undefined : parseManifest(manifestText);
+        if (parsed === undefined)
+            failures.push({ where: 'data', message: `${MANIFEST_FILE} 不见了` });
+        else if (!parsed.ok)
+            failures.push({ where: 'data', message: parsed.error });
+        const kit = kitOf(parsed?.ok === true ? parsed.manifest.runtime : undefined);
+        const elementFiles = build.filter(f => f.path.startsWith('elements/') && f.path.endsWith('.json'));
+        const validated = validateElements(Object.fromEntries(elementFiles.map(f => [f.path, f.data.toString('utf8')])), parsed?.ok === true ? parsed.manifest.elementTypes : [], kit);
+        failures.push(...validated.failures);
+        // A model look must point at a file the build carries.
+        const shipped = new Set(build.map(f => f.path));
+        for (const e of validated.elements) {
+            if (e.look3d?.kind === 'gltf' && !shipped.has(e.look3d.src)) {
+                failures.push({ where: e.file, message: `「${e.name}」的外观引用了 ${e.look3d.src}，项目里没有这个文件（放进 assets/ 再引用）` });
+            }
+        }
+        const browser = await this.checker.run(withKitRuntime(bundleOf(build), kit), Object.fromEntries(tests.map(t => [`tests/${t.path}`, t.data.toString('utf8')])), { blankProbe: kit.blankProbe });
+        failures.push(...browser.failures);
+        const ok = failures.length === 0;
+        const record = {
+            fingerprint, at: new Date().toISOString(), ok, failures, passed: browser.passed, attempt,
+            ...(browser.skipped === undefined ? {} : { skipped: browser.skipped }),
+            ...(!ok && attempt >= cap ? { gaveUp: true } : {}),
+        };
+        const writable = this.writable(session);
+        if (writable) {
+            await writeAtomic(join(root, STATE_DIR, 'checks.json'), `${JSON.stringify(record, null, 2)}\n`);
+            if (browser.screenshot !== undefined)
+                await writeAtomic(join(root, STATE_DIR, 'last-check.webp'), Buffer.from(browser.screenshot, 'base64'));
+        }
+        if (!ok) {
+            if (record.gaveUp === true)
+                await this.log(root, writable, `检查仍未通过，已停止自动修复（${failures.length} 项）：${failures.slice(0, 2).map(f => f.where).join('、')}`);
+            await this.touch(row.id);
+            return { kind: 'fail', record };
+        }
+        if (!writable)
+            return { kind: 'pass', record, deployed: null, candidate: null };
+        const version = await this.nextVersion(root);
+        await this.copyVersion(root, build, version);
+        // Each version keeps its own poster: the play area shows the version it plays, never a later or failed build.
+        if (browser.screenshot !== undefined)
+            await writeAtomic(join(root, STATE_DIR, 'shots', `${version}.webp`), Buffer.from(browser.screenshot, 'base64'));
+        const user = await this.userLayer(root);
+        const restyle = user.restyleTo;
+        // Every version carries whatever panel edits sit in the working files, whoever cut it.
+        const edits = user.edits.map(e => e.text);
+        const versionRecord = {
+            version, at: record.at, fingerprint, by,
+            note: restyle !== undefined ? `换成「${artStyleLabel(restyle)}」风格`
+                : edits.length > 0 ? `面板修改：${edits.join('、')}`
+                    : browser.passed > 0 ? `通过检查（${browser.passed} 个用例）` : '通过检查',
+        };
+        await this.appendVersion(root, { ...versionRecord, passed: browser.passed });
+        // A restyle always lands as a candidate, whatever auto-confirm says.
+        const autoConfirm = (parsed?.ok === true ? parsed.manifest.autoConfirm : true) && restyle === undefined;
+        if (restyle !== undefined || edits.length > 0) {
+            delete user.restyleTo;
+            user.edits = [];
+            await this.saveUserLayer(root, user);
+        }
+        if (autoConfirm) {
+            await writeAtomic(join(root, STATE_DIR, 'current.json'), `${JSON.stringify(versionRecord, null, 2)}\n`);
+            await rm(join(root, STATE_DIR, 'candidate.json'), { force: true });
+            await this.log(root, true, `v${version} 通过检查${browser.passed > 0 ? `（${browser.passed} 个用例）` : ''}，已进试玩区`);
+        }
+        else {
+            await writeAtomic(join(root, STATE_DIR, 'candidate.json'), `${JSON.stringify(versionRecord, null, 2)}\n`);
+            await this.log(root, true, `v${version} 通过检查，等用户确认${restyle === undefined ? '' : `（换风格：${artStyleLabel(restyle)}）`}`);
+        }
+        await this.prune(root);
+        await this.touch(row.id);
+        return { kind: 'pass', record, deployed: autoConfirm ? versionRecord : null, candidate: autoConfirm ? null : versionRecord };
+    }
+    async nextVersion(root) {
+        const names = await readdir(join(root, STATE_DIR, 'versions')).catch(() => []);
+        const numbers = names.map(Number).filter(n => Number.isInteger(n) && n > 0);
+        return (numbers.length === 0 ? 0 : Math.max(...numbers)) + 1;
+    }
+    async copyVersion(root, build, version) {
+        const dir = join(root, STATE_DIR, 'versions', String(version));
+        for (const f of build) {
+            const target = resolve(dir, f.path);
+            if (!inside(dir, target))
+                continue;
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, f.data);
+        }
+    }
+    /** Keep the newest versions plus whatever current/candidate point at. */
+    async prune(root) {
+        const versionsDir = join(root, STATE_DIR, 'versions');
+        const names = (await readdir(versionsDir).catch(() => [])).map(Number).filter(n => Number.isInteger(n) && n > 0).sort((a, b) => b - a);
+        const pinned = new Set();
+        for (const which of ['current', 'candidate']) {
+            const r = await readJson(join(root, STATE_DIR, `${which}.json`));
+            if (r !== undefined)
+                pinned.add(r.version);
+        }
+        for (const n of names.slice(KEEP_VERSIONS)) {
+            if (pinned.has(n))
+                continue;
+            await rm(join(versionsDir, String(n)), { recursive: true, force: true });
+            await rm(join(root, STATE_DIR, 'shots', `${n}.webp`), { force: true });
+        }
+    }
+    /** Promote the candidate to current (the user's 确认 when auto-confirm is off). */
+    async confirm(projectId, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const candidate = await readJson(join(row.root, STATE_DIR, 'candidate.json'));
+        if (candidate === undefined)
+            return { ok: false, error: 'no-version' };
+        await writeAtomic(join(row.root, STATE_DIR, 'current.json'), `${JSON.stringify(candidate, null, 2)}\n`);
+        await rm(join(row.root, STATE_DIR, 'candidate.json'), { force: true });
+        await this.log(row.root, true, `用户确认 v${candidate.version}，已进试玩区`);
+        await this.touch(projectId);
+        return { ok: true, version: candidate.version };
+    }
+    /**
+     * Turn auto-confirm on or off in `game.json` (the panel's switch). The
+     * manifest is the project's own file, so this goes through node behind the
+     * same writable check.
+     */
+    async setAutoConfirm(projectId, on, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const text = await readText(join(row.root, MANIFEST_FILE));
+        const parsed = text === undefined ? undefined : parseManifest(text);
+        if (parsed === undefined || !parsed.ok)
+            return { ok: false, error: 'invalid' };
+        await writeAtomic(join(row.root, MANIFEST_FILE), serializeManifest({ ...parsed.manifest, autoConfirm: on }));
+        await this.touch(projectId);
+        return { ok: true };
+    }
+    /** Throw the candidate away (the user's 退回); the model hears about it on the next send. */
+    async reject(projectId, reason, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const candidate = await readJson(join(row.root, STATE_DIR, 'candidate.json'));
+        if (candidate === undefined)
+            return { ok: false, error: 'no-version' };
+        await rm(join(row.root, STATE_DIR, 'candidate.json'), { force: true });
+        await this.updateVersions(row.root, list => list.map(v => (v.version === candidate.version ? { ...v, rejected: true } : v)));
+        const why = reason.trim().slice(0, 200);
+        await this.log(row.root, true, `用户退回 v${candidate.version}${why === '' ? '' : `：${why}`}`);
+        await this.addPending(row.root, { key: `reject:${candidate.version}`, text: `退回了候选 v${candidate.version}${why === '' ? '' : `（${why}）`}，试玩区仍是上一版` });
+        await this.touch(projectId);
+        return { ok: true };
+    }
+    /** Put an older version back into the play area. */
+    async rollback(projectId, version, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const entry = (await this.readVersions(row.root)).find(v => v.version === version);
+        const exists = await stat(join(row.root, STATE_DIR, 'versions', String(version))).then(() => true, () => false);
+        if (entry === undefined || !exists)
+            return { ok: false, error: 'no-version' };
+        const { passed: _passed, rejected: _rejected, ...record } = entry;
+        await writeAtomic(join(row.root, STATE_DIR, 'current.json'), `${JSON.stringify(record, null, 2)}\n`);
+        await this.log(row.root, true, `试玩区切回 v${version}`);
+        await this.addPending(row.root, { key: 'rollback', text: `把试玩区切回了 v${version}（工作目录里的代码没动）` });
+        await this.touch(projectId);
+        return { ok: true };
+    }
+    /** Files that differ between two versions' snapshots. */
+    async diff(projectId, from, to) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const hashes = async (version) => {
+            const dir = join(row.root, STATE_DIR, 'versions', String(version));
+            if (!await stat(dir).then(() => true, () => false))
+                return undefined;
+            return new Map((await walk(dir, () => true)).map(f => [f.path, createHash('sha1').update(f.data).digest('hex')]));
+        };
+        const a = await hashes(from), b = await hashes(to);
+        if (a === undefined || b === undefined)
+            return { ok: false, error: 'no-version' };
+        return {
+            ok: true,
+            diff: {
+                added: [...b.keys()].filter(k => !a.has(k)),
+                removed: [...a.keys()].filter(k => !b.has(k)),
+                changed: [...b.keys()].filter(k => a.has(k) && a.get(k) !== b.get(k)),
+            },
+        };
+    }
+    // ---------------------------------------------------------------- user layer
+    async userLayer(root) {
+        const raw = await readJson(join(root, STATE_DIR, 'user.json'));
+        return {
+            params: raw?.params !== null && typeof raw?.params === 'object' ? { ...raw.params } : {},
+            // `param:` entries came from the retired slider auto-pending (a slider is a trial now).
+            pending: Array.isArray(raw?.pending) ? raw.pending.filter(p => typeof p?.key === 'string' && typeof p.text === 'string' && !p.key.startsWith('param:')) : [],
+            edits: Array.isArray(raw?.edits) ? raw.edits.filter(p => typeof p?.key === 'string' && typeof p.text === 'string') : [],
+            ...(typeof raw?.restyleTo === 'string' ? { restyleTo: raw.restyleTo } : {}),
+        };
+    }
+    async saveUserLayer(root, user) {
+        await writeAtomic(join(root, STATE_DIR, 'user.json'), `${JSON.stringify(user, null, 2)}\n`);
+    }
+    /** Add (or replace by key) one pending change; `text: ''` removes it. */
+    async addPending(root, change) {
+        const user = await this.userLayer(root);
+        user.pending = user.pending.filter(p => p.key !== change.key);
+        if (change.text !== '')
+            user.pending.push(change);
+        await this.saveUserLayer(root, user);
+    }
+    /** Sessions whose agent turn is running now (the turn hooks keep it). */
+    activeTurns = new Set();
+    /** The turn hooks report a bound session's turn starting and ending. */
+    setTurnActive(sessionId, active) {
+        if (active)
+            this.activeTurns.add(sessionId);
+        else
+            this.activeTurns.delete(sessionId);
+    }
+    /**
+     * What the working files hold that the play area does not: build files
+     * added, changed or removed against the waiting candidate (else the live
+     * version), whoever wrote them — the panel, the agent, a CLI member, the
+     * user's own editor. Modification times pick the suspects; only those are
+     * compared byte for byte, so an unchanged project costs a stat walk.
+     */
+    async changes(projectId) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const root = row.root;
+        const state = join(root, STATE_DIR);
+        const base = (await readJson(join(state, 'candidate.json'))) ?? (await readJson(join(state, 'current.json')));
+        const hasEntry = await stat(join(root, 'index.html')).then(() => true, () => false);
+        const working = await statWalk(root, isBuildFile);
+        const files = [];
+        let lastMs = 0;
+        if (base === undefined) {
+            for (const f of working) {
+                files.push({ path: f.path, kind: 'added' });
+                lastMs = Math.max(lastMs, f.mtimeMs);
+            }
+        }
+        else {
+            const snapshot = join(state, 'versions', String(base.version));
+            // A file edited while that version's check ran is older than its record: look a minute back.
+            const since = Date.parse(base.at) - 60_000;
+            for (const f of working) {
+                if (f.mtimeMs < since)
+                    continue;
+                const before = await readFile(join(snapshot, f.path)).catch(() => undefined);
+                if (before === undefined)
+                    files.push({ path: f.path, kind: 'added' });
+                else if (!before.equals(await readFile(join(root, f.path)).catch(() => Buffer.alloc(0))))
+                    files.push({ path: f.path, kind: 'changed' });
+                else
+                    continue;
+                lastMs = Math.max(lastMs, f.mtimeMs);
+            }
+            const present = new Set(working.map(f => f.path));
+            for (const f of await statWalk(snapshot, () => true))
+                if (!present.has(f.path))
+                    files.push({ path: f.path, kind: 'removed' });
+        }
+        const user = await this.userLayer(root);
+        const registry = await this.readRegistry();
+        const turn = Object.entries(registry.bindings).some(([sid, pid]) => pid === projectId && this.activeTurns.has(sid));
+        const lastAt = lastMs > 0 ? new Date(lastMs).toISOString() : null;
+        const busy = turn ? 'turn' : lastMs > 0 && Date.now() - lastMs < BUSY_QUIET_MS ? 'recent' : null;
+        // The last check ran after the newest change and failed: that failure is about these very files.
+        const last = await readJson(join(state, 'checks.json'));
+        const failed = files.length > 0 && last !== undefined && !last.ok && Date.parse(last.at) >= lastMs
+            ? last.failures.slice(0, 8).map(f => ({ where: f.where, message: f.message.slice(0, 300) }))
+            : null;
+        return {
+            ok: true, against: base?.version ?? null, hasEntry, count: files.length, files: files.slice(0, 30), lastAt, busy,
+            edits: user.edits, failed,
+        };
+    }
+    /** Add (or replace by key) one uncommitted panel edit. */
+    async addEdit(root, change) {
+        const user = await this.userLayer(root);
+        user.edits = [...user.edits.filter(p => p.key !== change.key), change];
+        await this.saveUserLayer(root, user);
+    }
+    /** The agent has read the pending list (`game_read`): it is no longer news. */
+    async clearPending(projectId) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return;
+        const user = await this.userLayer(row.root);
+        if (user.pending.length === 0)
+            return;
+        user.pending = [];
+        await this.saveUserLayer(row.root, user);
+    }
+    /** Drop one pending change by key (the dock's ×). */
+    async dropPending(projectId, key, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        await this.addPending(row.root, { key, text: '' });
+        this.notify(projectId);
+        return { ok: true };
+    }
+    /**
+     * The user sent a message carrying the panel's change list (it starts
+     * with {@link PANEL_CHANGES_MARK}): drop exactly the changes it lists.
+     * Changes made after the list was written stay pending.
+     * @param sessionId - the sending session.
+     * @param text - the user message's text.
+     * @returns how many changes were cleared.
+     */
+    async clearSent(sessionId, text) {
+        if (!text.includes(PANEL_CHANGES_MARK))
+            return 0;
+        const row = await this.boundProject(sessionId);
+        if (row === undefined)
+            return 0;
+        const user = await this.userLayer(row.root);
+        const kept = user.pending.filter(p => !text.includes(p.text));
+        const cleared = user.pending.length - kept.length;
+        if (cleared === 0)
+            return 0;
+        user.pending = kept;
+        await this.saveUserLayer(row.root, user);
+        this.notify(row.id);
+        return cleared;
+    }
+    /** The manifest of a project, or undefined. */
+    async manifestOf(root) {
+        const text = await readText(join(root, MANIFEST_FILE));
+        const parsed = text === undefined ? undefined : parseManifest(text);
+        return parsed?.ok === true ? parsed.manifest : undefined;
+    }
+    /** Set one slider value (user layer; the play frame gets it live from the panel). */
+    async setParam(projectId, key, value, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const manifest = await this.manifestOf(row.root);
+        const param = manifest?.params.find(p => p.key === key);
+        if (param === undefined || !Number.isFinite(value))
+            return { ok: false, error: 'invalid' };
+        const clamped = Math.min(param.max, Math.max(param.min, value));
+        const user = await this.userLayer(row.root);
+        if (clamped === param.value)
+            delete user.params[key];
+        else
+            user.params[key] = clamped;
+        // A slider is a trial (2026-10-10): it changes the running game only. The
+        // agent hears about it when the user says so (告诉 agent) or finalizes.
+        await this.saveUserLayer(row.root, user);
+        this.notify(projectId);
+        return { ok: true };
+    }
+    /** 定稿: write the slider values into game.json as the new defaults. */
+    async finalizeParams(projectId, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const manifest = await this.manifestOf(row.root);
+        if (manifest === undefined)
+            return { ok: false, error: 'invalid' };
+        const user = await this.userLayer(row.root);
+        const changed = manifest.params.filter(p => user.params[p.key] !== undefined && user.params[p.key] !== p.value);
+        if (changed.length === 0)
+            return { ok: true };
+        const params = manifest.params.map(p => (user.params[p.key] === undefined ? p : { ...p, value: user.params[p.key] }));
+        await writeAtomic(join(row.root, MANIFEST_FILE), serializeManifest({ ...manifest, params }));
+        const summary = changed.map(p => `${p.label} ${num(p.value)}→${num(user.params[p.key])}`).join('、');
+        user.params = {};
+        user.pending = user.pending.filter(p => !p.key.startsWith('param:'));
+        user.pending.push({ key: 'params-final', text: `定稿参数：${summary}（已写进 game.json）` });
+        user.edits = [...user.edits.filter(e => e.key !== 'params'), { key: 'params', text: `参数定稿 ${summary}` }];
+        await this.saveUserLayer(row.root, user);
+        await this.log(row.root, true, `定稿参数：${summary}`);
+        await this.touch(projectId);
+        return { ok: true };
+    }
+    /** 还原: drop every slider override. */
+    async resetParams(projectId, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const user = await this.userLayer(row.root);
+        user.params = {};
+        user.pending = user.pending.filter(p => !p.key.startsWith('param:'));
+        await this.saveUserLayer(row.root, user);
+        this.notify(projectId);
+        return { ok: true };
+    }
+    /**
+     * Edit one element in the working files — its look, or scalar fields
+     * (`lore`, the 设定 text, included). The play area keeps its version until
+     * the user commits (`commit`); the edit is listed as uncommitted, and as
+     * pending for the agent.
+     */
+    async editElement(projectId, elementId, patch, session, note) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const files = await walk(join(row.root, 'elements'), p => p.endsWith('.json'));
+        const changes = {};
+        if (patch.look !== undefined) {
+            const look = (await this.kitFor(row.root)).normalizeLook(patch.look);
+            if (look === null)
+                return { ok: false, error: 'invalid' };
+            changes.look = look;
+        }
+        for (const [key, value] of Object.entries(patch.fields ?? {})) {
+            if (key === 'id' || key === 'look' || key.length > 40)
+                continue;
+            changes[key] = value === null ? undefined : key === 'lore' && typeof value === 'string' ? value.slice(0, LORE_MAX) : value;
+        }
+        for (const f of files) {
+            const next = patchElementText(f.data.toString('utf8'), elementId, changes);
+            if (next === undefined)
+                continue;
+            await writeAtomic(join(row.root, 'elements', f.path), next);
+            const parsed = JSON.parse(next);
+            const element = (Array.isArray(parsed) ? parsed : [parsed]).find(e => e.id === elementId);
+            const name = typeof element.name === 'string' ? element.name : elementId;
+            if (changes.look !== undefined) {
+                await this.addPending(row.root, { key: `look:${elementId}`, text: note ?? `改了「${name}」的外观（elements 文件里的 look 已更新）` });
+                await this.addEdit(row.root, { key: `look:${elementId}`, text: `${name}的外观` });
+            }
+            if ('lore' in changes) {
+                await this.addPending(row.root, { key: `lore:${elementId}`, text: `改了「${name}」的设定（elements 文件里的 lore），按新设定调整它的行为和文案` });
+                await this.addEdit(row.root, { key: `lore:${elementId}`, text: `${name}的设定` });
+            }
+            const fieldKeys = Object.keys(changes).filter(k => k !== 'look' && k !== 'lore');
+            if (fieldKeys.length > 0) {
+                await this.addPending(row.root, {
+                    key: `fields:${elementId}`,
+                    text: `改了「${name}」的字段：${fieldKeys.map(k => `${k}=${changes[k] === undefined ? '（删除）' : String(changes[k])}`).join('、')}`,
+                });
+                await this.addEdit(row.root, { key: `fields:${elementId}`, text: `${name}的${fieldKeys.join('、')}` });
+            }
+            await this.log(row.root, true, note ?? `用户编辑了元素「${name}」`);
+            await this.touch(projectId);
+            return { ok: true, element };
+        }
+        return { ok: false, error: 'not-found' };
+    }
+    /** Write one design chapter (the user's direct edit). */
+    async writeChapter(projectId, chapterId, text, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const spec = CHAPTERS.find(c => c.id === chapterId);
+        if (spec === undefined || spec.generated === true)
+            return { ok: false, error: 'invalid' };
+        await writeAtomic(join(row.root, spec.file), text.endsWith('\n') ? text : `${text}\n`);
+        await this.addPending(row.root, { key: `design:${chapterId}`, text: `直接改了策划《${spec.title}》（${spec.file}），以文件为准` });
+        await this.touch(projectId);
+        return { ok: true };
+    }
+    /** Edit the one-pager in game.json (pitch, element types, pillars) — the user's direct edit. */
+    async setOnePager(projectId, patch, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const manifest = await this.manifestOf(row.root);
+        if (manifest === undefined)
+            return { ok: false, error: 'invalid' };
+        const pitch = patch.pitch === undefined ? manifest.pitch : patch.pitch.trim().slice(0, 400);
+        const elementTypes = patch.elementTypes === undefined ? manifest.elementTypes : listOf(patch.elementTypes).slice(0, 12);
+        const pillars = patch.pillars === undefined ? manifest.pillars : listOf(patch.pillars.split(/\n/)).slice(0, 5);
+        if (pitch === '' || elementTypes.length === 0)
+            return { ok: false, error: 'invalid' };
+        const parts = [];
+        if (pitch !== manifest.pitch)
+            parts.push(`玩法「${pitch}」`);
+        if (elementTypes.join('、') !== manifest.elementTypes.join('、'))
+            parts.push(`元素类型 ${elementTypes.join('、')}`);
+        if (pillars.join('；') !== manifest.pillars.join('；'))
+            parts.push(`支柱 ${pillars.map((p, i) => `${i + 1}.${p}`).join(' ')}`);
+        if (parts.length === 0)
+            return { ok: true };
+        await writeAtomic(join(row.root, MANIFEST_FILE), serializeManifest({ ...manifest, pitch, elementTypes, pillars }));
+        await this.addPending(row.root, { key: 'onepager', text: `改了一页纸（game.json）：${parts.join('；')}` });
+        await this.log(row.root, true, `用户改了一页纸：${parts.join('；')}`);
+        await this.touch(projectId);
+        return { ok: true };
+    }
+    /** Ask for a restyle: the next passing version becomes a candidate. The panel puts the request into the composer. */
+    async requestRestyle(projectId, styleId, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        if (!this.writable(session))
+            return { ok: false, error: 'denied' };
+        const style = resolveArtStyle(styleId);
+        if (style === undefined)
+            return { ok: false, error: 'invalid' };
+        const user = await this.userLayer(row.root);
+        user.restyleTo = style;
+        await this.saveUserLayer(row.root, user);
+        this.notify(projectId);
+        return { ok: true };
+    }
+    // ---------------------------------------------------------------- appearance proposals
+    async proposals(root) {
+        const list = await readJson(join(root, STATE_DIR, 'proposals.json'));
+        return Array.isArray(list) ? list.slice(-12).reverse() : [];
+    }
+    /**
+     * Store up to 3 appearance variants for an element (the `game_propose`
+     * tool); the user picks one in the panel.
+     */
+    async proposeLooks(sessionId, elementId, request, variants) {
+        const row = await this.boundProject(sessionId);
+        if (row === undefined)
+            return { ok: false, error: '本会话还没有游戏项目' };
+        const view = await this.view(row.id);
+        const element = view?.elements.find(e => e.id === elementId);
+        if (element === undefined)
+            return { ok: false, error: `没有 id 为「${elementId}」的元素` };
+        const clean = [];
+        const bad = [];
+        const kit = await this.kitFor(row.root);
+        variants.slice(0, 3).forEach((v, i) => {
+            const look = kit.normalizeLook(v.look);
+            if (look === null)
+                bad.push(i + 1);
+            else
+                clean.push({ label: (v.label ?? '').trim().slice(0, 20) || 'ABC'[i], note: (v.note ?? '').trim().slice(0, 120), look });
+        });
+        if (clean.length === 0)
+            return { ok: false, error: `方案都不可用（第 ${bad.join('、')} 个）：${kit.lookHint}` };
+        const all = await readJson(join(row.root, STATE_DIR, 'proposals.json'));
+        const list = (Array.isArray(all) ? all : []).filter(p => !(p.elementId === elementId && p.picked === undefined));
+        list.push({ elementId, at: new Date().toISOString(), request: request.trim().slice(0, 200), variants: clean });
+        await writeAtomic(join(row.root, STATE_DIR, 'proposals.json'), `${JSON.stringify(list.slice(-20), null, 2)}\n`);
+        await this.touch(row.id);
+        return { ok: true, count: clean.length, name: element.name };
+    }
+    /** The user picks a variant: it replaces the element's look at once; the others stay in the history. */
+    async pickProposal(projectId, elementId, at, index, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const all = await readJson(join(row.root, STATE_DIR, 'proposals.json'));
+        const list = Array.isArray(all) ? all : [];
+        const proposal = list.find(p => p.elementId === elementId && p.at === at);
+        const variant = proposal?.variants[index];
+        if (proposal === undefined || variant === undefined)
+            return { ok: false, error: 'not-found' };
+        const edited = await this.editElement(projectId, elementId, { look: variant.look }, session, `外观方案：用户选了「${variant.label}」${variant.note === '' ? '' : `（${variant.note}）`}，已写进元素文件`);
+        if (!edited.ok)
+            return edited;
+        await writeAtomic(join(row.root, STATE_DIR, 'proposals.json'), `${JSON.stringify(list.map(p => (p === proposal ? { ...p, picked: index } : p)), null, 2)}\n`);
+        this.notify(projectId);
+        return { ok: true };
+    }
+    // ---------------------------------------------------------------- versions
+    async readVersions(root) {
+        const list = await readJson(join(root, STATE_DIR, 'versions.json'));
+        return Array.isArray(list) ? list.filter(v => typeof v?.version === 'number') : [];
+    }
+    async updateVersions(root, change) {
+        await writeAtomic(join(root, STATE_DIR, 'versions.json'), `${JSON.stringify(change(await this.readVersions(root)), null, 2)}\n`);
+    }
+    async appendVersion(root, entry) {
+        await this.updateVersions(root, list => [...list.filter(v => v.version !== entry.version), entry].slice(-50));
+    }
+    /** The 版本 view's rows, newest first: only versions whose snapshot still exists. */
+    async versionRows(root) {
+        const current = await readJson(join(root, STATE_DIR, 'current.json'));
+        const candidate = await readJson(join(root, STATE_DIR, 'candidate.json'));
+        const kept = new Set((await readdir(join(root, STATE_DIR, 'versions')).catch(() => [])).map(Number));
+        return (await this.readVersions(root)).filter(v => kept.has(v.version)).reverse().map(v => ({
+            version: v.version, at: v.at, fingerprint: v.fingerprint,
+            ...(v.by === undefined ? {} : { by: v.by }),
+            ...(v.note === undefined ? {} : { note: v.note }),
+            ...(v.passed === undefined ? {} : { passed: v.passed }),
+            status: v.version === current?.version ? 'current' : v.version === candidate?.version ? 'candidate' : v.rejected === true ? 'rejected' : 'past',
+        }));
+    }
+    /** The last check's screenshot (webp, base64), if any. */
+    async checkShot(projectId, version) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        // A version's own poster; without a version, the last check's (projects made before per-version posters).
+        const own = version === undefined ? undefined : await readFile(join(row.root, STATE_DIR, 'shots', `${Math.floor(version)}.webp`)).catch(() => undefined);
+        const data = own ?? (version === undefined ? await readFile(join(row.root, STATE_DIR, 'last-check.webp')).catch(() => undefined) : undefined);
+        return data === undefined ? { ok: false, error: 'no-version' } : { ok: true, webp: data.toString('base64') };
+    }
+    // ---------------------------------------------------------------- playtest log
+    /** Append one line to the project's playtest log (`.game/playtest-log.jsonl`). */
+    async log(root, writable, text) {
+        if (!writable)
+            return;
+        const path = join(root, STATE_DIR, 'playtest-log.jsonl');
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, `${JSON.stringify({ at: new Date().toISOString(), text })}\n`).catch(() => { });
+    }
+    /** Record what the panel saw during one play session (errors, length). */
+    async logPlay(projectId, entry, session) {
+        const row = await this.row(projectId);
+        if (row === undefined)
+            return { ok: false, error: 'not-found' };
+        const seconds = Math.max(0, Math.round(entry.seconds));
+        const errors = entry.errors.slice(0, 3).map(e => String(e).slice(0, 160));
+        const text = errors.length === 0
+            ? `试玩 v${entry.version} ${seconds} 秒，无报错`
+            : `试玩 v${entry.version} ${seconds} 秒，报错 ${entry.errors.length} 次：${errors.join('；')}`;
+        await this.log(row.root, this.writable(session), text);
+        this.notify(projectId);
+        return { ok: true };
+    }
+    /** The playtest log, newest first (last 60). */
+    async logEntries(root) {
+        const text = await readText(join(root, STATE_DIR, 'playtest-log.jsonl'));
+        if (text === undefined)
+            return [];
+        return text.split('\n').filter(Boolean).map(line => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return undefined;
+            }
+        }).filter((r) => r !== undefined && typeof r.text === 'string').slice(-60).reverse();
+    }
+    /** The generated 试玩记录 chapter, newest first. */
+    async playtestText(root) {
+        const rows = (await this.logEntries(root)).slice(0, 40);
+        if (rows.length === 0)
+            return '';
+        const local = (iso) => {
+            const d = new Date(iso);
+            const pad = (n) => String(n).padStart(2, '0');
+            return Number.isNaN(d.getTime()) ? iso : `${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+        };
+        return ['# 试玩记录', '', ...rows.map(r => `- ${local(r.at)} ${r.text}`), ''].join('\n');
+    }
+}