@linzumi/cli 0.0.23-beta → 0.0.24-beta

package/README.md

@@ -32,8 +32,20 @@ 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.
 
+Terms:
+
+- **Bootstrapper Codex**: the outer Codex started by the pasted command. It
+  sets up Linzumi and local processes, but does not edit the demo app.
+- **Linzumi Commander**: the long-running local bridge started with
+  `linzumi commander`; it owns the secure tunnel, trusted folder, browser
+  editor, and inner Codex launch.
+- **Linzumi Codex session**: the inner agent running inside the Linzumi thread;
+  it edits `/tmp/hello_linzumi` and posts progress.
+- **Human**: the workspace owner who opens the one-time login link and watches
+  the work in `#general` and `#linzumi-support`.
+
 The snippet uses automatic command approval and full local process access
-because the bootstrapper must start a real runner and browser editor on this
+because the bootstrapper must start a real Linzumi Commander and browser editor on this
 computer. It is intentionally not the dangerous sandbox-bypass mode.
 
 Today, your AI coding agent has two homes, both bad.
@@ -104,7 +116,7 @@ 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
-runner for that folder, start a Linzumi Codex session in a work thread, and
+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.
@@ -118,24 +130,27 @@ npx -y @linzumi/cli@latest signup --email alice@example.com --workspace-name "Al
 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
 (cd /tmp/hello_linzumi && npm run dev > /tmp/hello_linzumi/dev.log 2>&1 &)
-npx -y @linzumi/cli@latest agent runner /tmp/hello_linzumi \
-  --runner-id hello-linzumi-agent \
+npx -y @linzumi/cli@latest commander /tmp/hello_linzumi \
+  --runner-id "$commander_id" \
   --allowed-cwd /tmp/hello_linzumi \
   --forward-port 8787 \
   --sandbox danger-full-access \
   --approval-policy never
 ```
 
-The agent-owned runner reads `~/.linzumi/agent-token.json`, uses the
+The agent-owned Commander reads `~/.linzumi/agent-token.json`, uses the
 workspace/channel scope from the approval flow, trusts only the selected
 folder, advertises the explicit preview port, and listens only to the
-approving human unless `--listen-user` is explicitly passed. The bootstrap
-agent waits for `Runner connected:` before starting Codex in the Linzumi
+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.
 
-By default, the runner downloads the Linzumi-approved `code-server`
+By default, the Commander downloads the Linzumi-approved `code-server`
 runtime for your platform and verifies its checksum before enabling the
 browser editor. Linux editor launches are wrapped with `bubblewrap`
 (`bwrap`) for filesystem confinement.
@@ -146,20 +161,20 @@ workspace. The claim also provisions `#linzumi-support`, a shared channel
 connected to Linzumi's workspace so our team can see setup issues from our
 side; the bootstrap agent posts a hello there with the printed
 `support_channel_id`.
-Keep demo work in task threads; use the support channel when signup, runner,
+Keep demo work in task threads; use the support channel when signup, Commander,
 preview, or browser-editor setup gets stuck.
 
-Once the runner is online, the bootstrap agent can ask Linzumi to start
+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:
 
 ```bash
 npx -y @linzumi/cli@latest codex start <thread_id> \
-  --runner hello-linzumi-agent \
+  --runner "$commander_id" \
   --cwd /tmp/hello_linzumi \
   --work-description "Work only in /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."
 
 npx -y @linzumi/cli@latest editor open <thread_id> \
-  --runner hello-linzumi-agent \
+  --runner "$commander_id" \
   --cwd /tmp/hello_linzumi
 ```
 
@@ -261,7 +276,7 @@ intentionally. Every action is auditable from the thread.
 ## Pinning a version
 
 ```bash
-npm install -g @linzumi/cli@0.0.23-beta
+npm install -g @linzumi/cli@0.0.24-beta
 linzumi --version
 ```
 
@@ -284,7 +299,7 @@ linzumi connect \
 ### All the flags
 
 ```text
---agent-token-file <path>   Agent token cache for `linzumi agent runner`
+--agent-token-file <path>   Agent token cache for `linzumi commander`
 --oauth-callback-host <ip>  Sign-in callback host your browser can reach
 --codex-bin <path>          Codex executable, default `codex`
 --model <name>              Model requested for Codex sessions and labelled in Linzumi

package/dist/index.js

@@ -8397,7 +8397,7 @@ async function main(args) {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write(`linzumi 0.0.23-beta
+      process.stdout.write(`linzumi 0.0.24-beta
 `);
       return;
     case "auth":
