@linzumi/cli 0.0.5-beta → 0.0.6-beta

package/src/pendingKandanMessageQueue.ts

@@ -0,0 +1,109 @@
+/*
+- Date: 2026-04-26
+  Spec: kandan/server_v2/plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Provides the local Codex channel session with an amortized O(1)
+  pending Kandan message queue so long shared sessions avoid repeated
+  `Array.shift()` reindexing while preserving interrupt fusion order.
+*/
+import {
+  interruptQueuedMessages,
+  type QueueInterruptResult,
+  type QueuedKandanMessage,
+} from "./kandanQueue";
+
+export type PendingKandanMessageQueue = {
+  items: QueuedKandanMessage[];
+  head: number;
+};
+
+export function createPendingKandanMessageQueue(): PendingKandanMessageQueue {
+  return {
+    items: [],
+    head: 0,
+  };
+}
+
+export function pendingKandanMessageQueueLength(
+  queue: PendingKandanMessageQueue,
+): number {
+  return queue.items.length - queue.head;
+}
+
+export function enqueuePendingKandanMessage(
+  queue: PendingKandanMessageQueue,
+  message: QueuedKandanMessage,
+): void {
+  queue.items.push(message);
+}
+
+export function dequeuePendingKandanMessage(
+  queue: PendingKandanMessageQueue,
+): QueuedKandanMessage | undefined {
+  const message = queue.items[queue.head];
+
+  if (message === undefined) {
+    compactPendingKandanMessageQueue(queue);
+    return undefined;
+  }
+
+  queue.head = queue.head + 1;
+  compactPendingKandanMessageQueue(queue);
+  return message;
+}
+
+export function requeuePendingKandanMessageFront(
+  queue: PendingKandanMessageQueue,
+  message: QueuedKandanMessage,
+): void {
+  if (queue.head > 0) {
+    queue.head = queue.head - 1;
+    queue.items[queue.head] = message;
+    return;
+  }
+
+  queue.items.unshift(message);
+}
+
+export function interruptPendingKandanMessages(
+  queue: PendingKandanMessageQueue,
+  throughSeq: number | undefined,
+): QueueInterruptResult {
+  const result = interruptQueuedMessages(pendingKandanMessages(queue), throughSeq);
+
+  if (result.ok) {
+    replacePendingKandanMessages(queue, result.queue);
+  }
+
+  return result;
+}
+
+function replacePendingKandanMessages(
+  queue: PendingKandanMessageQueue,
+  messages: QueuedKandanMessage[],
+): void {
+  queue.items = messages;
+  queue.head = 0;
+}
+
+function pendingKandanMessages(
+  queue: PendingKandanMessageQueue,
+): QueuedKandanMessage[] {
+  return queue.head === 0 ? queue.items : queue.items.slice(queue.head);
+}
+
+function compactPendingKandanMessageQueue(queue: PendingKandanMessageQueue): void {
+  if (queue.head === 0) {
+    return;
+  }
+
+  if (queue.head >= queue.items.length) {
+    queue.items = [];
+    queue.head = 0;
+    return;
+  }
+
+  if (queue.head > queue.items.length / 2) {
+    queue.items = queue.items.slice(queue.head);
+    queue.head = 0;
+  }
+}

package/src/phoenix.ts

