@linzumi/cli 0.0.20-beta → 0.0.22-beta

package/src/index.ts

@@ -1,1080 +0,0 @@
-/*
-- Date: 2026-04-24
-  Spec: plans/2026-04-24-local-codex-runner-plan.md
-  Relationship: Provides the spec's initial Bun CLI entry point for starting
-  a customer-machine local runner with Kandan and Codex connection options.
-
-- Date: 2026-04-24
-  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
-  Relationship: Parses the channel-bound runner options that let a local Codex
-  process bind to one Kandan channel/thread and filter accepted senders.
-
-- Date: 2026-04-24
-  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
-  Relationship: Keeps default local runner identity collision-resistant for
-  concurrent local starts.
-
-- Date: 2026-04-26
-  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
-  Relationship: Exposes the live stream flush interval as a runner option so
-  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";
-import { writeCachedLocalRunnerToken } from "./authCache";
-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,
-  type LocalRunnerStartTarget,
-  validateLocalRunnerToken,
-} from "./oauth";
-import {
-  assertStartDependencies,
-  buildRunnerDependencyStatus,
-} from "./dependencyStatus";
-import { resolveEditorRuntime } from "./localEditorRuntime";
-import {
-  kandanTlsTrustFromEnv,
-  trustedFetch,
-  trustedWebSocketFactory,
-} from "./kandanTls";
-import {
-  defaultAgentTokenFilePath,
-  readStoredAgentTokenFile,
-  runAgentCliCommand,
-} from "./agentBootstrap";
-
-type FlagDefinition = {
-  readonly kind: "value" | "boolean";
-};
-
-const flagDefinitions = new Map<string, FlagDefinition>([
-  ["version", { kind: "boolean" }],
-  ["kandan-url", { kind: "value" }],
-  ["token", { kind: "value" }],
-  ["runner-id", { kind: "value" }],
-  ["cwd", { kind: "value" }],
-  ["codex-bin", { kind: "value" }],
-  ["codex-url", { kind: "value" }],
-  ["launch-tui", { kind: "boolean" }],
-  ["workspace", { kind: "value" }],
-  ["channel", { kind: "value" }],
-  ["kandan-thread-id", { kind: "value" }],
-  ["listen-user", { kind: "value" }],
-  ["model", { kind: "value" }],
-  ["reasoning-effort", { kind: "value" }],
-  ["sandbox", { kind: "value" }],
-  ["approval-policy", { kind: "value" }],
-  ["stream-flush-ms", { kind: "value" }],
-  ["allowed-cwd", { kind: "value" }],
-  ["forward-port", { kind: "value" }],
-  ["code-server-bin", { kind: "value" }],
-  ["fast", { kind: "boolean" }],
-  ["log-file", { kind: "value" }],
-  ["auth-file", { kind: "value" }],
-  ["agent-token-file", { kind: "value" }],
-  ["oauth-callback-host", { kind: "value" }],
-  ["help", { kind: "boolean" }],
-]);
-
-if (import.meta.main) {
-  try {
-    await main(process.argv.slice(2));
-  } catch (error) {
-    process.stderr.write(
-      `${error instanceof Error ? error.message : String(error)}\n`,
-    );
-    process.exit(1);
-  }
-}
-
-async function main(args: readonly string[]): Promise<void> {
-  const parsed = parseCommand(args);
-
-  switch (parsed.command) {
-    case "guide":
-      process.stdout.write(connectGuideText());
-      return;
-    case "version":
-      process.stdout.write("linzumi 0.0.20-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;
-    }
-    case "run": {
-      const options = await parseRunnerArgs(parsed.args);
-      await runLocalCodexRunner(options);
-      return;
-    }
-  }
-}
-
-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[] };
-
-function parseCommand(args: readonly string[]): ParsedCommand {
-  const [first, ...rest] = args;
-
-  switch (first) {
-    case undefined:
-    case "connect":
-    case "local-codex-runner":
-      return rest.length === 0
-        ? { command: "guide", args: [] }
-        : { command: "run", args: rest };
-    case "--version":
-      return { command: "version", args: [] };
-    case "--help":
-    case "-h":
-      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 "channel":
-    case "post":
-    case "inbox":
-    case "done":
-    case "codex":
-    case "editor":
-      return { command: "agent", args };
-    case "start":
-      return { command: "start", args: rest };
-    case "run":
-      return { command: "run", args: rest };
-    default:
-      return { command: "run", args };
-  }
-}
-
-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);
-
-  if (values.get("help") === true) {
-    process.stdout.write(helpText());
-    return;
-  }
-
-  const kandanUrl = required(values, "kandan-url");
-  const target = parseOptionalChannelTarget(values);
-  const token = await acquireLocalRunnerTokenDetails({
-    kandanUrl,
-    workspaceSlug: target?.workspaceSlug,
-    channelSlug: target?.channelSlug,
-    callbackHost: stringValue(values, "oauth-callback-host"),
-  });
-  const cached = writeCachedLocalRunnerToken({
-    kandanUrl,
-    accessToken: token.accessToken,
-    expiresInSeconds: token.expiresInSeconds,
-    authFilePath: stringValue(values, "auth-file"),
-  });
-
-  process.stdout.write(
-    `Saved Kandan local runner auth for ${cached.kandanBaseUrl}\n`,
-  );
-}
-
-type StartRunnerDeps = {
-  readonly resolveToken: typeof resolveLocalRunnerToken;
-  readonly fetchStartTarget: typeof fetchLocalRunnerStartTarget;
-  readonly validateToken: typeof validateLocalRunnerToken;
-  readonly buildDependencyStatus: typeof buildRunnerDependencyStatus;
-  readonly resolveEditorRuntime: typeof resolveEditorRuntime;
-};
-
-export async function parseStartRunnerArgs(
-  args: readonly string[],
-  deps: StartRunnerDeps = {
-    resolveToken: resolveLocalRunnerToken,
-    fetchStartTarget: fetchLocalRunnerStartTarget,
-    validateToken: validateLocalRunnerToken,
-    buildDependencyStatus: buildRunnerDependencyStatus,
-    resolveEditorRuntime,
-  },
-): Promise<RunnerOptions> {
-  const { cwdArg, flagArgs } = splitStartArgs(args);
-  const values = strictFlagValues(flagArgs);
-
-  if (values.get("help") === true) {
-    process.stdout.write(startHelpText());
-    process.exit(0);
-  }
-
-  rejectStartTargetingFlags(values);
-
-  const kandanUrl = stringValue(values, "kandan-url") ?? "wss://serve.linzumi.com";
-  const requestedCwd = resolveUserPath(cwdArg ?? process.cwd());
-  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({
-    cwd,
-    codexBin,
-    codeServerBin: customCodeServerBin,
-  });
-  assertStartDependencies(initialDependencyStatus);
-  const explicitToken = stringValue(values, "token");
-  const authFilePath = stringValue(values, "auth-file");
-  const callbackHost = stringValue(values, "oauth-callback-host");
-  const reportRejectedCachedToken = () => {
-    process.stderr.write(
-      "Cached Kandan local runner auth was rejected; starting OAuth.\n",
-    );
-  };
-  const token = await deps.resolveToken({
-    kandanUrl,
-    explicitToken,
-    onboarding: "start",
-    authFilePath,
-    callbackHost,
-    reportRejectedCachedToken,
-  });
-  const target = await deps.fetchStartTarget({ kandanUrl, accessToken: token });
-  const tokenMatchesTarget = await deps.validateToken({
-    kandanUrl,
-    accessToken: token,
-    workspaceSlug: target.workspaceSlug,
-    channelSlug: target.channelSlug,
-  });
-  const targetToken = tokenMatchesTarget
-    ? token
-    : await resolveStartTargetToken({
-        kandanUrl,
-        explicitToken,
-        target,
-        authFilePath,
-        callbackHost,
-        resolveToken: deps.resolveToken,
-        reportRejectedCachedToken,
-      });
-  const editorRuntime = await deps.resolveEditorRuntime({
-    kandanUrl,
-    token: targetToken,
-    customCodeServerBin,
-    fetchImpl: trustedFetch(kandanTlsTrustFromEnv()),
-  });
-  const dependencyStatus = await deps.buildDependencyStatus({
-    cwd,
-    codexBin,
-    codeServerBin: editorRuntime.codeServerBin,
-    editorRuntime: editorRuntime.status,
-  });
-  assertStartDependencies(dependencyStatus);
-
-  return {
-    kandanUrl,
-    token: targetToken,
-    runnerId: stringValue(values, "runner-id") ?? `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: target.workspaceSlug,
-      channelSlug: target.channelSlug,
-      kandanThreadId: stringValue(values, "kandan-thread-id"),
-      listenUser: stringValue(values, "listen-user") ?? defaultListenUserFromToken(targetToken),
-      model: stringValue(values, "model"),
-      reasoningEffort: stringValue(values, "reasoning-effort"),
-      sandbox: stringValue(values, "sandbox"),
-      approvalPolicy: stringValue(values, "approval-policy"),
-      streamFlushMs: positiveIntegerValue(values, "stream-flush-ms"),
-    },
-  };
-}
-
-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;
-  readonly target: LocalRunnerStartTarget;
-  readonly authFilePath?: string | undefined;
-  readonly callbackHost?: string | undefined;
-  readonly resolveToken: typeof resolveLocalRunnerToken;
-  readonly reportRejectedCachedToken: () => void;
-}): Promise<string> {
-  if (args.explicitToken !== undefined) {
-    throw new Error(
-      `provided local runner token is not scoped to ${args.target.workspaceSlug}/${args.target.channelSlug}`,
-    );
-  }
-
-  return await args.resolveToken({
-    kandanUrl: args.kandanUrl,
-    workspaceSlug: args.target.workspaceSlug,
-    channelSlug: args.target.channelSlug,
-    authFilePath: args.authFilePath,
-    callbackHost: args.callbackHost,
-    reportRejectedCachedToken: args.reportRejectedCachedToken,
-  });
-}
-
-type RunnerArgsDeps = {
-  readonly resolveToken: typeof resolveLocalRunnerToken;
-  readonly buildDependencyStatus: typeof buildRunnerDependencyStatus;
-  readonly resolveEditorRuntime: typeof resolveEditorRuntime;
-};
-
-export async function parseRunnerArgs(
-  args: readonly string[],
-  deps: RunnerArgsDeps = {
-    resolveToken: resolveLocalRunnerToken,
-    buildDependencyStatus: buildRunnerDependencyStatus,
-    resolveEditorRuntime,
-  },
-): Promise<RunnerOptions> {
-  const values = strictFlagValues(args);
-
-  if (values.get("help") === true) {
-    process.stdout.write(helpText());
-    process.exit(0);
-  }
-
-  if (values.get("version") === true) {
-    process.stdout.write("linzumi 0.0.20-beta\n");
-    process.exit(0);
-  }
-
-  const channelTarget = parseChannelSessionTarget(values);
-  const kandanUrl = required(values, "kandan-url");
-  const cwd = stringValue(values, "cwd") ?? process.cwd();
-  const codexBin = stringValue(values, "codex-bin") ?? "codex";
-  const customCodeServerBin = stringValue(values, "code-server-bin");
-  const explicitToken = stringValue(values, "token");
-  const token = await deps.resolveToken({
-    kandanUrl,
-    explicitToken,
-    workspaceSlug: channelTarget?.workspaceSlug,
-    channelSlug: channelTarget?.channelSlug,
-    authFilePath: stringValue(values, "auth-file"),
-    callbackHost: stringValue(values, "oauth-callback-host"),
-    reportRejectedCachedToken: () => {
-      process.stderr.write(
-        "Cached Kandan local runner auth was rejected; starting OAuth.\n",
-      );
-    },
-  });
-  const channelSession = parseChannelSession(values, token, channelTarget);
-  const editorRuntime = await deps.resolveEditorRuntime({
-    kandanUrl,
-    token,
-    customCodeServerBin,
-    fetchImpl: trustedFetch(kandanTlsTrustFromEnv()),
-  });
-  const dependencyStatus = await deps.buildDependencyStatus({
-    cwd,
-    codexBin,
-    codeServerBin: editorRuntime.codeServerBin,
-    editorRuntime: editorRuntime.status,
-  });
-  assertStartDependencies(dependencyStatus);
-
-  return {
-    kandanUrl,
-    token,
-    runnerId: stringValue(values, "runner-id") ?? `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: values.has("allowed-cwd")
-      ? assertConfiguredAllowedCwds(parseAllowedCwdList(stringValue(values, "allowed-cwd")))
-      : readConfiguredAllowedCwds(),
-    allowedForwardPorts: parseAllowedPortList(
-      stringValue(values, "forward-port"),
-    ),
-    codeServerBin: editorRuntime.codeServerBin,
-    editorRuntime: editorRuntime.runtime,
-    socketFactory: trustedWebSocketFactory(kandanTlsTrustFromEnv()),
-    dependencyStatus,
-    channelSession,
-  };
-}
-
-function strictFlagValues(args: readonly string[]): Map<string, string | true> {
-  const values = new Map<string, string | true>();
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (arg === undefined || !arg.startsWith("--")) {
-      throw new Error(`invalid argument: ${arg ?? ""}`);
-    }
-
-    const key = arg.slice(2);
-    const definition = flagDefinitions.get(key);
-
-    if (definition === undefined) {
-      throw new Error(`invalid flag: --${key}`);
-    }
-
-    if (definition.kind === "boolean") {
-      values.set(key, true);
-      continue;
-    }
-
-    const next = args[index + 1];
-
-    if (next === undefined || next.startsWith("--")) {
-      throw new Error(`missing value for --${key}`);
-    }
-
-    values.set(key, next);
-    index += 1;
-  }
-
-  return values;
-}
-
-function splitStartArgs(args: readonly string[]): {
-  readonly cwdArg: string | undefined;
-  readonly flagArgs: readonly string[];
-} {
-  let cwdArg: string | undefined;
-  const flagArgs: string[] = [];
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (arg === undefined) {
-      continue;
-    }
-
-    if (!arg.startsWith("--")) {
-      if (cwdArg !== undefined) {
-        throw new Error("linzumi start accepts at most one folder path");
-      }
-
-      cwdArg = arg;
-      continue;
-    }
-
-    flagArgs.push(arg);
-    const key = arg.slice(2);
-    const definition = flagDefinitions.get(key);
-
-    if (definition?.kind === "value") {
-      const next = args[index + 1];
-
-      if (next !== undefined) {
-        flagArgs.push(next);
-        index += 1;
-      }
-    }
-  }
-
-  return { cwdArg, flagArgs };
-}
-
-function rejectStartTargetingFlags(values: Map<string, string | true>): void {
-  const unsupportedFlags = ["workspace", "channel"].filter((flag) =>
-    values.has(flag),
-  );
-
-  if (unsupportedFlags.length > 0) {
-    throw new Error(
-      `linzumi start chooses its workspace during browser onboarding; remove ${unsupportedFlags
-        .map((flag) => `--${flag}`)
-        .join(", ")} or use linzumi connect for an explicit workspace/channel.`,
-    );
-  }
-}
-
-function resolveUserPath(pathValue: string): string {
-  if (pathValue === "~") {
-    return homedir();
-  }
-
-  if (pathValue.startsWith("~/")) {
-    return resolve(homedir(), pathValue.slice(2));
-  }
-
-  return resolve(pathValue);
-}
-
-function parseChannelSession(
-  values: Map<string, string | true>,
-  token: string,
-  target:
-    | { readonly workspaceSlug: string; readonly channelSlug: string }
-    | undefined,
-): RunnerOptions["channelSession"] {
-  if (target === undefined) {
-    return undefined;
-  }
-
-  const listenUser =
-    stringValue(values, "listen-user") ?? defaultListenUserFromToken(token);
-
-  return {
-    workspaceSlug: target.workspaceSlug,
-    channelSlug: target.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 parseChannelSessionTarget(
-  values: Map<string, string | true>,
-):
-  | { readonly workspaceSlug: string; readonly channelSlug: string }
-  | undefined {
-  return parseOptionalChannelTarget(values);
-}
-
-function defaultListenUserFromToken(token: string): string {
-  const username = identityFromAccessToken(token).actorUsername;
-
-  if (username !== undefined) {
-    return username;
-  }
-
-  throw new Error(
-    "missing --listen-user and authenticated user is unavailable",
-  );
-}
-
-function parseOptionalChannelTarget(
-  values: Map<string, string | true>,
-):
-  | { readonly workspaceSlug: string; readonly channelSlug: string }
-  | undefined {
-  const channel = stringValue(values, "channel");
-  const workspace = stringValue(values, "workspace");
-
-  if (channel === undefined && workspace === undefined) {
-    return undefined;
-  }
-
-  return channel !== undefined && channel.includes("/")
-    ? parseChannelPath(channel)
-    : {
-        workspaceSlug: workspace ?? required(values, "workspace"),
-        channelSlug: channel ?? required(values, "channel"),
-      };
-}
-
-function parseChannelPath(channel: string): {
-  readonly workspaceSlug: string;
-  readonly channelSlug: string;
-} {
-  const [workspaceSlug, channelSlug, ...rest] = channel.split("/");
-
-  if (
-    workspaceSlug === undefined ||
-    workspaceSlug.trim() === "" ||
-    channelSlug === undefined ||
-    channelSlug.trim() === "" ||
-    rest.length > 0
-  ) {
-    throw new Error("--channel must be CHANNEL or WORKSPACE/CHANNEL");
-  }
-
-  return {
-    workspaceSlug: workspaceSlug.trim(),
-    channelSlug: channelSlug.trim(),
-  };
-}
-
-function required(values: Map<string, string | true>, key: string): string {
-  const value = stringValue(values, key);
-
-  if (value === undefined) {
-    throw new Error(`missing --${key}`);
-  }
-
-  return value;
-}
-
-function stringValue(
-  values: Map<string, string | true>,
-  key: string,
-): string | undefined {
-  const value = values.get(key);
-
-  if (typeof value === "string" && value.trim() !== "") {
-    return value;
-  }
-
-  return undefined;
-}
-
-function positiveIntegerValue(
-  values: Map<string, string | true>,
-  key: string,
-): number | undefined {
-  const value = stringValue(values, key);
-
-  if (value === undefined) {
-    return undefined;
-  }
-
-  const parsed = Number(value);
-
-  if (Number.isInteger(parsed) && parsed > 0) {
-    return parsed;
-  }
-
-  throw new Error(`--${key} must be a positive integer`);
-}
-
-function helpText(): string {
-  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>       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 Linzumi thread instead of announcing a new root
-  --listen-user <user|all>    User whose replies are accepted, default authenticated user
-
-Codex:
-  --cwd <path>                Working directory for Codex, default current directory
-  --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 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>/.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
-    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 --token not-a-jwt --workspace <your-workspace> --channel <your-channel>
-      Missing --listen-user and authenticated user is unavailable.
-    linzumi connect --token "$TOKEN" --listen-users sean
-      Invalid flag: use --listen-user.
-    linzumi connect --workspace <your-workspace> --channel <your-channel> --allowed-cwd /does/not/exist
-      Invalid --allowed-cwd: allowed cwd roots must exist locally.
-    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
-
-Usage:
-  linzumi start <folder> [options]
-
-What it does:
-  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>       Linzumi backend URL, default wss://serve.linzumi.com
-  --token <jwt>               Optional scoped local-runner token override
-  --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>        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 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
-`;
-}
-
-function connectGuideText(): string {
-  return `linzumi start
-
-Fastest path:
-  linzumi start ~/
-
-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.
-
-Advanced (when you already know your workspace and channel):
-  linzumi connect --workspace <your-workspace> --channel <your-channel>
-
-For help:
-  linzumi connect --help
-`;
-}