@@ -8452,6 +8452,7 @@ 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 "signup":
     case "claim":
@@ -8686,7 +8687,7 @@ async function parseAgentRunnerArgs(args, deps = {
   }
   rejectAgentRunnerTargetingFlags(values);
   if (cwdArg !== undefined && values.has("cwd")) {
-    throw new Error("linzumi agent runner accepts either <folder> or --cwd, not both");
+    throw new Error("linzumi commander accepts either <folder> or --cwd, not both");
   }
   const tokenFilePath = stringValue3(values, "agent-token-file") ?? defaultAgentTokenFilePath();
   const tokenFile = readStoredAgentTokenFile(tokenFilePath, deps.readTextFile);
@@ -8752,14 +8753,14 @@ function readAgentTokenTextFile(path) {
 function rejectAgentRunnerTargetingFlags(values) {
   const unsupportedFlags = ["workspace", "channel", "token", "auth-file", "oauth-callback-host"].filter((flag) => values.has(flag));
   if (unsupportedFlags.length > 0) {
-    throw new Error(`linzumi agent runner uses the claimed agent token scope; remove ${unsupportedFlags.map((flag) => `--${flag}`).join(", ")}.`);
+    throw new Error(`linzumi commander uses the claimed agent token scope; remove ${unsupportedFlags.map((flag) => `--${flag}`).join(", ")}.`);
   }
 }
 function requiredStoredAgentChannel(channelId) {
   if (channelId !== undefined) {
     return channelId;
   }
-  throw new Error("agent token file is missing channelId; rerun linzumi claim before starting an agent runner");
+  throw new Error("agent token file is missing channelId; rerun linzumi claim before starting a Commander");
 }
 function requiredStoredOwnerUsername(ownerUsername) {
   if (ownerUsername !== undefined) {
@@ -8817,7 +8818,7 @@ async function parseRunnerArgs(args, deps = {
     process.exit(0);
   }
   if (values.get("version") === true) {
-    process.stdout.write(`linzumi 0.0.23-beta
+    process.stdout.write(`linzumi 0.0.24-beta
 `);
     process.exit(0);
   }
@@ -9039,7 +9040,7 @@ Usage:
   linzumi inbox <thread_id> --since-last
   linzumi done <thread_id> --message <message>
   linzumi init-hello-linzumi-demo-app
-  linzumi agent runner <folder> [options]
+  linzumi commander <folder> [options]
   linzumi start <folder> [options]
   linzumi paths list|add|remove [path]
   linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> [options]
@@ -9081,7 +9082,7 @@ 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 agent runner ~/code/my-app --runner-id launch-agent-runner
+    linzumi commander ~/code/my-app --runner-id launch-commander
     linzumi start ~/
     linzumi start ~/code/my-app
     linzumi connect --workspace <your-workspace> --channel <your-channel> --launch-tui
@@ -9173,13 +9174,14 @@ Examples:
 `;
 }
 function agentRunnerHelpText() {
-  return `Linzumi agent-owned local runner
+  return `Linzumi Commander
 
 Usage:
+  linzumi commander <folder> [options]
   linzumi agent runner <folder> [options]
 
 What it does:
-  Starts this computer as the claimed agent's scoped local runner. The command
+  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.
@@ -9187,7 +9189,7 @@ What it does:
 Options:
   --agent-token-file <path>   Agent token cache, default ~/.linzumi/agent-token.json
   --kandan-url <ws-url>       Kandan websocket base URL. Defaults deterministically from the stored apiUrl.
-  --runner-id <id>            Stable local runner id
+  --runner-id <id>            Stable Commander id
   --codex-bin <path>          Codex executable, default codex
   --code-server-bin <path>    Custom development code-server executable. By default Kandan installs the approved editor runtime.
   --listen-user <user>        Human whose replies Codex may accept, default owner from claim
@@ -9197,11 +9199,11 @@ Options:
   --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
-  --fast                      Mark this runner as low-latency/fast in Kandan
+  --fast                      Mark this Commander as low-latency/fast in Linzumi
 
 Examples:
-  linzumi agent runner "$PWD" --runner-id hello-world-agent
-  linzumi agent runner ~/code/my-app --kandan-url ws://127.0.0.1:4162 --runner-id local-qa-agent
+  linzumi commander "$PWD" --runner-id hello-world-commander
+  linzumi commander ~/code/my-app --kandan-url ws://127.0.0.1:4162 --runner-id local-qa-commander
 `;
 }
 function connectGuideText() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.23-beta",
+  "version": "0.0.24-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": {