@@ -54,6 +54,14 @@ export type PhoenixClient = {
 
 export function phoenixWebsocketUrl(baseUrl: string, token: string): string {
   const parsed = new URL(baseUrl);
+  switch (parsed.protocol) {
+    case "http:":
+      parsed.protocol = "ws:";
+      break;
+    case "https:":
+      parsed.protocol = "wss:";
+      break;
+  }
   parsed.pathname = parsed.pathname.replace(/\/$/, "") + "/socket/websocket";
   parsed.searchParams.set("token", token);
   parsed.searchParams.set("vsn", "2.0.0");

package/src/portForwardApproval.ts

@@ -0,0 +1,181 @@
+/*
+- Date: 2026-04-27
+  Spec: plans/2026-04-26-local-runner-subdomain-forwarding-epr.md
+  Relationship: Keeps local runner port-forward approval and revocation policy
+  pure so security decisions are tested directly instead of hiding inside the
+  channel-session orchestration module.
+*/
+import { type JsonObject } from "./protocol";
+import {
+  commandLabel,
+  sameForwardCandidate,
+  type PortForwardCandidate,
+} from "./portForwardWatcher";
+
+export type PendingPortForwardRequest = {
+  readonly requestId: string;
+  readonly port: number;
+  readonly pid: number;
+  readonly command: string;
+  readonly cwd?: string | undefined;
+  readonly sourceSeq: number;
+};
+
+export type PortForwardCandidateReview =
+  | {
+      readonly type: "skip";
+      readonly reason:
+        | "thread_not_bound"
+        | "suppressed_port"
+        | "already_pending"
+        | "already_approved"
+        | "recently_dismissed";
+    }
+  | { readonly type: "remember_approved_target"; readonly target: PortForwardCandidate }
+  | {
+      readonly type: "revoke_and_prompt";
+      readonly revoked: PortForwardCandidate;
+      readonly candidate: PortForwardCandidate;
+      readonly reason: "listener_changed";
+    }
+  | { readonly type: "prompt"; readonly candidate: PortForwardCandidate };
+
+export function reviewPortForwardCandidate(options: {
+  readonly candidate: PortForwardCandidate;
+  readonly threadBound: boolean;
+  readonly suppressedPorts?: ReadonlySet<number> | undefined;
+  readonly approvedPorts: ReadonlySet<number>;
+  readonly approvedTargets: ReadonlyMap<number, PortForwardCandidate>;
+  readonly dismissedTargets?: ReadonlyMap<number, PortForwardCandidate> | undefined;
+  readonly pendingRequests: readonly PendingPortForwardRequest[];
+}): PortForwardCandidateReview {
+  if (!options.threadBound) {
+    return { type: "skip", reason: "thread_not_bound" };
+  }
+
+  if (options.suppressedPorts?.has(options.candidate.port) === true) {
+    return { type: "skip", reason: "suppressed_port" };
+  }
+
+  const dismissedTarget = options.dismissedTargets?.get(options.candidate.port);
+
+  if (
+    dismissedTarget !== undefined &&
+    sameDismissedPortForwardTarget(dismissedTarget, options.candidate)
+  ) {
+    return { type: "skip", reason: "recently_dismissed" };
+  }
+
+  if (options.approvedPorts.has(options.candidate.port)) {
+    const approvedTarget = options.approvedTargets.get(options.candidate.port);
+
+    if (approvedTarget === undefined) {
+      return { type: "remember_approved_target", target: options.candidate };
+    }
+
+    if (sameForwardCandidate(approvedTarget, options.candidate)) {
+      return { type: "skip", reason: "already_approved" };
+    }
+
+    return {
+      type: "revoke_and_prompt",
+      revoked: approvedTarget,
+      candidate: options.candidate,
+      reason: "listener_changed",
+    };
+  }
+
+  if (options.pendingRequests.some(request => request.port === options.candidate.port)) {
+    return { type: "skip", reason: "already_pending" };
+  }
+
+  return { type: "prompt", candidate: options.candidate };
+}
+
+export function pendingRequestFromCandidate(options: {
+  readonly requestId: string;
+  readonly sourceSeq: number;
+  readonly candidate: PortForwardCandidate;
+}): PendingPortForwardRequest {
+  return {
+    requestId: options.requestId,
+    port: options.candidate.port,
+    pid: options.candidate.pid,
+    command: options.candidate.command,
+    ...(options.candidate.cwd === undefined ? {} : { cwd: options.candidate.cwd }),
+    sourceSeq: options.sourceSeq,
+  };
+}
+
+export function approvedTargetFromRequest(
+  request: PendingPortForwardRequest,
+): PortForwardCandidate {
+  return {
+    port: request.port,
+    pid: request.pid,
+    command: request.command,
+    ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
+  };
+}
+
+export function portForwardPromptLabel(candidate: PortForwardCandidate): string {
+  return commandLabel(candidate.command);
+}
+
+export function portForwardPromptBody(
+  candidate: PortForwardCandidate,
+  requestId: string,
+): string {
+  const label = portForwardPromptLabel(candidate);
+  const cwdLine = candidate.cwd === undefined ? undefined : `Working directory: ${candidate.cwd}`;
+
+  return [
+    `Detected ${label} listening from a descendant process.`,
+    `Port: ${candidate.port}`,
+    `PID: ${candidate.pid}`,
+    `Command: ${candidate.command}`,
+    ...(cwdLine === undefined ? [] : [cwdLine]),
+    "Kandan can open this as an authenticated HTTP, HTTPS, or WebSocket preview. It does not expose arbitrary TCP or UDP protocols.",
+    "Open this preview in Kandan?",
+    "",
+    `Fallback commands: ${portForwardDecisionCommand("approve", requestId)} or ${portForwardDecisionCommand("deny", requestId)}`,
+  ].join("\n");
+}
+
+export function portForwardPromptReason(candidate: PortForwardCandidate): string {
+  return [
+    `Port ${candidate.port}`,
+    `PID ${candidate.pid}`,
+    `command: ${candidate.command}`,
+    ...(candidate.cwd === undefined ? [] : [`cwd: ${candidate.cwd}`]),
+    "preview protocols: HTTP, HTTPS, WebSocket",
+  ].join(" / ");
+}
+
+export function portForwardDecisionCommand(
+  decision: "approve" | "deny",
+  requestId: string,
+): string {
+  return `/kandan ${decision}-port-forward ${requestId}`;
+}
+
+export function forwardPreviewPath(runnerId: string, port: number): string {
+  return `/local-codex-runners/${encodeURIComponent(runnerId)}/forwards/${port}/preview`;
+}
+
+export function revocationCapabilities(
+  capabilities: JsonObject | undefined,
+  port: number,
+): JsonObject {
+  return {
+    ...(capabilities ?? {}),
+    revokedPorts: [port],
+  };
+}
+
+function sameDismissedPortForwardTarget(
+  left: PortForwardCandidate,
+  right: PortForwardCandidate,
+): boolean {
+  return left.port === right.port && left.command === right.command && left.cwd === right.cwd;
+}

package/src/portForwardWatcher.ts

@@ -0,0 +1,404 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
+  Relationship: Detects descendant listener ports for the local Codex runner so
+  Kandan can prompt the authorized listener user before exposing a local
+  service through the runner forward route.
+*/
+import { spawnSync } from "node:child_process";
+import { basename } from "node:path";
+
+export type ProcessRow = {
+  readonly pid: number;
+  readonly ppid: number;
+  readonly command: string;
+};
+
+export type ListenSocketRow = {
+  readonly pid: number;
+  readonly port: number;
+  readonly command: string;
+};
+
+export type PortForwardCandidate = {
+  readonly port: number;
+  readonly pid: number;
+  readonly command: string;
+  readonly cwd?: string | undefined;
+};
+
+export type PortForwardWatcher = {
+  readonly close: () => void;
+};
+
+export type PortForwardWatcherOptions = {
+  readonly rootPid?: number | undefined;
+  readonly intervalMs?: number | undefined;
+  readonly debounceMs?: number | undefined;
+  readonly scanProcesses?: (() => readonly ProcessRow[]) | undefined;
+  readonly scanListenSockets?: (() => readonly ListenSocketRow[]) | undefined;
+  readonly scanProcessCwds?: ((pids: readonly number[]) => ReadonlyMap<number, string>) | undefined;
+  readonly nowMs?: (() => number) | undefined;
+  readonly onCandidate: (candidate: PortForwardCandidate) => void | Promise<void>;
+  readonly onError?: ((error: Error) => void) | undefined;
+};
+
+const defaultIntervalMs = 2_000;
+const defaultDebounceMs = 750;
+
+export type ObservedPortForwardCandidate = {
+  readonly candidate: PortForwardCandidate;
+  readonly firstSeenAtMs: number;
+};
+
+export function startPortForwardWatcher(
+  options: PortForwardWatcherOptions,
+): PortForwardWatcher {
+  const rootPid = options.rootPid ?? process.pid;
+  const intervalMs = options.intervalMs ?? defaultIntervalMs;
+  const debounceMs = options.debounceMs ?? defaultDebounceMs;
+  const scanProcesses = options.scanProcesses ?? readProcessRows;
+  const scanListenSockets = options.scanListenSockets ?? readListenSocketRows;
+  const scanProcessCwds = options.scanProcessCwds ?? readProcessCwdRows;
+  const nowMs = options.nowMs ?? Date.now;
+  const candidateStabilityByPort = new Map<number, ObservedPortForwardCandidate>();
+  const emittedByPort = new Map<number, PortForwardCandidate>();
+  const inFlight = { value: false };
+
+  const scan = () => {
+    if (inFlight.value) {
+      return;
+    }
+
+    inFlight.value = true;
+    void Promise.resolve()
+      .then(async () => {
+        const descendants = descendantPidSet(scanProcesses(), rootPid);
+        const sockets = scanListenSockets();
+        const candidatePids = sockets
+          .filter(socket => descendants.has(socket.pid))
+          .map(socket => socket.pid);
+        const candidates = detectedForwardCandidates(
+          sockets,
+          descendants,
+          scanProcessCwds(candidatePids),
+        );
+        const stable = stableForwardCandidates(
+          candidateStabilityByPort,
+          candidates,
+          nowMs(),
+          debounceMs,
+        );
+        const changes = changedForwardCandidates(emittedByPort, stable.stableCandidates);
+        candidateStabilityByPort.clear();
+        emittedByPort.clear();
+
+        for (const [port, observed] of stable.nextObservedByPort) {
+          candidateStabilityByPort.set(port, observed);
+        }
+
+        for (const [port, candidate] of changes.nextObservedByPort) {
+          emittedByPort.set(port, candidate);
+        }
+
+        for (const candidate of changes.changedCandidates) {
+          await options.onCandidate(candidate);
+        }
+      })
+      .catch(error => {
+        options.onError?.(error instanceof Error ? error : new Error(String(error)));
+      })
+      .finally(() => {
+        inFlight.value = false;
+      });
+  };
+
+  scan();
+  const interval = setInterval(scan, intervalMs);
+
+  return {
+    close: () => clearInterval(interval),
+  };
+}
+
+export function changedForwardCandidates(
+  previousObservedByPort: ReadonlyMap<number, PortForwardCandidate>,
+  candidates: readonly PortForwardCandidate[],
+): {
+  readonly nextObservedByPort: Map<number, PortForwardCandidate>;
+  readonly changedCandidates: PortForwardCandidate[];
+} {
+  const nextObservedByPort = new Map<number, PortForwardCandidate>();
+  const changedCandidates: PortForwardCandidate[] = [];
+
+  for (const candidate of candidates) {
+    nextObservedByPort.set(candidate.port, candidate);
+    const previous = previousObservedByPort.get(candidate.port);
+
+    if (previous === undefined || !sameForwardCandidate(previous, candidate)) {
+      changedCandidates.push(candidate);
+    }
+  }
+
+  return { nextObservedByPort, changedCandidates };
+}
+
+export function stableForwardCandidates(
+  previousObservedByPort: ReadonlyMap<number, ObservedPortForwardCandidate>,
+  candidates: readonly PortForwardCandidate[],
+  nowMs: number,
+  debounceMs: number,
+): {
+  readonly nextObservedByPort: Map<number, ObservedPortForwardCandidate>;
+  readonly stableCandidates: PortForwardCandidate[];
+} {
+  const nextObservedByPort = new Map<number, ObservedPortForwardCandidate>();
+  const stableCandidates: PortForwardCandidate[] = [];
+
+  for (const candidate of candidates) {
+    const previous = previousObservedByPort.get(candidate.port);
+    const firstSeenAtMs =
+      previous !== undefined && sameForwardCandidate(previous.candidate, candidate)
+        ? previous.firstSeenAtMs
+        : nowMs;
+    const observed = { candidate, firstSeenAtMs };
+    nextObservedByPort.set(candidate.port, observed);
+
+    if (debounceMs <= 0 || nowMs - firstSeenAtMs >= debounceMs) {
+      stableCandidates.push(candidate);
+    }
+  }
+
+  return { nextObservedByPort, stableCandidates };
+}
+
+export function sameForwardCandidate(
+  left: PortForwardCandidate,
+  right: PortForwardCandidate,
+): boolean {
+  return (
+    left.port === right.port &&
+    left.pid === right.pid &&
+    left.command === right.command &&
+    left.cwd === right.cwd
+  );
+}
+
+export function descendantPidSet(
+  rows: readonly ProcessRow[],
+  rootPid: number,
+): Set<number> {
+  const childrenByParent = new Map<number, number[]>();
+
+  for (const row of rows) {
+    const existing = childrenByParent.get(row.ppid) ?? [];
+    childrenByParent.set(row.ppid, [...existing, row.pid]);
+  }
+
+  const descendants = new Set<number>();
+  const queue = [...(childrenByParent.get(rootPid) ?? [])];
+
+  while (queue.length > 0) {
+    const pid = queue.shift();
+
+    if (pid === undefined || descendants.has(pid)) {
+      continue;
+    }
+
+    descendants.add(pid);
+    queue.push(...(childrenByParent.get(pid) ?? []));
+  }
+
+  return descendants;
+}
+
+export function detectedForwardCandidates(
+  sockets: readonly ListenSocketRow[],
+  descendantPids: ReadonlySet<number>,
+  processCwds: ReadonlyMap<number, string> = new Map(),
+): PortForwardCandidate[] {
+  return sockets
+    .filter(socket => descendantPids.has(socket.pid))
+    .filter(socket => socket.port > 0 && socket.port < 65_536)
+    .sort((left, right) => left.port - right.port)
+    .map(socket => {
+      const cwd = processCwds.get(socket.pid);
+
+      return {
+        port: socket.port,
+        pid: socket.pid,
+        command: socket.command,
+        ...(cwd === undefined ? {} : { cwd }),
+      };
+    });
+}
+
+export function parseProcessRows(output: string): ProcessRow[] {
+  return output
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line !== "")
+    .map(line => {
+      const match = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+
+      if (match === null) {
+        return undefined;
+      }
+
+      return {
+        pid: Number(match[1]),
+        ppid: Number(match[2]),
+        command: match[3] ?? "",
+      };
+    })
+    .filter((row): row is ProcessRow => row !== undefined);
+}
+
+export function parseLsofListenRows(output: string): ListenSocketRow[] {
+  const rows: ListenSocketRow[] = [];
+  let currentPid: number | undefined;
+  let currentCommand: string | undefined;
+
+  for (const rawLine of output.split("\n")) {
+    const line = rawLine.trim();
+
+    if (line.startsWith("p")) {
+      currentPid = Number(line.slice(1));
+      currentCommand = undefined;
+      continue;
+    }
+
+    if (line.startsWith("c")) {
+      currentCommand = line.slice(1);
+      continue;
+    }
+
+    if (!line.startsWith("n") || currentPid === undefined) {
+      continue;
+    }
+
+    const port = portFromLsofName(line.slice(1));
+
+    if (port !== undefined) {
+      rows.push({
+        pid: currentPid,
+        port,
+        command: currentCommand ?? "unknown",
+      });
+    }
+  }
+
+  return rows;
+}
+
+export function parseLsofCwdRows(output: string): Map<number, string> {
+  const rows = new Map<number, string>();
+  let currentPid: number | undefined;
+
+  for (const rawLine of output.split("\n")) {
+    const line = rawLine.trim();
+
+    if (line.startsWith("p")) {
+      currentPid = Number(line.slice(1));
+      continue;
+    }
+
+    if (line.startsWith("n") && currentPid !== undefined) {
+      const cwd = line.slice(1).trim();
+
+      if (cwd !== "") {
+        rows.set(currentPid, cwd);
+      }
+    }
+  }
+
+  return rows;
+}
+
+function readProcessRows(): ProcessRow[] {
+  const result = spawnSync("ps", ["-axo", "pid=,ppid=,command="], {
+    encoding: "utf8",
+  });
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(`ps failed with status ${result.status}: ${result.stderr}`);
+  }
+
+  return parseProcessRows(result.stdout);
+}
+
+function readListenSocketRows(): ListenSocketRow[] {
+  const result = spawnSync(
+    "lsof",
+    ["-nP", "-iTCP", "-sTCP:LISTEN", "-FpPcn"],
+    { encoding: "utf8" },
+  );
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    if (result.status === 1 && result.stdout.trim() === "") {
+      return [];
+    }
+
+    throw new Error(`lsof failed with status ${result.status}: ${result.stderr}`);
+  }
+
+  return parseLsofListenRows(result.stdout);
+}
+
+function readProcessCwdRows(pids: readonly number[]): ReadonlyMap<number, string> {
+  const uniquePids = [...new Set(pids)].filter(pid => Number.isInteger(pid) && pid > 0);
+
+  if (uniquePids.length === 0) {
+    return new Map();
+  }
+
+  const result = spawnSync(
+    "lsof",
+    ["-a", "-p", uniquePids.join(","), "-d", "cwd", "-Fn"],
+    { encoding: "utf8" },
+  );
+
+  if (result.error !== undefined) {
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    if (result.status === 1 && result.stdout.trim() === "") {
+      return new Map();
+    }
+
+    throw new Error(`lsof cwd failed with status ${result.status}: ${result.stderr}`);
+  }
+
+  return parseLsofCwdRows(result.stdout);
+}
+
+function portFromLsofName(name: string): number | undefined {
+  const match = name.match(/:(\d+)(?:\s|\(|$)/);
+
+  if (match === null) {
+    return undefined;
+  }
+
+  const port = Number(match[1]);
+
+  return Number.isInteger(port) ? port : undefined;
+}
+
+export function commandLabel(command: string): string {
+  const trimmed = command.trim();
+
+  if (trimmed === "") {
+    return "unknown";
+  }
+
+  return basename(trimmed.split(/\s+/)[0] ?? trimmed);
+}