tmux-ide 2.1.5 → 2.6.1

package/packages/daemon/dist/command-center/actions/contract.js

@@ -0,0 +1,2 @@
+// Action contract moved to @tmux-ide/contracts (T059). Re-export shim.
+export * from "@tmux-ide/contracts";

package/packages/daemon/dist/command-center/actions/dispatcher.d.ts

@@ -0,0 +1,27 @@
+/**
+ * v2 action dispatcher — single Hono route that resolves an action name
+ * against the registry, parses input + output with Zod, runs the handler,
+ * and broadcasts an `action.complete` WS frame on success.
+ *
+ * Endpoint: `POST /api/v2/action/:name`
+ *
+ * Wire envelope:
+ *   200 OK  { ok: true,  result }
+ *   200 OK  { ok: false, error: { code, message, details? } }   (typed app error)
+ *   400     malformed JSON body
+ *   404     unknown action name (transport-level — name isn't in the registry)
+ *
+ * `ok: false` is intentionally HTTP 200: it represents a typed application
+ * outcome the client is expected to handle. HTTP 4xx/5xx remain reserved
+ * for transport-level failures.
+ */
+import type { Context } from "hono";
+export interface DispatcherDeps {
+    /** Override the WS broadcaster (tests / non-default daemons). */
+    broadcast?: (name: string, result: unknown) => void;
+}
+/**
+ * Build the Hono handler. Exposed as a factory so tests can inject a
+ * broadcaster and assert on the WS event without mounting a real server.
+ */
+export declare function createActionDispatcher(deps?: DispatcherDeps): (c: Context) => Promise<Response>;

package/packages/daemon/dist/command-center/actions/dispatcher.js

@@ -0,0 +1,109 @@
+/**
+ * v2 action dispatcher — single Hono route that resolves an action name
+ * against the registry, parses input + output with Zod, runs the handler,
+ * and broadcasts an `action.complete` WS frame on success.
+ *
+ * Endpoint: `POST /api/v2/action/:name`
+ *
+ * Wire envelope:
+ *   200 OK  { ok: true,  result }
+ *   200 OK  { ok: false, error: { code, message, details? } }   (typed app error)
+ *   400     malformed JSON body
+ *   404     unknown action name (transport-level — name isn't in the registry)
+ *
+ * `ok: false` is intentionally HTTP 200: it represents a typed application
+ * outcome the client is expected to handle. HTTP 4xx/5xx remain reserved
+ * for transport-level failures.
+ */
+import { isActionName } from "./contract.js";
+import { wrapInternalError } from "./errors.js";
+import { getLooseActionEntry } from "./registry.js";
+import { broadcastActionComplete } from "../ws-events.js";
+function errorEnvelope(err) {
+    return { ok: false, error: err.toEnvelope() };
+}
+function zodErrorEnvelope(err) {
+    return {
+        ok: false,
+        error: {
+            code: "validation_failed",
+            message: "Input failed schema validation",
+            details: { issues: err.issues },
+        },
+    };
+}
+function outputZodErrorEnvelope(err) {
+    // A handler returned a value that does not conform to its declared output
+    // schema — log loudly and surface as `internal`. The dashboard treats
+    // this the same as any other server bug.
+    console.error("[actions] handler output failed schema validation", err.issues);
+    return {
+        ok: false,
+        error: {
+            code: "internal",
+            message: "Handler returned an invalid result",
+            details: { issues: err.issues },
+        },
+    };
+}
+/**
+ * Build the Hono handler. Exposed as a factory so tests can inject a
+ * broadcaster and assert on the WS event without mounting a real server.
+ */
+export function createActionDispatcher(deps = {}) {
+    const broadcast = deps.broadcast ?? broadcastActionComplete;
+    return async function dispatcher(c) {
+        const name = c.req.param("name");
+        if (!name || !isActionName(name)) {
+            return c.json({
+                ok: false,
+                error: {
+                    code: "validation_failed",
+                    message: `Unknown action: ${name}`,
+                    details: { name },
+                },
+            }, 404);
+        }
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch (err) {
+            // Malformed JSON is a transport problem, not an app outcome.
+            return c.json({
+                ok: false,
+                error: {
+                    code: "validation_failed",
+                    message: `Invalid JSON body: ${err.message ?? String(err)}`,
+                },
+            }, 400);
+        }
+        const actionName = name;
+        const entry = getLooseActionEntry(actionName);
+        const inputParsed = entry.inputSchema.safeParse(body);
+        if (!inputParsed.success) {
+            return c.json(zodErrorEnvelope(inputParsed.error), 200);
+        }
+        let result;
+        try {
+            result = await entry.handler(inputParsed.data);
+        }
+        catch (err) {
+            const wrapped = wrapInternalError(err);
+            return c.json(errorEnvelope(wrapped), 200);
+        }
+        const outputParsed = entry.resultSchema.safeParse(result);
+        if (!outputParsed.success) {
+            return c.json(outputZodErrorEnvelope(outputParsed.error), 200);
+        }
+        // Fire-and-forget: subscribers learn about the success via the WS bus.
+        try {
+            broadcast(actionName, outputParsed.data);
+        }
+        catch (err) {
+            // Broadcast failure must not turn a successful action into a failure.
+            console.error("[actions] broadcast failed:", err);
+        }
+        return c.json({ ok: true, result: outputParsed.data }, 200);
+    };
+}

