@ldlework/workmark 1.5.0 → 1.6.0

package/dist/cli.js

@@ -78,6 +78,7 @@ function toCommandMeta(cmd) {
         inputSchema: cmd.inputSchema,
         positional: cmd.positional,
         sourceFile: cmd.sourceFile ?? null,
+        interactive: cmd.interactive,
     };
 }
 // ---------------------------------------------------------------------------
@@ -86,7 +87,7 @@ function toCommandMeta(cmd) {
 async function main() {
     const [command, ...rest] = process.argv.slice(2);
     const workspace = await loadWorkspace();
-    const commands = await loadCommands(workspace);
+    const commands = await loadCommands(workspace, { surface: "cli" });
     if (command === "--introspect") {
         process.stdout.write(JSON.stringify(commands.map(toCommandMeta)) + "\n");
         return;

package/dist/index.js

@@ -7,11 +7,14 @@ import { loadWorkspace } from "./lib/workspace.js";
 async function main() {
     const server = new Server({ name: "workmark", version: "1.0.0" }, { capabilities: { tools: {} } });
     const workspace = await loadWorkspace();
-    const commands = await loadCommands(workspace);
-    const handlers = new Map(commands.map((c) => [c.name, c.handler]));
-    console.error(`Loaded ${commands.length} commands from ${workspace.projects.length} projects`);
+    const commands = await loadCommands(workspace, { surface: "mcp" });
+    // Interactive commands own a terminal — an MCP client has none to give.
+    const exposed = commands.filter((c) => !c.interactive);
+    const handlers = new Map(exposed.map((c) => [c.name, c.handler]));
+    const interactiveNames = new Set(commands.filter((c) => c.interactive).map((c) => c.name));
+    console.error(`Loaded ${exposed.length} commands from ${workspace.projects.length} projects`);
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: commands.map(({ name, description, inputSchema }) => ({
+        tools: exposed.map(({ name, description, inputSchema }) => ({
             name,
             description,
             inputSchema,
@@ -20,6 +23,9 @@ async function main() {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = handlers.get(request.params.name);
         if (!handler) {
+            if (interactiveNames.has(request.params.name)) {
+                throw new McpError(ErrorCode.InvalidRequest, `"${request.params.name}" is an interactive command (long-running, terminal-owning) — run it from a terminal: wm ${request.params.name}`);
+            }
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
         }
         return handler(request.params.arguments ?? {});

package/dist/lib/define.d.ts

@@ -20,6 +20,11 @@ export interface StaticCommandDef {
     select?: SelectMode;
     for?: string;
     run?: RunOptions;
+    /** Long-running command that owns the terminal (dev server, watcher).
+     * On the CLI, `ctx.sh` switches to inherited stdio with no timeout and
+     * resolves when the child exits. Not exposed over MCP. With `needs`,
+     * implies `select: "one"`. */
+    interactive?: boolean;
     args?: SchemaFields;
     flags?: SchemaFields;
     meta?: {
@@ -40,6 +45,7 @@ export declare function cmd<const N extends readonly Trait<string, unknown>[] =
     select?: SelectMode;
     for?: string;
     run?: RunOptions;
+    interactive?: boolean;
     args?: A;
     flags?: F;
     meta?: {

package/dist/lib/helpers.d.ts

@@ -12,3 +12,12 @@ export declare function execAsyncRaw(command: string, opts: ExecOptions): Promis
 /** Run a sequence of shell commands. Fails fast; concatenates outputs. */
 export declare function shSeq(commands: readonly string[], opts: ExecOptions): Promise<CallToolResult>;
 export declare function execAsync(command: string, opts: ExecOptions): Promise<CallToolResult>;
+/** Run a command with the terminal handed to the child: stdio inherited, no
+ * timeout, no output capture. Resolves when the child exits. Used for
+ * `interactive: true` commands — dev servers, watchers, REPLs.
+ *
+ * A null exit code (the child died to a signal, e.g. the user's Ctrl-C)
+ * counts as success: stopping a dev server is the normal way it ends. */
+export declare function execInteractive(command: string, opts: Pick<ExecOptions, "cwd" | "env">): Promise<CallToolResult>;
+/** Run a sequence of commands interactively. Fails fast. */
+export declare function shSeqInteractive(commands: readonly string[], opts: Pick<ExecOptions, "cwd" | "env">): Promise<CallToolResult>;

package/dist/lib/helpers.js

@@ -1,4 +1,4 @@
-import { execSync, exec as cpExec } from "node:child_process";
+import { execSync, exec as cpExec, spawn } from "node:child_process";
 import { promisify } from "node:util";
 // --- Response helpers ---
 export function ok(data) {
@@ -80,3 +80,42 @@ export async function execAsync(command, opts) {
         return fail(e);
     }
 }
+// --- Interactive execution (CLI surface only) ----------------------------
+/** Run a command with the terminal handed to the child: stdio inherited, no
+ * timeout, no output capture. Resolves when the child exits. Used for
+ * `interactive: true` commands — dev servers, watchers, REPLs.
+ *
+ * A null exit code (the child died to a signal, e.g. the user's Ctrl-C)
+ * counts as success: stopping a dev server is the normal way it ends. */
+export function execInteractive(command, opts) {
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd: opts.cwd,
+            shell: true,
+            stdio: "inherit",
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        });
+        // The child shares the terminal's foreground process group, so Ctrl-C
+        // reaches it directly. Ignore SIGINT in the parent while the child runs
+        // so wm survives long enough to report the child's exit.
+        const onSigint = () => { };
+        process.on("SIGINT", onSigint);
+        const done = (result) => {
+            process.off("SIGINT", onSigint);
+            resolve(result);
+        };
+        child.on("exit", (code) => {
+            done(code === 0 || code === null ? ok("") : fail(`exited with code ${code}`));
+        });
+        child.on("error", (e) => done(fail(e)));
+    });
+}
+/** Run a sequence of commands interactively. Fails fast. */
+export async function shSeqInteractive(commands, opts) {
+    for (const cmd of commands) {
+        const res = await execInteractive(cmd, opts);
+        if (res.isError)
+            return res;
+    }
+    return ok("");
+}

package/dist/lib/load.d.ts

@@ -1,3 +1,9 @@
-import type { ResolvedCommand } from "./types.js";
+import type { ResolvedCommand, Surface } from "./types.js";
 import type { Workspace } from "./workspace.js";
-export declare function loadCommands(workspace: Workspace): Promise<ResolvedCommand[]>;
+export interface LoadCommandsOptions {
+    /** Which host is executing. Interactive commands hand the terminal to the
+     * child only on "cli"; elsewhere they run buffered (and MCP hides them).
+     * Defaults to "mcp" — the conservative surface. */
+    surface?: Surface;
+}
+export declare function loadCommands(workspace: Workspace, options?: LoadCommandsOptions): Promise<ResolvedCommand[]>;

package/dist/lib/load.js

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, extname, join } from "node:path";
 import { createJiti } from "jiti";
 import { z } from "zod";
-import { execAsync, ok, fail, shSeq } from "./helpers.js";
+import { execAsync, execInteractive, ok, fail, shSeq, shSeqInteractive } from "./helpers.js";
 import { FROM_ARGS, FROM_WORKSPACE } from "./types.js";
 import { jitiOptions } from "./jiti-options.js";
 // --- Metadata derivation -------------------------------------------------
@@ -195,13 +195,18 @@ function buildSchema(args, flags, projectArg) {
         inputSchema.required = required;
     return { inputSchema, positional, projectArgName };
 }
-function makeBaseCtx(ws, cwdResolver, host) {
+function makeBaseCtx(ws, cwdResolver, host, interactive = false) {
     return {
         workspace: ws,
         ok,
         fail,
         sh: (cmd, opts) => {
             const options = { cwd: cwdResolver(), timeout: opts?.timeout, env: opts?.env };
+            if (interactive) {
+                return Array.isArray(cmd)
+                    ? shSeqInteractive(cmd, options)
+                    : execInteractive(cmd, options);
+            }
             return Array.isArray(cmd)
                 ? shSeq(cmd, options)
                 : execAsync(cmd, options);
@@ -210,12 +215,12 @@ function makeBaseCtx(ws, cwdResolver, host) {
         invoke: host.invoke,
     };
 }
-function makeNeedsCtx(ws, project, needs, host) {
+function makeNeedsCtx(ws, project, needs, host, interactive = false) {
     const traits = {};
     for (const t of needs)
         traits[t.name] = project.trait(t);
     return {
-        ...makeBaseCtx(ws, () => project.dir, host),
+        ...makeBaseCtx(ws, () => project.dir, host, interactive),
         project,
         traits,
     };
@@ -329,14 +334,21 @@ function collectFromArgsFields(fields) {
     }
     return out;
 }
-function resolve(def, workspace, group, sourceFile, host) {
+function resolve(def, workspace, group, sourceFile, host, surface) {
     const meta = deriveMetadata(def, sourceFile);
     const rawNeeds = def.needs ?? [];
     const needs = rawNeeds.map((t) => typeof t === "string" ? workspace.traits.require(t) : t);
-    const select = def.select ?? (needs.length > 0 ? "one-or-many" : "one");
+    const interactive = def.interactive === true;
+    // Interactive commands own the terminal — one child at a time, so with
+    // `needs` they default to (and require) single-project selection.
+    const select = def.select
+        ?? (needs.length > 0 ? (interactive ? "one" : "one-or-many") : "one");
     if (needs.length === 0 && select !== "one") {
         throw new Error(`Command "${meta.name}": select requires needs (at ${sourceFile})`);
     }
+    if (interactive && select !== "one") {
+        throw new Error(`Command "${meta.name}": interactive commands cannot use select "${select}" — the terminal can host one process at a time (at ${sourceFile})`);
+    }
     // `for` binds this command to a named project. No project arg is exposed on
     // any surface; ctx.project is the bound project.
     let boundProject = null;
@@ -366,19 +378,22 @@ function resolve(def, workspace, group, sourceFile, host) {
     // `for` suppresses the user-facing project arg.
     const projectArg = boundProject ? null : projectArgFor(needs, select, workspace);
     const { inputSchema, positional } = buildSchema(resolvedArgs, resolvedFlags, projectArg);
+    // The terminal handoff only exists on the CLI; other surfaces fall back to
+    // buffered execution (MCP additionally excludes interactive commands).
+    const interactiveExec = interactive && surface === "cli";
     const handler = async (args) => {
         const validated = validateFromArgsFields(args, fromArgsFields, workspace);
         if (needs.length === 0) {
-            const ctx = makeBaseCtx(workspace, () => workspace.root, host);
+            const ctx = makeBaseCtx(workspace, () => workspace.root, host, interactiveExec);
             return runHandler(def.handler, validated, ctx);
         }
         if (boundProject) {
-            const ctx = makeNeedsCtx(workspace, boundProject, needs, host);
+            const ctx = makeNeedsCtx(workspace, boundProject, needs, host, interactiveExec);
             return runHandler(def.handler, validated, ctx);
         }
         const projects = resolveProjects(needs, select, workspace, validated.project);
         if (select === "one") {
-            const ctx = makeNeedsCtx(workspace, projects[0], needs, host);
+            const ctx = makeNeedsCtx(workspace, projects[0], needs, host, interactiveExec);
             return runHandler(def.handler, stripProjectArg(validated), ctx);
         }
         return runMultiple(def.handler, validated, projects, needs, workspace, def.run, host);
@@ -394,6 +409,7 @@ function resolve(def, workspace, group, sourceFile, host) {
         sourceFile,
         select,
         needs: needs.map((t) => t.name),
+        interactive,
     };
 }
 // --- Discovery -----------------------------------------------------------
@@ -430,7 +446,8 @@ function walkCommands(root) {
     walk(root, []);
     return out;
 }
-export async function loadCommands(workspace) {
+export async function loadCommands(workspace, options) {
+    const surface = options?.surface ?? "mcp";
     const commandsDir = join(workspace.root, ".wm", "commands");
     if (!existsSync(commandsDir))
         return [];
@@ -462,7 +479,7 @@ export async function loadCommands(workspace) {
         const def = await importCommand(jiti, d.filePath);
         if (!def)
             continue;
-        const cmd = resolve(def, workspace, d.group, d.filePath, host);
+        const cmd = resolve(def, workspace, d.group, d.filePath, host, surface);
         // Override resolved name from path-derived name (filename was the fallback in meta).
         // Meta.name wins if explicitly set; otherwise use the discovered name.
         const userProvidedName = def.meta?.name;

package/dist/lib/types.d.ts

@@ -52,6 +52,10 @@ export interface IWorkspace {
 }
 /** How many projects a command runs against. */
 export type SelectMode = "one" | "one-or-many" | "all";
+/** Which host is executing commands. Interactive commands hand the terminal
+ * to the child process — only the CLI can do that; the MCP server excludes
+ * them from its tool list. */
+export type Surface = "cli" | "mcp";
 /** Framework-standard context passed to every handler. */
 export interface BaseCtx {
     workspace: IWorkspace;
@@ -91,6 +95,9 @@ export interface ResolvedCommand {
     select: SelectMode;
     /** Names of traits this command requires. Empty array = no needs. */
     needs: string[];
+    /** Long-running command that owns the terminal while it runs (dev server,
+     * watcher). CLI-only; the MCP server does not expose it. */
+    interactive: boolean;
 }
 export type ResolvedHandler = (args: Record<string, unknown>) => Promise<CallToolResult>;
 /** Per-project result shape for multi-target commands. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldlework/workmark",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "main": "dist/lib/load.js",
   "bin": {

package/src/cli.ts

@@ -92,6 +92,9 @@ interface CommandMetaJson {
   inputSchema: unknown;
   positional: string[];
   sourceFile: string | null;
+  /** Long-running terminal-owning command — hosts should run it in a real
+   * terminal rather than capturing its output. */
+  interactive: boolean;
 }
 
 function toCommandMeta(cmd: ResolvedCommand): CommandMetaJson {
@@ -103,6 +106,7 @@ function toCommandMeta(cmd: ResolvedCommand): CommandMetaJson {
     inputSchema: cmd.inputSchema,
     positional: cmd.positional,
     sourceFile: cmd.sourceFile ?? null,
+    interactive: cmd.interactive,
   };
 }
 
@@ -114,7 +118,7 @@ async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
 
   const workspace = await loadWorkspace();
-  const commands = await loadCommands(workspace);
+  const commands = await loadCommands(workspace, { surface: "cli" });
 
   if (command === "--introspect") {
     process.stdout.write(JSON.stringify(commands.map(toCommandMeta)) + "\n");

package/src/index.ts

@@ -18,13 +18,18 @@ async function main(): Promise<void> {
   );
 
   const workspace = await loadWorkspace();
-  const commands = await loadCommands(workspace);
-  const handlers = new Map(commands.map((c) => [c.name, c.handler]));
+  const commands = await loadCommands(workspace, { surface: "mcp" });
+  // Interactive commands own a terminal — an MCP client has none to give.
+  const exposed = commands.filter((c) => !c.interactive);
+  const handlers = new Map(exposed.map((c) => [c.name, c.handler]));
+  const interactiveNames = new Set(
+    commands.filter((c) => c.interactive).map((c) => c.name),
+  );
 
-  console.error(`Loaded ${commands.length} commands from ${workspace.projects.length} projects`);
+  console.error(`Loaded ${exposed.length} commands from ${workspace.projects.length} projects`);
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: commands.map(({ name, description, inputSchema }) => ({
+    tools: exposed.map(({ name, description, inputSchema }) => ({
       name,
       description,
       inputSchema,
@@ -34,6 +39,12 @@ async function main(): Promise<void> {
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const handler = handlers.get(request.params.name);
     if (!handler) {
+      if (interactiveNames.has(request.params.name)) {
+        throw new McpError(
+          ErrorCode.InvalidRequest,
+          `"${request.params.name}" is an interactive command (long-running, terminal-owning) — run it from a terminal: wm ${request.params.name}`,
+        );
+      }
       throw new McpError(
         ErrorCode.MethodNotFound,
         `Unknown tool: ${request.params.name}`,

package/src/lib/define.ts

@@ -63,6 +63,11 @@ export interface StaticCommandDef {
   select?: SelectMode;
   for?: string;
   run?: RunOptions;
+  /** Long-running command that owns the terminal (dev server, watcher).
+   * On the CLI, `ctx.sh` switches to inherited stdio with no timeout and
+   * resolves when the child exits. Not exposed over MCP. With `needs`,
+   * implies `select: "one"`. */
+  interactive?: boolean;
   args?: SchemaFields;
   flags?: SchemaFields;
   meta?: { name?: string; label?: string; description?: string };
@@ -84,6 +89,7 @@ export function cmd<
   select?: SelectMode;
   for?: string;
   run?: RunOptions;
+  interactive?: boolean;
   args?: A;
   flags?: F;
   meta?: { name?: string; label?: string; description?: string };

package/src/lib/helpers.ts

@@ -1,4 +1,4 @@
-import { execSync, exec as cpExec } from "node:child_process";
+import { execSync, exec as cpExec, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 
@@ -104,3 +104,50 @@ export async function execAsync(
     return fail(e);
   }
 }
+
+// --- Interactive execution (CLI surface only) ----------------------------
+
+/** Run a command with the terminal handed to the child: stdio inherited, no
+ * timeout, no output capture. Resolves when the child exits. Used for
+ * `interactive: true` commands — dev servers, watchers, REPLs.
+ *
+ * A null exit code (the child died to a signal, e.g. the user's Ctrl-C)
+ * counts as success: stopping a dev server is the normal way it ends. */
+export function execInteractive(
+  command: string,
+  opts: Pick<ExecOptions, "cwd" | "env">,
+): Promise<CallToolResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd: opts.cwd,
+      shell: true,
+      stdio: "inherit",
+      env: opts.env ? { ...process.env, ...opts.env } : process.env,
+    });
+    // The child shares the terminal's foreground process group, so Ctrl-C
+    // reaches it directly. Ignore SIGINT in the parent while the child runs
+    // so wm survives long enough to report the child's exit.
+    const onSigint = () => {};
+    process.on("SIGINT", onSigint);
+    const done = (result: CallToolResult) => {
+      process.off("SIGINT", onSigint);
+      resolve(result);
+    };
+    child.on("exit", (code) => {
+      done(code === 0 || code === null ? ok("") : fail(`exited with code ${code}`));
+    });
+    child.on("error", (e) => done(fail(e)));
+  });
+}
+
+/** Run a sequence of commands interactively. Fails fast. */
+export async function shSeqInteractive(
+  commands: readonly string[],
+  opts: Pick<ExecOptions, "cwd" | "env">,
+): Promise<CallToolResult> {
+  for (const cmd of commands) {
+    const res = await execInteractive(cmd, opts);
+    if (res.isError) return res;
+  }
+  return ok("");
+}

package/src/lib/load.ts

@@ -2,7 +2,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, extname, join } from "node:path";
 import { createJiti } from "jiti";
 import { z } from "zod";
-import { execAsync, ok, fail, shSeq } from "./helpers.js";
+import { execAsync, execInteractive, ok, fail, shSeq, shSeqInteractive } from "./helpers.js";
 import type {
   BaseCtx,
   HandlerReturn,
@@ -15,6 +15,7 @@ import type {
   RunOptions,
   SchemaFields,
   SelectMode,
+  Surface,
   Trait,
 } from "./types.js";
 import { FROM_ARGS, FROM_WORKSPACE } from "./types.js";
@@ -254,6 +255,7 @@ function makeBaseCtx(
   ws: IWorkspace,
   cwdResolver: () => string,
   host: InvocationHost,
+  interactive = false,
 ): BaseCtx {
   return {
     workspace: ws,
@@ -261,6 +263,11 @@ function makeBaseCtx(
     fail,
     sh: (cmd, opts) => {
       const options = { cwd: cwdResolver(), timeout: opts?.timeout, env: opts?.env };
+      if (interactive) {
+        return Array.isArray(cmd)
+          ? shSeqInteractive(cmd, options)
+          : execInteractive(cmd as string, options);
+      }
       return Array.isArray(cmd)
         ? shSeq(cmd, options)
         : execAsync(cmd as string, options);
@@ -275,11 +282,12 @@ function makeNeedsCtx(
   project: IProject,
   needs: readonly Trait[],
   host: InvocationHost,
+  interactive = false,
 ): NeedsCtx<Record<string, unknown>> {
   const traits: Record<string, unknown> = {};
   for (const t of needs) traits[t.name] = project.trait(t as Trait<string, unknown>);
   return {
-    ...makeBaseCtx(ws, () => project.dir, host),
+    ...makeBaseCtx(ws, () => project.dir, host, interactive),
     project,
     traits,
   };
@@ -435,17 +443,27 @@ function resolve(
   group: string,
   sourceFile: string,
   host: InvocationHost,
+  surface: Surface,
 ): ResolvedCommand {
   const meta = deriveMetadata(def, sourceFile);
   const rawNeeds = def.needs ?? [];
   const needs: Trait[] = rawNeeds.map((t) =>
     typeof t === "string" ? workspace.traits.require(t) : t as Trait,
   );
-  const select: SelectMode = def.select ?? (needs.length > 0 ? "one-or-many" : "one");
+  const interactive = def.interactive === true;
+  // Interactive commands own the terminal — one child at a time, so with
+  // `needs` they default to (and require) single-project selection.
+  const select: SelectMode = def.select
+    ?? (needs.length > 0 ? (interactive ? "one" : "one-or-many") : "one");
 
   if (needs.length === 0 && select !== "one") {
     throw new Error(`Command "${meta.name}": select requires needs (at ${sourceFile})`);
   }
+  if (interactive && select !== "one") {
+    throw new Error(
+      `Command "${meta.name}": interactive commands cannot use select "${select}" — the terminal can host one process at a time (at ${sourceFile})`,
+    );
+  }
 
   // `for` binds this command to a named project. No project arg is exposed on
   // any surface; ctx.project is the bound project.
@@ -485,23 +503,27 @@ function resolve(
   const projectArg = boundProject ? null : projectArgFor(needs, select, workspace);
   const { inputSchema, positional } = buildSchema(resolvedArgs, resolvedFlags, projectArg);
 
+  // The terminal handoff only exists on the CLI; other surfaces fall back to
+  // buffered execution (MCP additionally excludes interactive commands).
+  const interactiveExec = interactive && surface === "cli";
+
   const handler: ResolvedHandler = async (args) => {
     const validated = validateFromArgsFields(args, fromArgsFields, workspace);
 
     if (needs.length === 0) {
-      const ctx = makeBaseCtx(workspace, () => workspace.root, host);
+      const ctx = makeBaseCtx(workspace, () => workspace.root, host, interactiveExec);
       return runHandler(def.handler, validated, ctx);
     }
 
     if (boundProject) {
-      const ctx = makeNeedsCtx(workspace, boundProject, needs, host);
+      const ctx = makeNeedsCtx(workspace, boundProject, needs, host, interactiveExec);
       return runHandler(def.handler, validated, ctx);
     }
 
     const projects = resolveProjects(needs, select, workspace, validated.project);
 
     if (select === "one") {
-      const ctx = makeNeedsCtx(workspace, projects[0], needs, host);
+      const ctx = makeNeedsCtx(workspace, projects[0], needs, host, interactiveExec);
       return runHandler(def.handler, stripProjectArg(validated), ctx);
     }
 
@@ -519,6 +541,7 @@ function resolve(
     sourceFile,
     select,
     needs: needs.map((t) => t.name),
+    interactive,
   };
 }
 
@@ -567,7 +590,18 @@ function walkCommands(root: string): Discovered[] {
   return out;
 }
 
-export async function loadCommands(workspace: Workspace): Promise<ResolvedCommand[]> {
+export interface LoadCommandsOptions {
+  /** Which host is executing. Interactive commands hand the terminal to the
+   * child only on "cli"; elsewhere they run buffered (and MCP hides them).
+   * Defaults to "mcp" — the conservative surface. */
+  surface?: Surface;
+}
+
+export async function loadCommands(
+  workspace: Workspace,
+  options?: LoadCommandsOptions,
+): Promise<ResolvedCommand[]> {
+  const surface: Surface = options?.surface ?? "mcp";
   const commandsDir = join(workspace.root, ".wm", "commands");
   if (!existsSync(commandsDir)) return [];
 
@@ -598,7 +632,7 @@ export async function loadCommands(workspace: Workspace): Promise<ResolvedComman
   for (const d of discovered) {
     const def = await importCommand(jiti, d.filePath);
     if (!def) continue;
-    const cmd = resolve(def, workspace, d.group, d.filePath, host);
+    const cmd = resolve(def, workspace, d.group, d.filePath, host, surface);
     // Override resolved name from path-derived name (filename was the fallback in meta).
     // Meta.name wins if explicitly set; otherwise use the discovered name.
     const userProvidedName = def.meta?.name;

package/src/lib/types.ts

@@ -70,6 +70,11 @@ export interface IWorkspace {
 /** How many projects a command runs against. */
 export type SelectMode = "one" | "one-or-many" | "all";
 
+/** Which host is executing commands. Interactive commands hand the terminal
+ * to the child process — only the CLI can do that; the MCP server excludes
+ * them from its tool list. */
+export type Surface = "cli" | "mcp";
+
 /** Framework-standard context passed to every handler. */
 export interface BaseCtx {
   workspace: IWorkspace;
@@ -105,6 +110,9 @@ export interface ResolvedCommand {
   select: SelectMode;
   /** Names of traits this command requires. Empty array = no needs. */
   needs: string[];
+  /** Long-running command that owns the terminal while it runs (dev server,
+   * watcher). CLI-only; the MCP server does not expose it. */
+  interactive: boolean;
 }
 
 export type ResolvedHandler = (