@linzumi/cli 0.0.10-beta → 0.0.12-beta

package/README.md

@@ -1,21 +1,29 @@
 # Linzumi CLI
 
-Run an AI coding session on the code that is already on your computer, then
-open the editor and app preview from a shared browser workspace.
-
-Linzumi is for the common team workflow that is still too painful:
-
-- your branch is only on your laptop
-- your app only runs with your local setup, secrets, database, or devices
-- you want an AI agent to read, edit, run, and explain that code
-- you want a teammate to see the editor or preview without cloning the repo
-- you do not want to move the project into a cloud VM just to collaborate
-
-The CLI connects your machine to Kandan, Linzumi's shared browser workspace.
-Your code, terminal commands, dev servers, and editor runtime stay local. Kandan
-handles sign-in, sharing, HTTPS browser access, and permission checks.
-
-## Try It
+```text
+                  ▓▓╗     ▓▓╗▓▓▓╗   ▓▓╗▓▓▓▓▓▓▓╗▓▓╗   ▓▓╗▓▓▓╗   ▓▓▓╗▓▓╗
+                  ▓▓║     ▓▓║▓▓▓▓╗  ▓▓║╚══▓▓▓╔╝▓▓║   ▓▓║▓▓▓▓╗ ▓▓▓▓║▓▓║
+                  ▓▓║     ▓▓║▓▓╔▓▓╗ ▓▓║  ▓▓▓╔╝ ▓▓║   ▓▓║▓▓╔▓▓▓▓╔▓▓║▓▓║
+                  ▓▓║     ▓▓║▓▓║╚▓▓╗▓▓║ ▓▓▓╔╝  ▓▓║   ▓▓║▓▓║╚▓▓╔╝▓▓║▓▓║
+                  ▓▓▓▓▓▓▓░░░░░░░░╚▓▓▓▓║▓▓▓▓▓▓▓╗╚▓▓▓▓▓▓╔╝░░░░░░░░▓▓║▓▓║
+                  ╚═══▒▒▒@@@@@@@@▒▒═══╝╚══════╝ ╚════▒▒▒@@@@@@@@▒▒╝╚═╝
+                   ▒@@@@@@@@@@@@@@@@▒             ▒@@@@@@@@@@@@@@@@▒
+                 @@@@@@@@@@@@@@@@@@@@@           @@@@@@@@@@@@@@@@@@@@@
+                    @@@@@@@@@@@@@@@                 @@@@@@@@@@@@@@@
+                           ║║                             ║║
+                           ║║                             ║║
+                           ║║        ()-().----.          ║║
+                           ║║         \"/` ___  ;_________║║_.'
+                           ║║          ` ^^   ^^          ║║
+             ──────────────╨╨─────────────··────··────────╨╨──────────────
+                           multiplayer Codex, on your own code
+```
+
+Linzumi turns a folder on your laptop into a shared workspace. You and your teammates open the same browser app, point AI coding agents at the real code on your machines, and watch each other work — no cloud VM, no pushing a branch just to show someone a preview.
+
+Your code, your terminal, and your dev server stay on your laptop. Linzumi handles sign-in, sharing controls, and the secure browser link your teammates use to join you.
+
+## Quick start
 
 Use Chrome, Edge, Arc, Brave, or another Chromium-based browser.
 
@@ -24,191 +32,99 @@ npm install -g @linzumi/cli@beta
 linzumi start ~/code/my-app
 ```
 
-Then in the browser:
-
-```text
-Explain this project, open the editor, and tell me how to run it.
-```
-
-If the project has a dev server, start it locally:
-
-```bash
-npm run dev
-```
-
-Open the forwarded preview from Kandan. You should get a normal HTTPS URL that
-you can share with an approved teammate, without exposing a raw `localhost`
-address.
+That is it. Here is what happens next:
 
-To pin this exact beta:
+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 computer shows up as available in your workspace.
+5. Type something in chat — like *"Explain this project and tell me how to run it."* — and Codex picks it up on your machine.
 
-```bash
-npm install -g @linzumi/cli@0.0.10-beta
-linzumi start ~/code/my-app
-```
+The rest of this README is detail.
 
-## What You Get
+## What you can do with it
 
-Linzumi turns your local project into a shared coding workspace:
+- **Onboard yourself to a new repo.** Ask Codex to map the project for you — what it does, where to start reading, how to run it.
+- **Make a real change without context-switching.** Codex edits the files on your disk. You watch the diff land in chat, or jump into the browser editor (it is VS Code, in your browser, pointed at your folder).
+- **Show someone what is on your screen.** Open the browser editor or share your local dev server through a normal HTTPS link. No exposing `localhost` to the internet, no copy-pasting IPs.
+- **Work with a teammate on the same code.** They join your channel, see the same threads, and can start their own Codex run on their own machine.
 
-1. Codex can inspect and edit the folder you allowed.
-2. You can open a browser editor for that local folder.
-3. Local app previews are reachable through Kandan HTTPS URLs.
-4. Approved teammates can join the editor or preview.
-5. Kandan enforces auth, sharing grants, and allowed-port policy.
+## Working as a team
 
-The important part: your project does not have to leave your computer for this
-to work.
+This is the part that makes Linzumi different from running an AI coding agent alone in a terminal.
 
-## What Runs Where
+- **Your computers are always in sight.** Every machine you have run `linzumi start` on shows up as a runner in your workspace. From any channel you are in, you can see how many of your runners are reachable right now and which ones are listening on that channel.
 
-On your computer, the CLI starts a runner. The runner can:
+- **Put Codex on the job from the channel.** Pick an available runner and trusted folder from the channel menu, enter what Codex should work on, and start the session. Linzumi asks that runner to attach a fresh Codex to the folder you picked, using the runner, folder, and Codex settings shown in the menu.
 
-- launch or connect to Codex
-- download the Kandan-approved editor runtime
-- start code-server for the folder you chose
-- connect to explicitly approved local ports
-- stream editor and preview traffic through Kandan
+- **One Codex per thread.** Once a Codex picks up a thread, that thread belongs to it — no second Codex can step in and trample the work. (A future release will allow handing a thread off; for now the lock holds for the life of the thread.)
 
-In the browser, Kandan provides:
+- **Browse what your computers have been up to.** Open the runners dropdown and you see, across all your devices, the most recently active threads — each with its title and a short AI-written summary of what is happening. Pop into any of them and keep working.
 
-- sign-in and workspace UI
-- local-runner status
-- editor and preview links
-- sharing controls
-- HTTPS termination
-- access checks before traffic reaches your machine
+- **Chat with humans without waking up Codex.** Start a message with `&` and Codex will not see it. Use it for side conversations with teammates inside a thread, without nudging the agent.
 
-When docs mention `127.0.0.1` or `localhost` on the local-service hop, that
-means your computer, not the Kandan server.
-
-## Requirements
-
-Install these before running the beta:
+## Pin a specific version
 
 ```bash
-node --version
-npm --version
-bun --version
-codex --version
-```
-
-Expected:
-
-- Node.js 20 or newer
-- npm
-- Bun 1.2 or newer
-- Codex CLI
-- Chrome, Edge, Arc, Brave, or another Chromium-based browser
-
-Safari is semi-supported for now. Use Chromium for the best editor and
-collaboration behavior.
-
-## First Run
-
-```bash
-linzumi start ~/code/my-app
+npm install -g @linzumi/cli@0.0.12-beta
+linzumi --version
 ```
 
-What happens:
-
-1. The CLI opens Kandan.
-2. You sign up or sign in.
-3. Kandan asks permission to connect this computer.
-4. The CLI stores a scoped local-runner token.
-5. The CLI checks Bun, Codex, and the Kandan editor runtime.
-6. Kandan shows the computer as connected.
-
-The first editor launch can download a Kandan-approved runtime archive. Later
-runs reuse the verified runtime from:
-
-```text
-~/.linzumi/editor-runtimes
-```
+## What You Get
 
-The production path does not use a random local `code-server` install. Kandan
-publishes a checksummed runtime manifest, and the CLI only advertises editor
-readiness after that runtime is verified locally.
+Run an AI coding session on the code that is already on your computer. Linzumi is for the moments when you do not want to move the project into a cloud VM just to let teammates watch Codex work, open the browser editor, or review a forwarded local preview.
 
 ## Good Things To Try
 
-Ask Codex to map the project:
-
-```text
-What does this app do? Where should I start reading?
-```
-
-Ask Codex to make a small change:
-
-```text
-Find the main settings page and add a clear empty state.
-```
+- Start in a repo and ask Codex to explain how to run it.
+- Open the Codex editor from the runner controls once the folder is trusted.
+- Forward a local dev server and share the preview with a teammate.
 
-Open the editor from Kandan and inspect the changed files.
+## Trusted folders
 
-Start a local dev server:
+Linzumi only starts Codex or opens the Codex editor inside folders you trust. The default trusted folder list lives at `~/.linzumi/config.json`.
 
 ```bash
-npm run dev
+linzumi paths list
+linzumi paths add ~/code/my-app
+linzumi paths remove ~/code/my-app
 ```
 
-If a port is not auto-detected, restart with an explicit approved port:
+`linzumi connect` uses those trusted folders by default. Pass `--allowed-cwd <paths>` when you want one runner process to use an explicit comma-separated folder list instead of `~/.linzumi/config.json`.
 
-```bash
-linzumi start ~/code/my-app --forward-port 3000
-```
+## What you need installed
 
-For a collaboration test, invite another user, open the same file in the local
-editor, and type in Chromium. Remote cursor labels and selections should be
-visible.
+- Node.js 20 or newer
+- Bun 1.2 or newer
+- The Codex CLI
+- A Chromium-based browser (Chrome, Edge, Arc, or Brave)
 
-## Hosted Kandan
+Safari is semi-supported. Live editing and live collaboration are smoother in Chromium.
 
-For a hosted Kandan deployment, point the CLI at the hosted websocket URL:
+## If something looks wrong
 
-```bash
-linzumi start ~/code/my-app --kandan-url wss://<your-kandan-host>
-```
+- **`linzumi: command not found`** — your global npm bin folder is not on `PATH`. Run `npm prefix -g` and add the `bin` folder under that path to your shell `PATH`.
+- **`bun: command not found`** — install Bun, then rerun `linzumi start`.
+- **`codex: command not found`** — install or configure the Codex CLI, or pass `--codex-bin <path>` to `linzumi start`.
+- **The browser sign-in opens but never returns to the CLI** — your browser cannot reach the address the CLI is listening on. Pass `--oauth-callback-host <ip-or-host-your-browser-can-reach>`.
+- **The browser editor never says it is ready** — rerun `linzumi start` and watch the console for the editor download step. Slow networks can make the very first launch take a minute or two.
+- **Collaboration looks off in Safari** — switch to a Chromium browser for now.
 
-For Render-hosted Kandan, public TLS should work without local certificate
-flags. The CLI derives the HTTPS API origin from the websocket URL for OAuth,
-runtime manifest download, and runtime archive download.
+## Advanced
 
-For local development with a private CA:
+Most people never need anything in this section.
 
-```bash
-KANDAN_TLS_CA_FILE=/path/to/ca.crt linzumi start ~/code/my-app \
-  --kandan-url wss://linzumi.io:4140
-```
-
-## Tailscale Development
-
-If your browser needs to reach a local Kandan server through Tailscale:
+### Point at a self-hosted Linzumi
 
 ```bash
-linzumi start ~/code/my-app \
-  --kandan-url ws://100.71.192.98:4162 \
-  --oauth-callback-host 100.71.192.98
+linzumi start ~/code/my-app --kandan-url wss://your-host
 ```
 
-Use your own Tailscale IP.
-
-## Commands
-
-```bash
-linzumi
-linzumi --help
-linzumi --version
-linzumi start <folder>
-linzumi connect --help
-linzumi connect [runner options]
-linzumi auth [auth options]
-```
+Public TLS hosts work without extra flags. For local development against a private CA, set `KANDAN_TLS_CA_FILE` to your CA bundle and pass `--kandan-url` as usual.
 
-Most people should use `linzumi start`.
+### Lower-level connect
 
-`linzumi connect` is the lower-level command for connecting to an explicit
-workspace and channel:
+`linzumi start` is what you want almost every time. The lower-level form, useful when you already know your workspace and channel:
 
 ```bash
 linzumi connect \
@@ -218,71 +134,29 @@ linzumi connect \
   --cwd ~/code/my-app
 ```
 
-## Useful Options
+### All the flags
 
-```bash
---kandan-url <ws-url>       Kandan websocket URL
---oauth-callback-host <ip>  Callback host reachable by your browser
+```text
+--kandan-url <ws-url>       Linzumi base URL (defaults to the hosted service)
+--oauth-callback-host <ip>  Sign-in callback host your browser can reach
 --runner-id <id>            Stable id for this computer
---codex-bin <path>          Codex executable, default codex
---model <name>              Codex model metadata shown in Kandan
---reasoning-effort <value>  Codex reasoning metadata shown in Kandan
+--codex-bin <path>          Codex executable, default `codex`
+--model <name>              Codex model metadata shown in Linzumi
+--reasoning-effort <value>  Codex reasoning metadata shown in Linzumi
 --fast                      Mark this runner as low-latency
---forward-port <ports>      Comma-separated local ports Kandan may expose
---allowed-cwd <paths>       Comma-separated roots Kandan may use
+--forward-port <ports>      Comma-separated local ports Linzumi may share
+--allowed-cwd <paths>       Override ~/.linzumi/config.json with comma-separated trusted roots
 --log-file <path>           JSONL runner event log
 ```
 
-`--code-server-bin` exists only as a development override. It is not the
-supported production editor path.
-
-## Troubleshooting
-
-Check the CLI version:
-
-```bash
-linzumi --version
-```
-
-Expected:
-
-```text
-linzumi 0.0.10-beta
-```
-
-If `linzumi` is not found, your global npm bin directory is not on `PATH`.
-
-If `bun` is not found, install Bun and rerun `linzumi start`.
+### Tailscale
 
-If `codex` is not found, install or configure the Codex CLI, or pass
-`--codex-bin`.
-
-If OAuth opens but does not return to the CLI, pass an
-`--oauth-callback-host` that your browser can reach.
-
-If the editor does not become ready, do not install a local code-server package
-as a workaround. The server-managed runtime must download and verify cleanly.
-Rerun the CLI and check the runner log.
-
-If collaboration behaves oddly in Safari, retry in Chromium. Safari is currently
-semi-supported.
-
-## For Kandan Release Engineers
-
-The production contract is:
-
-1. Build the server-approved editor runtime archive.
-2. Publish the manifest and archive from Kandan.
-3. Publish the CLI beta.
-4. The CLI downloads only the approved runtime archive.
-5. The CLI verifies the archive SHA before advertising editor readiness.
-
-For local package verification:
+If your browser reaches your local Linzumi server through Tailscale, pass both your Tailscale IP for the URL and for the sign-in callback:
 
 ```bash
-bun test
-npm pack --dry-run
+linzumi start ~/code/my-app \
+  --kandan-url ws://100.71.192.98:4162 \
+  --oauth-callback-host 100.71.192.98
 ```
 
-The npm package must include this README, `bin/linzumi.js`, and the `src`
-runtime files.
+Use your own Tailscale IP, not that one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.10-beta",
+  "version": "0.0.12-beta",
   "description": "Connect your computer to Kandan for local Codex sessions, editors, and forwarded previews",
   "type": "module",
   "bin": {
@@ -29,5 +29,5 @@
     "node": ">=20",
     "bun": ">=1.2.0"
   },
-  "readme": "# Linzumi CLI\n\nRun an AI coding session on the code that is already on your computer, then\nopen the editor and app preview from a shared browser workspace.\n\nLinzumi is for the common team workflow that is still too painful:\n\n- your branch is only on your laptop\n- your app only runs with your local setup, secrets, database, or devices\n- you want an AI agent to read, edit, run, and explain that code\n- you want a teammate to see the editor or preview without cloning the repo\n- you do not want to move the project into a cloud VM just to collaborate\n\nThe CLI connects your machine to Kandan, Linzumi's shared browser workspace.\nYour code, terminal commands, dev servers, and editor runtime stay local. Kandan\nhandles sign-in, sharing, HTTPS browser access, and permission checks.\n\n## Try It\n\nUse Chrome, Edge, Arc, Brave, or another Chromium-based browser.\n\n```bash\nnpm install -g @linzumi/cli@beta\nlinzumi start ~/code/my-app\n```\n\nThen in the browser:\n\n```text\nExplain this project, open the editor, and tell me how to run it.\n```\n\nIf the project has a dev server, start it locally:\n\n```bash\nnpm run dev\n```\n\nOpen the forwarded preview from Kandan. You should get a normal HTTPS URL that\nyou can share with an approved teammate, without exposing a raw `localhost`\naddress.\n\nTo pin this exact beta:\n\n```bash\nnpm install -g @linzumi/cli@0.0.10-beta\nlinzumi start ~/code/my-app\n```\n\n## What You Get\n\nLinzumi turns your local project into a shared coding workspace:\n\n1. Codex can inspect and edit the folder you allowed.\n2. You can open a browser editor for that local folder.\n3. Local app previews are reachable through Kandan HTTPS URLs.\n4. Approved teammates can join the editor or preview.\n5. Kandan enforces auth, sharing grants, and allowed-port policy.\n\nThe important part: your project does not have to leave your computer for this\nto work.\n\n## What Runs Where\n\nOn your computer, the CLI starts a runner. The runner can:\n\n- launch or connect to Codex\n- download the Kandan-approved editor runtime\n- start code-server for the folder you chose\n- connect to explicitly approved local ports\n- stream editor and preview traffic through Kandan\n\nIn the browser, Kandan provides:\n\n- sign-in and workspace UI\n- local-runner status\n- editor and preview links\n- sharing controls\n- HTTPS termination\n- access checks before traffic reaches your machine\n\nWhen docs mention `127.0.0.1` or `localhost` on the local-service hop, that\nmeans your computer, not the Kandan server.\n\n## Requirements\n\nInstall these before running the beta:\n\n```bash\nnode --version\nnpm --version\nbun --version\ncodex --version\n```\n\nExpected:\n\n- Node.js 20 or newer\n- npm\n- Bun 1.2 or newer\n- Codex CLI\n- Chrome, Edge, Arc, Brave, or another Chromium-based browser\n\nSafari is semi-supported for now. Use Chromium for the best editor and\ncollaboration behavior.\n\n## First Run\n\n```bash\nlinzumi start ~/code/my-app\n```\n\nWhat happens:\n\n1. The CLI opens Kandan.\n2. You sign up or sign in.\n3. Kandan asks permission to connect this computer.\n4. The CLI stores a scoped local-runner token.\n5. The CLI checks Bun, Codex, and the Kandan editor runtime.\n6. Kandan shows the computer as connected.\n\nThe first editor launch can download a Kandan-approved runtime archive. Later\nruns reuse the verified runtime from:\n\n```text\n~/.linzumi/editor-runtimes\n```\n\nThe production path does not use a random local `code-server` install. Kandan\npublishes a checksummed runtime manifest, and the CLI only advertises editor\nreadiness after that runtime is verified locally.\n\n## Good Things To Try\n\nAsk Codex to map the project:\n\n```text\nWhat does this app do? Where should I start reading?\n```\n\nAsk Codex to make a small change:\n\n```text\nFind the main settings page and add a clear empty state.\n```\n\nOpen the editor from Kandan and inspect the changed files.\n\nStart a local dev server:\n\n```bash\nnpm run dev\n```\n\nIf a port is not auto-detected, restart with an explicit approved port:\n\n```bash\nlinzumi start ~/code/my-app --forward-port 3000\n```\n\nFor a collaboration test, invite another user, open the same file in the local\neditor, and type in Chromium. Remote cursor labels and selections should be\nvisible.\n\n## Hosted Kandan\n\nFor a hosted Kandan deployment, point the CLI at the hosted websocket URL:\n\n```bash\nlinzumi start ~/code/my-app --kandan-url wss://<your-kandan-host>\n```\n\nFor Render-hosted Kandan, public TLS should work without local certificate\nflags. The CLI derives the HTTPS API origin from the websocket URL for OAuth,\nruntime manifest download, and runtime archive download.\n\nFor local development with a private CA:\n\n```bash\nKANDAN_TLS_CA_FILE=/path/to/ca.crt linzumi start ~/code/my-app \\\n  --kandan-url wss://linzumi.io:4140\n```\n\n## Tailscale Development\n\nIf your browser needs to reach a local Kandan server through Tailscale:\n\n```bash\nlinzumi start ~/code/my-app \\\n  --kandan-url ws://100.71.192.98:4162 \\\n  --oauth-callback-host 100.71.192.98\n```\n\nUse your own Tailscale IP.\n\n## Commands\n\n```bash\nlinzumi\nlinzumi --help\nlinzumi --version\nlinzumi start <folder>\nlinzumi connect --help\nlinzumi connect [runner options]\nlinzumi auth [auth options]\n```\n\nMost people should use `linzumi start`.\n\n`linzumi connect` is the lower-level command for connecting to an explicit\nworkspace and channel:\n\n```bash\nlinzumi connect \\\n  --kandan-url wss://serve.kandanai.com \\\n  --workspace default \\\n  --channel general \\\n  --cwd ~/code/my-app\n```\n\n## Useful Options\n\n```bash\n--kandan-url <ws-url>       Kandan websocket URL\n--oauth-callback-host <ip>  Callback host reachable by your browser\n--runner-id <id>            Stable id for this computer\n--codex-bin <path>          Codex executable, default codex\n--model <name>              Codex model metadata shown in Kandan\n--reasoning-effort <value>  Codex reasoning metadata shown in Kandan\n--fast                      Mark this runner as low-latency\n--forward-port <ports>      Comma-separated local ports Kandan may expose\n--allowed-cwd <paths>       Comma-separated roots Kandan may use\n--log-file <path>           JSONL runner event log\n```\n\n`--code-server-bin` exists only as a development override. It is not the\nsupported production editor path.\n\n## Troubleshooting\n\nCheck the CLI version:\n\n```bash\nlinzumi --version\n```\n\nExpected:\n\n```text\nlinzumi 0.0.10-beta\n```\n\nIf `linzumi` is not found, your global npm bin directory is not on `PATH`.\n\nIf `bun` is not found, install Bun and rerun `linzumi start`.\n\nIf `codex` is not found, install or configure the Codex CLI, or pass\n`--codex-bin`.\n\nIf OAuth opens but does not return to the CLI, pass an\n`--oauth-callback-host` that your browser can reach.\n\nIf the editor does not become ready, do not install a local code-server package\nas a workaround. The server-managed runtime must download and verify cleanly.\nRerun the CLI and check the runner log.\n\nIf collaboration behaves oddly in Safari, retry in Chromium. Safari is currently\nsemi-supported.\n\n## For Kandan Release Engineers\n\nThe production contract is:\n\n1. Build the server-approved editor runtime archive.\n2. Publish the manifest and archive from Kandan.\n3. Publish the CLI beta.\n4. The CLI downloads only the approved runtime archive.\n5. The CLI verifies the archive SHA before advertising editor readiness.\n\nFor local package verification:\n\n```bash\nbun test\nnpm pack --dry-run\n```\n\nThe npm package must include this README, `bin/linzumi.js`, and the `src`\nruntime files."
+  "readmeFilename": "README.md"
 }