package/packages/daemon/dist/command-center/actions/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed errors for the v2 action dispatcher. Every error path through a
+ * handler funnels into one of these so the dispatcher can map to the
+ * `{ ok: false, error: { code, message, details? } }` envelope without
+ * stringly-typed catches.
+ *
+ * Codes are stable wire identifiers — never rename without a coordinated
+ * dashboard release. New codes go at the bottom of the union.
+ */
+import { TerminalCwdError } from "../../server/pty-bridge.ts";
+export type ActionErrorCode = "project_not_found" | "cwd_not_found" | "cwd_not_directory" | "cwd_stat_failed" | "session_already_running" | "session_not_running" | "launch_failed" | "stop_failed" | "terminal_not_found" | "validation_failed" | "task_not_found" | "goal_not_found" | "milestone_not_found" | "mission_not_set" | "task_dependency_unmet" | "task_already_assigned" | "skill_invalid" | "skill_not_found" | "ide_yml_missing" | "config_path_invalid" | "config_validation_failed" | "validation_assertion_not_found" | "webhook_not_found" | "webhook_test_failed" | "remote_access_restart_failed" | "shutdown_already_in_progress" | "bad_request" | "thread_not_found" | "permission_request_not_found" | "internal";
+export declare class ActionError extends Error {
+    readonly code: ActionErrorCode;
+    readonly details: unknown | undefined;
+    constructor(args: {
+        code: ActionErrorCode;
+        message: string;
+        details?: unknown;
+        cause?: unknown;
+    });
+    toEnvelope(): {
+        code: ActionErrorCode;
+        message: string;
+        details?: unknown;
+    };
+}
+/**
+ * Translate a {@link TerminalCwdError} into an {@link ActionError} with the
+ * matching wire code. The cwd is preserved in `details` so the dashboard can
+ * surface it without re-parsing the error message.
+ */
+export declare function actionErrorFromCwdError(err: TerminalCwdError): ActionError;
+/**
+ * Wrap an unknown thrown value as an `internal` ActionError. Used as the
+ * last-resort branch in dispatcher catch blocks so handlers never leak raw
+ * Error stacks across the wire.
+ */
+export declare function wrapInternalError(err: unknown): ActionError;

package/packages/daemon/dist/command-center/actions/errors.js

@@ -0,0 +1,56 @@
+/**
+ * Typed errors for the v2 action dispatcher. Every error path through a
+ * handler funnels into one of these so the dispatcher can map to the
+ * `{ ok: false, error: { code, message, details? } }` envelope without
+ * stringly-typed catches.
+ *
+ * Codes are stable wire identifiers — never rename without a coordinated
+ * dashboard release. New codes go at the bottom of the union.
+ */
+import { TerminalCwdError } from "../../server/pty-bridge.js";
+export class ActionError extends Error {
+    code;
+    details;
+    constructor(args) {
+        super(args.message, args.cause !== undefined ? { cause: args.cause } : undefined);
+        this.name = "ActionError";
+        this.code = args.code;
+        this.details = args.details;
+    }
+    toEnvelope() {
+        return this.details !== undefined
+            ? { code: this.code, message: this.message, details: this.details }
+            : { code: this.code, message: this.message };
+    }
+}
+const CWD_REASON_TO_CODE = {
+    notFound: "cwd_not_found",
+    notDirectory: "cwd_not_directory",
+    statFailed: "cwd_stat_failed",
+};
+/**
+ * Translate a {@link TerminalCwdError} into an {@link ActionError} with the
+ * matching wire code. The cwd is preserved in `details` so the dashboard can
+ * surface it without re-parsing the error message.
+ */
+export function actionErrorFromCwdError(err) {
+    return new ActionError({
+        code: CWD_REASON_TO_CODE[err.reason],
+        message: err.message,
+        details: { cwd: err.cwd, reason: err.reason },
+        cause: err,
+    });
+}
+/**
+ * Wrap an unknown thrown value as an `internal` ActionError. Used as the
+ * last-resort branch in dispatcher catch blocks so handlers never leak raw
+ * Error stacks across the wire.
+ */
+export function wrapInternalError(err) {
+    if (err instanceof ActionError)
+        return err;
+    if (err instanceof TerminalCwdError)
+        return actionErrorFromCwdError(err);
+    const message = err instanceof Error ? err.message : String(err);
+    return new ActionError({ code: "internal", message, cause: err });
+}

