summer-engine 2.8.2 → 3.0.0

package/dist/{commands → cli/commands}/memory.js

@@ -1,9 +1,9 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { Command } from "commander";
-import { checkEngineHealth, getApiPort } from "../lib/engine.js";
-import { getProjectMemorySummary, } from "../lib/project-memory.js";
-import { c, pad, tildeify } from "../lib/format.js";
+import { checkEngineHealth, getApiPort } from "../../core/engine.js";
+import { getProjectMemorySummary, } from "../../project-memory/project-memory.js";
+import { c, pad, tildeify } from "../../core/format.js";
 export const memoryCommand = new Command("memory")
     .description("Inspect project memory in .summer")
     .option("--project <path>", "Project directory to inspect")
@@ -59,7 +59,7 @@ memoryCommand
     }
     console.log(join(resolvedProject.projectPath, ".summer"));
 });
-export async function resolveMemoryProject(projectOption) {
+async function resolveMemoryProject(projectOption) {
     if (projectOption) {
         const projectPath = resolve(projectOption);
         if (!existsSync(projectPath)) {
@@ -105,17 +105,26 @@ export function findProjectRoot(startDir) {
 }
 export function resolveMemoryFilePath(projectPath, requested) {
     const summerDir = resolve(projectPath, ".summer");
-    const rawPath = requested.startsWith(".summer/")
-        ? resolve(projectPath, requested)
-        : resolve(summerDir, requested);
-    const withinSummer = isPathInside(summerDir, rawPath);
-    if (!withinSummer) {
+    // Accept Windows-style separators in the requested name on every platform;
+    // memory file names never legitimately contain a backslash.
+    const normalized = requested.replace(/\\/g, "/");
+    const rawPath = normalized.startsWith(".summer/")
+        ? resolve(projectPath, normalized)
+        : resolve(summerDir, normalized);
+    if (!isPathInside(summerDir, rawPath)) {
         throw new Error("Memory files must be inside the project's .summer directory.");
     }
     if (!existsSync(rawPath)) {
         throw new Error(`Memory file not found: ${requested}`);
     }
-    if (!statSync(rawPath).isFile()) {
+    // The lexical check above follows nothing; a symlink placed inside .summer
+    // can point anywhere. Compare real paths on BOTH sides so a link that leaves
+    // .summer is refused (and a legitimately symlinked .summer still works).
+    const realPath = realpathSync(rawPath);
+    if (!isPathInside(realpathSync(summerDir), realPath)) {
+        throw new Error("Memory files must be inside the project's .summer directory (a symlink that leaves it is refused).");
+    }
+    if (!statSync(realPath).isFile()) {
         throw new Error(`Memory path is not a file: ${requested}`);
     }
     return rawPath;

package/dist/cli/commands/open.d.ts

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import { type OpenDeps, type OpenResult, type OpenSurface } from "../../core/capabilities/navigation/open.js";
+/**
+ * `summer open` has two jobs that share one verb:
+ *
+ * 1. `summer open <project-dir>` — the original command: open a project in
+ *    Summer Engine (launching it when it is not running). Any argument that is
+ *    an existing directory or looks like a filesystem path takes this branch,
+ *    so nothing that worked before changes.
+ * 2. `summer open <target>` — navigation (docs/design/NAVIGATION-DESIGN.md):
+ *    a product-map id ("billing"), an intent phrase ("change my plan"), a
+ *    res:// path, or a summerengine.com path. Same behavior as the
+ *    summer_open MCP tool and `summer tool open` (core/capabilities/navigation).
+ */
+export interface OpenNavigationOptions {
+    print?: boolean;
+    list?: boolean;
+    web?: boolean;
+    editor?: boolean;
+    json?: boolean;
+    path?: string;
+    node?: string;
+    scene?: string;
+    param?: string[];
+}
+/**
+ * Which branch does `summer open <arg>` take?
+ * - An exact product-map id or alias (`billing`, `inspector`) is ALWAYS a
+ *   navigation target, even if a directory of that name exists in cwd — use
+ *   `./billing` to open a project folder that happens to share a name.
+ * - `./x`, `../x`, `~/x`, `.`, `..`, Windows drive paths: project directory.
+ * - `/x`: a project directory when it exists on disk; otherwise a
+ *   summerengine.com path (`/pricing`) when the map knows it; otherwise the
+ *   project-directory branch, which reports "Directory not found".
+ * - Anything else: a project directory only when it exists as one.
+ */
+export declare function looksLikeProjectPath(arg: string): boolean;
+export declare function parseParamOptions(options: OpenNavigationOptions): Record<string, string>;
+export declare function surfaceFromOptions(options: OpenNavigationOptions): OpenSurface;
+export declare function formatOpenResult(result: OpenResult): string;
+export declare function defaultOpenDeps(): OpenDeps;
+/** The navigation branch. Returns the result so tests can assert without a
+ *  process exit; sets exitCode 1 when nothing could be opened. */
+export declare function runOpenNavigation(target: string | undefined, options: OpenNavigationOptions, deps?: OpenDeps, log?: (line: string) => void): Promise<OpenResult>;
+export declare const openCommand: Command;

package/dist/cli/commands/open.js

@@ -0,0 +1,216 @@
+import { Command } from "commander";
+import { existsSync, statSync } from "fs";
+import { resolve } from "path";
+import open from "open";
+import { getApiPort, checkEngineHealth } from "../../core/engine.js";
+import { getAuthToken } from "../../core/auth.js";
+import { resolveGatewayUrl } from "../../core/config.js";
+import { EngineApiClient } from "../../core/api-client.js";
+import { resolveTarget, runOpen, } from "../../core/capabilities/navigation/open.js";
+import { getNavTarget } from "../../core/capabilities/navigation/targets.js";
+import { c, sym } from "../../core/format.js";
+/**
+ * Which branch does `summer open <arg>` take?
+ * - An exact product-map id or alias (`billing`, `inspector`) is ALWAYS a
+ *   navigation target, even if a directory of that name exists in cwd — use
+ *   `./billing` to open a project folder that happens to share a name.
+ * - `./x`, `../x`, `~/x`, `.`, `..`, Windows drive paths: project directory.
+ * - `/x`: a project directory when it exists on disk; otherwise a
+ *   summerengine.com path (`/pricing`) when the map knows it; otherwise the
+ *   project-directory branch, which reports "Directory not found".
+ * - Anything else: a project directory only when it exists as one.
+ */
+export function looksLikeProjectPath(arg) {
+    const trimmed = arg.trim();
+    if (getNavTarget(trimmed.toLowerCase().replace(/\s+/g, "-")))
+        return false;
+    if (/^(\.\/|\.\.\/|~)/.test(trimmed) || /^[A-Za-z]:[\\/]/.test(trimmed) || trimmed === "." || trimmed === "..")
+        return true;
+    if (trimmed.startsWith("/")) {
+        if (isDirectory(trimmed))
+            return true;
+        const resolution = resolveTarget(trimmed, {}, "web");
+        return !(resolution.kind === "target");
+    }
+    return isDirectory(trimmed);
+}
+function isDirectory(path) {
+    try {
+        return statSync(resolve(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function parseParamOptions(options) {
+    const params = {};
+    for (const pair of options.param ?? []) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            throw new Error(`--param expects key=value, got "${pair}"`);
+        params[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+    }
+    if (options.path)
+        params.path = options.path;
+    if (options.node)
+        params.node = options.node;
+    if (options.scene)
+        params.scene = options.scene;
+    return params;
+}
+export function surfaceFromOptions(options) {
+    if (options.web && options.editor)
+        throw new Error("--web and --editor are mutually exclusive");
+    return options.web ? "web" : options.editor ? "editor" : "auto";
+}
+export function formatOpenResult(result) {
+    const lines = [];
+    switch (result.action) {
+        case "listed": {
+            const targets = result.targets ?? [];
+            const width = Math.max(...targets.map((t) => t.id.length), 2);
+            lines.push(c.bold(`Summer destinations (${targets.length})`));
+            for (const t of targets) {
+                const req = t.requires.login ? c.dim(" [login]") : "";
+                const avail = t.availability === "available"
+                    ? c.green("available  ")
+                    : t.availability === "legacy"
+                        ? c.dim("legacy op  ")
+                        : t.availability === "unavailable"
+                            ? c.yellow("unavailable")
+                            : t.availability === "unknown"
+                                ? c.dim("unknown    ")
+                                : c.dim("web        ");
+                lines.push(`  ${t.id.padEnd(width)}  ${avail} ${t.title}${req}`);
+            }
+            lines.push("");
+            lines.push(c.dim("Editor availability comes from the connected engine (unknown = engine not running; unavailable = update Summer Engine)."));
+            lines.push(c.dim("Open one: summer open <id>   Print instead: summer open <id> --print   Phrases work too: summer open \"change my plan\""));
+            break;
+        }
+        case "opened":
+            lines.push(`${sym.ok()} Opened ${result.target?.title ?? result.url ?? "destination"}`);
+            if (result.opened_url)
+                lines.push(`  ${result.opened_url}`);
+            if (result.op)
+                lines.push(`  ${c.dim(JSON.stringify(result.op))}`);
+            if (result.hint)
+                lines.push(`  ${c.dim(result.hint)}`);
+            break;
+        case "printed":
+            if (result.url)
+                lines.push(result.url);
+            if (result.login_url && result.logged_in === false)
+                lines.push(c.dim(`not logged in here — through login: ${result.login_url}`));
+            if (result.op)
+                lines.push(JSON.stringify(result.op));
+            if (result.target)
+                lines.push(c.dim(`${result.target.title} — ${result.target.description}`));
+            if (result.engine && !result.engine.running)
+                lines.push(c.dim("(engine not running; nothing was sent)"));
+            break;
+        case "ambiguous":
+            lines.push(`${sym.warn()} ${result.hint ?? "Several destinations match."}`);
+            for (const m of result.matches ?? [])
+                lines.push(`  ${m.id.padEnd(18)} ${m.surface.padEnd(6)} ${m.title}`);
+            break;
+        case "unsupported":
+            lines.push(`${sym.warn()} ${result.target?.title ?? result.target?.id} is not available on this Summer Engine build.`);
+            if (result.hint)
+                lines.push(`  ${result.hint}`);
+            if (result.op)
+                lines.push(`  would send: ${JSON.stringify(result.op)}`);
+            break;
+        case "open_failed":
+        case "blocked_origin":
+            lines.push(c.red(result.hint ?? result.action));
+            if (result.url)
+                lines.push(`  ${result.url}`);
+            break;
+        case "engine_not_running":
+            lines.push(c.red("Summer Engine is not running (or no project is open) — nothing was opened."));
+            if (result.op)
+                lines.push(`  would send: ${JSON.stringify(result.op)}`);
+            lines.push("  Start it with 'summer run <project>' or open the project in the Summer desktop app, then retry.");
+            break;
+        default:
+            lines.push(c.red(result.hint ?? result.action));
+            for (const m of result.matches ?? [])
+                lines.push(`  ${m.id.padEnd(18)} ${m.title}`);
+    }
+    return lines.join("\n");
+}
+export function defaultOpenDeps() {
+    return {
+        engine: () => EngineApiClient.connect(),
+        openUrl: (url) => open(url),
+        isLoggedIn: async () => (await getAuthToken()) !== null,
+        gatewayUrl: resolveGatewayUrl,
+    };
+}
+/** The navigation branch. Returns the result so tests can assert without a
+ *  process exit; sets exitCode 1 when nothing could be opened. */
+export async function runOpenNavigation(target, options, deps = defaultOpenDeps(), log = console.log) {
+    const result = await runOpen({
+        target: options.list ? undefined : target,
+        params: parseParamOptions(options),
+        surface: surfaceFromOptions(options),
+        open: options.print !== true,
+    }, deps);
+    log(options.json ? JSON.stringify(result, null, 2) : formatOpenResult(result));
+    if (!result.ok)
+        process.exitCode = 1;
+    return result;
+}
+async function openProjectPath(projectPath) {
+    const fullPath = resolve(projectPath);
+    if (!existsSync(fullPath)) {
+        console.error(`Directory not found: ${fullPath}`);
+        process.exit(1);
+    }
+    if (!existsSync(`${fullPath}/project.godot`)) {
+        console.error(`No project.godot found in ${fullPath}\n` +
+            "This doesn't look like a Summer Engine project.\n" +
+            "Create one with: summer create 3d-basic my-game");
+        process.exit(1);
+    }
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (!health) {
+        console.log("Engine not running. Launching with this project...");
+        // Import dynamically to avoid circular deps. `from: "user"` means the
+        // array holds ONLY user arguments — no node/script prefix — otherwise
+        // commander binds `[path]` to "node".
+        const { runCommand } = await import("./run.js");
+        await runCommand.parseAsync([fullPath], { from: "user" });
+        return;
+    }
+    console.log(`Opening project: ${fullPath}`);
+    console.log("Note: To switch projects, close the current one in Summer Engine first,\n" +
+        "then run: summer run " + fullPath);
+}
+export const openCommand = new Command("open")
+    .description("Open a project in Summer Engine, or open a Summer destination by name — a summerengine.com page (billing, my-games, pricing, mcp-guide …) or an editor surface (scene, node, script, inspector …)")
+    .argument("[target]", "Project directory (contains project.godot), or a destination: id, phrase, res:// path, or summerengine.com path")
+    .option("--print", "Resolve only: print the URL or engine op, open nothing")
+    .option("--list", "List every destination with surface and status")
+    .option("--web", "Only match website destinations")
+    .option("--editor", "Only match editor destinations")
+    .option("--json", "Print the full result as JSON")
+    .option("--path <res>", "res:// path for scene / script / file targets")
+    .option("--node <path>", "Node path for the node target, e.g. Player/Camera3D")
+    .option("--scene <res>", "Scene to open before selecting a node")
+    .option("--param <key=value>", "Slot value (gameId, section, username, version, guide); repeatable", (value, previous = []) => [...previous, value])
+    .action(async (target, options) => {
+    if (target !== undefined && !options.list && looksLikeProjectPath(target)) {
+        await openProjectPath(target);
+        return;
+    }
+    try {
+        await runOpenNavigation(target, options);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+});

package/dist/{commands → cli/commands}/plan.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
-import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../lib/game-task-plan.js";
-import { c } from "../lib/format.js";
+import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../../core/capabilities/game-task-plan.js";
+import { c } from "../../core/format.js";
 function parseChoice(value, choices, label) {
     if (!value)
         return undefined;

package/dist/{commands → cli/commands}/publish.js

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { publishCreator } from "../lib/creator.js";
+import { publishCreator } from "../../core/capabilities/creator.js";
 export const publishCommand = new Command("publish")
     .description("Publish a confirmed creator release")
     .argument("[project]", "Project root. Defaults to the current directory.")

package/dist/{commands → cli/commands}/releases.js

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { listCreatorReleases } from "../lib/creator.js";
+import { listCreatorReleases } from "../../core/capabilities/creator.js";
 export const releasesCommand = new Command("releases")
     .description("List creator releases for a project")
     .option("--project-id <id>", "Creator project ID")

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { ENGINE_BIN_ENV } from "../../core/engine-install.js";
+export type RunBinaryResolution = {
+    binary: string;
+    source: "--bin" | typeof ENGINE_BIN_ENV | "installed";
+} | {
+    binary: null;
+    error: string;
+};
+/**
+ * Which engine executable `summer run` launches (and probes with --help):
+ * `--bin <path>`, else SUMMER_BIN, else the installed engine
+ * (findEngineBinary, which also honours the older SUMMER_ENGINE_BINARY).
+ * An explicit override is never silently swapped for the installed engine:
+ * a missing path or a bare `.app` bundle is an error, because the caller
+ * asked for THAT build (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 5).
+ */
+export declare function resolveRunBinary(binFlag: string | undefined, env?: NodeJS.ProcessEnv): RunBinaryResolution;
+export declare const runCommand: Command;

package/dist/cli/commands/run.js

@@ -0,0 +1,255 @@
+import { Command } from "commander";
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+import { getSummerDir } from "../../core/auth.js";
+import { getApiPort, checkEngineHealth } from "../../core/engine.js";
+import { describeEngineExecutableProblem, ENGINE_BIN_ENV, engineBinaryOverride, findEngineBinary, } from "../../core/engine-install.js";
+import { advertisedBackgroundPosture, backgroundLaunchSupport, detectBackgroundLaunchSupport, planLaunch, resolveLaunchPosture, BACKGROUND_LAUNCH_FLAG, BACKGROUND_LAUNCH_MIN_ENGINE_VERSION, } from "../../core/launch-posture.js";
+import { sleep } from "../../core/util/sleep.js";
+const LAUNCH_LOCK_STALE_MS = 60_000;
+const LAUNCH_LOCK_WAIT_MS = 15_000;
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        return code === "EPERM";
+    }
+}
+async function removeStaleLaunchLock(lockDir) {
+    const ownerPath = join(lockDir, "owner.json");
+    try {
+        const raw = await readFile(ownerPath, "utf-8");
+        const owner = JSON.parse(raw);
+        const pid = typeof owner.pid === "number" ? owner.pid : 0;
+        const createdAt = typeof owner.createdAt === "number" ? owner.createdAt : 0;
+        const staleByTime = Date.now() - createdAt > LAUNCH_LOCK_STALE_MS;
+        const staleByPid = !isProcessAlive(pid);
+        if (!staleByTime && !staleByPid) {
+            return false;
+        }
+    }
+    catch {
+        // Broken owner metadata should not permanently block launches.
+    }
+    await rm(lockDir, { recursive: true, force: true });
+    return true;
+}
+async function withLaunchLock(fn) {
+    const summerDir = getSummerDir();
+    await mkdir(summerDir, { recursive: true, mode: 0o700 });
+    const lockDir = join(summerDir, "launch.lock");
+    const ownerPath = join(lockDir, "owner.json");
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            await mkdir(lockDir, { mode: 0o700 });
+            try {
+                await writeFile(ownerPath, JSON.stringify({ pid: process.pid, createdAt: Date.now() }, null, 2), { encoding: "utf-8", mode: 0o600 });
+                return await fn();
+            }
+            finally {
+                await rm(lockDir, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST") {
+                throw error;
+            }
+            if (await removeStaleLaunchLock(lockDir)) {
+                continue;
+            }
+            if (Date.now() - startedAt > LAUNCH_LOCK_WAIT_MS) {
+                throw new Error("Another `summer run` launch is still in progress. Try again in a few seconds.");
+            }
+            await sleep(100);
+        }
+    }
+}
+/**
+ * Which engine executable `summer run` launches (and probes with --help):
+ * `--bin <path>`, else SUMMER_BIN, else the installed engine
+ * (findEngineBinary, which also honours the older SUMMER_ENGINE_BINARY).
+ * An explicit override is never silently swapped for the installed engine:
+ * a missing path or a bare `.app` bundle is an error, because the caller
+ * asked for THAT build (docs/design/archive/TK-VS-FOLD-2026-09-07.md, gap 5).
+ */
+export function resolveRunBinary(binFlag, env = process.env) {
+    const fromEnv = engineBinaryOverride(env);
+    const explicit = binFlag?.trim()
+        ? { source: "--bin", path: binFlag.trim() }
+        : fromEnv?.name === ENGINE_BIN_ENV
+            ? { source: ENGINE_BIN_ENV, path: fromEnv.path }
+            : null;
+    if (explicit) {
+        const path = resolve(explicit.path);
+        const problem = describeEngineExecutableProblem(path, explicit.source);
+        return problem ? { binary: null, error: problem } : { binary: path, source: explicit.source };
+    }
+    const installed = findEngineBinary();
+    if (!installed) {
+        return {
+            binary: null,
+            error: "Summer Engine not found. Install it first:\n" +
+                "  summer install\n" +
+                "  or download from https://summerengine.com/download\n" +
+                `To launch a build that is not installed, pass --bin <executable> or set ${ENGINE_BIN_ENV}.`,
+        };
+    }
+    return { binary: installed, source: "installed" };
+}
+export const runCommand = new Command("run")
+    .description("Launch Summer Engine with a project. Without a path it launches a bare " +
+    "detached editor (project manager), which requires --no-project.")
+    .argument("[path]", "Path to a project directory (must contain project.godot)")
+    .option("--no-project", "Launch a bare detached editor (project manager) without opening a project")
+    .option("--background", "Launch without taking focus: the window exists but stays behind until clicked " +
+    "(default when stdout is not a terminal, i.e. an agent is driving)")
+    .option("--focus", "Launch and bring the editor to the front (default when a human runs this in a terminal)")
+    .option("--bin <path>", `Engine executable to launch instead of the installed one (env: ${ENGINE_BIN_ENV}). ` +
+    "On macOS this is the executable inside the bundle, e.g. /path/Summer.app/Contents/MacOS/Summer, never the .app itself")
+    .action(async (projectPath, opts) => {
+    // Posture is decided up front so a bad flag combination fails before any
+    // filesystem or engine work. Why the TTY heuristic: a human at a terminal
+    // typed `summer run` to SEE the editor; an agent (no TTY on stdout) is
+    // launching it as a means to an end while the user works on something else
+    // and must not be interrupted. See src/core/launch-posture.ts.
+    let posture;
+    try {
+        posture = resolveLaunchPosture({ focus: opts.focus, background: opts.background }, { stdoutIsTTY: process.stdout.isTTY === true });
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
+    const fullProjectPath = projectPath ? resolve(projectPath) : null;
+    if (!fullProjectPath && opts.project !== false) {
+        console.error("summer run needs a project path (a directory containing project.godot).\n" +
+            "To launch a bare editor without a project, pass --no-project.");
+        process.exitCode = 1;
+        return;
+    }
+    if (fullProjectPath) {
+        if (!existsSync(fullProjectPath)) {
+            console.error(`Directory not found: ${fullProjectPath}`);
+            process.exit(1);
+        }
+        if (!existsSync(join(fullProjectPath, "project.godot"))) {
+            console.error(`No project.godot found in ${fullProjectPath}\n` +
+                "This doesn't look like a Summer Engine project.");
+            process.exit(1);
+        }
+    }
+    await withLaunchLock(async () => {
+        const port = await getApiPort();
+        const health = await checkEngineHealth(port);
+        if (health) {
+            const runningProjectPath = health.project_path
+                ? resolve(health.project_path)
+                : null;
+            if (!fullProjectPath || runningProjectPath === fullProjectPath) {
+                console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
+                if (health.project_name) {
+                    console.log(`  Project: ${health.project_name}`);
+                }
+                if (health.project_path) {
+                    console.log(`  Path: ${health.project_path}`);
+                }
+                return;
+            }
+            console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
+            console.log(`  Current project: ${health.project_path ?? health.project_name ?? "unknown"}`);
+            console.error(`Refusing to launch a second editor for: ${fullProjectPath}\n` +
+                "Close or switch the current Summer Engine project first, then run this command again.");
+            process.exitCode = 1;
+            return;
+        }
+        const resolved = resolveRunBinary(opts.bin);
+        if (resolved.binary === null) {
+            console.error(resolved.error);
+            process.exitCode = 1;
+            return;
+        }
+        const binary = resolved.binary;
+        if (resolved.source !== "installed") {
+            console.log(`Using engine from ${resolved.source}: ${binary}`);
+        }
+        // The engine is not running yet, so /api/health cannot tell us whether
+        // it honours --summer-background. Ask THAT binary itself (`--help`, which
+        // exits headless before any window exists; cached per install) with the
+        // installed version as pre-check and fallback; pass the flag only when
+        // the engine is known to support it. Focus launches have nothing to decide.
+        const support = posture === "background" ? await detectBackgroundLaunchSupport(binary) : backgroundLaunchSupport(null);
+        const plan = planLaunch(posture, support);
+        const args = ["--editor", ...plan.extraArgs];
+        if (fullProjectPath) {
+            args.unshift("--path", fullProjectPath);
+        }
+        if (plan.note)
+            console.log(plan.note);
+        console.log(plan.background
+            ? "Launching Summer Engine in the background (the window will not take focus until you click it)..."
+            : "Launching Summer Engine...");
+        // Direct executable, never `open -a`: LaunchServices activates whatever
+        // it opens and would defeat --summer-background regardless of flags.
+        const child = spawn(binary, args, { detached: true, stdio: "ignore" });
+        // A stale or non-executable binary surfaces as an async "error" event
+        // (ENOENT/EACCES). Without a listener Node raises it as an uncaught
+        // exception with a raw stack; catch it and report the path instead.
+        const spawnState = { error: null };
+        child.on("error", (error) => {
+            spawnState.error = error;
+        });
+        child.unref();
+        // Wait for engine to start responding
+        const startTime = Date.now();
+        const timeout = 20000;
+        while (Date.now() - startTime < timeout) {
+            await sleep(500);
+            if (spawnState.error) {
+                reportSpawnFailure(spawnState.error, binary);
+                return;
+            }
+            const newPort = await getApiPort();
+            const h = await checkEngineHealth(newPort);
+            if (h) {
+                console.log(`Summer Engine running (v${h.version}) on port ${newPort}`);
+                if (h.project_name) {
+                    console.log(`  Project: ${h.project_name}`);
+                }
+                // Background was wanted but the flag was withheld, and the running
+                // engine now says (capabilities.launchPostures, else its version)
+                // that it would have honoured it: say so, so the next launch can be
+                // fixed rather than silently repeating a focus launch.
+                if (posture === "background" && !plan.background) {
+                    const advert = advertisedBackgroundPosture(h.capabilities);
+                    const wouldHonour = advert ?? backgroundLaunchSupport(h.version).supported;
+                    if (wouldHonour) {
+                        console.log(`  Note: this engine (v${h.version}) ${advert ? "advertises" : "should support"} background launches (${BACKGROUND_LAUNCH_FLAG}, ${BACKGROUND_LAUNCH_MIN_ENGINE_VERSION}+), but that could not be confirmed before launch on this platform.`);
+                    }
+                }
+                return;
+            }
+        }
+        if (spawnState.error) {
+            reportSpawnFailure(spawnState.error, binary);
+            return;
+        }
+        console.log("Summer Engine launched but API not responding yet.\n" +
+            "It may still be loading. Run 'summer status' to check.");
+    });
+});
+function reportSpawnFailure(error, binary) {
+    const code = error.code ?? error.message;
+    console.error(`Summer Engine binary failed to start: ${code} (${binary})\n` +
+        "Re-run 'summer install' to repair the installation, or check the binary path.");
+    process.exitCode = 1;
+}