@linzumi/cli 0.0.26-beta → 0.0.27-beta

package/README.md

@@ -22,15 +22,20 @@
 Copy this into your terminal:
 
 ```bash
-codex --ask-for-approval never --sandbox danger-full-access -- 'Get me up and running with Linzumi from https://linzumi.com/agents.md. Read it with curl.'
+codex -c sandbox_workspace_write.network_access=true --ask-for-approval never --sandbox danger-full-access -- 'Follow https://linzumi.com/agents.md to get me up and running. Read the instructions with curl.'
 ```
 
 That's the launch path: the first Codex is only the bootstrapper. It
 opens the agent instructions, confirms your email and workspace details,
 asks you for the emailed code when it arrives, creates `/tmp/hello_linzumi`,
-starts that hot-reload app on your computer, creates the shared support
-channel, starts a Linzumi Codex session in a work thread, and opens the
-browser editor pointed at the demo app.
+creates the shared support channel, starts the Linzumi Commander for that
+folder, asks the Commander to launch the inner Linzumi Codex session in a work
+thread, and opens the browser editor pointed at the demo app. The
+Commander-launched Codex session starts the hot-reload app and edits it.
+When you ask the bootstrapper to get you to "wow" or get you up and running,
+that means the complete first-run outcome: a running Linzumi workspace, browser
+VS Code editor, editable `/tmp/hello_linzumi` app on your computer, and a
+shareable Linzumi secure-tunnel preview URL for that app.
 
 Terms:
 
@@ -101,7 +106,7 @@ Here's what the next 30 seconds look like:
 1. Your browser opens to Linzumi.
 2. Sign in (or sign up — one click).
 3. Linzumi asks if it can connect to this computer. Click allow.
-4. Your laptop appears as a runner in your workspace, and
+4. Your laptop appears as a Commander in your workspace, and
    `~/code/my-app` is added to your trusted-paths list automatically.
 5. Type something in chat — *"Explain this project and tell me how
    to run it"* — and Linzumi Codex picks it up on your machine.
@@ -115,11 +120,13 @@ hosted at `https://linzumi.com/agents.md`; `https://linzumi.com/skills.md`
 stays available for compatibility. The bootstrap agent will confirm your
 email and workspace choice up front, ask for the emailed code after signup
 sends it, say hello to `@sean` in the shared support channel,
-generate `/tmp/hello_linzumi`, start its hot-reload Node server, start the
-Commander for that folder, start a Linzumi Codex session in a work thread, and
-open the browser editor. The Linzumi Codex session then adds confetti to the
-demo page while you watch. Workspace names are plain display names from 2 to
-100 characters; Linzumi generates the URL-safe workspace slug.
+generate `/tmp/hello_linzumi`, trust that folder in `~/.linzumi/config.json`,
+start the global Commander daemon, ask the Commander to launch a Linzumi Codex
+session in a new work thread, and open the browser editor. The
+Commander-launched Linzumi Codex session starts the
+hot-reload app and adds confetti to the demo page while you watch. Workspace
+names are plain display names from 2 to 100 characters; Linzumi generates the
+URL-safe workspace slug.
 
 Under the hood, the npm package exposes these commands for the bootstrap
 agent to run. They are not extra human setup steps after the one pasted
@@ -129,29 +136,27 @@ Codex command.
 npx -y @linzumi/cli@latest signup --email alice@example.com --workspace-name "Alice's Linzumi" --agent-name BuildBot
 npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
 npx -y @linzumi/cli@latest channel post <support_channel_id> "Hello @sean, starting this launch run."
-npx -y @linzumi/cli@latest thread new "Hello Linzumi confetti" --message "Preparing the Hello Linzumi demo. Next I will generate /tmp/hello_linzumi, start its hot-reload server bound to 0.0.0.0 on port 8787, and ask Linzumi Codex to add confetti when the page loads."
-commander_id="hello-linzumi-commander-${thread_id%%-*}"
 npx -y @linzumi/cli@latest init-hello-linzumi-demo-app --parent-dir /tmp --name hello_linzumi --host 0.0.0.0 --port 8787 --reset --json
 project_dir="$(cd /tmp/hello_linzumi && pwd -P)"
-(cd "$project_dir" && npm run dev > "$project_dir/dev.log" 2>&1 &)
-npx -y @linzumi/cli@latest commander "$project_dir" \
+commander_id="hello-linzumi-commander-$(uuidgen | tr '[:upper:]' '[:lower:]' | cut -c1-8)"
+npx -y @linzumi/cli@latest paths add "$project_dir"
+npx -y @linzumi/cli@latest commander daemon \
   --runner-id "$commander_id" \
-  --allowed-cwd "$project_dir" \
   --forward-port 8787 \
   --sandbox danger-full-access \
   --approval-policy never
+npx -y @linzumi/cli@latest commander wait --runner-id "$commander_id" --timeout-ms 30000
 ```
 
 The agent-owned Commander reads `~/.linzumi/agent-token.json`, uses the
-workspace/channel scope from the approval flow, trusts only the selected
-folder, marks that same folder trusted in Codex's normal project config so
-Codex does not stop for an interactive trust prompt, advertises the explicit
-preview port, and listens only to the approving human unless `--listen-user` is
-explicitly passed. Use a unique
-Commander id per launch thread; Linzumi stores trusted-folder config per
-Commander id, so reusing an old fixed id can pick up stale allowed-cwd config.
-The bootstrap agent waits for `Runner connected:` before starting Codex in the Linzumi
-thread.
+workspace/channel scope from the approval flow, reads trusted folders from
+`~/.linzumi/config.json`, marks approved project directories trusted in
+Codex's normal project config so Codex does not stop for an interactive trust
+prompt, advertises the explicit preview port, and listens only to the
+approving human unless `--listen-user` is explicitly passed. Use a unique
+Commander id per launch. `linzumi commander daemon` writes a status record and
+log under `~/.linzumi/commanders`, and `linzumi commander wait` returns only
+after the Commander is connected.
 
 By default, the Commander downloads the Linzumi-approved `code-server`
 runtime for your platform and verifies its checksum before enabling the
@@ -167,16 +172,21 @@ side; the bootstrap agent posts a hello there with the printed
 Keep demo work in task threads; use the support channel when signup, Commander,
 preview, or browser-editor setup gets stuck.
 
-Once the Commander is online, the bootstrap agent can ask Linzumi to start
-Codex and open the browser editor for the same thread and folder:
+Once the Commander is online, the bootstrap agent can ask Linzumi to create
+the work thread, have the Commander start Codex, and open the browser editor
+for the same thread and folder:
 
 ```bash