package/packages/daemon/dist/command-center/actions/handlers/_project-context.d.ts

@@ -0,0 +1,12 @@
+import { type ProjectResolverDeps } from "./_resolve-project.ts";
+export interface ProjectContextDeps extends ProjectResolverDeps {
+    cwd?: string;
+}
+export interface ProjectContextInput {
+    projectName?: string;
+}
+export interface ProjectContext {
+    dir: string;
+    sessionName: string;
+}
+export declare function resolveProjectContext(input: ProjectContextInput, deps?: ProjectContextDeps): ProjectContext;

package/packages/daemon/dist/command-center/actions/handlers/_project-context.js

@@ -0,0 +1,12 @@
+import { basename } from "node:path";
+import { getSessionName } from "../../../lib/yaml-io.js";
+import { resolveProject } from "./_resolve-project.js";
+export function resolveProjectContext(input, deps = {}) {
+    if (input.projectName) {
+        const project = resolveProject(input.projectName, deps);
+        return { dir: project.dir, sessionName: project.sessionName };
+    }
+    const dir = deps.cwd ?? process.cwd();
+    const sessionName = getSessionName(dir).name || basename(dir);
+    return { dir, sessionName };
+}

package/packages/daemon/dist/command-center/actions/handlers/_resolve-project.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared helper: resolve a registered project by name and project the
+ * fields the action handlers actually consume.
+ *
+ * Lives in handlers/ so the registry stays the only public surface; tests
+ * import from here directly.
+ */
+import type { RegisteredProject } from "../../../schemas/registry.ts";
+export interface ResolvedProject {
+    name: string;
+    dir: string;
+    sessionName: string;
+    /**
+     * `true` when the project was resolved from a live tmux session
+     * (rather than the registry). Useful for handlers that want to
+     * auto-register on first action — out of scope for this slice but
+     * makes the intent explicit at the boundary.
+     */
+    fromLiveSession: boolean;
+}
+export interface ProjectResolverDeps {
+    /** Override for tests — must satisfy the same contract as `getProject`. */
+    getProject?: (name: string) => RegisteredProject | null;
+    /** Override the live-session existence probe. */
+    hasSession?: (session: string) => boolean;
+    /** Override the live-session cwd lookup. */
+    getSessionCwd?: (session: string) => string | null;
+}
+/**
+ * Resolve a project by name. The registry is the canonical source of
+ * truth, but as a fallback we also accept a live tmux session by the
+ * same name — the dashboard merges registered projects + live sessions
+ * in its sidebar, so action handlers must accept either. Throws an
+ * {@link ActionError} with code `project_not_found` when neither path
+ * succeeds.
+ *
+ * Note: the registry does not currently persist a session name distinct
+ * from the project name, so the session name returned here mirrors the
+ * project name. If they diverge in the future, this is the only call site
+ * that needs to change.
+ */
+export declare function resolveProject(name: string, deps?: ProjectResolverDeps): ResolvedProject;

package/packages/daemon/dist/command-center/actions/handlers/_resolve-project.js

