@linzumi/cli 0.0.11-beta → 0.0.13-beta

package/src/index.ts

@@ -20,8 +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 { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { runLocalCodexRunner, type RunnerOptions } from "./runner";
@@ -30,9 +36,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,
@@ -49,6 +63,11 @@ import {
   trustedFetch,
   trustedWebSocketFactory,
 } from "./kandanTls";
+import {
+  defaultAgentTokenFilePath,
+  readStoredAgentTokenFile,
+  runAgentCliCommand,
+} from "./agentBootstrap";
 
 type FlagDefinition = {
   readonly kind: "value" | "boolean";
@@ -78,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" }],
 ]);
@@ -101,13 +121,28 @@ async function main(args: readonly string[]): Promise<void> {
       process.stdout.write(connectGuideText());
       return;
     case "version":
-      process.stdout.write("linzumi 0.0.11-beta\n");
+      process.stdout.write("linzumi 0.0.13-beta\n");
       return;
     case "auth":
       await runAuthCommand(parsed.args);
       return;
+    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;
     }
@@ -123,6 +158,9 @@ 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: "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[] };
 
@@ -143,6 +181,23 @@ 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 "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":
@@ -152,6 +207,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);
 
@@ -208,10 +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 = assertConfiguredAllowedCwds([requestedCwd]);
-  const cwd = allowedCwds[0] ?? requestedCwd;
+  const cwd = assertConfiguredAllowedCwds([requestedCwd])[0] ?? requestedCwd;
+  const explicitAllowedCwds = values.has("allowed-cwd")
+    ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue(values, "allowed-cwd")))
+    : [];
+  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({
@@ -300,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;
@@ -347,7 +614,7 @@ export async function parseRunnerArgs(
   }
 
   if (values.get("version") === true) {
-    process.stdout.write("linzumi 0.0.11-beta\n");
+    process.stdout.write("linzumi 0.0.13-beta\n");
     process.exit(0);
   }
 
@@ -395,9 +662,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"),
     ),
@@ -642,24 +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:
@@ -667,44 +942,58 @@ 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 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
+    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
 
   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.
 `;
 }
 
+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
 
@@ -712,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
 `;
 }
 
@@ -744,16 +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 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

package/src/kandanQueue.ts

@@ -8,12 +8,22 @@
   Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
   Relationship: Carries selected queued message seqs through interrupt fusion
   so the UI can show which pending replies were accepted by the interrupt.
+
+- Date: 2026-05-02
+  Spec: plans/2026-05-02-agent-first-zero-to-codex-launch-plan.md
+  Relationship: Carries Kandan attachment metadata through npm CLI runner queue
+  fusion so attachment-backed replies stay intact before Codex sees them.
 */
+import { type KandanChatAttachment } from "./channelSessionSupport";
+
+export type QueuedKandanAttachment = KandanChatAttachment;
+
 export type QueuedKandanMessage = {
   readonly seq: number;
   readonly actorSlug: string | undefined;
   readonly actorUserId: number | undefined;
   readonly body: string;
+  readonly attachments: readonly QueuedKandanAttachment[];
 };
 
 export type QueueInterruptResult =
@@ -98,5 +108,6 @@ function fuseQueuedMessages(
     actorSlug: "kandan",
     actorUserId: undefined,
     body: selected.map(codexInputForQueuedKandanMessage).join("\n\n---\n\n"),
+    attachments: selected.flatMap(message => message.attachments),
   };
 }

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[],