summer-engine 2.8.2 → 3.1.0

package/dist/core/engine-install.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Where each platform's engine binary lives, shared by `summer install`,
+ * `summer run`, and `summer doctor` so they can never disagree about what
+ * "installed" means.
+ *
+ * Mac and Windows are installed by their platform installers into well-known
+ * locations. Linux has no installer: `summer install` places (or symlinks) the
+ * binary into ~/.summer/engine/, and SUMMER_ENGINE_BINARY points at a prebuilt
+ * binary directly — the path cloud containers that ship their own build use.
+ *
+ * The Linux install *resolution* logic (which source to install from, which
+ * release asset to pick, how to unpack it) also lives here so the CLI command
+ * stays commander wiring + process I/O only.
+ */
+/** Env var naming the engine executable to launch and probe (absolute path).
+ *  The ONE name shared with the autopilot scaffold (assets/autopilot/run.sh)
+ *  and evals/mitl; `summer run --bin <path>` is its flag form. On macOS it is
+ *  the executable inside the bundle (.../Summer.app/Contents/MacOS/Summer). */
+export declare const ENGINE_BIN_ENV = "SUMMER_BIN";
+/** Older name for the same override, documented for Linux cloud containers
+ *  (`running-in-the-cloud`, CHANGELOG 3.0.0) and still honoured after
+ *  ENGINE_BIN_ENV. `summer install` on Linux registers the binary it names. */
+export declare const ENGINE_BINARY_ENV = "SUMMER_ENGINE_BINARY";
+/** The explicit engine override in force — ENGINE_BIN_ENV first, then
+ *  ENGINE_BINARY_ENV — or null when neither is set (blank counts as unset). */
+export declare function engineBinaryOverride(env?: NodeJS.ProcessEnv): {
+    name: string;
+    path: string;
+} | null;
+/**
+ * Why an explicitly named engine path cannot be launched, or null when it can.
+ * A `.app` bundle is refused even when it exists: `summer run` spawns the
+ * executable directly, because `open` (the only way to launch a bundle)
+ * activates the app and defeats background launches, and a binary copied OUT
+ * of the bundle dies on its Sparkle @rpath — so the value has to be the
+ * executable inside the bundle.
+ */
+export declare function describeEngineExecutableProblem(path: string, source: string): string | null;
+/** Env var naming a direct artifact URL (tar.gz, zip, or raw binary) to install
+ *  on Linux instead of the published release. */
+export declare const ENGINE_URL_ENV = "SUMMER_ENGINE_URL";
+/** The single executable name Linux release artifacts contain and installs
+ *  register. Matches the release asset contents (.github/workflows/release.yml
+ *  in the engine repository). */
+export declare const LINUX_ENGINE_BINARY_NAME = "summer-linux-x86_64";
+/**
+ * Where Linux release artifacts are published today: GitHub Releases on the
+ * engine repository (engine tags are v0.*; see .github/workflows/release.yml).
+ * This is the ONE place to change when Linux artifacts move to the desktop
+ * releases CDN — point it at an endpoint returning the same GitHub-style
+ * releases JSON (an array of { tag_name, draft, prerelease, assets:[{ name,
+ * browser_download_url }] }).
+ */
+export declare const LINUX_RELEASES_API_URL = "https://api.github.com/repos/SummerEngine/SummerEngine/releases?per_page=30";
+/** Release asset naming contract with .github/workflows/release.yml. */
+export declare const LINUX_ASSET_PATTERN: RegExp;
+export declare function linuxEngineInstallDir(): string;
+export declare function macEnginePaths(env?: NodeJS.ProcessEnv): string[];
+export declare function windowsEnginePaths(env?: NodeJS.ProcessEnv): string[];
+export declare function linuxEnginePaths(): string[];
+export declare function engineBinaryCandidates(os?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string[];
+/** First existing engine binary for this machine, or null. SUMMER_BIN /
+ *  SUMMER_ENGINE_BINARY wins when set and present; a set-but-missing override
+ *  falls through to the platform locations rather than reporting a phantom
+ *  install (`summer run` is stricter: see resolveRunBinary). */
+export declare function findEngineBinary(os?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string | null;
+export type LinuxInstallSource = {
+    kind: "binary";
+    path: string;
+} | {
+    kind: "url";
+    url: string;
+} | {
+    kind: "release";
+    apiUrl: string;
+};
+/**
+ * Resolution order for `summer install` on Linux:
+ *   1. SUMMER_ENGINE_BINARY — an existing engine binary on disk (the path cloud
+ *      containers with a prebuilt engine use). Registered, nothing downloaded.
+ *   2. SUMMER_ENGINE_URL — any artifact URL: .tar.gz, .zip, or a raw executable.
+ *   3. The published Linux release artifact (LINUX_RELEASES_API_URL).
+ */
+export declare function resolveLinuxInstallSource(env?: NodeJS.ProcessEnv): LinuxInstallSource;
+export interface LinuxReleaseAsset {
+    version: string;
+    url: string;
+    /** Sibling "<asset>.sha256" download URL when the release published one. */
+    sha256Url?: string;
+}
+/**
+ * Newest published (non-draft, non-prerelease) release that actually carries a
+ * Linux artifact. Releases are shared between engine tags (v0.x) and CLI tags
+ * (v1.x, v2.x), and CLI releases have no engine binaries — so "latest release"
+ * is the wrong query and this scans instead.
+ */
+export declare function pickLinuxReleaseAsset(releases: unknown): LinuxReleaseAsset;
+/** How to unpack a downloaded Linux artifact, judged by its file name
+ *  (query string ignored). Anything that is not a known archive is treated as
+ *  the raw executable itself. */
+export declare function linuxArchiveKind(nameOrUrl: string): "tar.gz" | "zip" | "binary";
+/** Locate the engine executable inside an extracted artifact: the canonical
+ *  name first, then the only file, then anything that looks like an engine
+ *  build (covers artifacts packed straight from bin/). */
+export declare function findExtractedEngineBinary(files: string[]): string | null;

package/dist/core/engine-install.js

@@ -0,0 +1,190 @@
+import { existsSync, statSync } from "fs";
+import { homedir, platform } from "os";
+import { basename, join } from "path";
+/**
+ * Where each platform's engine binary lives, shared by `summer install`,
+ * `summer run`, and `summer doctor` so they can never disagree about what
+ * "installed" means.
+ *
+ * Mac and Windows are installed by their platform installers into well-known
+ * locations. Linux has no installer: `summer install` places (or symlinks) the
+ * binary into ~/.summer/engine/, and SUMMER_ENGINE_BINARY points at a prebuilt
+ * binary directly — the path cloud containers that ship their own build use.
+ *
+ * The Linux install *resolution* logic (which source to install from, which
+ * release asset to pick, how to unpack it) also lives here so the CLI command
+ * stays commander wiring + process I/O only.
+ */
+/** Env var naming the engine executable to launch and probe (absolute path).
+ *  The ONE name shared with the autopilot scaffold (assets/autopilot/run.sh)
+ *  and evals/mitl; `summer run --bin <path>` is its flag form. On macOS it is
+ *  the executable inside the bundle (.../Summer.app/Contents/MacOS/Summer). */
+export const ENGINE_BIN_ENV = "SUMMER_BIN";
+/** Older name for the same override, documented for Linux cloud containers
+ *  (`running-in-the-cloud`, CHANGELOG 3.0.0) and still honoured after
+ *  ENGINE_BIN_ENV. `summer install` on Linux registers the binary it names. */
+export const ENGINE_BINARY_ENV = "SUMMER_ENGINE_BINARY";
+/** The explicit engine override in force — ENGINE_BIN_ENV first, then
+ *  ENGINE_BINARY_ENV — or null when neither is set (blank counts as unset). */
+export function engineBinaryOverride(env = process.env) {
+    for (const name of [ENGINE_BIN_ENV, ENGINE_BINARY_ENV]) {
+        const path = env[name]?.trim();
+        if (path)
+            return { name, path };
+    }
+    return null;
+}
+/**
+ * Why an explicitly named engine path cannot be launched, or null when it can.
+ * A `.app` bundle is refused even when it exists: `summer run` spawns the
+ * executable directly, because `open` (the only way to launch a bundle)
+ * activates the app and defeats background launches, and a binary copied OUT
+ * of the bundle dies on its Sparkle @rpath — so the value has to be the
+ * executable inside the bundle.
+ */
+export function describeEngineExecutableProblem(path, source) {
+    const trimmed = path.replace(/[\\/]+$/, "");
+    if (/\.app$/i.test(basename(trimmed))) {
+        return (`${source} names the bundle ${trimmed}, not the engine executable. Pass the executable inside it: ` +
+            `${join(trimmed, "Contents", "MacOS", "Summer")}\n` +
+            "summer run spawns that executable directly: launching the .app would go through `open`, which activates " +
+            "the app and defeats background launches, and a binary copied out of the bundle dies on its Sparkle @rpath.");
+    }
+    if (!existsSync(trimmed)) {
+        return `${source} names ${trimmed}, but nothing exists there.`;
+    }
+    if (statSync(trimmed).isDirectory()) {
+        return `${source} names ${trimmed}, which is a directory, not the engine executable.`;
+    }
+    return null;
+}
+/** Env var naming a direct artifact URL (tar.gz, zip, or raw binary) to install
+ *  on Linux instead of the published release. */
+export const ENGINE_URL_ENV = "SUMMER_ENGINE_URL";
+/** The single executable name Linux release artifacts contain and installs
+ *  register. Matches the release asset contents (.github/workflows/release.yml
+ *  in the engine repository). */
+export const LINUX_ENGINE_BINARY_NAME = "summer-linux-x86_64";
+/**
+ * Where Linux release artifacts are published today: GitHub Releases on the
+ * engine repository (engine tags are v0.*; see .github/workflows/release.yml).
+ * This is the ONE place to change when Linux artifacts move to the desktop
+ * releases CDN — point it at an endpoint returning the same GitHub-style
+ * releases JSON (an array of { tag_name, draft, prerelease, assets:[{ name,
+ * browser_download_url }] }).
+ */
+export const LINUX_RELEASES_API_URL = "https://api.github.com/repos/SummerEngine/SummerEngine/releases?per_page=30";
+/** Release asset naming contract with .github/workflows/release.yml. */
+export const LINUX_ASSET_PATTERN = /^Summer-linux-x86_64.*\.tar\.gz$/;
+export function linuxEngineInstallDir() {
+    return join(homedir(), ".summer", "engine");
+}
+export function macEnginePaths(env = process.env) {
+    return [
+        "/Applications/Summer.app/Contents/MacOS/Summer",
+        `${env.HOME}/Applications/Summer.app/Contents/MacOS/Summer`,
+    ];
+}
+export function windowsEnginePaths(env = process.env) {
+    return [
+        `${env.LOCALAPPDATA}\\SummerEngine\\current\\Summer.exe`,
+        `${env.LOCALAPPDATA}\\Programs\\Summer Engine\\Summer.exe`,
+        `${env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
+    ];
+}
+export function linuxEnginePaths() {
+    return [join(linuxEngineInstallDir(), LINUX_ENGINE_BINARY_NAME)];
+}
+export function engineBinaryCandidates(os = platform(), env = process.env) {
+    const override = engineBinaryOverride(env)?.path;
+    const platformPaths = os === "darwin"
+        ? macEnginePaths(env)
+        : os === "linux"
+            ? linuxEnginePaths()
+            : windowsEnginePaths(env);
+    return override ? [override, ...platformPaths] : platformPaths;
+}
+/** First existing engine binary for this machine, or null. SUMMER_BIN /
+ *  SUMMER_ENGINE_BINARY wins when set and present; a set-but-missing override
+ *  falls through to the platform locations rather than reporting a phantom
+ *  install (`summer run` is stricter: see resolveRunBinary). */
+export function findEngineBinary(os = platform(), env = process.env) {
+    for (const path of engineBinaryCandidates(os, env)) {
+        if (path && existsSync(path))
+            return path;
+    }
+    return null;
+}
+/**
+ * Resolution order for `summer install` on Linux:
+ *   1. SUMMER_ENGINE_BINARY — an existing engine binary on disk (the path cloud
+ *      containers with a prebuilt engine use). Registered, nothing downloaded.
+ *   2. SUMMER_ENGINE_URL — any artifact URL: .tar.gz, .zip, or a raw executable.
+ *   3. The published Linux release artifact (LINUX_RELEASES_API_URL).
+ */
+export function resolveLinuxInstallSource(env = process.env) {
+    const binary = env[ENGINE_BINARY_ENV]?.trim();
+    if (binary)
+        return { kind: "binary", path: binary };
+    const url = env[ENGINE_URL_ENV]?.trim();
+    if (url)
+        return { kind: "url", url };
+    return { kind: "release", apiUrl: LINUX_RELEASES_API_URL };
+}
+/**
+ * Newest published (non-draft, non-prerelease) release that actually carries a
+ * Linux artifact. Releases are shared between engine tags (v0.x) and CLI tags
+ * (v1.x, v2.x), and CLI releases have no engine binaries — so "latest release"
+ * is the wrong query and this scans instead.
+ */
+export function pickLinuxReleaseAsset(releases) {
+    const list = Array.isArray(releases) ? releases : [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const release = entry;
+        if (release.draft === true || release.prerelease === true)
+            continue;
+        const assets = Array.isArray(release.assets) ? release.assets : [];
+        const named = assets.filter((asset) => Boolean(asset &&
+            typeof asset === "object" &&
+            typeof asset.name === "string" &&
+            typeof asset
+                .browser_download_url === "string"));
+        const artifact = named.find((asset) => LINUX_ASSET_PATTERN.test(asset.name));
+        if (!artifact)
+            continue;
+        const checksum = named.find((asset) => asset.name === `${artifact.name}.sha256`);
+        return {
+            version: typeof release.tag_name === "string" ? release.tag_name : "unknown",
+            url: artifact.browser_download_url,
+            ...(checksum ? { sha256Url: checksum.browser_download_url } : {}),
+        };
+    }
+    throw new Error("No published release carries a Linux engine artifact yet " +
+        `(looked for ${String(LINUX_ASSET_PATTERN)}). ` +
+        `Set ${ENGINE_URL_ENV} to a build artifact URL, or ${ENGINE_BINARY_ENV} to an existing binary, and re-run \`summer install\`.`);
+}
+/** How to unpack a downloaded Linux artifact, judged by its file name
+ *  (query string ignored). Anything that is not a known archive is treated as
+ *  the raw executable itself. */
+export function linuxArchiveKind(nameOrUrl) {
+    const path = nameOrUrl.split(/[?#]/, 1)[0].toLowerCase();
+    if (path.endsWith(".tar.gz") || path.endsWith(".tgz"))
+        return "tar.gz";
+    if (path.endsWith(".zip"))
+        return "zip";
+    return "binary";
+}
+/** Locate the engine executable inside an extracted artifact: the canonical
+ *  name first, then the only file, then anything that looks like an engine
+ *  build (covers artifacts packed straight from bin/). */
+export function findExtractedEngineBinary(files) {
+    const canonical = files.find((f) => basename(f) === LINUX_ENGINE_BINARY_NAME);
+    if (canonical)
+        return canonical;
+    if (files.length === 1)
+        return files[0];
+    return (files.find((f) => /godot\.linuxbsd\..*editor|summer.*linux/i.test(basename(f))) ??
+        null);
+}

package/dist/core/engine.d.ts

@@ -0,0 +1,94 @@
+import { type EngineCapabilities } from "./capability-skew.js";
+export interface EngineSelection {
+    instanceId?: string;
+    projectPath?: string;
+    cwd?: string;
+}
+export interface EngineDiscoveryOptions {
+    summerDir?: string;
+    nowMs?: number;
+}
+export interface DiscoverEngineOptions extends EngineDiscoveryOptions {
+    /** Working directory whose enclosing project (walk up to project.godot)
+     *  breaks a tie between several live editors. Default: process.cwd(). */
+    cwd?: string;
+    /** Environment to read SUMMER_ENGINE_PROJECT / SUMMER_ENGINE_INSTANCE_ID
+     *  from. Default: process.env. */
+    env?: NodeJS.ProcessEnv;
+}
+/** Env names the MCP server already honours for an explicit selection
+ *  (src/mcp/server.ts startMcpServer). The CLI face reads the same two so a
+ *  script can pin the editor without a per-command flag. */
+export declare const ENGINE_PROJECT_ENV = "SUMMER_ENGINE_PROJECT";
+export declare const ENGINE_INSTANCE_ENV = "SUMMER_ENGINE_INSTANCE_ID";
+/** An explicit editor selection from the environment, or null when neither
+ *  variable is set. */
+export declare function engineSelectionFromEnv(env?: NodeJS.ProcessEnv): EngineSelection | null;
+export interface EngineInstance {
+    schemaVersion: 1;
+    instanceId: string;
+    pid: number;
+    port: number;
+    token: string;
+    projectId?: string;
+    projectIdHash?: string;
+    resourceRoot: string;
+    projectName?: string;
+    heartbeatAt: number;
+    engineVersion?: string;
+}
+export interface EngineConnection {
+    port: number;
+    token: string;
+    health: EngineHealth;
+    instance?: EngineInstance;
+    selection: EngineSelection | null;
+    source: "registry" | "legacy";
+}
+export declare function getApiToken(summerDir?: string): Promise<string | null>;
+export declare function getApiPort(summerDir?: string): Promise<number>;
+export declare function findProjectRoot(startPath: string): Promise<string | null>;
+export declare function listEngineInstances(nowMs?: number, summerDir?: string): Promise<EngineInstance[]>;
+export declare function resolveEngineConnection(selection?: EngineSelection, options?: EngineDiscoveryOptions): Promise<EngineConnection>;
+/**
+ * The registry half of no-selection discovery (the CLI face; see
+ * EngineApiClient.connect, which reads the global pointer first). Editors
+ * launched `--summer-no-publish`, or a second editor that never owned the
+ * pointer, exist only here. "Live" = pid alive + heartbeat fresh
+ * (listEngineInstances) + /api/health answers with the registered instanceId.
+ *
+ *   exactly one live editor  -> that connection
+ *   several                  -> the one whose project encloses `cwd`, else an
+ *                               error listing them and how to pick one
+ *   none                     -> null (the caller words the "not running" error,
+ *                               since only it knows whether a pointer existed)
+ *
+ * Reads only `summerDir` (default ~/.summer); never the pointer files.
+ */
+export declare function discoverRegistryConnection(options?: DiscoverEngineOptions): Promise<EngineConnection | null>;
+/** The no-selection "nothing reachable" error, worded by whether a pointer
+ *  existed. Kept here so the CLI face and its tests share one text; the
+ *  "no api-token found" phrase is what headless/resolve.ts keys on. */
+export declare function engineNotRunningError(pointer: {
+    port: number;
+    token: string | null;
+}, summerDir?: string): Error;
+export interface EngineHealth {
+    ok: boolean;
+    engine: string;
+    version: string;
+    port: number;
+    pid?: number;
+    instanceId?: string;
+    projectId?: string;
+    projectIdHash?: string;
+    mainAliveMs?: number;
+    queueDepth?: number;
+    /** Advertised by newer engines only: dispatchable op kinds, single-only ops,
+     *  protocol version. Absent on older builds — absence proves nothing. */
+    capabilities?: EngineCapabilities;
+    project_name?: string;
+    project_path?: string;
+    scene?: string;
+}
+export declare function checkEngineHealth(port: number): Promise<EngineHealth | null>;

package/dist/{lib → core}/engine.js

@@ -1,10 +1,27 @@
 import { lstat, readFile, readdir, realpath, stat } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { getSummerDir } from "./auth.js";
+import { asRecord, numberFrom, stringFrom } from "./util/json.js";
+import { processIsAlive } from "./util/process.js";
+import { parseEngineCapabilities, } from "./capability-skew.js";
 const DEFAULT_PORT = 6550;
 const INSTANCE_SCHEMA_VERSION = 1;
 const INSTANCE_STALE_MS = 180_000;
 const MAX_INSTANCE_FILE_BYTES = 64 * 1024;
+/** Env names the MCP server already honours for an explicit selection
+ *  (src/mcp/server.ts startMcpServer). The CLI face reads the same two so a
+ *  script can pin the editor without a per-command flag. */
+export const ENGINE_PROJECT_ENV = "SUMMER_ENGINE_PROJECT";
+export const ENGINE_INSTANCE_ENV = "SUMMER_ENGINE_INSTANCE_ID";
+/** An explicit editor selection from the environment, or null when neither
+ *  variable is set. */
+export function engineSelectionFromEnv(env = process.env) {
+    const instanceId = stringFromUnknown(env[ENGINE_INSTANCE_ENV]);
+    const projectPath = stringFromUnknown(env[ENGINE_PROJECT_ENV]);
+    if (!instanceId && !projectPath)
+        return null;
+    return { instanceId, projectPath };
+}
 export async function getApiToken(summerDir = getSummerDir()) {
     try {
         const token = await readFile(join(summerDir, "api-token"), "utf-8");
@@ -29,22 +46,6 @@ function stringFromUnknown(value) {
         ? value.trim()
         : undefined;
 }
-function numberFromUnknown(value) {
-    return typeof value === "number" && Number.isFinite(value)
-        ? value
-        : undefined;
-}
-function processIsAlive(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === "EPERM";
-    }
-}
 async function canonicalPath(path) {
     const absolute = resolve(path);
     try {
@@ -84,11 +85,11 @@ function parseEngineInstance(value) {
     if (!record || record.schemaVersion !== INSTANCE_SCHEMA_VERSION)
         return null;
     const instanceId = stringFromUnknown(record.instanceId);
-    const pid = numberFromUnknown(record.pid);
-    const port = numberFromUnknown(record.port);
+    const pid = numberFrom(record.pid);
+    const port = numberFrom(record.port);
     const token = stringFromUnknown(record.token);
     const resourceRoot = stringFromUnknown(record.resourceRoot);
-    const heartbeatAt = numberFromUnknown(record.heartbeatAt);
+    const heartbeatAt = numberFrom(record.heartbeatAt);
     if (!instanceId ||
         !pid ||
         !Number.isInteger(pid) ||
@@ -255,16 +256,60 @@ export async function resolveEngineConnection(selection = {}, options = {}) {
         source: "legacy",
     };
 }
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : null;
-}
-function stringFrom(value) {
-    return typeof value === "string" && value.length > 0 ? value : undefined;
+/**
+ * The registry half of no-selection discovery (the CLI face; see
+ * EngineApiClient.connect, which reads the global pointer first). Editors
+ * launched `--summer-no-publish`, or a second editor that never owned the
+ * pointer, exist only here. "Live" = pid alive + heartbeat fresh
+ * (listEngineInstances) + /api/health answers with the registered instanceId.
+ *
+ *   exactly one live editor  -> that connection
+ *   several                  -> the one whose project encloses `cwd`, else an
+ *                               error listing them and how to pick one
+ *   none                     -> null (the caller words the "not running" error,
+ *                               since only it knows whether a pointer existed)
+ *
+ * Reads only `summerDir` (default ~/.summer); never the pointer files.
+ */
+export async function discoverRegistryConnection(options = {}) {
+    const summerDir = options.summerDir ?? getSummerDir();
+    const registered = await listEngineInstances(options.nowMs ?? Date.now(), summerDir);
+    const live = [];
+    for (const instance of registered) {
+        try {
+            live.push(await connectionForInstance(instance, {}));
+        }
+        catch {
+            // Not answering, or a different editor now owns that port: not live.
+        }
+    }
+    if (live.length === 0)
+        return null;
+    if (live.length === 1)
+        return live[0];
+    const projectRoot = await findProjectRoot(options.cwd ?? process.cwd());
+    if (projectRoot) {
+        const canonicalRoot = await canonicalPath(projectRoot);
+        const matching = live.filter((connection) => connection.instance?.resourceRoot === canonicalRoot);
+        if (matching.length === 1)
+            return matching[0];
+    }
+    const instances = live.map((connection) => connection.instance);
+    throw new Error("Multiple Summer editors are running and none of them has the project for the current directory open. " +
+        "Run this from inside the project directory, or pick one: " +
+        `set ${ENGINE_PROJECT_ENV}=<project path> (or ${ENGINE_INSTANCE_ENV}=<id>); ` +
+        "for the MCP server pass `summer mcp --project <path>` (or `--instance <id>`).\n" +
+        formatInstances(instances));
 }
-function numberFrom(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+/** The no-selection "nothing reachable" error, worded by whether a pointer
+ *  existed. Kept here so the CLI face and its tests share one text; the
+ *  "no api-token found" phrase is what headless/resolve.ts keys on. */
+export function engineNotRunningError(pointer, summerDir = getSummerDir()) {
+    const instancesDir = join(summerDir, "instances");
+    if (pointer.token) {
+        return new Error(`Summer Engine is not responding on port ${pointer.port} (stale api-token pointer) and no live editor is registered in ${instancesDir}. Make sure it's open.`);
+    }
+    return new Error(`Summer Engine is not running (no api-token found, no live editor registered in ${instancesDir}). Open Summer Engine first.`);
 }
 export async function checkEngineHealth(port) {
     try {
@@ -294,6 +339,7 @@ export async function checkEngineHealth(port) {
             projectIdHash: stringFrom(data.projectIdHash),
             mainAliveMs: numberFrom(data.mainAliveMs),
             queueDepth: numberFrom(data.queueDepth),
+            capabilities: parseEngineCapabilities(data.capabilities),
             project_name: stringFrom(data.project_name),
             project_path: stringFrom(data.project_path),
             scene: stringFrom(data.scene),

package/dist/core/feedback/client.d.ts

@@ -0,0 +1,88 @@
+export declare function getFeedbackSessionId(): string;
+/** Test-only seam. */
+export declare function _resetFeedbackSessionForTests(): void;
+/** Kill switches: send NOTHING when either is set to "1". */
+export declare function isFeedbackDisabled(): boolean;
+/**
+ * Anonymous install id: a random uuid persisted once in ~/.summer/.
+ * Falls back to an ephemeral uuid if the store is unreadable/unwritable —
+ * feedback must never fail because the store does.
+ */
+export declare function getInstallId(): Promise<string>;
+/**
+ * First-run notice gate: returns true exactly once per machine — the first
+ * time the feedback tool is ever called — and writes the marker so every
+ * later call returns false. That first call sends nothing (the notice must
+ * precede the first event). Errors → false (no notice beats a crash, and
+ * the disclosure also lives in the tool description).
+ */
+export declare function consumeFirstRunNotice(): Promise<boolean>;
+/** Every field a report POST carries, in one place so the tool description,
+ *  the first-run notice and the tests cannot disagree about what is sent. */
+export declare const FEEDBACK_FIELDS_SENT: string;
+export declare const FIRST_RUN_NOTICE: string;
+export interface LibraryFeedbackReport {
+    entry_id: string;
+    outcome: "worked" | "worked_with_fixes" | "wrong" | "outdated" | "incomplete" | "did_not_apply" | "misrouted";
+    note?: string;
+    deviation?: string;
+}
+export interface SendLibraryFeedbackInput {
+    reports: LibraryFeedbackReport[];
+    engine_version: string;
+    /** Self-reported model id of the reporting agent ("unknown" allowed). */
+    agent_model: string;
+    /**
+     * Host app identity ("name version", e.g. "claude-code 2.1.0") captured
+     * from the MCP initialize handshake by the server adapter — never
+     * self-reported by the agent. Omitted when the handshake carried none.
+     */
+    client?: string;
+}
+/**
+ * Why a batch was dropped — so an agent can tell a missing endpoint from a
+ * network blip (E2E 2026-09-03 F-03: production answered 404 and the tool
+ * said only `dropped: true`). Describes the RESPONSE only; nothing about it
+ * is sent anywhere.
+ */
+export type FeedbackDropReason = 
+/** HTTP 404 — the gateway has no library-feedback route (deploy order). */
+"endpoint_missing"
+/** Any other 4xx — the gateway refused this batch (auth, schema, rate). */
+ | "rejected"
+/** 5xx — the gateway failed; the route exists. */
+ | "server_error"
+/** fetch threw: offline, DNS, TLS, or the 1s timeout. No response at all. */
+ | "network";
+export interface SendLibraryFeedbackResult {
+    /** true ONLY when the gateway accepted the report (2xx) within the timeout. */
+    recorded: boolean;
+    /** present (true) only when disabled by env — nothing sent. */
+    disabled?: boolean;
+    /** present (true) only on the very first call ever made on this machine —
+     *  nothing sent; `notice` explains and asks for a re-send. */
+    first_run?: boolean;
+    /** present (true) when the POST failed / timed out / was refused. There is
+     *  no queue and no retry: the batch is gone. Honest, non-fatal. */
+    dropped?: boolean;
+    /** present alongside dropped — the HTTP status the gateway answered with;
+     *  absent when the request never got a response (reason "network"). */
+    status?: number;
+    /** present alongside dropped — see FeedbackDropReason. */
+    reason?: FeedbackDropReason;
+    /** present only alongside first_run. */
+    notice?: string;
+}
+/** Classify a non-2xx response. Exported for tests. */
+export declare function dropReasonForStatus(status: number): FeedbackDropReason;
+/**
+ * Send one batched feedback report. Never throws. Blocks at most TIMEOUT_MS.
+ *
+ * Result matrix:
+ * - env kill switch          → { recorded: false, disabled: true }     (nothing sent)
+ * - first call on machine    → { recorded: false, first_run: true, notice } (nothing sent)
+ * - gateway accepted (2xx)   → { recorded: true }
+ * - non-2xx                  → { recorded: false, dropped: true, status, reason } (no retry exists)
+ * - fetch threw / timed out  → { recorded: false, dropped: true, reason: "network" }
+ */
+export declare function sendLibraryFeedback(input: SendLibraryFeedbackInput): Promise<SendLibraryFeedbackResult>;