-npx -y @linzumi/cli@latest codex start <thread_id> \
+npx -y @linzumi/cli@latest codex start-new \
+  --title "Hello Linzumi confetti" \
   --runner "$commander_id" \
   --cwd "$project_dir" \
-  --work-description "Work only in the canonical Hello Linzumi project directory printed by pwd -P for /tmp/hello_linzumi. Add tasteful confetti when the Hello Linzumi page loads, keep the hot-reload app working on port 8787, and post the exact files changed."
+  --work-description "Start the Hello Linzumi hot-reload app on 0.0.0.0:8787, add tasteful confetti when the page loads, keep the preview working, and post the exact files changed." \
+  --developer-prompt "The Bootstrapper Codex generated the project and then handed off. You are the Commander-launched Linzumi Codex session. Start any dev server yourself as your descendant process, bind user-visible servers to 0.0.0.0, work only in the approved Hello Linzumi folder, and do not create a branch or PR for this demo." \
+  --idempotency-key "hello-linzumi-${commander_id}"
 
-npx -y @linzumi/cli@latest editor open <thread_id> \
+thread_id="<thread_id printed by codex start-new>"
+npx -y @linzumi/cli@latest editor open "$thread_id" \
   --runner "$commander_id" \
   --cwd "$project_dir"
 ```
@@ -189,10 +199,10 @@ forwarded preview readiness, and the first visible Codex edit.
 
 You now have:
 
-- **A runner.** Your laptop, listed in the workspace, advertising
+- **A Commander.** Your laptop, listed in the workspace, advertising
   `/tmp/hello_linzumi` and the explicit preview port.
 - **A workspace** you can invite teammates into. They open the same
-  browser app, see the same threads, and can start their own runners
+  browser app, see the same threads, and can start their own Commanders
   on their own machines.
 - **A private Linzumi support channel.** We can see this channel; we
   **cannot** see your repo contents, your tokens, your Codex
@@ -219,20 +229,20 @@ This is what makes Linzumi different from running an AI coding agent
 alone in a terminal.
 
 - **Your laptops are always in sight.** Every machine you've run
-  `linzumi start` on shows up as a runner. From any channel, you can
-  see how many of your runners are reachable right now and which ones
+  `linzumi start` on shows up as a Commander. From any channel, you can
+  see how many of your Commanders are reachable right now and which ones
   are listening on that channel.
 
-- **Put Codex on the job from the channel.** Pick an available runner
+- **Put Codex on the job from the channel.** Pick an available Commander
   and a trusted folder from the channel menu, type what Codex should
-  work on, hit start. Linzumi attaches a fresh Codex to that runner
+  work on, hit start. Linzumi asks that Commander to attach a fresh Codex
   with the folder and settings you picked.
 
 - **One Codex per thread.** Once a Linzumi Codex session picks up a
   thread, it owns the thread — no second Codex can step in and trample
   the work. The lock holds for the life of the thread.
 
-- **Browse what your team's been up to.** Open the runners dropdown
+- **Browse what your team's been up to.** Open the Commanders dropdown
   to see, across every device, the most recently active threads with
   short AI-written summaries. Jump in and keep working.
 
@@ -255,7 +265,7 @@ linzumi paths remove ~/code/my-app
 on first use. `linzumi connect` uses the list as-is — or pass
 `--allowed-cwd <paths>` for a one-off comma-separated override.
 
-There's no credential escalation: Linzumi only asks the runner to start
+There's no credential escalation: Linzumi only asks the Commander to start
 Codex or the editor inside trusted folders. Those processes still run
 with your shell's operating-system privileges, so choose trusted folders
 intentionally. Every action is auditable from the thread.
@@ -279,7 +289,7 @@ intentionally. Every action is auditable from the thread.
 ## Pinning a version
 
 ```bash
-npm install -g @linzumi/cli@0.0.26-beta
+npm install -g @linzumi/cli@0.0.27-beta
 linzumi --version
 ```
 
@@ -307,15 +317,15 @@ linzumi connect \
 --codex-bin <path>          Codex executable, default `codex`
 --model <name>              Model requested for Codex sessions and labelled in Linzumi
 --reasoning-effort <value>  Reasoning effort requested for Codex sessions and labelled in Linzumi
---fast                      Advertise this runner as low-latency in the workspace
+--fast                      Advertise this Commander as low-latency in the workspace
 --forward-port <ports>      Comma-separated local TCP ports Linzumi may share as authenticated previews
 --allowed-cwd <paths>       Override ~/.linzumi/config.json with comma-separated trusted roots
---log-file <path>           JSONL runner event log
+--log-file <path>           JSONL Commander event log
 ```
 
 `--runner-id`, `--auth-file`, `--code-server-bin`, `--codex-url`,
 `--launch-tui`, `--listen-user`, `--sandbox`, `--approval-policy`,
 `--stream-flush-ms`, and `--token` are also accepted; `linzumi
 --help` shows them all with brief descriptions. They exist for