@@ -0,0 +1,48 @@
+/**
+ * Shared helper: resolve a registered project by name and project the
+ * fields the action handlers actually consume.
+ *
+ * Lives in handlers/ so the registry stays the only public surface; tests
+ * import from here directly.
+ */
+import { getProject as getRegisteredProject } from "../../../lib/project-registry.js";
+import { getSessionCwd as getSessionCwdDefault, hasSession as hasSessionDefault, } from "@tmux-ide/tmux-bridge";
+import { ActionError } from "../errors.js";
+/**
+ * Resolve a project by name. The registry is the canonical source of
+ * truth, but as a fallback we also accept a live tmux session by the
+ * same name — the dashboard merges registered projects + live sessions
+ * in its sidebar, so action handlers must accept either. Throws an
+ * {@link ActionError} with code `project_not_found` when neither path
+ * succeeds.
+ *
+ * Note: the registry does not currently persist a session name distinct
+ * from the project name, so the session name returned here mirrors the
+ * project name. If they diverge in the future, this is the only call site
+ * that needs to change.
+ */
+export function resolveProject(name, deps = {}) {
+    const lookup = deps.getProject ?? getRegisteredProject;
+    const project = lookup(name);
+    if (project) {
+        return {
+            name: project.name,
+            dir: project.dir,
+            sessionName: project.name,
+            fromLiveSession: false,
+        };
+    }
+    // Registry miss — fall back to a live tmux session of the same name.
+    const hasSession = deps.hasSession ?? hasSessionDefault;
+    if (hasSession(name)) {
+        const cwd = (deps.getSessionCwd ?? getSessionCwdDefault)(name);
+        if (cwd) {
+            return { name, dir: cwd, sessionName: name, fromLiveSession: true };
+        }
+    }
+    throw new ActionError({
+        code: "project_not_found",
+        message: `Project "${name}" not found in registry or as a live tmux session`,
+        details: { name },
+    });
+}

package/packages/daemon/dist/command-center/actions/handlers/app-set-remote-access.d.ts

@@ -0,0 +1,23 @@
+import { type AppSettings } from "../../../lib/app-settings.ts";
+import type { ActionInput, ActionResult } from "../contract.ts";
+export interface RemoteAccessRestartRequest {
+    enabled: boolean;
+    bindHostname: "0.0.0.0" | "127.0.0.1";
+    token: string | null;
+    port?: number;
+}
+export interface RemoteAccessRestartResult {
+    port?: number;
+    host?: string;
+}
+export interface AppSetRemoteAccessDeps {
+    readSettings?: () => AppSettings;
+    writeSettings?: (next: AppSettings) => void;
+    generateToken?: () => string;
+    restartDaemon?: (request: RemoteAccessRestartRequest) => Promise<RemoteAccessRestartResult> | RemoteAccessRestartResult;
+    deferRestart?: (restart: () => void) => void;
+    port?: number;
+    host?: string;
+}
+export declare function setRemoteAccessRestartBackend(backend: ((request: RemoteAccessRestartRequest) => Promise<RemoteAccessRestartResult> | RemoteAccessRestartResult) | null): void;
+export declare function appSetRemoteAccessHandler(input: ActionInput<"app.setRemoteAccess">, deps?: AppSetRemoteAccessDeps): Promise<ActionResult<"app.setRemoteAccess">>;

package/packages/daemon/dist/command-center/actions/handlers/app-set-remote-access.js

@@ -0,0 +1,67 @@
+import { hostname, networkInterfaces } from "node:os";
+import { generateAuthToken } from "../../../lib/auth-token.js";
+import { readAppSettings, writeAppSettings } from "../../../lib/app-settings.js";
+let remoteAccessRestartBackend = null;
+export function setRemoteAccessRestartBackend(backend) {
+    remoteAccessRestartBackend = backend;
+}
+function currentPort(deps) {
+    const envPort = Number(process.env.TMUX_IDE_DAEMON_PORT);
+    return deps.port ?? (Number.isInteger(envPort) && envPort > 0 ? envPort : 6060);
+}
+function primaryLanHost() {
+    const interfaces = networkInterfaces();
+    for (const entries of Object.values(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.family === "IPv4" && !entry.internal)
+                return entry.address;
+        }
+    }
+    return hostname();
+}
+function buildUrl(host, port) {
+    return `http://${host}:${port}`;
+}
+function defaultDeferRestart(restart) {
+    setImmediate(restart);
+}
+export async function appSetRemoteAccessHandler(input, deps = {}) {
+    const readSettings = deps.readSettings ?? readAppSettings;
+    const writeSettings = deps.writeSettings ?? writeAppSettings;
+    const nextEnabled = input.enabled;
+    const current = readSettings();
+    const token = nextEnabled
+        ? (current.remoteAccess.token ?? (deps.generateToken ?? generateAuthToken)())
+        : null;
+    const next = {
+        ...current,
+        remoteAccess: { enabled: nextEnabled, token },
+    };
+    writeSettings(next);
+    const port = currentPort(deps);
+    const request = {
+        enabled: nextEnabled,
+        bindHostname: nextEnabled ? "0.0.0.0" : "127.0.0.1",
+        token,
+        port,
+    };
+    const restartDaemon = deps.restartDaemon ?? remoteAccessRestartBackend;
+    if (restartDaemon) {
+        (deps.deferRestart ?? defaultDeferRestart)(() => {
+            void Promise.resolve(restartDaemon(request)).catch((err) => {
+                console.error(`[actions] Failed to restart daemon for remote access: ${err.message ?? String(err)}`);
+            });
+        });
+    }
+    if (!nextEnabled) {
+        return { enabled: false, url: null, token: null, qrPayload: null };
+    }
+    const host = deps.host ?? primaryLanHost();
+    const url = buildUrl(host, port);
+    return {
+        enabled: true,
+        url,
+        token,
+        qrPayload: `${url}?token=${encodeURIComponent(token ?? "")}`,
+    };
+}