package/src/channelSession.ts

@@ -1171,6 +1171,20 @@ async function handleKandanChatEvent(
     return;
   }
 
+  if (event.body.trimStart().startsWith("&")) {
+    args.log("kandan.message_ignored", {
+      seq: event.seq,
+      actor_slug: event.actorSlug ?? null,
+      actor_user_id: event.actorUserId ?? null,
+      reason: "human_only",
+    });
+    await publishKandanMessageState(args, event, {
+      status: "ignored",
+      reason: "human_only",
+    });
+    return;
+  }
+
   const portForwardDecision = parsePortForwardDecision(event.body);
   if (portForwardDecision !== undefined) {
     const result = await resolvePendingPortForwardRequest(args, state, payloadContext, {

package/src/index.ts

@@ -22,6 +22,7 @@
   capability metadata without creating an implicit tunnel.
 */
 import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { runLocalCodexRunner, type RunnerOptions } from "./runner";
@@ -30,9 +31,17 @@ import { resolveLocalRunnerToken } from "./authResolution";
 import { identityFromAccessToken } from "./channelSessionSupport";
 import {
   assertConfiguredAllowedCwds,
+  expandUserPath,
   parseAllowedCwdList,
   parseAllowedPortList,
 } from "./localCapabilities";
+import {
+  addAllowedCwd,
+  localConfigPath,
+  readConfiguredAllowedCwds,
+  readLocalConfig,
+  removeAllowedCwd,
+} from "./localConfig";
 import {
   acquireLocalRunnerTokenDetails,
   fetchLocalRunnerStartTarget,
@@ -101,11 +110,14 @@ async function main(args: readonly string[]): Promise<void> {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write("linzumi 0.0.10-beta\n");
+      process.stdout.write("linzumi 0.0.12-beta\n");
       return;
     case "auth":
       await runAuthCommand(parsed.args);
       return;
+    case "paths":
+      runPathsCommand(parsed.args);
+      return;
     case "start": {
       const options = await parseStartRunnerArgs(parsed.args);
       await runLocalCodexRunner(options);
@@ -123,6 +135,7 @@ type ParsedCommand =
   | { readonly command: "guide"; readonly args: readonly string[] }
   | { readonly command: "version"; readonly args: readonly string[] }
   | { readonly command: "auth"; readonly args: readonly string[] }
+  | { readonly command: "paths"; readonly args: readonly string[] }
   | { readonly command: "start"; readonly args: readonly string[] }
   | { readonly command: "run"; readonly args: readonly string[] };
 
@@ -143,6 +156,8 @@ function parseCommand(args: readonly string[]): ParsedCommand {
       return { command: "run", args: ["--help"] };
     case "auth":
       return { command: "auth", args: rest };
+    case "paths":
+      return { command: "paths", args: rest };
     case "start":
       return { command: "start", args: rest };
     case "run":
@@ -152,6 +167,53 @@ function parseCommand(args: readonly string[]): ParsedCommand {
   }
 }
 
+function runPathsCommand(args: readonly string[]): void {
+  const [subcommand, pathValue, ...rest] = args;
+
+  if (subcommand === undefined || subcommand === "help" || subcommand === "--help") {
+    process.stdout.write(pathsHelpText());
+    return;
+  }
+
+  if (rest.length > 0) {
+    throw new Error("linzumi paths accepts one path argument");
+  }
+
+  switch (subcommand) {
+    case "list": {
+      const config = readLocalConfig();
+      if (config.allowedCwds.length === 0) {
+        process.stdout.write(`No trusted paths configured in ${localConfigPath()}\n`);
+        return;
+      }
+
+      process.stdout.write(`${config.allowedCwds.join("\n")}\n`);
+      return;
+    }
+    case "add": {
+      if (pathValue === undefined || pathValue.trim() === "") {
+        throw new Error("missing path for linzumi paths add");
+      }
+
+      const trustedPath = realpathSync(resolve(expandUserPath(pathValue)));
+      addAllowedCwd(pathValue);
+      process.stdout.write(`Trusted ${trustedPath}\n`);
+      return;
+    }
+    case "remove": {
+      if (pathValue === undefined || pathValue.trim() === "") {
+        throw new Error("missing path for linzumi paths remove");
+      }
+
+      removeAllowedCwd(pathValue);
+      process.stdout.write(`Removed trusted path ${pathValue}\n`);
+      return;
+    }
+    default:
+      throw new Error(`invalid paths command: ${subcommand}`);
+  }
+}
+
 async function runAuthCommand(args: readonly string[]): Promise<void> {
   const values = strictFlagValues(args);
 
@@ -210,7 +272,9 @@ export async function parseStartRunnerArgs(
 
   const kandanUrl = stringValue(values, "kandan-url") ?? "wss://serve.kandanai.com";
   const requestedCwd = resolveUserPath(cwdArg ?? process.cwd());
-  const allowedCwds = assertConfiguredAllowedCwds([requestedCwd]);
+  const allowedCwds = values.has("allowed-cwd")
+    ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue(values, "allowed-cwd")))
+    : assertConfiguredAllowedCwds([requestedCwd]);
   const cwd = allowedCwds[0] ?? requestedCwd;
   const codexBin = stringValue(values, "codex-bin") ?? "codex";
   const customCodeServerBin = stringValue(values, "code-server-bin");
@@ -347,7 +411,7 @@ export async function parseRunnerArgs(
   }
 
   if (values.get("version") === true) {
-    process.stdout.write("linzumi 0.0.10-beta\n");
+    process.stdout.write("linzumi 0.0.12-beta\n");
     process.exit(0);
   }
 
@@ -395,9 +459,9 @@ export async function parseRunnerArgs(
     launchTui: values.get("launch-tui") === true,
     fast: values.get("fast") === true,
     logFile: stringValue(values, "log-file"),
-    allowedCwds: assertConfiguredAllowedCwds(
-      parseAllowedCwdList(stringValue(values, "allowed-cwd")),
-    ),
+    allowedCwds: values.has("allowed-cwd")
+      ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue(values, "allowed-cwd")))
+      : readConfiguredAllowedCwds(),
     allowedForwardPorts: parseAllowedPortList(
       stringValue(values, "forward-port"),
     ),
@@ -647,6 +711,7 @@ function helpText(): string {
 Usage:
   linzumi
   linzumi start <folder> [options]
+  linzumi paths list|add|remove [path]
   linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> [options]
   linzumi auth --kandan-url <ws-url> [--workspace <slug> --channel <slug>]
 
@@ -686,6 +751,8 @@ Examples:
     linzumi connect --kandan-url wss://serve.kandanai.com --workspace linzumi --channel seans-playground --codex-bin codex --model gpt-5.5 --reasoning-effort low --fast --launch-tui
     linzumi auth --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground
     linzumi auth --kandan-url ws://100.71.192.98:4160 --oauth-callback-host 100.71.192.98 --workspace default --channel seans-playground
+    linzumi paths add ~/code/linzumi
+    linzumi paths list
     linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --workspace default --channel seans-playground --cwd /tmp/kandan-runner-a
     linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground
     linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --channel default/seans-playground --listen-user all --launch-tui
@@ -705,6 +772,19 @@ Examples:
 `;
 }
 
+function pathsHelpText(): string {
+  return `Linzumi trusted paths
+
+Usage:
+  linzumi paths list
+  linzumi paths add <path>
+  linzumi paths remove <path>
+
+Trusted paths are stored in ~/.linzumi/config.json. linzumi connect uses them
+unless --allowed-cwd is passed for that runner process.
+`;
+}
+
 function startHelpText(): string {
   return `Linzumi one-command local runner
 
@@ -748,6 +828,7 @@ This opens Kandan in your browser, creates or reuses your personal coding
 space, and starts this computer as a local Codex runner.
 
 Advanced:
+  linzumi paths add "$PWD"
   linzumi connect
 
 Connect this computer to Kandan as a local Codex runner.

package/src/localCapabilities.ts

@@ -7,6 +7,7 @@
   forwarding is advertised only for explicitly configured local ports.
 */
 import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
 
 export type CwdCapabilityDecision =
@@ -66,13 +67,25 @@ export function assertConfiguredAllowedCwds(
 ): string[] {
   return paths.map((path) => {
     try {
-      return realpathSync(resolve(path));
+      return realpathSync(resolve(expandUserPath(path)));
     } catch (_error) {
       throw new Error(`invalid --allowed-cwd: ${path} does not exist`);
     }
   });
 }
 
+export function expandUserPath(pathValue: string): string {
+  if (pathValue === "~") {
+    return homedir();
+  }
+
+  if (pathValue.startsWith("~/")) {
+    return resolve(homedir(), pathValue.slice(2));
+  }
+
+  return pathValue;
+}
+
 export function resolveAllowedCwd(
   requestedCwd: string | undefined,
   allowedRoots: readonly string[],

package/src/localConfig.ts

@@ -0,0 +1,99 @@
+/*
+- Date: 2026-05-01
+  Spec: ../../kandan/server_v2/plans/2026-05-01-runner-editor-dropdown-and-thread-controls.md
+  Relationship: Owns the npm-first local runner's trusted-folder config at
+  ~/.linzumi/config.json so README path-management commands are product truth.
+*/
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { expandUserPath } from "./localCapabilities";
+
+export type LinzumiConfig = {
+  readonly version: 1;
+  readonly allowedCwds: readonly string[];
+};
+
+export function localConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.LINZUMI_CONFIG_FILE;
+
+  return override !== undefined && override.trim() !== ""
+    ? resolve(expandUserPath(override))
+    : resolve(homedir(), ".linzumi", "config.json");
+}
+
+export function readLocalConfig(path: string = localConfigPath()): LinzumiConfig {
+  if (!existsSync(path)) {
+    return { version: 1, allowedCwds: [] };
+  }
+
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+
+  if (!isConfigPayload(parsed)) {
+    throw new Error(`invalid Linzumi config: ${path}`);
+  }
+
+  return {
+    version: 1,
+    allowedCwds: uniqueStrings(parsed.allowedCwds),
+  };
+}
+
+export function readConfiguredAllowedCwds(path: string = localConfigPath()): string[] {
+  return readLocalConfig(path).allowedCwds.map((cwd) => {
+    try {
+      return realpathSync(resolve(expandUserPath(cwd)));
+    } catch (_error) {
+      throw new Error(`invalid Linzumi config allowed path: ${cwd} does not exist`);
+    }
+  });
+}
+
+export function addAllowedCwd(pathValue: string, path: string = localConfigPath()): string[] {
+  const normalizedPath = realpathSync(resolve(expandUserPath(pathValue)));
+  const config = readLocalConfig(path);
+  const allowedCwds = uniqueStrings([...config.allowedCwds, normalizedPath]);
+  writeLocalConfig({ version: 1, allowedCwds }, path);
+  return allowedCwds;
+}
+
+export function removeAllowedCwd(pathValue: string, path: string = localConfigPath()): string[] {
+  const requestedPath = resolve(expandUserPath(pathValue));
+  const normalizedRequest = realpathOrResolved(requestedPath);
+  const config = readLocalConfig(path);
+  const allowedCwds = config.allowedCwds.filter((cwd) => {
+    const normalizedExisting = realpathOrResolved(cwd);
+    return cwd !== pathValue && normalizedExisting !== normalizedRequest;
+  });
+  writeLocalConfig({ version: 1, allowedCwds }, path);
+  return allowedCwds;
+}
+
+export function writeLocalConfig(config: LinzumiConfig, path: string = localConfigPath()): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function isConfigPayload(value: unknown): value is LinzumiConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { readonly version?: unknown }).version === 1 &&
+    Array.isArray((value as { readonly allowedCwds?: unknown }).allowedCwds) &&
+    (value as { readonly allowedCwds: readonly unknown[] }).allowedCwds.every(
+      (cwd) => typeof cwd === "string" && cwd.trim() !== "",
+    )
+  );
+}
+
+function uniqueStrings(values: readonly string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter((value) => value !== ""))];
+}
+
+function realpathOrResolved(pathValue: string): string {
+  try {
+    return realpathSync(resolve(expandUserPath(pathValue)));
+  } catch (_error) {
+    return resolve(expandUserPath(pathValue));
+  }
+}

package/src/localEditor.ts

@@ -592,7 +592,7 @@ export function prepareLocalEditorCollaboration(
     return undefined;
   }
 
-  const targetPath = `/local-codex-runner-targets/${encodeURIComponent(runnerId)}/forwards/${serverPort}`;
+  const targetPath = `/local-codex-runners/${encodeURIComponent(runnerId)}/forwards/${serverPort}/preview-target`;
   const serverUrl = new URL(targetPath, `${browserBaseUrl}/`).toString();
   const bootstrapServerUrl =
     collaboration.bootstrapToken === undefined || collaboration.bootstrapToken === ""

package/src/protocol.ts

@@ -133,6 +133,7 @@ export type KandanControl =
       readonly type: "start_instance";
       readonly instanceId?: string;
       readonly cwd?: string;
+      readonly workDescription?: string;
       readonly launchTui?: boolean;
       readonly model?: string;
       readonly reasoningEffort?: string;

package/src/runner.ts

@@ -60,7 +60,6 @@ import { join } from "node:path";
 import { attachChannelSession } from "./channelSession";
 import { connectCodexAppServer, startCodexAppServer } from "./codexAppServer";
 import { arrayValue, integerValue, objectValue, stringValue } from "./json";
-import { connectForwardTunnel } from "./forwardTunnel";
 import { resolveAllowedCwd } from "./localCapabilities";
 import {
   createForwardWebSocketManager,
@@ -82,6 +81,7 @@ import {
 import { connectPhoenixClient } from "./phoenix";
 import {
   type JsonObject,
+  type JsonRpcResponse,
   type JsonValue,
   type KandanChannelSessionOptions,
   type KandanControl,
@@ -183,8 +183,6 @@ async function openLocalCodexRunner(
     allowedPorts: Array.from(liveForwardPorts).sort(
       (left, right) => left - right,
     ),
-    streamingForwarding: true,
-    streamingForwardingVersion: 1,
     toolStatus:
       options.dependencyStatus === undefined
         ? null
@@ -209,18 +207,11 @@ async function openLocalCodexRunner(
   const joinPayload = (): JsonObject => ({
     clientName: "kandan-local-codex-runner",
     version: "0.0.1",
+    workspace: options.channelSession?.workspaceSlug ?? null,
+    channel: options.channelSession?.channelSlug ?? null,
     capabilities: capabilitiesPayload(),
   });
   await kandan.join(topic, joinPayload(), { rejoinPayload: joinPayload });
-  const forwardTunnel = await connectForwardTunnel({
-    kandanUrl: options.kandanUrl,
-    token: options.token,
-    runnerId: options.runnerId,
-    allowedPorts: () => Array.from(liveForwardPorts),
-    log,
-    socketFactory: options.socketFactory,
-  });
-  cleanup.actions.push(() => forwardTunnel.close());
 
   const started =
     options.codexUrl === undefined
@@ -661,6 +652,22 @@ async function discoverCodexThreads(
         .filter((thread) => thread.id !== "");
 }
 
+function extractStartedThreadId(response: JsonRpcResponse): string | undefined {
+  if ("error" in response) {
+    return undefined;
+  }
+
+  return stringValue(objectValue(objectValue(response.result)?.thread)?.id);
+}
+
+function normalizedWorkDescription(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+
+  return normalized === undefined || normalized === ""
+    ? undefined
+    : normalized;
+}
+
 function makeRunnerLogger(options: RunnerOptions): RunnerLogger {
   return createRunnerLogger(
     options.logFile ?? join(options.cwd, ".kandan-local-codex-runner.log"),
@@ -808,6 +815,15 @@ async function applyControl(
         ...(control.sandbox === undefined ? {} : { sandbox: control.sandbox }),
         ...(control.fast === true ? { serviceTier: "fast" } : {}),
       });
+      const codexThreadId = extractStartedThreadId(response);
+      const workDescription = normalizedWorkDescription(control.workDescription);
+
+      if (codexThreadId !== undefined && workDescription !== undefined) {
+        await codex.request("turn/start", {
+          threadId: codexThreadId,
+          input: [{ type: "text", text: workDescription }],
+        });
+      }
 
       return {
         instanceId,