-multi-runner orchestration, custom Codex deployments, and CI
+multi-Commander orchestration, custom Codex deployments, and CI
 scenarios — not for everyday use.

package/dist/index.js

@@ -1,9 +1,9 @@
 // src/index.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { existsSync as existsSync9, readFileSync as readFileSync8, realpathSync as realpathSync5 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
-import { resolve as resolve7 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { existsSync as existsSync10, readFileSync as readFileSync9, realpathSync as realpathSync5 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
+import { resolve as resolve8 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/runner.ts
 import { spawn as spawn6 } from "node:child_process";
@@ -6781,7 +6781,7 @@ async function openLocalCodexRunner(options, log, cleanup, close) {
       if (handled !== undefined) {
         return handled;
       }
-      return applyControl(codex, instanceId, options, allowedCwds.value, control);
+      return applyControl(codex, kandan, topic, instanceId, options, allowedCwds.value, control);
     }).then((response) => {
       return kandan.push(topic, "codex_response", response);
     }).catch((error) => {
@@ -6916,7 +6916,7 @@ async function prepareCodexThreadForTuiResume(codex, codexThreadId) {
     throw new Error(`failed to verify Codex TUI resume: ${verified.error.message}`);
   }
 }
-async function applyControl(codex, instanceId, options, allowedCwds, control) {
+async function applyControl(codex, kandan, topic, instanceId, options, allowedCwds, control) {
   switch (control.type) {
     case "start_instance": {
       const cwd = resolveAllowedCwd(control.cwd, allowedCwds);
@@ -6931,10 +6931,15 @@ async function applyControl(codex, instanceId, options, allowedCwds, control) {
       if (options.codexUrl === undefined) {
         ensureCodexProjectTrusted(cwd.cwd);
       }
+      const developerPrompt = normalizedWorkDescription(control.developerPrompt);
       const response = await codex.request("thread/start", {
         cwd: cwd.cwd,
         serviceName: "kandan-local-runner",
         personality: "pragmatic",
+        developerInstructions: commanderDeveloperInstructions({
+          cwd: cwd.cwd,
+          developerPrompt
+        }),
         ...control.model === undefined ? {} : { model: control.model },
         ...control.reasoningEffort === undefined ? {} : { reasoningEffort: control.reasoningEffort },
         ...control.approvalPolicy === undefined ? {} : { approvalPolicy: control.approvalPolicy },
@@ -6943,6 +6948,9 @@ async function applyControl(codex, instanceId, options, allowedCwds, control) {
       });
       const codexThreadId = extractStartedThreadId(response);
       const workDescription = normalizedWorkDescription(control.workDescription);
+      if (codexThreadId !== undefined && developerPrompt !== undefined) {
+        await postVisibleDeveloperPrompt(kandan, topic, control, developerPrompt);
+      }
       if (codexThreadId !== undefined && workDescription !== undefined) {
         await codex.request("turn/start", {
           threadId: codexThreadId,
@@ -7015,6 +7023,83 @@ async function applyControl(codex, instanceId, options, allowedCwds, control) {
       return { instanceId, controlType: control.type, skipped: true };
   }
 }
+function commanderDeveloperInstructions(args) {
+  const customPrompt = args.developerPrompt === undefined ? "" : `
+<invoker_developer_prompt>
+${args.developerPrompt}
+</invoker_developer_prompt>
+`;
+  return `<context>
+You are a Linzumi Codex session launched by the Linzumi Commander.
+The Commander is the local bridge process that connects this computer to the
+user's Linzumi workspace, secure preview tunnel, browser VS Code editor, and
+thread transcript. Your work and progress are relayed into that Linzumi thread.
+</context>
+
+<term_definitions>
+Bootstrapper Codex: The outer setup agent that claimed/signup, generated the
+demo folder when applicable, and asked Linzumi to start this session. It does
+not own implementation work.
+Linzumi Commander: The local long-running process that launched this Codex
+session, enforces the trusted folder, and forwards descendant preview ports to
+Linzumi.
+Linzumi Codex session: You, the inner Codex process that performs the actual
+work in the approved project folder.
+Approved project folder: ${args.cwd}
+</term_definitions>
+
+<task_instructions>
+Work only in the approved project folder unless the human explicitly asks for
+something else in the Linzumi thread. Start, inspect, and modify the local app
+from that folder. Report concise progress and exact blockers in the thread.
+</task_instructions>
+
+<rules>
+You MUST treat the Linzumi thread as the source of truth for user-facing
+progress.
+You MUST keep user-visible preview servers bound to 0.0.0.0, not 127.0.0.1 or
+localhost, so the Linzumi secure tunnel can reach them.
+You MUST keep any preview or dev server as your descendant process so the
+Commander can discover and forward it.
+You MUST NOT ask the Bootstrapper Codex to do implementation work.
+You MUST NOT inspect unrelated repositories or folders.
+You MUST report the exact blocker if a command, preview, editor, or tunnel step
+fails.
+</rules>
+
+<examples>
+GOOD preview command: npm run dev -- --host 0.0.0.0 --port 8787
+BAD preview command: npm run dev -- --host 127.0.0.1
+</examples>
+${customPrompt}
+<task_reminder>
+You are the Commander-launched Linzumi Codex session. Do the implementation
+work in the approved project folder, keep preview servers reachable through the
+secure tunnel, and keep the Linzumi thread truthful.
+</task_reminder>`;
+}
+async function postVisibleDeveloperPrompt(kandan, topic, control, developerPrompt) {
+  const workspace = normalizedWorkDescription(control.workspace);
+  const channel = normalizedWorkDescription(control.channel);
+  const threadId = normalizedWorkDescription(control.threadId);
+  if (workspace === undefined || channel === undefined || threadId === undefined) {
+    return;
+  }
+  await kandan.push(topic, "session:post_thread_message", {
+    workspace,
+    channel,
+    thread_id: threadId,
+    body: `Starting a new Codex thread with instructions:
+
+${developerPrompt}`,
+    payload: {
+      local_codex_runner: {
+        event_type: "codex_start_instructions"
+      }
+    },
+    client_message_id: `codex-start-instructions-${threadId}`
+  });
+}
 async function startOwnedCodexAppServer(options) {
   ensureCodexProjectTrusted(options.cwd);
   return await startCodexAppServer(options.codexBin, options.cwd, {
@@ -7325,6 +7410,9 @@ async function runAgentCliCommand(args, deps = {
     case "codexStart":
       await runCodexStart(command, deps);
       return;
+    case "codexStartNew":
+      await runCodexStartNew(command, deps);
+      return;
     case "editorOpen":
       await runEditorOpen(command, deps);
       return;
@@ -7460,10 +7548,31 @@ function parseAgentCommand(args) {
     }
     case "codex": {
       const [subcommand, ...subcommandArgs] = rest;
-      if (subcommand !== "start") {
-        throw new Error("linzumi codex supports: start");
+      if (subcommand !== "start" && subcommand !== "start-new") {
+        throw new Error("linzumi codex supports: start, start-new");
       }
       const parsed = parseAgentArgs(subcommandArgs);
+      if (subcommand === "start-new") {
+        if (parsed.positionals.length > 0) {
+          throw new Error("linzumi codex start-new does not accept positional arguments");
+        }
+        return {
+          kind: "codexStartNew",
+          apiUrl: agentApiUrl(parsed.flags),
+          title: requiredFlag(parsed.flags, "title"),
+          runnerId: requiredFlag(parsed.flags, "runner"),
+          cwd: requiredFlag(parsed.flags, "cwd"),
+          workDescription: requiredFlag(parsed.flags, "work-description"),
+          developerPrompt: optionalFlag(parsed.flags, "developer-prompt"),
+          idempotencyKey: optionalFlag(parsed.flags, "idempotency-key"),
+          model: optionalFlag(parsed.flags, "model"),
+          reasoningEffort: optionalFlag(parsed.flags, "reasoning-effort"),
+          approvalPolicy: optionalFlag(parsed.flags, "approval-policy"),
+          sandbox: optionalFlag(parsed.flags, "sandbox"),
+          fast: parsed.flags.get("fast") === "true",
+          tokenFile: agentTokenFile(parsed.flags)
+        };
+      }
       const [threadId, ...extra] = parsed.positionals;
       if (threadId === undefined || threadId.trim() === "") {
         throw new Error("missing thread id");
@@ -7478,6 +7587,7 @@ function parseAgentCommand(args) {
         runnerId: requiredFlag(parsed.flags, "runner"),
         cwd: requiredFlag(parsed.flags, "cwd"),
         workDescription: requiredFlag(parsed.flags, "work-description"),
+        developerPrompt: optionalFlag(parsed.flags, "developer-prompt"),
         model: optionalFlag(parsed.flags, "model"),
         reasoningEffort: optionalFlag(parsed.flags, "reasoning-effort"),
         approvalPolicy: optionalFlag(parsed.flags, "approval-policy"),
@@ -7641,6 +7751,7 @@ async function runCodexStart(command, deps) {
   putOptional(body, "reasoning_effort", command.reasoningEffort);
   putOptional(body, "approval_policy", command.approvalPolicy);
   putOptional(body, "sandbox", command.sandbox);
+  putOptional(body, "developer_prompt", command.developerPrompt);
   if (command.fast) {
     body.fast = true;
   }
@@ -7650,6 +7761,33 @@ async function runCodexStart(command, deps) {
   deps.stdout.write(`runner_id: ${requiredString(response, "runner_id")}
 `);
 }
+async function runCodexStartNew(command, deps) {
+  const tokenFile = readTokenFile(command.tokenFile, deps.readTextFile);
+  const body = {
+    title: command.title,
+    runner_id: command.runnerId,
+    cwd: command.cwd,
+    work_description: command.workDescription
+  };
+  putOptional(body, "developer_prompt", command.developerPrompt);
+  putOptional(body, "idempotency_key", command.idempotencyKey);
+  putOptional(body, "model", command.model);
+  putOptional(body, "reasoning_effort", command.reasoningEffort);
+  putOptional(body, "approval_policy", command.approvalPolicy);
+  putOptional(body, "sandbox", command.sandbox);
+  if (command.fast) {
+    body.fast = true;
+  }
+  const response = await postJson(command.apiUrl, "/agent/codex/start", body, tokenFile.agentToken, deps.fetchImpl);
+  deps.stdout.write(`thread_id: ${requiredString(response, "thread_id")}
+`);
+  deps.stdout.write(`thread_url: ${requiredString(response, "thread_url")}
+`);
+  deps.stdout.write(`codex_status: ${requiredString(response, "status")}
+`);
+  deps.stdout.write(`runner_id: ${requiredString(response, "runner_id")}
+`);
+}
 async function runEditorOpen(command, deps) {
   const tokenFile = readTokenFile(command.tokenFile, deps.readTextFile);
   const response = await postJson(command.apiUrl, `/agent/threads/${encodeURIComponent(command.threadId)}/editor/open`, {
@@ -7831,7 +7969,8 @@ Usage:
   linzumi post <thread_id> <message> [--kind progress|question]
   linzumi inbox <thread_id> --since-last
   linzumi done <thread_id> --message <message>
-  linzumi codex start <thread_id> --runner <runner_id> --cwd <path> --work-description <text>
+  linzumi codex start <thread_id> --runner <runner_id> --cwd <path> --work-description <text> [--developer-prompt <text>]
+  linzumi codex start-new --title <title> --runner <runner_id> --cwd <path> --work-description <text> [--developer-prompt <text>] [--idempotency-key <key>]
   linzumi editor open <thread_id> --runner <runner_id> --cwd <path>
 
 Options:
@@ -8407,6 +8546,232 @@ To kick the agent off:
 3. Paste into the thread. Codex will pick it up and start editing this folder.
 `;
 
+// src/commanderDaemon.ts
+import {
+  existsSync as existsSync9,
+  closeSync,
+  mkdirSync as mkdirSync9,
+  openSync as openSync2,
+  readFileSync as readFileSync8,
+  watch,
+  writeFileSync as writeFileSync8
+} from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { dirname as dirname8, join as join9, resolve as resolve7 } from "node:path";
+import { execFileSync, spawn as spawn7 } from "node:child_process";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var connectedMarker = "Runner connected:";
+function commanderStatusDir() {
+  return join9(homedir7(), ".linzumi", "commanders");
+}
+function commanderStatusFile(runnerId, statusDir = commanderStatusDir()) {
+  return join9(statusDir, `${safeRunnerId(runnerId)}.json`);
+}
+function defaultCommanderLogFile(runnerId, statusDir = commanderStatusDir()) {
+  return join9(statusDir, `${safeRunnerId(runnerId)}.log`);
+}
+function startCommanderDaemon(options) {
+  const statusDir = options.statusDir ?? commanderStatusDir();
+  const statusFile = commanderStatusFile(options.runnerId, statusDir);
+  const logFile = resolve7(options.logFile ?? defaultCommanderLogFile(options.runnerId, statusDir));
+  const entrypoint = options.entrypoint ?? currentEntrypoint();
+  const nodeBin = options.nodeBin ?? process.execPath;
+  const command = [
+    entrypoint,
+    "commander",
+    ...options.cwd === undefined ? [] : [options.cwd],
+    ...options.args,
+    "--runner-id",
+    options.runnerId,
+    "--log-file",
+    logFile
+  ];
+  mkdirSync9(statusDir, { recursive: true });
+  mkdirSync9(dirname8(logFile), { recursive: true });
+  const out = openSync2(logFile, "a");
+  const err = openSync2(logFile, "a");
+  const child = (options.spawnImpl ?? spawn7)(nodeBin, command, {
+    detached: true,
+    stdio: ["ignore", out, err],
+    env: process.env
+  });
+  closeSync(out);
+  closeSync(err);
+  child.unref();
+  if (child.pid === undefined) {
+    throw new Error("commander daemon did not report a pid");
+  }
+  const processIdentity = readProcessIdentity(child.pid);
+  const record = {
+    runnerId: options.runnerId,
+    pid: child.pid,
+    ...processIdentity?.startedAt === undefined ? {} : { processStartedAt: processIdentity.startedAt },
+    cwd: process.cwd(),
+    ...options.cwd === undefined ? {} : { launchFolder: options.cwd },
+    logFile,
+    startedAt: new Date().toISOString(),
+    command: [nodeBin, ...command]
+  };
+  writeFileSync8(statusFile, `${JSON.stringify(record, null, 2)}
+`);
+  return record;
+}
+function commanderDaemonStatus(runnerId, statusDir = commanderStatusDir(), processIdentityReader = readProcessIdentity) {
+  const statusFile = commanderStatusFile(runnerId, statusDir);
+  if (!existsSync9(statusFile)) {
+    return { status: "missing", runnerId, statusFile };
+  }
+  const record = parseRecord(readFileSync8(statusFile, "utf8"));
+  return processIsRunning(record.pid) && processMatchesRecord(record, processIdentityReader) ? { status: "running", record } : { status: "stopped", record };
+}
+async function waitForCommanderDaemon(options) {
+  const now = options.now ?? (() => Date.now());
+  const readTextFile = options.readTextFile ?? ((path) => existsSync9(path) ? readFileSync8(path, "utf8") : undefined);
+  const statusImpl = options.statusImpl ?? commanderDaemonStatus;
+  const deadline = now() + options.timeoutMs;
+  while (now() <= deadline) {
+    const status = statusImpl(options.runnerId, options.statusDir);
+    switch (status.status) {
+      case "missing":
+        return { ok: false, reason: "missing" };
+      case "stopped":
+        return { ok: false, reason: "stopped" };
+      case "running": {
+        const log = readTextFile(status.record.logFile);
+        if (log === undefined) {
+          return { ok: false, reason: "timeout" };
+        }
+        if (log.includes(connectedMarker)) {
+          return { ok: true, record: status.record };
+        }
+        await waitForFileChangeOrTimeout(status.record.logFile, deadline, now, () => {
+          const updatedLog = readTextFile(status.record.logFile);
+          return updatedLog !== undefined && updatedLog.includes(connectedMarker);
+        });
+      }
+    }
+  }
+  return { ok: false, reason: "timeout" };
+}
+function stopCommanderDaemon(runnerId, statusDir = commanderStatusDir()) {
+  const status = commanderDaemonStatus(runnerId, statusDir);
+  if (status.status === "running") {
+    process.kill(status.record.pid, "SIGINT");
+  }
+  return status;
+}
+function currentEntrypoint() {
+  const scriptPath = process.argv[1];
+  if (scriptPath !== undefined) {
+    return scriptPath;
+  }
+  return fileURLToPath2(import.meta.url);
+}
+function parseRecord(content) {
+  const parsed = JSON.parse(content);
+  const record = typeof parsed === "object" && parsed !== null ? parsed : {};
+  const pid = typeof record.pid === "number" ? record.pid : undefined;
+  const runnerId = recordString(record.runnerId);
+  const cwd = recordString(record.cwd);
+  const launchFolder = recordString(record.launchFolder);
+  const logFile = recordString(record.logFile);
+  const startedAt = recordString(record.startedAt);
+  const processStartedAt = recordString(record.processStartedAt);
+  const commandValue = record.command;
+  const command = Array.isArray(commandValue) ? commandValue.filter((value) => typeof value === "string") : [];
+  if (pid === undefined || runnerId === undefined || cwd === undefined || logFile === undefined || startedAt === undefined) {
+    throw new Error("commander daemon status file is invalid");
+  }
+  return {
+    pid,
+    ...processStartedAt === undefined ? {} : { processStartedAt },
+    runnerId,
+    cwd,
+    ...launchFolder === undefined ? {} : { launchFolder },
+    logFile,
+    startedAt,
+    command
+  };
+}
+function recordString(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function processIsRunning(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+function processMatchesRecord(record, processIdentityReader) {
+  const identity = processIdentityReader(record.pid);
+  const commandLine = identity?.command;
+  if (commandLine === undefined || commandLine.trim() === "") {
+    return false;
+  }
+  const commandMatches = record.command.every((part) => commandLine.includes(part));
+  if (!commandMatches) {
+    return false;
+  }
+  return record.processStartedAt === undefined || identity?.startedAt === record.processStartedAt;
+}
+function readProcessIdentity(pid) {
+  try {
+    const output = execFileSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "command="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (output === "") {
+      return;
+    }
+    const match = output.match(/^(\S+\s+\S+\s+\d+\s+\d{2}:\d{2}:\d{2}\s+\d{4})\s+(.+)$/);
+    if (match === null) {
+      return { command: output };
+    }
+    return { startedAt: match[1], command: match[2] };
+  } catch (_error) {
+    return;
+  }
+}
+function safeRunnerId(runnerId) {
+  const safe = runnerId.replace(/[^a-zA-Z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
+  if (safe === "") {
+    throw new Error("runner id must contain a filesystem-safe character");
+  }
+  return safe;
+}
+async function waitForFileChangeOrTimeout(path, deadline, now, ready2 = () => false) {
+  const remaining = Math.max(0, deadline - now());
+  await new Promise((resolve8) => {
+    let resolved = false;
+    let watcher;
+    const finish = () => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      watcher?.close();
+      clearTimeout(timer);
+      resolve8();
+    };
+    const timer = setTimeout(finish, remaining);
+    try {
+      watcher = watch(path, finish);
+      watcher.on("error", finish);
+      if (ready2()) {
+        finish();
+      }
+    } catch (_error) {
+      if (ready2()) {
+        finish();
+        return;
+      }
+      finish();
+    }
+  });
+}
+
 // src/index.ts
 var flagDefinitions = new Map([
   ["version", { kind: "boolean" }],
@@ -8431,6 +8796,8 @@ var flagDefinitions = new Map([
   ["code-server-bin", { kind: "value" }],
   ["fast", { kind: "boolean" }],
   ["log-file", { kind: "value" }],
+  ["status-dir", { kind: "value" }],
+  ["timeout-ms", { kind: "value" }],
   ["auth-file", { kind: "value" }],
   ["agent-token-file", { kind: "value" }],
   ["oauth-callback-host", { kind: "value" }],
@@ -8460,7 +8827,7 @@ function isMainModule() {
   if (scriptPath === undefined) {
     return false;
   }
-  return fileURLToPath2(import.meta.url) === resolve7(scriptPath);
+  return fileURLToPath3(import.meta.url) === resolve8(scriptPath);
 }
 async function main(args) {
   const parsed = parseCommand(args);
@@ -8469,7 +8836,7 @@ async function main(args) {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write(`linzumi 0.0.26-beta
+      process.stdout.write(`linzumi 0.0.27-beta
 `);
       return;
     case "auth":
@@ -8484,6 +8851,9 @@ async function main(args) {
     case "agent":
       await runAgentCliCommand(parsed.args);
       return;
+    case "commanderDaemon":
+      await runCommanderDaemonCommand(parsed.args);
+      return;
     case "agentRunner": {
       const options = await parseAgentRunnerArgs(parsed.args);
       await runLocalCodexRunner(options);
@@ -8524,8 +8894,17 @@ function parseCommand(args) {
     case "agent":
       return rest[0] === "runner" ? { command: "agentRunner", args: rest.slice(1) } : { command: "agent", args: rest };
     case "agent-runner":
-    case "commander":
       return { command: "agentRunner", args: rest };
+    case "commander":
+      return ["daemon", "status", "wait", "stop"].includes(rest[0] ?? "") ? { command: "commanderDaemon", args: rest } : { command: "agentRunner", args: rest };
+    case "commander-daemon":
+      return { command: "commanderDaemon", args: ["daemon", ...rest] };
+    case "commander-status":
+      return { command: "commanderDaemon", args: ["status", ...rest] };
+    case "commander-wait":
+      return { command: "commanderDaemon", args: ["wait", ...rest] };
+    case "commander-stop":
+      return { command: "commanderDaemon", args: ["stop", ...rest] };
     case "signup":
     case "claim":
     case "thread":
@@ -8604,7 +8983,7 @@ function runPathsCommand(args) {
       if (pathValue === undefined || pathValue.trim() === "") {
         throw new Error("missing path for linzumi paths add");
       }
-      const trustedPath = realpathSync5(resolve7(expandUserPath(pathValue)));
+      const trustedPath = realpathSync5(resolve8(expandUserPath(pathValue)));
       addAllowedCwd(pathValue);
       process.stdout.write(`Trusted ${trustedPath}
 `);
@@ -8623,6 +9002,79 @@ function runPathsCommand(args) {
       throw new Error(`invalid paths command: ${subcommand}`);
   }
 }
+async function runCommanderDaemonCommand(args) {
+  const [subcommand, ...rest] = args;
+  switch (subcommand) {
+    case "daemon": {
+      const { cwdArg, flagArgs } = splitStartArgs(rest);
+      const values = strictFlagValues(flagArgs);
+      if (values.get("help") === true) {
+        process.stdout.write(commanderDaemonHelpText());
+        return;
+      }
+      const runnerId = required(values, "runner-id");
+      const cwd = cwdArg === undefined || cwdArg.trim() === "" ? undefined : resolveUserPath(cwdArg);
+      const record = startCommanderDaemon({
+        runnerId,
+        cwd,
+        args: stripDaemonSupervisorFlags(flagArgs),
+        logFile: stringValue3(values, "log-file"),
+        statusDir: stringValue3(values, "status-dir")
+      });
+      process.stdout.write(`commander_status: daemon_started
+`);
+      process.stdout.write(`runner_id: ${record.runnerId}
+`);
+      process.stdout.write(`pid: ${record.pid}
+`);
+      process.stdout.write(`log_file: ${record.logFile}
+`);
+      if (record.launchFolder !== undefined) {
+        process.stdout.write(`launch_folder: ${record.launchFolder}
+`);
+      }
+      return;
+    }
+    case "status": {
+      const values = strictFlagValues(rest);
+      const runnerId = required(values, "runner-id");
+      const status = commanderDaemonStatus(runnerId, stringValue3(values, "status-dir"));
+      process.stdout.write(`${JSON.stringify(status)}
+`);
+      return;
+    }
+    case "wait": {
+      const values = strictFlagValues(rest);
+      const runnerId = required(values, "runner-id");
+      const timeoutMs = positiveIntegerValue(values, "timeout-ms") ?? 30000;
+      const result = await waitForCommanderDaemon({
+        runnerId,
+        timeoutMs,
+        statusDir: stringValue3(values, "status-dir")
+      });
+      if (result.ok) {
+        process.stdout.write(`commander_status: connected
+`);
+        process.stdout.write(`runner_id: ${result.record.runnerId}
+`);
+        process.stdout.write(`pid: ${result.record.pid}
+`);
+        return;
+      }
+      throw new Error(`commander did not connect: ${result.reason}`);
+    }
+    case "stop": {
+      const values = strictFlagValues(rest);
+      const runnerId = required(values, "runner-id");
+      const status = stopCommanderDaemon(runnerId, stringValue3(values, "status-dir"));
+      process.stdout.write(`${JSON.stringify(status)}
+`);
+      return;
+    }
+    default:
+      process.stdout.write(commanderDaemonHelpText());
+  }
+}
 async function runAuthCommand(args) {
   const values = strictFlagValues(args);
   if (values.get("help") === true) {
@@ -8766,8 +9218,9 @@ async function parseAgentRunnerArgs(args, deps = {
   const channelSlug = requiredStoredAgentChannel(tokenFile.channelId);
   const listenUser = stringValue3(values, "listen-user") ?? requiredStoredOwnerUsername(tokenFile.ownerUsername);
   const kandanUrl = stringValue3(values, "kandan-url") ?? agentApiUrlToKandanUrl(tokenFile.apiUrl);
-  const requestedCwd = resolveUserPath(cwdArg ?? stringValue3(values, "cwd") ?? process.cwd());
-  const allowedCwds = values.has("allowed-cwd") ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue3(values, "allowed-cwd"))) : assertConfiguredAllowedCwds([requestedCwd]);
+  const requestedCwdValue = cwdArg ?? stringValue3(values, "cwd");
+  const requestedCwd = resolveUserPath(requestedCwdValue ?? process.cwd());
+  const allowedCwds = values.has("allowed-cwd") ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue3(values, "allowed-cwd"))) : requestedCwdValue === undefined ? readConfiguredAllowedCwds() : assertConfiguredAllowedCwds([requestedCwd]);
   const cwd = allowedCwds[0] ?? requestedCwd;
   const codexBin = stringValue3(values, "codex-bin") ?? "codex";
   const customCodeServerBin = stringValue3(values, "code-server-bin");
@@ -8820,7 +9273,7 @@ async function parseAgentRunnerArgs(args, deps = {
   };
 }
 function readAgentTokenTextFile(path) {
-  return existsSync9(path) ? readFileSync8(path, "utf8") : undefined;
+  return existsSync10(path) ? readFileSync9(path, "utf8") : undefined;
 }
 function rejectAgentRunnerTargetingFlags(values) {
   const unsupportedFlags = ["workspace", "channel", "token", "auth-file", "oauth-callback-host"].filter((flag) => values.has(flag));
@@ -8890,7 +9343,7 @@ async function parseRunnerArgs(args, deps = {
     process.exit(0);
   }
   if (values.get("version") === true) {
-    process.stdout.write(`linzumi 0.0.26-beta
+    process.stdout.write(`linzumi 0.0.27-beta
 `);
     process.exit(0);
   }
@@ -9001,6 +9454,32 @@ function splitStartArgs(args) {
   }
   return { cwdArg, flagArgs };
 }
+function stripDaemonSupervisorFlags(args) {
+  const stripped = [];
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === undefined) {
+      continue;
+    }
+    const key = arg.startsWith("--") ? arg.slice(2) : undefined;
+    const definition = key === undefined ? undefined : flagDefinitions.get(key);
+    if (key === "runner-id" || key === "log-file" || key === "status-dir") {
+      if (definition?.kind === "value") {
+        index += 1;
+      }
+      continue;
+    }
+    stripped.push(arg);
+    if (definition?.kind === "value") {
+      const next = args[index + 1];
+      if (next !== undefined) {
+        stripped.push(next);
+        index += 1;
+      }
+    }
+  }
+  return stripped;
+}
 function rejectStartTargetingFlags(values) {
   const unsupportedFlags = ["workspace", "channel"].filter((flag) => values.has(flag));
   if (unsupportedFlags.length > 0) {
@@ -9009,12 +9488,12 @@ function rejectStartTargetingFlags(values) {
 }
 function resolveUserPath(pathValue) {
   if (pathValue === "~") {
-    return homedir7();
+    return homedir8();
   }
   if (pathValue.startsWith("~/")) {
-    return resolve7(homedir7(), pathValue.slice(2));
+    return resolve8(homedir8(), pathValue.slice(2));
   }
-  return resolve7(pathValue);
+  return resolve8(pathValue);
 }
 function parseChannelSession(values, token, target) {
   if (target === undefined) {
@@ -9112,6 +9591,9 @@ Usage:
   linzumi inbox <thread_id> --since-last
   linzumi done <thread_id> --message <message>
   linzumi init-hello-linzumi-demo-app
+  linzumi codex start-new --title <title> --runner <runner_id> --cwd <path> --work-description <text>
+  linzumi commander daemon --runner-id <id>
+  linzumi commander wait --runner-id <id>
   linzumi commander <folder> [options]
   linzumi start <folder> [options]
   linzumi paths list|add|remove [path]
@@ -9154,7 +9636,8 @@ Examples:
     linzumi post thr_abc123 "PR is open"
     linzumi done thr_abc123 --message "Done: https://github.com/example/repo/pull/1"
     linzumi init-hello-linzumi-demo-app
-    linzumi commander ~/code/my-app --runner-id launch-commander
+    linzumi paths add ~/code/my-app
+    linzumi commander daemon --runner-id launch-commander
     linzumi start ~/
     linzumi start ~/code/my-app
     linzumi connect --workspace <your-workspace> --channel <your-channel> --launch-tui
@@ -9201,6 +9684,35 @@ Options:
   --json               Print machine-readable project details.
 `;
 }
+function commanderDaemonHelpText() {
+  return `Linzumi Commander daemon
+
+Usage:
+  linzumi commander daemon --runner-id <id> [options]
+  linzumi commander daemon <folder> --runner-id <id> [options]
+  linzumi commander status --runner-id <id>
+  linzumi commander wait --runner-id <id> [--timeout-ms <ms>]
+  linzumi commander stop --runner-id <id>
+
+What it does:
+  Starts the workspace Commander as a detached process, writes a status file,
+  and gives the Bootstrapper Codex explicit status and readiness commands. With
+  no folder argument, the Commander reads trusted folders from
+  ~/.linzumi/config.json so the Linzumi UI can launch Codex sessions in any
+  configured folder.
+
+Options:
+  --runner-id <id>            Stable Commander id, required
+  --status-dir <path>         Status directory, default ~/.linzumi/commanders
+  --log-file <path>           Commander log path, default in the status dir
+  --timeout-ms <ms>           Wait timeout, default 30000
+
+All normal Commander options such as --agent-token-file, --allowed-cwd,
+--forward-port, --sandbox, --approval-policy, --codex-bin, and
+--code-server-bin can be passed to the daemon command. Passing --allowed-cwd is
+an explicit override; otherwise the global daemon uses ~/.linzumi/config.json.
+`;
+}
 function pathsHelpText() {
   return `Linzumi trusted paths
 
@@ -9250,13 +9762,19 @@ function agentRunnerHelpText() {
 
 Usage:
   linzumi commander <folder> [options]
+  linzumi commander daemon [options]
+  linzumi commander daemon <folder> [options]
+  linzumi commander status --runner-id <id>
+  linzumi commander wait --runner-id <id>
+  linzumi commander stop --runner-id <id>
   linzumi agent runner <folder> [options]
 
 What it does:
   Starts this computer as the claimed agent's scoped Linzumi Commander. The command
-  reads ~/.linzumi/agent-token.json, uses its workspace/channel scope, trusts
-  only the selected folder by default, and listens only to the owning human
-  recorded during claim unless --listen-user is passed.
+  reads ~/.linzumi/agent-token.json, uses its workspace/channel scope, reads
+  trusted folders from ~/.linzumi/config.json when no folder is passed, and
+  listens only to the owning human recorded during claim unless --listen-user is
+  passed.
 
 Options:
   --agent-token-file <path>   Agent token cache, default ~/.linzumi/agent-token.json
@@ -9270,11 +9788,12 @@ Options:
   --sandbox <value>           Sandbox metadata shown in Kandan
   --approval-policy <value>   Approval-policy metadata shown in Kandan
   --forward-port <ports>      Comma-separated local TCP ports Kandan may expose as previews
-  --allowed-cwd <paths>       Override the selected folder with comma-separated trusted roots
+  --allowed-cwd <paths>       Override ~/.linzumi/config.json or selected folder with comma-separated trusted roots
   --fast                      Mark this Commander as low-latency/fast in Linzumi
 
 Examples:
-  linzumi commander "$PWD" --runner-id hello-world-commander
+  linzumi paths add "$PWD"
+  linzumi commander daemon --runner-id hello-world-commander
   linzumi commander ~/code/my-app --kandan-url ws://127.0.0.1:4162 --runner-id local-qa-commander
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.26-beta",
+  "version": "0.0.27-beta",
   "description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {