@modootoday/pmcp 0.14.1 → 0.16.0

package/dist/tui-worker.js

@@ -64,6 +64,11 @@ var tuiOptions = [
   },
   { name: "rows", describe: "Terminal rows (12\u20131000)", placeholder: "<count>" },
   { name: "index", describe: "Worker dock index", placeholder: "<count>" },
+  {
+    name: "memory-mb",
+    describe: "Worker memory reservation",
+    placeholder: "<count>"
+  },
   {
     name: "confirm-session",
     describe: "Exact target ID for stop",
@@ -71,9 +76,24 @@ var tuiOptions = [
   },
   {
     name: "config",
-    describe: "Optional mailbox pmcp.toml",
+    describe: "Project pmcp.toml (or mailbox config for create)",
     placeholder: "<file>"
   },
+  {
+    name: "runtime",
+    describe: "Native runtime ID for main launch or worker start",
+    placeholder: "<runtime>"
+  },
+  {
+    name: "yes",
+    describe: "Confirm the first native runtime start",
+    boolean: true
+  },
+  {
+    name: "new",
+    describe: "Create a workspace after the previous group is stopped",
+    boolean: true
+  },
   {
     name: "actor-file",
     describe: "Optional private mailbox observer credential",
@@ -81,6 +101,10 @@ var tuiOptions = [
   }
 ];
 var allowed = {
+  launch: ["config", "runtime", "yes", "new"],
+  plan: ["config", "runtime"],
+  recovery: ["config"],
+  "start-worker": ["config", "view", "runtime", "memory-mb"],
   doctor: [],
   create: ["group-file", "columns", "rows", "config", "actor-file"],
   inspect: ["view"],
@@ -98,10 +122,12 @@ var allowed = {
   close: ["view"],
   dismiss: ["view"],
   management: ["view"],
+  "worker-menu": ["view"],
   check: ["view"]
 };
 function parseTui(args) {
-  const [action, ...extra] = args.positional;
+  let [action, ...extra] = args.positional;
+  if (action === void 0) action = one(args, "view") ? "open" : "launch";
   const options = action ? allowed[action] : void 0;
   if (!action || !options || extra.length)
     throw new ArgumentError("Provide one supported TUI operation");
@@ -121,6 +147,33 @@ function parseTui(args) {
     return Number(value);
   };
   if (action === "doctor") return { action, input: {} };
+  if (action === "start-worker") {
+    const config = one(args, "config");
+    const viewFile = one(args, "view");
+    if (config && viewFile)
+      throw new ArgumentError("Choose --config or --view for worker start");
+    return {
+      action,
+      viewFile,
+      input: {},
+      startup: {
+        config,
+        runtime: required("runtime"),
+        memoryMb: number("memory-mb")
+      }
+    };
+  }
+  if (action === "launch" || action === "plan" || action === "recovery")
+    return {
+      action,
+      input: {},
+      startup: {
+        config: one(args, "config"),
+        runtime: one(args, "runtime"),
+        fresh: args.flags.has("new"),
+        confirmed: args.flags.has("yes")
+      }
+    };
   if (action === "create") {
     const config = one(args, "config");
     const actorFile = one(args, "actor-file");
@@ -677,9 +730,9 @@ async function attachNative(spec, renew) {
   }, 2e4) : void 0;
   let exitCode;
   try {
-    exitCode = await new Promise((resolve4, reject) => {
+    exitCode = await new Promise((resolve5, reject) => {
       client.once("error", reject);
-      client.once("exit", (code) => resolve4(code ?? 1));
+      client.once("exit", (code) => resolve5(code ?? 1));
     });
   } finally {
     if (timer) clearInterval(timer);
@@ -858,7 +911,6 @@ var Connection = class {
   constructor(records2) {
     this.records = records2;
   }
-  records;
   tmux(args, options = {}) {
     return command(
       "tmux",
@@ -1095,8 +1147,6 @@ var LaunchJournal = class {
     this.id = id2;
     runtimeUnit(id2);
   }
-  records;
-  id;
   path(kind) {
     if (!["intent", "proof", "grant", "committed", "aborted"].includes(kind))
       throw new Error("invalid_launch_artifact");
@@ -1594,7 +1644,7 @@ var DockerEngine = class {
     if (!/^1\.\d+$/.test(version))
       throw new Error("invalid_docker_api_version");
     const payload = JSON.stringify(configuration);
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve5, reject) => {
       const req = request(
         {
           socketPath: new URL(endpoint).pathname,
@@ -1629,7 +1679,7 @@ var DockerEngine = class {
               );
               if (!/^[a-f0-9]{64}$/.test(id2))
                 throw new Error("invalid_container_id");
-              resolve4(id2);
+              resolve5(id2);
             } catch (error) {
               reject(error);
             }
@@ -2225,7 +2275,6 @@ var Backend = class {
     this.runDirectory = recordStore.directory;
     this.metadataPath = recordStore.metadataPath;
   }
-  recordStore;
   connection;
   owner;
   socket;
@@ -2709,7 +2758,7 @@ async function watchSession(operation) {
       )
     });
     if (index + 1 < count)
-      await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
+      await new Promise((resolve5) => setTimeout(resolve5, intervalMs));
   }
   return {
     schemaVersion: 1,
@@ -3364,7 +3413,6 @@ var CommonHarness = class {
   constructor(view) {
     this.view = view;
   }
-  view;
   async call(family, action, input = {}) {
     const group = new GroupStore(this.view.groupFile).state.group;
     if (group.owner !== this.view.groupOwner) throw new Error("foreign_group");
@@ -3398,6 +3446,19 @@ var CommonHarness = class {
 // src/tui/application/feedback.ts
 import { join as join20 } from "path";
 var hints = {
+  startup_requires_recovery: "Run pmcp tui recovery for saved ownership and exact inspection commands. No runtime was restarted.",
+  startup_group_paused: "The saved group is paused. Resume it explicitly through the harness CLI before reopening.",
+  startup_main_unavailable: "Inspect the saved main and recovery state. Stop the old group explicitly before using pmcp tui --new.",
+  startup_busy: "Another workspace launch is running. Wait and retry.",
+  startup_runtime_conflict: "The saved main uses another runtime. Stop the old group before creating a new workspace.",
+  workspace_already_running: "Reopen the existing workspace, or stop its exact owned group before using --new.",
+  runtime_executable_unavailable: "Install the selected native CLI on PATH, or choose an installed runtime with --runtime.",
+  view_client_unavailable: "Open the view before using the worker menu, or run pmcp tui start-worker with --view and --runtime.",
+  runtime_not_granted: "Choose a runtime granted by this owned group. Inspect the group before creating another workspace.",
+  runtime_capacity_exceeded: "Stop an exact owned worker before adding another, or use the main session alone.",
+  aggregate_memory_budget_exceeded: "Use fewer sessions or start a worker with an explicit smaller --memory-mb reservation.",
+  group_not_ready: "Inspect the group and resume a paused group explicitly before adding a worker.",
+  startup_group_not_ready: "Inspect the group and resume a paused group explicitly before adding a worker.",
   control_connection_lost: "The native writer or lease disappeared. Inspect and release control before reconnecting.",
   control_busy: "Another controller holds the lease. Release it explicitly before retrying.",
   native_writer_active: "A native writer is still attached. Detach that writer before retrying.",
@@ -3453,6 +3514,14 @@ function phaseLabel(phase2) {
   return labels[phase2];
 }
 
+// src/tui/presentation/target.ts
+function targetStatus(view) {
+  const role2 = view.target === view.mainId ? "MAIN" : "WORKER";
+  const phase2 = view.phase === "read-only" ? "OBSERVE" : phaseLabel(view.phase);
+  const input = view.phase === "controlled" ? "INPUT ON" : "INPUT OFF";
+  return `${role2} ${view.target.slice(0, 8)} | ${phase2} | ${input}`;
+}
+
 // src/tui/adapters/tmux/connection.ts
 import { spawn as spawn2 } from "child_process";
 import { join as join21 } from "path";
@@ -3501,9 +3570,6 @@ var ViewConnection = class {
     this.identity = identity;
     this.socket = join21(directory, "s");
   }
-  directory;
-  owner;
-  identity;
   socket;
   raw(args) {
     const env = { ...process.env };
@@ -3573,9 +3639,9 @@ var ViewConnection = class {
       ["-S", this.socket, "attach-session", "-E", "-t", view.session],
       { stdio: "inherit", env }
     );
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve5, reject) => {
       client.once("error", reject);
-      client.once("exit", (code) => resolve4(code ?? 1));
+      client.once("exit", (code) => resolve5(code ?? 1));
     });
   }
 };
@@ -3606,7 +3672,8 @@ function bindKeys(connection, view, file) {
     ["b", "mailbox"],
     ["d", "detach"],
     ["!", "dismiss"],
-    ["g", "management"]
+    ["g", "management"],
+    ["n", "worker-menu"]
   ])
     connection.command([
       "bind-key",
@@ -3627,7 +3694,7 @@ function bindKeys(connection, view, file) {
     "bind-key",
     "?",
     "display-message",
-    "m main; w/1-4 worker; c control; r release; h history; b mailbox; d detach; ! dismiss error; double Ctrl-g forwards native Ctrl-g"
+    "m main; n add worker; w/1-4 worker; c control; r release; h history; b mailbox; d detach; ! dismiss error; double Ctrl-g forwards native Ctrl-g"
   ]);
   connection.command([
     "set-hook",
@@ -3654,8 +3721,6 @@ var TmuxView = class {
       view.serverIdentity
     );
   }
-  view;
-  stateFile;
   connection;
   shell(argv2) {
     return `exec ${argv2.map(quote).join(" ")}`;
@@ -3827,7 +3892,7 @@ var TmuxView = class {
       "set-option",
       "-g",
       "status-right",
-      `${view.target === view.mainId ? "main" : "worker"} | ${phaseLabel(view.phase)}${failure2} | Ctrl-g ?`
+      `${targetStatus(view)}${failure2} | Ctrl-g ?`
     ]);
   }
   input(pane, enabled) {
@@ -3850,6 +3915,32 @@ var TmuxView = class {
   clients() {
     return this.connection.command(["list-clients", "-F", "#{client_pid}"]);
   }
+  workerMenu(view) {
+    const pane = view.workerPane ?? view.mainPane;
+    this.connection.assertOwned(pane);
+    const popup = [
+      "tmux",
+      "-S",
+      this.connection.socket,
+      "display-popup",
+      "-E",
+      "-t",
+      pane,
+      "-w",
+      "90%",
+      "-h",
+      "80%",
+      this.shell([
+        view.node,
+        view.worker,
+        "worker-menu",
+        "--view",
+        this.stateFile,
+        "--callback"
+      ])
+    ];
+    this.connection.command(["run-shell", "-b", popup.map(quote).join(" ")]);
+  }
   copy(pane) {
     this.connection.assertOwned(pane);
     this.connection.command(["copy-mode", "-t", pane]);
@@ -3880,7 +3971,7 @@ async function waitFor(predicate, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await predicate()) return;
-    await new Promise((resolve4) => setTimeout(resolve4, 50));
+    await new Promise((resolve5) => setTimeout(resolve5, 50));
   }
   throw new Error("writer_not_ready");
 }
@@ -3916,6 +4007,7 @@ function dockLines(snapshot) {
     ),
     "",
     "Ctrl-g w: observe worker",
+    "Ctrl-g n: add worker",
     "Ctrl-g m: return to main",
     "Ctrl-g c: acquire control",
     "Ctrl-g r: release control",
@@ -3927,7 +4019,7 @@ function dockLines(snapshot) {
   ];
 }
 function coordinationLines(snapshot, view) {
-  const target = `TARGET ${view.target === view.mainId ? "main" : "worker"} ${safe(view.target.slice(0, 8))} / ${phaseLabel(view.phase)}`;
+  const target = `TARGET ${safe(targetStatus(view))}`;
   if (view.failure)
     return [
       target,
@@ -4076,6 +4168,7 @@ function resolveEncoder(model = DEFAULT_MODEL_ID, options = {}) {
 }
 
 // src/config.ts
+var CONFIG_FILE = "pmcp.toml";
 function embeddingSection(path, dir, value) {
   if (value === void 0) return void 0;
   if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -4166,6 +4259,17 @@ var CATALOG_KEYS = /* @__PURE__ */ new Set([
   "scopes",
   "builtin"
 ]);
+function findConfig(start2) {
+  let dir = resolve2(start2);
+  for (; ; ) {
+    const candidate = join23(dir, CONFIG_FILE);
+    if (existsSync10(candidate)) return candidate;
+    if (existsSync10(join23(dir, ".git"))) return null;
+    const parent = dirname5(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
 function stringList(path, key, value) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
     throw new ConfigError(path, `[catalog] ${key} must be a list of strings`);
@@ -4304,8 +4408,6 @@ var MailboxError = class extends Error {
     this.retryable = retryable;
     this.name = "MailboxError";
   }
-  code;
-  retryable;
 };
 function failure(error) {
   if (error instanceof MailboxError) {
@@ -5551,7 +5653,7 @@ ${content}
     stopped = true;
   });
   while (!stopped) {
-    await new Promise((resolve4) => setTimeout(resolve4, 1500));
+    await new Promise((resolve5) => setTimeout(resolve5, 1500));
     await draw();
   }
 }
@@ -5669,6 +5771,11 @@ var handlers = {
   close: closeView,
   check: checkControl,
   dismiss: ({ view, file }) => dismissFailure(file, view),
+  "worker-menu": async (context) => {
+    if (!context.renderer.clients()) throw new Error("view_client_unavailable");
+    await releaseControl(context);
+    context.renderer.workerMenu(context.view);
+  },
   management: async (context) => {
     await releaseControl(context);
     if (context.view.managementWindow) {
@@ -5802,6 +5909,70 @@ function runtime() {
   return { node: realpathSync10(available.node), worker: bundled };
 }
 
+// src/tui/startup/diagnostics.ts
+function remediation(tools, userManagerAvailable) {
+  const steps = [];
+  if (tools.platform !== "linux")
+    steps.push(
+      "Use a qualified Linux host for the terminal workspace. Other PMCP CLI features do not require this host profile."
+    );
+  const missing = ["tmux", "flock", "systemctl", "systemdRun"].filter(
+    (name) => !tools[name]
+  );
+  if (missing.length)
+    steps.push(
+      `Install the missing tmux, util-linux or systemd tools for your distribution and add them to PATH: ${missing.join(", ")}.`
+    );
+  if (!tools.nodeSupported)
+    steps.push(
+      "Select Node.js 22 or later through your existing version manager and check node --version in this terminal."
+    );
+  if (tools.supported && !userManagerAvailable)
+    steps.push(
+      "Check systemctl --user status in your login session and restore access to its user manager before launching. Doctor does not start or repair services."
+    );
+  return steps;
+}
+function inspectTerminalHost() {
+  const tools = dependencies();
+  let userManagerAvailable = false;
+  let reason;
+  try {
+    if (!tools.supported) throw new Error("tui_dependencies_unavailable");
+    assertNativeHost();
+    userManagerAvailable = true;
+  } catch (error) {
+    reason = error instanceof Error ? error.message : "native_host_unavailable";
+  }
+  const runtimes = Object.entries(runtimeExecutables).map(
+    ([id2, executable]) => {
+      const path = locateExecutable(executable);
+      return {
+        id: id2,
+        executable,
+        installed: Boolean(path),
+        ...path ? { path } : {},
+        nativeAcceptance: "not-assessed",
+        authentication: "not-inspected"
+      };
+    }
+  );
+  return {
+    schemaVersion: 1,
+    ok: true,
+    ...tools,
+    supported: tools.supported && userManagerAvailable,
+    userManagerAvailable,
+    ...reason ? { reason } : {},
+    runtimes,
+    qualification: "Prerequisite availability only; native behavior and cgroup delegation require separate qualification.",
+    remediation: remediation(tools, userManagerAvailable),
+    nextCommands: ["pmcp tui plan", "pmcp tui recovery"],
+    providerInvoked: false,
+    authenticationInspected: false
+  };
+}
+
 // src/tui/application/create.ts
 import { join as join29 } from "path";
 import { realpathSync as realpathSync11 } from "fs";
@@ -5880,8 +6051,9 @@ async function createView(input) {
 
 // src/tui/application/invoke.ts
 async function invokeTui(invocation) {
-  if (invocation.action === "doctor")
-    return { schemaVersion: 1, ok: true, ...dependencies() };
+  if (["launch", "plan", "recovery", "start-worker"].includes(invocation.action))
+    throw new Error("startup_requires_cli_context");
+  if (invocation.action === "doctor") return inspectTerminalHost();
   if (invocation.action === "create") return createView(invocation.create);
   if (invocation.action === "inspect")
     return operate("inspect", invocation.viewFile);
@@ -5917,11 +6089,379 @@ function failedInvocation(action, error) {
   };
 }
 
+// src/tui/startup/workspace.ts
+import { existsSync as existsSync16 } from "fs";
+
+// src/tui/startup/config.ts
+import { realpathSync as realpathSync12 } from "fs";
+import { resolve as resolve4 } from "path";
+var preference = [
+  "codex-cli",
+  "gemini-cli",
+  "antigravity",
+  "grok-cli",
+  "claude-code"
+];
+function startupSettings(request2) {
+  const path = request2.config ? resolve4(request2.cwd, request2.config) : findConfig(request2.cwd);
+  const config = path ? readConfig(path) : void 0;
+  const source2 = config?.raw.tui;
+  const fail = (message) => {
+    throw new ConfigError(path ?? "pmcp.toml", `[tui] ${message}`);
+  };
+  if (source2 !== void 0 && (source2 === null || typeof source2 !== "object" || Array.isArray(source2)))
+    fail("must be a table");
+  const values = source2 ?? {};
+  const allowed2 = /* @__PURE__ */ new Set([
+    "runtime",
+    "memory_mb",
+    "session_memory_mb",
+    "max_active",
+    "group_file"
+  ]);
+  for (const key of Object.keys(values)) {
+    if (!allowed2.has(key)) fail(`unknown key ${key}`);
+  }
+  const string = (key) => {
+    const value = values[key];
+    if (value === void 0) return void 0;
+    if (typeof value !== "string" || !value.trim())
+      fail(`${key} must be a non-empty string`);
+    return value;
+  };
+  const integer2 = (key, fallback, min, max) => {
+    const value = values[key] ?? fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+      fail(`${key} must be an integer`);
+    if (Number(value) < min || Number(value) > max)
+      fail(`${key} must be between ${min} and ${max}`);
+    return Number(value);
+  };
+  const configuredRuntime = string("runtime");
+  if (configuredRuntime !== void 0 && configuredRuntime !== "auto" && !Object.hasOwn(runtimeExecutables, configuredRuntime))
+    fail("runtime must be auto or a supported runtime ID");
+  const available = preference.filter(
+    (runtime3) => locateExecutable(runtimeExecutables[runtime3], request2.cwd)
+  );
+  let runtime2 = request2.runtime ?? configuredRuntime ?? "auto";
+  if (runtime2 === "auto") runtime2 = available[0] ?? "codex-cli";
+  if (!Object.hasOwn(runtimeExecutables, runtime2))
+    fail("runtime must be a supported runtime ID");
+  const memoryMb = integer2("memory_mb", 2048, 128, 4096);
+  const sessionMemoryMb = integer2("session_memory_mb", 768, 32, 1536);
+  if (sessionMemoryMb > memoryMb)
+    fail("session memory exceeds the group budget");
+  const groupFile = string("group_file");
+  return {
+    projectRoot: realpathSync12(config?.dir ?? request2.cwd),
+    ...config ? { configFile: config.path } : {},
+    runtime: runtime2,
+    allowedRuntimes: [.../* @__PURE__ */ new Set([...available, runtime2])],
+    memoryMb,
+    sessionMemoryMb,
+    maxActive: integer2("max_active", 2, 1, 5),
+    ...groupFile ? { groupFile: resolve4(config?.dir ?? request2.cwd, groupFile) } : {}
+  };
+}
+
+// src/tui/startup/state.ts
+import { createHash as createHash8 } from "crypto";
+import { existsSync as existsSync15, lstatSync as lstatSync8, mkdirSync as mkdirSync6 } from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname as dirname9, join as join30 } from "path";
+function startupFile(projectRoot) {
+  const root = join30(
+    process.env.XDG_STATE_HOME ?? join30(homedir6(), ".local/state"),
+    "pmcp/launcher"
+  );
+  const key = createHash8("sha256").update(projectRoot).digest("hex");
+  return join30(root, `${key}.json`);
+}
+function readStartup(file, projectRoot) {
+  if (!existsSync15(file)) return null;
+  const value = object(readPrivateJson(file));
+  if (value.schemaVersion !== 1 || value.projectRoot !== projectRoot)
+    throw new Error("foreign_startup_state");
+  if (!["creating", "starting", "view-pending", "ready"].includes(
+    String(value.phase)
+  ))
+    throw new Error("invalid_startup_state");
+  text(value.runtime, "runtime");
+  if (value.phase !== "creating") {
+    text(value.groupFile, "group_file");
+    text(value.generation, "generation");
+  }
+  if (value.phase === "ready") text(value.viewFile, "view_file");
+  return value;
+}
+function saveStartup(file, state) {
+  privateJson(file, state);
+}
+
+// src/tui/startup/workspace.ts
+function succeeded(receipt) {
+  if (receipt.ok !== true)
+    throw new Error(String(receipt.error ?? "startup_operation_failed"));
+  return receipt;
+}
+async function prepareWorkspace(request2) {
+  const settings = startupSettings(request2);
+  const file = startupFile(settings.projectRoot);
+  let state = readStartup(file, settings.projectRoot);
+  if (state && !["ready", "view-pending"].includes(state.phase)) {
+    if (!request2.fresh || state.phase === "creating")
+      throw new Error("startup_requires_recovery");
+  }
+  if (state && settings.groupFile && state.groupFile !== settings.groupFile)
+    throw new Error("startup_group_conflict");
+  if (state) {
+    const group = new GroupStore(state.groupFile).state.group;
+    assertGroup(group, settings.projectRoot, state.generation);
+    if (group.state === "paused") throw new Error("startup_group_paused");
+    if (request2.fresh) {
+      if (group.state !== "stopped")
+        throw new Error("workspace_already_running");
+      state = null;
+    } else {
+      if (group.state !== "ready") throw new Error("startup_requires_recovery");
+      if (request2.runtime && request2.runtime !== state.runtime)
+        throw new Error("startup_runtime_conflict");
+    }
+  }
+  if (!state && settings.groupFile) {
+    const store = new GroupStore(settings.groupFile);
+    const group = store.state.group;
+    assertGroup(group, settings.projectRoot);
+    if (group.state !== "ready") throw new Error("startup_group_not_ready");
+    state = {
+      schemaVersion: 1,
+      projectRoot: settings.projectRoot,
+      phase: "view-pending",
+      groupFile: store.path,
+      generation: group.generation,
+      runtime: settings.runtime
+    };
+    saveStartup(file, state);
+  }
+  if (!state) {
+    state = {
+      schemaVersion: 1,
+      projectRoot: settings.projectRoot,
+      phase: "creating",
+      runtime: settings.runtime
+    };
+    saveStartup(file, state);
+    const created = succeeded(
+      await invoke({
+        family: "group",
+        action: "create",
+        input: {
+          projectRoot: settings.projectRoot,
+          allowedRuntimes: [...settings.allowedRuntimes],
+          memoryMb: settings.memoryMb,
+          maxActive: settings.maxActive
+        }
+      })
+    );
+    state.groupFile = String(created.groupFile);
+    state.generation = created.group.generation;
+    state.phase = "starting";
+    saveStartup(file, state);
+    succeeded(
+      await invoke({
+        family: "session",
+        action: "start",
+        groupFile: state.groupFile,
+        generation: state.generation,
+        input: {
+          runtime: settings.runtime,
+          role: "main",
+          memoryMb: settings.sessionMemoryMb
+        }
+      })
+    );
+    state.phase = "view-pending";
+    saveStartup(file, state);
+  }
+  const observed = succeeded(
+    await invoke({
+      family: "session",
+      action: "list",
+      groupFile: state.groupFile
+    })
+  );
+  const sessions = observed.sessions;
+  const main = sessions.find(
+    (session) => session.role === "main" && session.alive
+  );
+  if (!main) throw new Error("startup_main_unavailable");
+  state.runtime = main.runtime;
+  const existing = state.viewFile && existsSync16(state.viewFile) ? readView(state.viewFile).view : void 0;
+  if (existing) {
+    if (existing.groupFile !== state.groupFile || existing.generation !== state.generation)
+      throw new Error("foreign_startup_view");
+  }
+  if (!existing || existing.state === "closed") {
+    const created = await createView({
+      groupFile: state.groupFile,
+      columns: process.stdout.columns ?? Number(process.env.PMCP_TUI_COLUMNS),
+      rows: process.stdout.rows ?? Number(process.env.PMCP_TUI_ROWS)
+    });
+    state.viewFile = created.viewFile;
+  }
+  state.phase = "ready";
+  saveStartup(file, state);
+  return {
+    schemaVersion: 1,
+    ok: true,
+    viewFile: state.viewFile,
+    groupFile: state.groupFile,
+    generation: state.generation,
+    runtime: state.runtime,
+    readOnly: true
+  };
+}
+function assertGroup(group, projectRoot, generation) {
+  if (group.projectRoot !== projectRoot)
+    throw new Error("startup_project_mismatch");
+  if (generation && group.generation !== generation)
+    throw new Error("stale_group_generation");
+}
+
+// src/tui/application/worker-start.ts
+async function startViewWorker(file, runtime2, memoryMb) {
+  const { view, common } = openView(file);
+  if (view.state !== "open") throw new Error("view_closed");
+  const observed = await common.snapshot();
+  if (observed.group.state !== "ready") throw new Error("group_not_ready");
+  const main = observed.sessions.find(
+    (session) => session.id === view.mainId && session.role === "main"
+  );
+  if (!main?.alive) throw new Error("startup_main_unavailable");
+  return common.call("session", "start", {
+    input: { role: "worker", runtime: runtime2, memoryMb: memoryMb ?? main.memoryMb }
+  });
+}
+
+// src/cli/entry.ts
+function interactiveEntry(terminal) {
+  if (!terminal.stdin || !terminal.stdout) return false;
+  if (!terminal.term || terminal.term === "dumb") return false;
+  return !terminal.ci || terminal.ci === "false" || terminal.ci === "0";
+}
+
+// src/tui/startup/host.ts
+function terminalSupport() {
+  try {
+    if (!dependencies().supported)
+      throw new Error("tui_dependencies_unavailable");
+    assertNativeHost();
+    planLayout(process.stdout.columns ?? 0, process.stdout.rows ?? 0);
+    return { supported: true };
+  } catch (error) {
+    return {
+      supported: false,
+      reason: error instanceof Error ? error.message : "terminal_unavailable"
+    };
+  }
+}
+function requireTerminal() {
+  if (!interactiveEntry({
+    stdin: process.stdin.isTTY === true,
+    stdout: process.stdout.isTTY === true,
+    term: process.env.TERM,
+    ci: process.env.CI
+  }))
+    throw new Error("terminal_required");
+  const support = terminalSupport();
+  if (!support.supported) throw new Error(support.reason);
+}
+
+// src/tui/presentation/runtime-choice.ts
+import { createInterface } from "readline/promises";
+async function chooseRuntime(prompt, choices, preferred) {
+  if (!choices.length) throw new Error("runtime_executable_unavailable");
+  const fallback = Math.max(choices.indexOf(preferred), 0);
+  process.stderr.write(
+    `${choices.map((runtime2, index) => `${index + 1}. ${runtime2}`).join("\n")}
+`
+  );
+  while (true) {
+    const answer = (await prompt.question(
+      `Runtime [1-${choices.length}, Enter=${fallback + 1}, q=cancel] `
+    )).trim();
+    if (answer === "q") return void 0;
+    if (answer === "") return choices[fallback];
+    if (!/^\d+$/.test(answer)) continue;
+    const index = Number(answer) - 1;
+    if (Number.isSafeInteger(index) && index >= 0 && index < choices.length)
+      return choices[index];
+  }
+}
+async function confirmRuntimeStart(prompt, runtime2) {
+  const answer = await prompt.question(
+    `Start ${runtime2}? [Enter=start, q=cancel] `
+  );
+  return answer.trim() === "";
+}
+function terminalPrompt() {
+  return createInterface({ input: process.stdin, output: process.stderr });
+}
+
+// src/tui/presentation/worker-menu.ts
+async function runWorkerMenu(file) {
+  requireTerminal();
+  const { view, common } = openView(file);
+  if (view.state !== "open") throw new Error("view_closed");
+  const observed = await common.snapshot();
+  const group = observed.group;
+  if (group.state !== "ready") throw new Error("startup_group_not_ready");
+  const choices = group.allowedRuntimes.filter((runtime2) => {
+    const executable = runtimeExecutables[runtime2];
+    if (!executable) return false;
+    if (group.profile === "docker")
+      return Boolean(group.dockerPolicy?.commands[runtime2]);
+    return Boolean(locateExecutable(executable, group.projectRoot));
+  });
+  const main = observed.sessions.find((session) => session.id === view.mainId);
+  if (!main?.alive) throw new Error("startup_main_unavailable");
+  process.stderr.write(`PMCP WORKER | ${group.projectRoot}
+`);
+  const prompt = terminalPrompt();
+  try {
+    const runtime2 = await chooseRuntime(prompt, choices, main.runtime);
+    if (!runtime2 || !await confirmRuntimeStart(prompt, runtime2)) return;
+    await startViewWorker(file, runtime2);
+  } finally {
+    prompt.close();
+  }
+}
+
 // src/tui/application/worker.ts
 var [role, ...argv] = process.argv.slice(2);
 var callback2 = argv.includes("--callback");
 try {
-  if (role === "attach") {
+  if (role === "startup") {
+    const [encoded, ...extra] = argv;
+    if (!encoded || extra.length || encoded.length > 16384 || !/^[A-Za-z0-9_-]+$/.test(encoded))
+      throw new Error("invalid_startup_arguments");
+    const request2 = JSON.parse(
+      Buffer.from(encoded, "base64url").toString("utf8")
+    );
+    if (typeof request2.cwd !== "string" || !request2.cwd)
+      throw new Error("invalid_startup_arguments");
+    const result = await prepareWorkspace(request2);
+    process.stdout.write(`${JSON.stringify(result)}
+`);
+  } else if (role === "worker-menu") {
+    const invocation = parseTui(
+      parseArgs(
+        ["worker-menu", ...argv.filter((arg) => arg !== "--callback")],
+        tuiOptions
+      )
+    );
+    await runWorkerMenu(invocation.viewFile);
+  } else if (role === "attach") {
     const [file, sessionId, leaseFile] = argv;
     if (!file || !sessionId) throw new Error("invalid_attachment_arguments");
     await waitFor(() => {
@@ -5953,7 +6493,14 @@ try {
         tuiOptions
       )
     );
-    if (invocation.action === "create" || invocation.action === "doctor")
+    if ([
+      "create",
+      "doctor",
+      "launch",
+      "plan",
+      "recovery",
+      "start-worker"
+    ].includes(invocation.action))
       throw new Error("unsupported_worker_operation");
     const result = role === "locked" ? await operate(
       invocation.action,
@@ -5972,7 +6519,8 @@ try {
     const file = argv[index + 1];
     if (index >= 0 && file) {
       try {
-        recordCallbackFailure(file, argv[0] ?? "callback", error);
+        const action = role === "worker-menu" ? role : argv[0] ?? "callback";
+        recordCallbackFailure(file, action, error);
         const { view } = readView(file);
         if (view.state === "open") new TmuxView(view, file).status(view);
       } catch {