@linzumi/cli 0.0.12-beta → 0.0.13-beta

package/src/channelSessionSupport.ts

@@ -8,12 +8,26 @@
   Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
   Relationship: Keeps local Codex version discovery bounded so channel
   availability is not blocked indefinitely by a bad executable.
+
+- Date: 2026-05-02
+  Spec: plans/2026-05-02-agent-first-zero-to-codex-launch-plan.md
+  Relationship: Keeps the npm CLI runner in parity with the legacy local
+  runner by carrying Kandan attachment metadata into queued Codex input.
 */
 import { spawnSync } from "node:child_process";
 import { hostname } from "node:os";
-import { integerValue, objectValue, stringValue } from "./json";
+import { arrayValue, integerValue, objectValue, stringValue } from "./json";
 import { type JsonObject, type JsonValue, isJsonObject } from "./protocol";
 
+export type KandanChatAttachment = {
+  readonly id: string | undefined;
+  readonly kind: string | undefined;
+  readonly fileName: string | undefined;
+  readonly contentType: string | undefined;
+  readonly sizeBytes: number | undefined;
+  readonly url: string | undefined;
+};
+
 export type KandanChatEvent = {
   readonly seq: number;
   readonly type: string;
@@ -24,6 +38,7 @@ export type KandanChatEvent = {
   readonly replyToSeq: number | undefined;
   readonly localRunnerEventType: string | undefined;
   readonly body: string;
+  readonly attachments: readonly KandanChatAttachment[];
 };
 
 export type RunnerIdentity = {
@@ -114,9 +129,45 @@ export function parseKandanChatEvent(
       stringValue(payload.body) ??
       stringValue(payload.text) ??
       "",
+    attachments: parseKandanChatAttachments(
+      arrayValue(payload.attachments) ?? arrayValue(value.attachments) ?? [],
+    ),
   };
 }
 
+function parseKandanChatAttachments(
+  attachments: readonly JsonValue[],
+): readonly KandanChatAttachment[] {
+  return attachments.flatMap(attachment => {
+    const value = objectValue(attachment);
+
+    if (value === undefined) {
+      return [];
+    }
+
+    return [
+      {
+        id: stringValue(value.id),
+        kind: stringValue(value.kind),
+        fileName:
+          stringValue(value.file_name) ??
+          stringValue(value.fileName) ??
+          stringValue(value.name),
+        contentType:
+          stringValue(value.content_type) ??
+          stringValue(value.contentType) ??
+          stringValue(value.mime_type) ??
+          stringValue(value.mimeType),
+        sizeBytes:
+          integerValue(value.size_bytes) ??
+          integerValue(value.sizeBytes) ??
+          integerValue(value.size),
+        url: stringValue(value.url),
+      },
+    ];
+  });
+}
+
 export function isCodexAuthoredEvent(
   event: Pick<
     KandanChatEvent,
@@ -206,10 +257,12 @@ export function localRunnerPayload(
   codexThreadId: string,
   context: RunnerPayloadContext,
   sourceMessageSeq?: number | undefined,
+  extraLocalRunnerMetadata?: JsonObject | undefined,
 ): JsonObject {
   return {
     metadata: {
       local_codex_runner: {
+        ...(extraLocalRunnerMetadata ?? {}),
         runner_id: options.runnerId,
         instance_id: instanceId,
         event_type: eventType,

package/src/forwardTunnel.ts

@@ -394,14 +394,15 @@ function openWebSocketStream(
 
   let opened = false;
   const pendingMessages: WebSocketPendingMessage[] = [];
-  const socket = new WebSocket(
-    localForwardWebSocketUrl(
-      scheme,
-      request.port,
-      request.path,
-      request.queryString,
-    ),
+  const url = localForwardWebSocketUrl(
+    scheme,
+    request.port,
+    request.path,
+    request.queryString,
   );
+  const protocols = webSocketProtocols(request.headers);
+  const socket =
+    protocols === undefined ? new WebSocket(url) : new WebSocket(url, protocols);
   streams.set(streamId, { kind: "websocket", socket, pendingMessages });
   socket.addEventListener("open", () => {
     opened = true;
@@ -425,6 +426,11 @@ function openWebSocketStream(
     });
   });
   socket.addEventListener("close", (event) => {
+    const stream = streams.get(streamId);
+    if (stream?.kind !== "websocket" || stream.socket !== socket) {
+      return;
+    }
+
     streams.delete(streamId);
     send({
       type: "websocket_close",
@@ -433,6 +439,11 @@ function openWebSocketStream(
     });
   });
   socket.addEventListener("error", () => {
+    const stream = streams.get(streamId);
+    if (stream?.kind !== "websocket" || stream.socket !== socket) {
+      return;
+    }
+
     streams.delete(streamId);
     if (!opened && scheme === "ws") {
       openWebSocketStream(
@@ -648,6 +659,20 @@ function requestHeaders(headers: JsonValue | undefined): Headers {
   return result;
 }
 
+function webSocketProtocols(headers: Headers): string[] | undefined {
+  const protocolHeader = headers.get("sec-websocket-protocol");
+  if (protocolHeader === null) {
+    return undefined;
+  }
+
+  const protocols = protocolHeader
+    .split(",")
+    .map((protocol) => protocol.trim())
+    .filter((protocol) => protocol !== "");
+
+  return protocols.length === 0 ? undefined : protocols;
+}
+
 function responseHeaders(headers: Headers): JsonObject[] {
   return Array.from(headers.entries())
     .filter(([name]) => !blockedFetchResponseHeaderNames.has(name.toLowerCase()))

package/src/index.ts

@@ -20,9 +20,14 @@
   local users can tune Kandan persistence batching without changing the Codex
   transcript protocol, and exposes explicit local preview forwarding ports as
   capability metadata without creating an implicit tunnel.
+
+- Date: 2026-05-02
+  Spec: plans/2026-05-02-agent-first-zero-to-codex-launch-plan.md
+  Relationship: Routes the agent-first bootstrap commands that support the
+  zero-to-hello-world-pr+editor launch path.
 */
 import { randomUUID } from "node:crypto";
-import { realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { runLocalCodexRunner, type RunnerOptions } from "./runner";
@@ -58,6 +63,11 @@ import {
   trustedFetch,
   trustedWebSocketFactory,
 } from "./kandanTls";
+import {
+  defaultAgentTokenFilePath,
+  readStoredAgentTokenFile,
+  runAgentCliCommand,
+} from "./agentBootstrap";
 
 type FlagDefinition = {
   readonly kind: "value" | "boolean";
@@ -87,6 +97,7 @@ const flagDefinitions = new Map<string, FlagDefinition>([
   ["fast", { kind: "boolean" }],
   ["log-file", { kind: "value" }],
   ["auth-file", { kind: "value" }],
+  ["agent-token-file", { kind: "value" }],
   ["oauth-callback-host", { kind: "value" }],
   ["help", { kind: "boolean" }],
 ]);
@@ -110,7 +121,7 @@ async function main(args: readonly string[]): Promise<void> {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write("linzumi 0.0.12-beta\n");
+      process.stdout.write("linzumi 0.0.13-beta\n");
       return;
     case "auth":
       await runAuthCommand(parsed.args);
@@ -118,8 +129,20 @@ async function main(args: readonly string[]): Promise<void> {
     case "paths":
       runPathsCommand(parsed.args);
       return;
+    case "agent":
+      await runAgentCliCommand(parsed.args);
+      return;
+    case "agentRunner": {
+      const options = await parseAgentRunnerArgs(parsed.args);
+      await runLocalCodexRunner(options);
+      return;
+    }
     case "start": {
       const options = await parseStartRunnerArgs(parsed.args);
+      // Persist the resolved cwd to the trusted-paths list so the user
+      // doesn't have to remember to run `linzumi paths add` separately.
+      // addAllowedCwd is idempotent and honors LINZUMI_CONFIG_FILE for tests.
+      addAllowedCwd(options.cwd);
       await runLocalCodexRunner(options);
       return;
     }
@@ -136,6 +159,8 @@ type ParsedCommand =
   | { readonly command: "version"; readonly args: readonly string[] }
   | { readonly command: "auth"; readonly args: readonly string[] }
   | { readonly command: "paths"; readonly args: readonly string[] }
+  | { readonly command: "agent"; readonly args: readonly string[] }
+  | { readonly command: "agentRunner"; readonly args: readonly string[] }
   | { readonly command: "start"; readonly args: readonly string[] }
   | { readonly command: "run"; readonly args: readonly string[] };
 
@@ -158,6 +183,21 @@ function parseCommand(args: readonly string[]): ParsedCommand {
       return { command: "auth", args: rest };
     case "paths":
       return { command: "paths", args: rest };
+    case "agent":
+      return rest[0] === "runner"
+        ? { command: "agentRunner", args: rest.slice(1) }
+        : { command: "agent", args: rest };
+    case "agent-runner":
+      return { command: "agentRunner", args: rest };
+    case "signup":
+    case "claim":
+    case "thread":
+    case "post":
+    case "inbox":
+    case "done":
+    case "codex":
+    case "editor":
+      return { command: "agent", args };
     case "start":
       return { command: "start", args: rest };
     case "run":
@@ -270,12 +310,13 @@ export async function parseStartRunnerArgs(
 
   rejectStartTargetingFlags(values);
 
-  const kandanUrl = stringValue(values, "kandan-url") ?? "wss://serve.kandanai.com";
+  const kandanUrl = stringValue(values, "kandan-url") ?? "wss://serve.linzumi.com";
   const requestedCwd = resolveUserPath(cwdArg ?? process.cwd());
-  const allowedCwds = values.has("allowed-cwd")
+  const cwd = assertConfiguredAllowedCwds([requestedCwd])[0] ?? requestedCwd;
+  const explicitAllowedCwds = values.has("allowed-cwd")
     ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue(values, "allowed-cwd")))
-    : assertConfiguredAllowedCwds([requestedCwd]);
-  const cwd = allowedCwds[0] ?? requestedCwd;
+    : [];
+  const allowedCwds = Array.from(new Set([cwd, ...explicitAllowedCwds]));
   const codexBin = stringValue(values, "codex-bin") ?? "codex";
   const customCodeServerBin = stringValue(values, "code-server-bin");
   const initialDependencyStatus = await deps.buildDependencyStatus({
@@ -364,6 +405,168 @@ export async function parseStartRunnerArgs(
   };
 }
 
+type AgentRunnerDeps = {
+  readonly readTextFile: (path: string) => string | undefined;
+  readonly buildDependencyStatus: typeof buildRunnerDependencyStatus;
+  readonly resolveEditorRuntime: typeof resolveEditorRuntime;
+};
+
+export async function parseAgentRunnerArgs(
+  args: readonly string[],
+  deps: AgentRunnerDeps = {
+    readTextFile: readAgentTokenTextFile,
+    buildDependencyStatus: buildRunnerDependencyStatus,
+    resolveEditorRuntime,
+  },
+): Promise<RunnerOptions> {
+  const { cwdArg, flagArgs } = splitStartArgs(args);
+  const values = strictFlagValues(flagArgs);
+
+  if (values.get("help") === true) {
+    process.stdout.write(agentRunnerHelpText());
+    process.exit(0);
+  }
+
+  rejectAgentRunnerTargetingFlags(values);
+
+  if (cwdArg !== undefined && values.has("cwd")) {
+    throw new Error("linzumi agent runner accepts either <folder> or --cwd, not both");
+  }
+
+  const tokenFilePath = stringValue(values, "agent-token-file") ?? defaultAgentTokenFilePath();
+  const tokenFile = readStoredAgentTokenFile(tokenFilePath, deps.readTextFile);
+  const channelSlug = requiredStoredAgentChannel(tokenFile.channelId);
+  const listenUser =
+    stringValue(values, "listen-user") ?? requiredStoredOwnerUsername(tokenFile.ownerUsername);
+  const kandanUrl = stringValue(values, "kandan-url") ?? agentApiUrlToKandanUrl(tokenFile.apiUrl);
+  const requestedCwd = resolveUserPath(
+    cwdArg ?? stringValue(values, "cwd") ?? process.cwd(),
+  );
+  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");
+  const initialDependencyStatus = await deps.buildDependencyStatus({
+    cwd,
+    codexBin,
+    codeServerBin: customCodeServerBin,
+  });
+  assertStartDependencies(initialDependencyStatus);
+  const editorRuntime = await deps.resolveEditorRuntime({
+    kandanUrl,
+    token: tokenFile.agentToken,
+    customCodeServerBin,
+    fetchImpl: trustedFetch(kandanTlsTrustFromEnv()),
+  });
+  const dependencyStatus = await deps.buildDependencyStatus({
+    cwd,
+    codexBin,
+    codeServerBin: editorRuntime.codeServerBin,
+    editorRuntime: editorRuntime.status,
+  });
+  assertStartDependencies(dependencyStatus);
+
+  return {
+    kandanUrl,
+    token: tokenFile.agentToken,
+    runnerId: stringValue(values, "runner-id") ?? `agent-runner-${randomUUID()}`,
+    cwd,
+    codexBin,
+    codexUrl: stringValue(values, "codex-url"),
+    launchTui: values.get("launch-tui") === true,
+    fast: values.get("fast") === true,
+    logFile: stringValue(values, "log-file"),
+    allowedCwds,
+    allowedForwardPorts: parseAllowedPortList(
+      stringValue(values, "forward-port"),
+    ),
+    codeServerBin: editorRuntime.codeServerBin,
+    editorRuntime: editorRuntime.runtime,
+    socketFactory: trustedWebSocketFactory(kandanTlsTrustFromEnv()),
+    dependencyStatus,
+    channelSession: {
+      workspaceSlug: tokenFile.workspaceId,
+      channelSlug,
+      kandanThreadId: stringValue(values, "kandan-thread-id"),
+      listenUser,
+      model: stringValue(values, "model"),
+      reasoningEffort: stringValue(values, "reasoning-effort"),
+      sandbox: stringValue(values, "sandbox"),
+      approvalPolicy: stringValue(values, "approval-policy"),
+      streamFlushMs: positiveIntegerValue(values, "stream-flush-ms"),
+    },
+  };
+}
+
+function readAgentTokenTextFile(path: string): string | undefined {
+  return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+
+function rejectAgentRunnerTargetingFlags(values: Map<string, string | true>): void {
+  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(", ")}.`,
+    );
+  }
+}
+
+function requiredStoredAgentChannel(channelId: string | undefined): string {
+  if (channelId !== undefined) {
+    return channelId;
+  }
+
+  throw new Error(
+    "agent token file is missing channelId; rerun linzumi claim before starting an agent runner",
+  );
+}
+
+function requiredStoredOwnerUsername(ownerUsername: string | undefined): string {
+  if (ownerUsername !== undefined) {
+    return ownerUsername;
+  }
+
+  throw new Error(
+    "agent token file is missing ownerUsername; rerun linzumi claim or pass --listen-user explicitly",
+  );
+}
+
+function agentApiUrlToKandanUrl(apiUrl: string): string {
+  const url = parseAgentApiUrl(apiUrl);
+
+  switch (url.protocol) {
+    case "https:":
+      url.protocol = "wss:";
+      return trimTrailingSlash(url.toString());
+    case "http:":
+      url.protocol = "ws:";
+      return trimTrailingSlash(url.toString());
+    case "wss:":
+    case "ws:":
+      return trimTrailingSlash(url.toString());
+    default:
+      throw new Error("agent token file apiUrl must use http, https, ws, or wss");
+  }
+}
+
+function parseAgentApiUrl(apiUrl: string): URL {
+  try {
+    return new URL(apiUrl);
+  } catch (_error) {
+    throw new Error("agent token file apiUrl is not a valid URL");
+  }
+}
+
+function trimTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
 async function resolveStartTargetToken(args: {
   readonly kandanUrl: string;
   readonly explicitToken?: string | undefined;
@@ -411,7 +614,7 @@ export async function parseRunnerArgs(
   }
 
   if (values.get("version") === true) {
-    process.stdout.write("linzumi 0.0.12-beta\n");
+    process.stdout.write("linzumi 0.0.13-beta\n");
     process.exit(0);
   }
 
@@ -706,25 +909,32 @@ function positiveIntegerValue(
 }
 
 function helpText(): string {
-  return `Kandan local Codex runner
+  return `Linzumi local Codex runner
 
 Usage:
   linzumi
+  linzumi signup --email <email> --agent-name <name>
+  linzumi claim --pending <pending_id> --code <XXXX-XXXX>
+  linzumi thread new <title> --message <message>
+  linzumi post <thread_id> <message>
+  linzumi inbox <thread_id> --since-last
+  linzumi done <thread_id> --message <message>
+  linzumi agent runner <folder> [options]
   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>]
 
 Required:
-  --kandan-url <ws-url>       Kandan websocket base URL, for example ws://127.0.0.1:4160
-  --token <jwt>               Optional override token. Otherwise ~/.kandan/auth.json is validated or OAuth opens.
-  --auth-file <path>          Auth cache path, default ~/.kandan/auth.json
-  --oauth-callback-host <ip>  Callback host reachable by your browser, for example a Tailscale IP
+  --kandan-url <ws-url>       Linzumi backend URL, default wss://serve.linzumi.com
+  --token <jwt>               Optional override token. Otherwise ~/.linzumi/auth.json is validated or OAuth opens.
+  --auth-file <path>          Auth cache path, default ~/.linzumi/auth.json
+  --oauth-callback-host <ip>  Callback host reachable by your browser
 
 Channel binding:
   --workspace <slug>          Workspace slug
   --channel <slug|w/c>        Channel slug, or workspace/channel
-  --kandan-thread-id <uuid>   Resume an existing Kandan thread instead of announcing a new root
+  --kandan-thread-id <uuid>   Resume an existing Linzumi thread instead of announcing a new root
   --listen-user <user|all>    User whose replies are accepted, default authenticated user
 
 Codex:
@@ -732,42 +942,41 @@ Codex:
   --codex-bin <path>          Codex executable, default codex
   --codex-url <ws-url>        Existing Codex app-server websocket URL
   --launch-tui                Launch codex --remote against the app-server
-  --model <name>              Model requested for the Codex thread and shown in Kandan
-  --reasoning-effort <value>  Reasoning effort requested for Codex and shown in Kandan
-  --sandbox <value>           Sandbox metadata shown in Kandan
-  --approval-policy <value>   Approval-policy metadata shown in Kandan
-  --stream-flush-ms <ms>      Batch live Codex deltas before Kandan persistence, default 150
+  --model <name>              Model requested for the Codex thread and shown in Linzumi
+  --reasoning-effort <value>  Reasoning effort requested for Codex and shown in Linzumi
+  --sandbox <value>           Sandbox metadata shown in Linzumi
+  --approval-policy <value>   Approval-policy metadata shown in Linzumi
+  --stream-flush-ms <ms>      Batch live Codex deltas before Linzumi persistence, default 150
   --fast                      Mark this runner as low-latency/fast in the availability message
-  --log-file <path>           JSONL event log path, default <cwd>/.kandan-local-codex-runner.log
-  --allowed-cwd <paths>       Comma-separated roots where Kandan may start new local Codex sessions
-  --forward-port <ports>      Comma-separated local TCP ports Kandan may expose as authenticated previews
-  --code-server-bin <path>    Custom development code-server executable. The default editor runtime is downloaded from Kandan.
+  --log-file <path>           JSONL event log path, default <cwd>/.linzumi-runner.log
+  --allowed-cwd <paths>       Comma-separated roots where Linzumi may start new local Codex sessions
+  --forward-port <ports>      Comma-separated local TCP ports Linzumi may expose as authenticated previews
+  --code-server-bin <path>    Custom development code-server executable. The default editor runtime is downloaded from Linzumi.
 
 Examples:
   Good:
+    linzumi signup --email alice@example.com --agent-name BuildBot
+    linzumi claim --pending pnd_2k4f9w --code 7K2C-9X4M
+    linzumi thread new "Hello world" --message "Starting now. ETA 3m."
+    linzumi post thr_abc123 "PR is open"
+    linzumi done thr_abc123 --message "Done: https://github.com/example/repo/pull/1"
+    linzumi agent runner ~/code/my-app --runner-id launch-agent-runner
     linzumi start ~/
-    linzumi start ~/code/my-app --kandan-url wss://serve.kandanai.com
-    linzumi connect --kandan-url wss://serve.kandanai.com --workspace linzumi --channel seans-playground --codex-bin codex --launch-tui
-    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 start ~/code/my-app
+    linzumi connect --workspace <your-workspace> --channel <your-channel> --launch-tui
+    linzumi connect --workspace <your-workspace> --channel <your-channel> --model gpt-5 --reasoning-effort low --fast --launch-tui
+    linzumi auth --workspace <your-workspace> --channel <your-channel>
+    linzumi paths add ~/code/my-app
     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
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --allowed-cwd ~/code/linzumi,~/scratch
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --forward-port 3000,5173
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --allowed-cwd ~/code/linzumi
 
   Bad:
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --token not-a-jwt --workspace default --channel seans-playground
+    linzumi connect --token not-a-jwt --workspace <your-workspace> --channel <your-channel>
       Missing --listen-user and authenticated user is unavailable.
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --listen-users sean
+    linzumi connect --token "$TOKEN" --listen-users sean
       Invalid flag: use --listen-user.
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --allowed-cwd /does/not/exist
+    linzumi connect --workspace <your-workspace> --channel <your-channel> --allowed-cwd /does/not/exist
       Invalid --allowed-cwd: allowed cwd roots must exist locally.
-    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --forward-port vite
+    linzumi connect --workspace <your-workspace> --channel <your-channel> --forward-port vite
       Invalid --forward-port: value must be a TCP port from 1 to 65535.
 `;
 }
@@ -792,29 +1001,62 @@ Usage:
   linzumi start <folder> [options]
 
 What it does:
-  Opens Kandan in your browser, creates or reuses your personal coding space,
-  grants a scoped local-runner token, and starts this computer as a runner for
-  Codex sessions, local previews, and the Kandan editor.
+  Opens Linzumi in your browser, creates or reuses your personal coding space,
+  grants a scoped local-runner token, persists <folder> to your trusted-paths
+  list, and starts this computer as a runner for Codex sessions, local
+  previews, and the browser VS Code editor.
 
 Options:
-  --kandan-url <ws-url>       Kandan websocket base URL, default wss://serve.kandanai.com
+  --kandan-url <ws-url>       Linzumi backend URL, default wss://serve.linzumi.com
   --token <jwt>               Optional scoped local-runner token override
-  --auth-file <path>          Auth cache path, default ~/.kandan/auth.json
+  --auth-file <path>          Auth cache path, default ~/.linzumi/auth.json
   --oauth-callback-host <ip>  Callback host reachable by your browser
+  --codex-bin <path>          Codex executable, default codex
+  --code-server-bin <path>    Custom development code-server executable. By default Linzumi installs the approved editor runtime.
+  --listen-user <user|all>    User whose replies are accepted, default authenticated user
+  --model <name>              Model requested for Codex sessions
+  --reasoning-effort <value>  Reasoning effort requested for Codex sessions
+  --sandbox <value>           Sandbox metadata shown in Linzumi
+  --approval-policy <value>   Approval-policy metadata shown in Linzumi
+  --forward-port <ports>      Comma-separated local TCP ports Linzumi may expose as previews
+  --fast                      Mark this runner as low-latency/fast in Linzumi
+
+Examples:
+  linzumi start ~/
+  linzumi start ~/code/my-app
+`;
+}
+
+function agentRunnerHelpText(): string {
+  return `Linzumi agent-owned local runner
+
+Usage:
+  linzumi agent runner <folder> [options]
+
+What it does:
+  Starts this computer as the claimed agent's scoped local runner. 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.
+
+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
   --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|all>    User whose replies are accepted, default authenticated user
+  --listen-user <user>        Human whose replies Codex may accept, default owner from claim
   --model <name>              Model requested for Codex sessions
   --reasoning-effort <value>  Reasoning effort requested for Codex sessions
   --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
   --fast                      Mark this runner as low-latency/fast in Kandan
 
 Examples:
-  linzumi start ~/
-  linzumi start ~/code/my-app --kandan-url ws://100.71.192.98:4162 --oauth-callback-host 100.71.192.98
+  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
 `;
 }
 
@@ -824,17 +1066,12 @@ function connectGuideText(): string {
 Fastest path:
   linzumi start ~/
 
-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
+This opens Linzumi in your browser, creates or reuses your personal coding
+space, persists this folder to your trusted-paths list, and starts this
+computer as a local Codex runner.
 
-Connect this computer to Kandan as a local Codex runner.
-
-Use:
-  linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> [options]
+Advanced (when you already know your workspace and channel):
+  linzumi connect --workspace <your-workspace> --channel <your-channel>
 
 For help:
   linzumi connect --help