package/packages/daemon/dist/command-center/actions/handlers/config-actions.d.ts

@@ -0,0 +1,12 @@
+import type { ActionInput, ActionResult } from "../contract.ts";
+import { type ProjectContextDeps } from "./_project-context.ts";
+interface ConfigActionDeps extends ProjectContextDeps {
+    broadcastConfigChanged?: (sessionName: string) => void;
+}
+export declare function configSetHandler(input: ActionInput<"config.set">, deps?: ConfigActionDeps): ActionResult<"config.set">;
+export declare function configAddPaneHandler(input: ActionInput<"config.addPane">, deps?: ConfigActionDeps): ActionResult<"config.addPane">;
+export declare function configRemovePaneHandler(input: ActionInput<"config.removePane">, deps?: ConfigActionDeps): ActionResult<"config.removePane">;
+export declare function configAddRowHandler(input: ActionInput<"config.addRow">, deps?: ConfigActionDeps): ActionResult<"config.addRow">;
+export declare function configEnableTeamHandler(input: ActionInput<"config.enableTeam">, deps?: ConfigActionDeps): ActionResult<"config.enableTeam">;
+export declare function configDisableTeamHandler(input: ActionInput<"config.disableTeam">, deps?: ConfigActionDeps): ActionResult<"config.disableTeam">;
+export {};

package/packages/daemon/dist/command-center/actions/handlers/config-actions.js

@@ -0,0 +1,69 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { configAddPane, configAddRow, configDisableTeam, configEnableTeam, configRemovePane, configSetValue, } from "../../../config.js";
+import { broadcastConfigChanged as broadcastConfigChangedDefault } from "../../ws-events.js";
+import { ActionError } from "../errors.js";
+import { resolveProjectContext } from "./_project-context.js";
+function mutateConfigAction(input, deps, fn) {
+    const context = resolveProjectContext(input, deps);
+    if (!existsSync(join(context.dir, "ide.yml"))) {
+        throw new ActionError({
+            code: "ide_yml_missing",
+            message: "ide.yml was not found",
+            details: { dir: context.dir },
+        });
+    }
+    try {
+        const result = fn(context.dir);
+        (deps.broadcastConfigChanged ?? broadcastConfigChangedDefault)(context.sessionName);
+        return result;
+    }
+    catch (err) {
+        const message = err.message ?? String(err);
+        throw new ActionError({
+            code: message.toLowerCase().includes("path")
+                ? "config_path_invalid"
+                : "config_validation_failed",
+            message,
+            cause: err,
+        });
+    }
+}
+export function configSetHandler(input, deps = {}) {
+    const config = mutateConfigAction(input, deps, (dir) => configSetValue(dir, input.path, input.value));
+    return { config };
+}
+export function configAddPaneHandler(input, deps = {}) {
+    const pane = {
+        title: input.title,
+        command: input.command,
+        type: input.type,
+        target: input.target,
+        dir: input.dir,
+        size: input.size,
+        focus: input.focus,
+        env: input.env,
+        role: input.role,
+        task: input.task,
+        specialty: input.specialty,
+        skill: input.skill,
+    };
+    const config = mutateConfigAction(input, deps, (dir) => configAddPane(dir, input.rowIndex, pane));
+    return { config };
+}
+export function configRemovePaneHandler(input, deps = {}) {
+    const config = mutateConfigAction(input, deps, (dir) => configRemovePane(dir, input.rowIndex, input.paneIndex)).config;
+    return { config };
+}
+export function configAddRowHandler(input, deps = {}) {
+    const config = mutateConfigAction(input, deps, (dir) => configAddRow(dir, input.size));
+    return { config };
+}
+export function configEnableTeamHandler(input, deps = {}) {
+    const config = mutateConfigAction(input, deps, (dir) => configEnableTeam(dir, input.name));
+    return { config };
+}
+export function configDisableTeamHandler(input, deps = {}) {
+    const config = mutateConfigAction(input, deps, (dir) => configDisableTeam(dir));
+    return { config };
+}

