summer-engine 2.6.6 → 2.7.0

package/dist/lib/api-client.js

@@ -1,6 +1,7 @@
 import { mkdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
+import { randomUUID } from "node:crypto";
 import { getApiToken, getApiPort, checkEngineHealth } from "./engine.js";
 import { classifyOpsResponse, pollOpToTerminal, } from "./async-op-lifecycle.js";
 function asRecord(value) {
@@ -131,6 +132,13 @@ export class EngineApiClient {
         const projectIdHash = this.targetIdentity.projectIdHash;
         return projectIdHash ? { projectIdHash } : {};
     }
+    requireBoundIdentity() {
+        const { instanceId, projectId, projectIdHash } = this.targetIdentity;
+        if (!instanceId || !projectId || !projectIdHash) {
+            throw new Error("Safe project mutation requires a complete engine/project identity. Call summer_get_project_context to bind this MCP session, then retry. Nothing was written.");
+        }
+        return { projectIdHash };
+    }
     targetUrl(path) {
         const url = new URL(path, `http://127.0.0.1:${this.port}`);
         const { instanceId, projectId, projectIdHash } = this.targetIdentity;
@@ -190,24 +198,98 @@ export class EngineApiClient {
      * result (HTTP 200 — dormant/older engine) OR the async lifecycle (202
      * {requestId} -> long-poll /api/ops/result until terminal). Compatible with
      * both — inspects the HTTP status, not a flag. `timeoutMs` is the poll loop's
-     * total budget; a long op that keeps advancing is not falsely timed out.
+     * client wait budget; expiry preserves the requestId and last known lifecycle
+     * state instead of pretending the accepted operation did not apply.
      */
     async _requestQueued(method, path, body, timeoutMs) {
-        const res = await this._fetchRaw(method, path, body, timeoutMs);
+        // Mint the request ID before submission. If the acknowledgement or a later
+        // poll is lost, callers retain the exact identity needed to reconcile the
+        // accepted lifecycle instead of issuing an unsafe blind retry.
+        let clientRequestId;
+        let requestBody = body;
+        if (method === "POST") {
+            const bodyRecord = asRecord(body) ?? {};
+            const existingOptions = asRecord(bodyRecord.options) ?? {};
+            clientRequestId =
+                stringFrom(existingOptions.requestId) ?? `mcp-${randomUUID()}`;
+            requestBody = {
+                ...bodyRecord,
+                options: {
+                    ...existingOptions,
+                    requestId: clientRequestId,
+                },
+            };
+        }
+        let res;
+        try {
+            res = await this._fetchRaw(method, path, requestBody, timeoutMs);
+        }
+        catch (error) {
+            if (!clientRequestId)
+                throw error;
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new Error(`Summer Engine did not acknowledge request ${clientRequestId}; dispatch state is unknown. Do not retry blindly. ${detail}`);
+        }
         // 202 (queued) + 429 (backpressure, errorClass in body) are handled below;
         // any other non-2xx is a real transport error.
         if (!res.ok && res.status !== 202 && res.status !== 429) {
             const text = await res.text().catch(() => "");
-            throw new Error(`Engine API error ${res.status}: ${text.slice(0, 200)}`);
+            const suffix = clientRequestId ? ` (requestId ${clientRequestId})` : "";
+            throw new Error(`Engine API error ${res.status}${suffix}: ${text.slice(0, 200)}`);
         }
         const respBody = await res.json().catch(() => ({}));
         const classified = classifyOpsResponse(res.status, respBody);
         if (classified.mode === "legacy") {
+            if (res.status === 429) {
+                return {
+                    ...(asRecord(respBody) ?? {}),
+                    requestId: clientRequestId,
+                    terminalState: stringFrom(asRecord(respBody)?.terminalState) ?? "queue_full",
+                    dispatchState: "not_sent",
+                };
+            }
             return respBody;
         }
-        return pollOpToTerminal((waitMs) => this._pollResult(classified.requestId, waitMs), {
-            totalTimeoutMs: timeoutMs,
-        });
+        // The acknowledgement is authoritative for polling. Current engines echo
+        // the client-generated ID, while older engines may ignore options.requestId
+        // and mint their own; polling the submitted ID against those engines would
+        // wait forever on an unknown lifecycle.
+        const acceptedRequestId = classified.requestId || clientRequestId;
+        if (!acceptedRequestId) {
+            return {
+                status: "error",
+                error: "Summer Engine accepted an operation without returning a requestId; final state is uncertain.",
+                terminalState: "uncertain",
+                errorClass: "transient",
+                dispatchState: "uncertain",
+            };
+        }
+        try {
+            const terminal = await pollOpToTerminal((waitMs) => this._pollResult(acceptedRequestId, waitMs), {
+                totalTimeoutMs: timeoutMs,
+                requestId: acceptedRequestId,
+            });
+            if (clientRequestId && clientRequestId !== acceptedRequestId) {
+                terminal.submissionRequestId = clientRequestId;
+            }
+            return terminal;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return {
+                status: "error",
+                error: `Summer Engine accepted request ${acceptedRequestId}, but its final receipt could not be retrieved. ` +
+                    `The operation may still be running or may already have applied; inspect the target before retrying. ${detail}`,
+                terminalState: "uncertain",
+                errorClass: "transient",
+                dispatchState: "uncertain",
+                requestId: acceptedRequestId,
+                ...(clientRequestId && clientRequestId !== acceptedRequestId
+                    ? { submissionRequestId: clientRequestId }
+                    : {}),
+                lastKnownStatus: "unknown",
+            };
+        }
     }
     async health() {
         return this.request("GET", "/api/health");
@@ -218,12 +300,31 @@ export class EngineApiClient {
         // async-202 (Block E).
         // Attach the bound project identity so the engine rejects a write aimed at a
         // different project (identity_mismatch, atomic — before any op applies).
-        const merged = { ...this.identityOptions(), ...(options ?? {}) };
+        const merged = { ...(options ?? {}), ...this.identityOptions() };
         const body = Object.keys(merged).length ? { ops, options: merged } : { ops };
         return this._requestQueued("POST", "/api/ops", body, 120_000);
     }
-    async getSceneState() {
-        return this.request("GET", "/api/state/scene");
+    /**
+     * Mutation path for MCP file tools. Unlike legacy executeOps callers, this
+     * fails closed when health did not provide a complete target identity. The
+     * bound hash is stamped last so a caller cannot override it in options.
+     */
+    async executeIdentityBoundOps(ops, options) {
+        const identity = this.requireBoundIdentity();
+        return this.executeOps(ops, { ...(options ?? {}), ...identity });
+    }
+    async readProjectFile(path, maxBytes = 200_000) {
+        const query = new URLSearchParams({
+            path,
+            maxBytes: String(maxBytes),
+        });
+        return this.request("GET", `/api/state/read-file?${query.toString()}`);
+    }
+    async getSceneState(scenePath) {
+        const query = scenePath
+            ? `?scene=${encodeURIComponent(scenePath)}`
+            : "";
+        return this.request("GET", `/api/state/scene${query}`);
     }
     async getProjectState() {
         return this.request("GET", "/api/state/project");

package/dist/lib/async-op-lifecycle.d.ts

@@ -40,6 +40,10 @@ export declare function classifyOpsResponse(httpStatus: number, body: unknown):
 export interface PollOpts {
     /** Hard wall-clock cap on the whole poll loop (ms). The per-tool budget. */
     totalTimeoutMs: number;
+    /** Stable client-generated correlation ID. Preserved in non-terminal timeout
+     *  receipts so callers can reconcile the accepted operation instead of
+     *  blindly retrying it. */
+    requestId?: string;
     /** Give up if the op hasn't advanced for this long (ms). Default = totalTimeoutMs. */
     noProgressTimeoutMs?: number;
     /** Server long-poll wait per GET (ms). Default 5000 — the engine holds the
@@ -54,7 +58,8 @@ export interface PollOpts {
 /**
  * Drive an async op to a terminal result by polling. `pollOnce(waitMs)` performs
  * one GET /api/ops/result (long-poll up to waitMs). Returns the engine's apply
- * dict with terminalState/errorClass/appliedSeq merged on top, or a synthetic
- * `timed_out` result if the budget is exhausted.
+ * dict with terminalState/errorClass/appliedSeq merged on top, or a truthful
+ * non-terminal `still_queued` / `still_running` / `uncertain` receipt when the
+ * client budget expires before the engine publishes a terminal.
  */
 export declare function pollOpToTerminal(pollOnce: (waitMs: number) => Promise<OpResultEnvelope>, opts: PollOpts): Promise<Record<string, unknown>>;

package/dist/lib/async-op-lifecycle.js

@@ -30,17 +30,37 @@ export function classifyOpsResponse(httpStatus, body) {
     }
     return { mode: "legacy", legacyResult: body };
 }
-const TIMED_OUT_RESULT = {
-    status: "error",
-    error: "Tool timeout - Summer Engine may be unresponsive",
-    terminalState: "timed_out",
-    errorClass: "transient",
-};
+function incompleteResult(requestId, lastStatus) {
+    if (lastStatus === "queued") {
+        return {
+            status: "error",
+            error: `Summer Engine accepted request ${requestId ?? "(unknown)"}, but it was still queued when this tool stopped waiting. ` +
+                "It may still run; do not retry blindly.",
+            terminalState: "still_queued",
+            errorClass: "transient",
+            dispatchState: "accepted",
+            requestId,
+            lastKnownStatus: "queued",
+        };
+    }
+    const wasRunning = lastStatus === "running";
+    return {
+        status: "error",
+        error: `Summer Engine did not provide a final receipt for request ${requestId ?? "(unknown)"}. ` +
+            `${wasRunning ? "The operation was still running" : "Its dispatch state is uncertain"}; inspect the target before retrying.`,
+        terminalState: wasRunning ? "still_running" : "uncertain",
+        errorClass: "transient",
+        dispatchState: wasRunning ? "sent" : "uncertain",
+        requestId,
+        lastKnownStatus: lastStatus ?? "unknown",
+    };
+}
 /**
  * Drive an async op to a terminal result by polling. `pollOnce(waitMs)` performs
  * one GET /api/ops/result (long-poll up to waitMs). Returns the engine's apply
- * dict with terminalState/errorClass/appliedSeq merged on top, or a synthetic
- * `timed_out` result if the budget is exhausted.
+ * dict with terminalState/errorClass/appliedSeq merged on top, or a truthful
+ * non-terminal `still_queued` / `still_running` / `uncertain` receipt when the
+ * client budget expires before the engine publishes a terminal.
  */
 export async function pollOpToTerminal(pollOnce, opts) {
     const now = opts.now ?? (() => Date.now());
@@ -57,6 +77,9 @@ export async function pollOpToTerminal(pollOnce, opts) {
         const env = await pollOnce(pollWaitMs);
         if (isTerminalStatus(env.status)) {
             const out = { ...(env.result ?? {}) };
+            const requestId = opts.requestId ?? env.requestId;
+            if (requestId)
+                out.requestId = requestId;
             if (env.terminalState)
                 out.terminalState = env.terminalState;
             if (env.errorClass)
@@ -76,7 +99,7 @@ export async function pollOpToTerminal(pollOnce, opts) {
             lastProgress = progressJson;
         }
         if (t - start >= opts.totalTimeoutMs || t - lastAdvanceAt >= noProgressMs) {
-            return { ...TIMED_OUT_RESULT };
+            return incompleteResult(opts.requestId ?? env.requestId, env.status);
         }
         await sleep(pacingMs);
     }

package/dist/lib/debug-report.d.ts

@@ -0,0 +1,50 @@
+import { type DoctorResult } from "../commands/doctor.js";
+export interface DebugReportOptions {
+    issue?: string;
+    outputPath?: string;
+    includePlaySession?: boolean;
+    playWaitMs?: number;
+    maxConsoleLines?: number;
+    maxDebuggerEntries?: number;
+    includeDoctor?: boolean;
+    baseDir?: string;
+}
+export interface DebugReportArtifact {
+    path: string;
+    markdown: string;
+    report: DebugReport;
+}
+export interface DebugReport {
+    generatedAt: string;
+    issue: string | null;
+    environment: {
+        cliVersion: string;
+        nodeVersion: string;
+        platform: string;
+        release: string;
+        cwd: string;
+        hostname: string;
+    };
+    doctor: DoctorResult | null;
+    mcp: {
+        logPath: string;
+        recentLog: string[];
+    };
+    engine: {
+        connected: boolean;
+        error?: string;
+        health?: unknown;
+        project?: unknown;
+        scene?: unknown;
+        diagnostics?: unknown;
+        console?: unknown;
+        debuggerErrors?: unknown;
+        debuggerWarnings?: unknown;
+        playSession?: unknown;
+    };
+}
+export declare function defaultDebugReportFilename(date?: Date): string;
+export declare function redactDebugReport(report: DebugReport): DebugReport;
+export declare function renderDebugReportMarkdown(report: DebugReport): string;
+export declare function collectDebugReport(options?: DebugReportOptions): Promise<DebugReport>;
+export declare function createDebugReportArtifact(options?: DebugReportOptions): Promise<DebugReportArtifact>;

package/dist/lib/debug-report.js

@@ -0,0 +1,308 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { hostname, platform, release } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { EngineApiClient } from "./api-client.js";
+import { shapeEngineLogResponse } from "./log-filters.js";
+import { tildeify } from "./format.js";
+import { getMcpLogPath, readRecentMcpLogLines } from "./mcp-log.js";
+import { runDoctor } from "../commands/doctor.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+function sleep(ms) {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function timestampForFile(date) {
+    return date.toISOString().replace(/[:.]/g, "-");
+}
+export function defaultDebugReportFilename(date = new Date()) {
+    return `summer-debug-report-${timestampForFile(date)}.md`;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function pickString(value, keys) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === "string" && candidate.length > 0)
+            return candidate;
+    }
+    return null;
+}
+function projectPathFromReport(report) {
+    return pickString(report.engine.health, ["project_path", "projectPath", "projectRoot", "project_root"]);
+}
+function resolveOutputPath(report, options) {
+    if (options.outputPath) {
+        return isAbsolute(options.outputPath)
+            ? options.outputPath
+            : resolve(process.cwd(), options.outputPath);
+    }
+    const baseDir = options.baseDir ?? projectPathFromReport(report) ?? process.cwd();
+    return join(baseDir, defaultDebugReportFilename(new Date(report.generatedAt)));
+}
+async function writeMarkdown(path, markdown) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, markdown, "utf-8");
+}
+async function safeCollect(label, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        return {
+            ok: false,
+            label,
+            error: errorMessage(error),
+        };
+    }
+}
+function firstOpsResult(value) {
+    const root = asRecord(value);
+    const results = root?.results;
+    if (Array.isArray(results) && results.length > 0) {
+        return asRecord(results[0]);
+    }
+    return root;
+}
+function isGamePlaying(value) {
+    return firstOpsResult(value)?.playing === true;
+}
+async function collectConsole(client, maxConsoleLines) {
+    const raw = await client.executeOps([
+        { op: "GetConsoleOutput", max_lines: maxConsoleLines },
+    ]);
+    return shapeEngineLogResponse(raw, {
+        errorsOnly: false,
+        maxEntries: maxConsoleLines,
+    }).result;
+}
+async function collectDebugger(client, type, maxEntries) {
+    const op = {
+        op: "GetDebuggerErrors",
+        max_errors: maxEntries,
+        include_stack: true,
+    };
+    if (type === "warning")
+        op.type = "warning";
+    const raw = await client.executeOps([op]);
+    return shapeEngineLogResponse(raw, { maxEntries }).result;
+}
+async function collectPlaySession(client, options) {
+    const session = {
+        requested: true,
+        waitMs: options.playWaitMs,
+    };
+    session.before = await safeCollect("is-running-before", () => client.executeOps([{ op: "IsGameRunning" }]));
+    const wasPlaying = isGamePlaying(session.before);
+    session.wasPlayingBefore = wasPlaying;
+    if (wasPlaying) {
+        session.note =
+            "Game was already running. Collected current runtime diagnostics without clearing console, launching, or stopping.";
+    }
+    else {
+        session.clearConsole = await safeCollect("clear-console", () => client.executeOps([{ op: "ClearConsoleOutput" }]));
+        session.play = await safeCollect("play", () => client.play());
+    }
+    await sleep(options.playWaitMs);
+    session.diagnostics = await safeCollect("diagnostics-after-play", () => client.getDiagnostics());
+    session.console = await safeCollect("console-after-play", () => collectConsole(client, options.maxConsoleLines));
+    session.debuggerErrors = await safeCollect("debugger-errors-after-play", () => collectDebugger(client, "error", options.maxDebuggerEntries));
+    session.debuggerWarnings = await safeCollect("debugger-warnings-after-play", () => collectDebugger(client, "warning", options.maxDebuggerEntries));
+    if (!wasPlaying) {
+        session.stop = await safeCollect("stop", () => client.stop());
+    }
+    return session;
+}
+function redact(value) {
+    if (Array.isArray(value))
+        return value.map((item) => redact(item));
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const [key, nested] of Object.entries(value)) {
+        if (/token|secret|password|authorization|cookie|api[-_]?key|hostname/i.test(key)) {
+            out[key] = "[REDACTED]";
+        }
+        else {
+            out[key] = redact(nested);
+        }
+    }
+    return out;
+}
+export function redactDebugReport(report) {
+    return redact(report);
+}
+function jsonBlock(value) {
+    return `\`\`\`json\n${JSON.stringify(redact(value), null, 2)}\n\`\`\``;
+}
+function doctorSummary(doctor) {
+    if (!doctor)
+        return "Doctor was skipped.";
+    return `${doctor.summary.failures} failures, ${doctor.summary.warnings} warnings, ${doctor.summary.ok} OK.`;
+}
+function issueText(issue) {
+    return issue && issue.trim().length > 0 ? issue.trim() : "No issue text provided.";
+}
+export function renderDebugReportMarkdown(report) {
+    const health = asRecord(report.engine.health);
+    const projectName = pickString(health, ["project_name", "projectName"]) ?? "unknown";
+    const projectPath = pickString(health, ["project_path", "projectPath"]) ?? "unknown";
+    const scene = pickString(health, ["scene", "scenePath", "scene_path"]) ?? "unknown";
+    return `# Summer Debug Report
+
+Generated: ${report.generatedAt}
+
+## Before Sending
+
+This report is meant for Summer Engine support or an assisting AI agent. It does not include auth tokens or project file contents, but it may include local paths, project names, console output, and stack traces. Review it before sending.
+
+## User Issue
+
+${issueText(report.issue)}
+
+## Quick Summary
+
+- Doctor: ${doctorSummary(report.doctor)}
+- Engine connected: ${report.engine.connected ? "yes" : "no"}
+- Project: ${projectName}
+- Project path: ${tildeify(projectPath)}
+- Scene: ${scene}
+
+## Environment
+
+${jsonBlock({
+        ...report.environment,
+        cwd: tildeify(report.environment.cwd),
+        hostname: report.environment.hostname ? "[local-hostname-present]" : "",
+    })}
+
+## Doctor Checks
+
+${report.doctor ? jsonBlock(report.doctor) : "Doctor was skipped."}
+
+## MCP Lifecycle Log
+
+Log path: ${tildeify(report.mcp.logPath)}
+
+${report.mcp.recentLog.length > 0 ? `\`\`\`jsonl\n${report.mcp.recentLog.join("\n")}\n\`\`\`` : "No MCP lifecycle log entries found."}
+
+## Engine Health
+
+${report.engine.health ? jsonBlock(report.engine.health) : report.engine.error ?? "Engine was not reachable."}
+
+## Project State
+
+${report.engine.project ? jsonBlock(report.engine.project) : "No project state collected."}
+
+## Scene State
+
+${report.engine.scene ? jsonBlock(report.engine.scene) : "No scene state collected."}
+
+## Diagnostics
+
+${report.engine.diagnostics ? jsonBlock(report.engine.diagnostics) : "No diagnostics collected."}
+
+## Console
+
+${report.engine.console ? jsonBlock(report.engine.console) : "No console output collected."}
+
+## Debugger Errors
+
+${report.engine.debuggerErrors ? jsonBlock(report.engine.debuggerErrors) : "No debugger errors collected."}
+
+## Debugger Warnings
+
+${report.engine.debuggerWarnings ? jsonBlock(report.engine.debuggerWarnings) : "No debugger warnings collected."}
+
+## Play Session
+
+${report.engine.playSession ? jsonBlock(report.engine.playSession) : "No play session requested. Re-run with --play if the issue only appears while the game is running."}
+
+## Agent Handoff Prompt
+
+\`\`\`text
+You are debugging a Summer Engine project. Use the Summer debug skill and this report as the starting evidence.
+
+User issue:
+${issueText(report.issue)}
+
+Process:
+1. Start with the collected diagnostics, console output, and debugger errors in this report.
+2. Form one specific hypothesis before editing.
+3. Ask before making project changes.
+4. After a fix, re-run the diagnostic that found the issue and update the report or final answer with the exact evidence.
+\`\`\`
+`;
+}
+export async function collectDebugReport(options = {}) {
+    const generatedAt = new Date().toISOString();
+    const includeDoctor = options.includeDoctor ?? true;
+    const report = {
+        generatedAt,
+        issue: options.issue?.trim() || null,
+        environment: {
+            cliVersion: version,
+            nodeVersion: process.version,
+            platform: platform(),
+            release: release(),
+            cwd: process.cwd(),
+            hostname: hostname(),
+        },
+        doctor: null,
+        mcp: {
+            logPath: getMcpLogPath(),
+            recentLog: [],
+        },
+        engine: {
+            connected: false,
+        },
+    };
+    if (includeDoctor) {
+        report.doctor = await runDoctor({ quiet: true });
+    }
+    report.mcp.recentLog = await readRecentMcpLogLines();
+    let client;
+    try {
+        client = await EngineApiClient.connect();
+        report.engine.connected = true;
+    }
+    catch (error) {
+        report.engine.error = errorMessage(error);
+        report.mcp.recentLog = await readRecentMcpLogLines();
+        return report;
+    }
+    const maxConsoleLines = options.maxConsoleLines ?? 200;
+    const maxDebuggerEntries = options.maxDebuggerEntries ?? 100;
+    report.engine.health = await safeCollect("health", () => client.health());
+    report.engine.project = await safeCollect("project-state", () => client.getProjectState());
+    report.engine.scene = await safeCollect("scene-state", () => client.getSceneState());
+    report.engine.diagnostics = await safeCollect("diagnostics", () => client.getDiagnostics());
+    report.engine.console = await safeCollect("console", () => collectConsole(client, maxConsoleLines));
+    report.engine.debuggerErrors = await safeCollect("debugger-errors", () => collectDebugger(client, "error", maxDebuggerEntries));
+    report.engine.debuggerWarnings = await safeCollect("debugger-warnings", () => collectDebugger(client, "warning", maxDebuggerEntries));
+    if (options.includePlaySession) {
+        report.engine.playSession = await collectPlaySession(client, {
+            playWaitMs: options.playWaitMs ?? 2500,
+            maxConsoleLines,
+            maxDebuggerEntries,
+        });
+    }
+    report.mcp.recentLog = await readRecentMcpLogLines();
+    return report;
+}
+export async function createDebugReportArtifact(options = {}) {
+    const report = await collectDebugReport(options);
+    const markdown = renderDebugReportMarkdown(report);
+    const path = resolveOutputPath(report, options);
+    await writeMarkdown(path, markdown);
+    return { path, markdown, report };
+}

package/dist/lib/game-task-plan.js

@@ -249,7 +249,7 @@ function inferSkills(mode, target, goal) {
         addSkill(routes, "design-mechanic", "Implement the core shooting/combat loop.", 230);
         addSkill(routes, "design-level", "Shape the arena, spawn space, cover, and pacing.", 210);
     }
-    addSkill(routes, "gdscript-patterns", "Use direct host file edits for scripts, then verify through MCP.", 90);
+    addSkill(routes, "gdscript-patterns", "Use guarded Summer file tools for scripts, then verify through MCP.", 90);
     addSkill(routes, "verification-before-completion", "Do not finish without a clean verification story.", 80);
     return routes
         .sort((a, b) => b.weight - a.weight)
@@ -350,7 +350,7 @@ export function buildGameTaskPlan(options) {
         verification,
         principles: [
             "The agent should build a playable game slice, not a static demo.",
-            "Use host file edits for code/data/docs; use MCP for live scene state, imports, inspector values, play, and diagnostics.",
+            "Use identity-bound Summer file tools for code/data/docs and Summer scene tools for live hierarchy/inspector changes.",
             "Reuse/import assets before paid generation unless the user explicitly wants custom output.",
             "Prefer exact IDs and structured tool results over search guesses after asset creation.",
             "Verify through the engine before claiming completion.",
@@ -358,8 +358,8 @@ export function buildGameTaskPlan(options) {
         recommendedSkills: inferSkills(mode, target, goal),
         mcpToolPlan: buildMcpToolPlan(mode, target, assetPolicy, verification, goal),
         hostFileWork: [
-            "Write and edit .gd/.cs scripts directly with host file tools.",
-            "Use direct file edits for JSON, markdown, project notes, and simple resources.",
+            "Read and mutate project text through summer_read_file, summer_replace_text, and guarded summer_write_file.",
+            "Use create_only:true for new files and an engine sha256 receipt for overwrites.",
             "Read relevant .summer memory files when project context reports them.",
         ],
         userGates: buildUserGates(mode, assetPolicy),

package/dist/lib/mcp-boot-notice.d.ts

@@ -0,0 +1,3 @@
+import type { BootDriftNotice } from "./version-check.js";
+export declare function getCachedBootDriftNotice(): BootDriftNotice | null;
+export declare function setCachedBootDriftNotice(notice: BootDriftNotice | null): void;

package/dist/lib/mcp-boot-notice.js

@@ -0,0 +1,7 @@
+let cachedBootDriftNotice = null;
+export function getCachedBootDriftNotice() {
+    return cachedBootDriftNotice;
+}
+export function setCachedBootDriftNotice(notice) {
+    cachedBootDriftNotice = notice;
+}

package/dist/lib/mcp-log.d.ts

@@ -0,0 +1,3 @@
+export declare function getMcpLogPath(): string;
+export declare function appendMcpLogEvent(event: string, details?: Record<string, unknown>): void;
+export declare function readRecentMcpLogLines(maxLines?: number): Promise<string[]>;