package/packages/daemon/dist/command-center/actions/handlers/daemon-shutdown.d.ts

@@ -0,0 +1,6 @@
+import type { ActionInput, ActionResult } from "../contract.ts";
+export interface DaemonShutdownDeps {
+    shutdown?: (reason: string | null) => Promise<void> | void;
+}
+export declare function setDaemonShutdownBackend(backend: ((reason: string | null) => Promise<void> | void) | null): void;
+export declare function daemonShutdownHandler(input: ActionInput<"daemon.shutdown">, deps?: DaemonShutdownDeps): ActionResult<"daemon.shutdown">;

package/packages/daemon/dist/command-center/actions/handlers/daemon-shutdown.js

@@ -0,0 +1,24 @@
+import { ActionError } from "../errors.js";
+let shutdownBackend = null;
+let shutdownInProgress = false;
+export function setDaemonShutdownBackend(backend) {
+    shutdownBackend = backend;
+    if (!backend)
+        shutdownInProgress = false;
+}
+export function daemonShutdownHandler(input, deps = {}) {
+    if (shutdownInProgress) {
+        throw new ActionError({
+            code: "shutdown_already_in_progress",
+            message: "Daemon shutdown is already in progress",
+        });
+    }
+    shutdownInProgress = true;
+    const shutdown = deps.shutdown ?? shutdownBackend;
+    process.nextTick(() => {
+        void Promise.resolve(shutdown?.(input.reason ?? null)).catch((err) => {
+            console.error("[daemon] shutdown action failed:", err);
+        });
+    });
+    return { stopping: true };
+}

package/packages/daemon/dist/command-center/actions/handlers/project-activate.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectActivationOptions } from "../../../lib/active-projects.ts";
+import type { ActionInput, ActionResult } from "../contract.ts";
+import { type ProjectResolverDeps } from "./_resolve-project.ts";
+export interface ProjectActivateDeps extends ProjectResolverDeps {
+    activateProject?: (name: string, options?: ProjectActivationOptions) => Promise<void>;
+}
+export declare function projectActivateHandler(input: ActionInput<"project.activate">, deps?: ProjectActivateDeps): Promise<ActionResult<"project.activate">>;

package/packages/daemon/dist/command-center/actions/handlers/project-activate.js

@@ -0,0 +1,19 @@
+import { activateProject as activateProjectDefault } from "../../../lib/active-projects.js";
+import { ActionError } from "../errors.js";
+import { resolveProject } from "./_resolve-project.js";
+export async function projectActivateHandler(input, deps = {}) {
+    const project = resolveProject(input.name, deps);
+    const activateProject = deps.activateProject ?? activateProjectDefault;
+    try {
+        await activateProject(project.name);
+    }
+    catch (err) {
+        throw new ActionError({
+            code: "internal",
+            message: `Failed to activate project "${project.name}": ${err.message ?? String(err)}`,
+            details: { projectName: project.name },
+            cause: err,
+        });
+    }
+    return { active: true, projectName: project.name };
+}

package/packages/daemon/dist/command-center/actions/handlers/project-launch.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Handler: `project.launch`.
+ *
+ * Idempotent programmatic launch. Resolves the project from the registry,
+ * checks whether a session is already running, and returns
+ * `{ started: false }` without invoking the launcher when so. Otherwise
+ * delegates to `src/launch.ts` with `attach: false`.
+ */
+import { type ActionInput, type ActionResult } from "../contract.ts";
+import { type ProjectResolverDeps } from "./_resolve-project.ts";
+export interface ProjectLaunchDeps extends ProjectResolverDeps {
+    hasSession?: (session: string) => boolean;
+    launch?: (dir: string, options: {
+        json: boolean;
+        attach: boolean;
+    }) => Promise<void>;
+}
+export declare function projectLaunchHandler(input: ActionInput<"project.launch">, deps?: ProjectLaunchDeps): Promise<ActionResult<"project.launch">>;