khala-cli 0.4.6 → 0.4.8

package/README.md

@@ -1,6 +1,6 @@
 # khala-cli
 
-The `khala` command connects your existing Claude Code, Codex or Cursor session to a
+The `khala` command connects your existing Claude Code, Codex, Cursor or OpenCode session to a
 [Khala](https://khala.aiur.team) channel: an MCP server (`khala_join`, `khala_status`,
 `khala_read`, `khala_send`, `khala_event`), delivery hooks that bring channel messages into
 the session, and local channels on this computer. Requires Node 22 or newer.
@@ -40,6 +40,23 @@ under Settings → MCP). Undo with `npx -y khala-cli install cursor --uninstall`
 cannot wake an idle chat; new messages arrive when a chat finishes a turn (Sync) or after a
 tool call (Steer).
 
+## OpenCode
+
+```sh
+npx -y khala-cli install opencode
+```
+
+This installs a stable CLI and, when published on npm, pins `khala-opencode` at the same version in the global
+`~/.config/opencode/opencode.json` (or under `XDG_CONFIG_HOME`). The plugin registers
+Khala's MCP server. If the version is unpublished or the registry check fails, it configures
+MCP-only mode (Async, no wake); re-run `khala install opencode` after updating. Existing
+`opencode.jsonc` files require a manual merge or conversion to JSON before retrying. Restart OpenCode after installation. Existing settings and sibling
+plugins are preserved. Undo with `npx -y khala-cli install opencode --uninstall`.
+
+For unpublished-build testing only, `KHALA_INSTALL_SPEC` selects a CLI tarball and
+`KHALA_OPENCODE_PLUGIN_SPEC` forces plugin mode with a spec such as
+`file:/tmp/khala-opencode-0.1.0.tgz`.
+
 ## Then
 
 Tell your agent "Join this Khala channel: <link>" and open the confirmation link it returns.

package/dist/{chunk-2U4E7AM7.mjs → chunk-2DHIAFEV.mjs}

@@ -1,19 +1,28 @@
 import { createRequire as __khalaCreateRequire } from 'node:module'; const require = __khalaCreateRequire(import.meta.url);
 import {
-  HARNESS_REGISTRY,
-  LEGACY_HARNESSES,
-  harnessInfo
-} from "./chunk-DPW43YNC.mjs";
+  KHALA_AGENT_VERSION
+} from "./chunk-5LIE5GUU.mjs";
+import {
+  bundle
+} from "./chunk-APMWDF6B.mjs";
+import {
+  StateError,
+  ensureStateDir,
+  readJson,
+  stateRoot
+} from "./chunk-CBPLCCRZ.mjs";
 import {
   LISTENING_MODES
-} from "./chunk-AUJEUKVM.mjs";
+} from "./chunk-IQJQ4RF5.mjs";
 import {
+  HARNESS_REGISTRY,
   M1_LABEL_MAX_BYTES,
   array,
   decodeWith,
   displayText,
   elementPath,
   fail,
+  harnessInfo,
   identifier,
   literal,
   nullable,
@@ -28,7 +37,7 @@ import {
   utcTimestamp,
   utf8Length,
   version
-} from "./chunk-SN3STAO2.mjs";
+} from "./chunk-NKX3SLS7.mjs";
 
 // src/client.ts
 var KhalaClientError = class extends Error {
@@ -58,8 +67,8 @@ function fnv1a(value) {
 function defaultHumanColor(ownerId) {
   return HUMAN_COLOR_IDS[fnv1a(ownerId) % HUMAN_COLOR_IDS.length];
 }
-function readHumanColorId(input, path) {
-  if (!isHumanColorId(input)) return fail(path, "invalid_value");
+function readHumanColorId(input, path2) {
+  if (!isHumanColorId(input)) return fail(path2, "invalid_value");
   return input;
 }
 
@@ -74,8 +83,8 @@ function normalizeInitials(input) {
 function isCanonicalInitials(value) {
   return typeof value === "string" && normalizeInitials(value) === value;
 }
-function readHumanInitials(input, path) {
-  if (!isCanonicalInitials(input)) return fail(path, "invalid_value");
+function readHumanInitials(input, path2) {
+  if (!isCanonicalInitials(input)) return fail(path2, "invalid_value");
   return input;
 }
 
@@ -103,9 +112,6 @@ function checkNewUsername(input) {
   if (!checked.ok) return checked;
   return newAgentSuffix.test(checked.name) ? { ok: false, error: "reserved" } : checked;
 }
-var MODEL_NAMES = Object.fromEntries(
-  LEGACY_HARNESSES.map((id) => [id, harnessInfo(id).modelName])
-);
 function defaultAgentName(username, harness, n = 1) {
   return `${username}-${harnessInfo(harness).modelName}${n === 1 ? "" : `-${n}`}`;
 }
@@ -161,90 +167,90 @@ var localRoomKey = (roomId) => {
 var localRoomPath = (roomId, tail) => `/api/local/rooms/${encodeURIComponent(roomId)}/${tail}`;
 var LOCAL_OWNER_ID = "local-owner";
 var LOCAL_OWNER_DEVICE_ID = "KH_LOCAL_OWNER";
-function readLocalRoomId(input, path) {
-  const value = readRoomId(input, path);
-  if (!isLocalRoomId(value)) fail(path, "invalid_value");
+function readLocalRoomId(input, path2) {
+  const value = readRoomId(input, path2);
+  if (!isLocalRoomId(value)) fail(path2, "invalid_value");
   return value;
 }
-function readLocalUserId(input, path) {
-  const value = readMatrixUserId(input, path);
-  if (!isLocalUserId(value)) fail(path, "invalid_value");
+function readLocalUserId(input, path2) {
+  const value = readMatrixUserId(input, path2);
+  if (!isLocalUserId(value)) fail(path2, "invalid_value");
   return value;
 }
-function readLocalEventId(input, path) {
-  const value = identifier(input, path);
-  if (!isLocalEventId(value)) fail(path, "invalid_value");
+function readLocalEventId(input, path2) {
+  const value = identifier(input, path2);
+  if (!isLocalEventId(value)) fail(path2, "invalid_value");
   return value;
 }
-function readLocalTxnId(input, path) {
-  const value = identifier(input, path);
-  if (!isLocalTxnId(value)) fail(path, "invalid_value");
+function readLocalTxnId(input, path2) {
+  const value = identifier(input, path2);
+  if (!isLocalTxnId(value)) fail(path2, "invalid_value");
   return value;
 }
-function readLocalUsername(input, path) {
-  const value = identifier(input, path);
+function readLocalUsername(input, path2) {
+  const value = identifier(input, path2);
   const checked = checkName(value, "username");
-  if (!checked.ok || checked.name !== value) fail(path, "invalid_value");
+  if (!checked.ok || checked.name !== value) fail(path2, "invalid_value");
   return value;
 }
-function readLocalInitials(input, path) {
-  return readHumanInitials(input, path);
+function readLocalInitials(input, path2) {
+  return readHumanInitials(input, path2);
 }
-function record(input, path, required, optional = []) {
+function record(input, path2, required, optional = []) {
   const present = optional.filter((key) => typeof input === "object" && input !== null && Object.hasOwn(input, key));
-  return object(input, path, [...required, ...present]);
+  return object(input, path2, [...required, ...present]);
 }
 function has(input, key) {
   return typeof input === "object" && input !== null && Object.hasOwn(input, key);
 }
-function plainObject(input, path) {
-  if (typeof input !== "object" || input === null || Array.isArray(input)) fail(path, "not_object");
+function plainObject(input, path2) {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) fail(path2, "not_object");
   const prototype = Object.getPrototypeOf(input);
-  if (prototype !== Object.prototype && prototype !== null) fail(path, "not_object");
+  if (prototype !== Object.prototype && prototype !== null) fail(path2, "not_object");
   return input;
 }
-function contentObject(input, path) {
-  const value = plainObject(input, path);
+function contentObject(input, path2) {
+  const value = plainObject(input, path2);
   let encoded;
   try {
     encoded = JSON.stringify(value);
   } catch {
-    fail(path, "invalid_value");
+    fail(path2, "invalid_value");
   }
-  if (utf8Length(encoded) > LOCAL_CONTENT_MAX_BYTES) fail(path, "too_long");
+  if (utf8Length(encoded) > LOCAL_CONTENT_MAX_BYTES) fail(path2, "too_long");
   return value;
 }
-function channelName(input, path) {
-  const value = displayName(input, path);
-  if ([...value].length > LOCAL_CHANNEL_NAME_MAX_CHARS) fail(path, "too_long");
-  if (value !== value.trim()) fail(path, "invalid_value");
+function channelName(input, path2) {
+  const value = displayName(input, path2);
+  if ([...value].length > LOCAL_CHANNEL_NAME_MAX_CHARS) fail(path2, "too_long");
+  if (value !== value.trim()) fail(path2, "invalid_value");
   return value;
 }
-function displayName(input, path) {
-  const value = displayText(input, path, M1_LABEL_MAX_BYTES);
-  if (value.length === 0) fail(path, "empty");
+function displayName(input, path2) {
+  const value = displayText(input, path2, M1_LABEL_MAX_BYTES);
+  if (value.length === 0) fail(path2, "empty");
   return value;
 }
-function seq(input, path) {
-  const value = safeInteger(input, path);
-  if (value === 0) fail(path, "invalid_value");
+function seq(input, path2) {
+  const value = safeInteger(input, path2);
+  if (value === 0) fail(path2, "invalid_value");
   return value;
 }
-function readCreateContent(input, path) {
-  const r = record(input, path, ["name", "createdBy"], ["operationId"]);
+function readCreateContent(input, path2) {
+  const r = record(input, path2, ["name", "createdBy"], ["operationId"]);
   return {
     name: channelName(r.field("name"), r.at("name")),
     createdBy: readLocalUserId(r.field("createdBy"), r.at("createdBy")),
     ...has(input, "operationId") ? { operationId: readLocalTxnId(r.field("operationId"), r.at("operationId")) } : {}
   };
 }
-function readNameContent(input, path) {
-  const r = object(input, path, ["name"]);
+function readNameContent(input, path2) {
+  const r = object(input, path2, ["name"]);
   return { name: channelName(r.field("name"), r.at("name")) };
 }
-function readMemberContent(input, path) {
+function readMemberContent(input, path2) {
   const modeKey = "com.khala.listening_mode";
-  const r = record(input, path, ["user", "membership", "displayname", "kind"], ["harness", "invitedBy", modeKey]);
+  const r = record(input, path2, ["user", "membership", "displayname", "kind"], ["harness", "invitedBy", modeKey]);
   const kind = literal(r.field("kind"), r.at("kind"), ["human", "agent"]);
   if (kind === "human") {
     for (const key of ["harness", modeKey]) if (has(input, key)) fail(r.at(key), "invalid_value");
@@ -266,28 +272,28 @@ function decodeLocalMemberContent(input) {
   return decodeWith(() => readMemberContent(input, ""));
 }
 var EVENT_TYPES = ["m.room.create", "m.room.name", "m.room.member", "m.room.message", "com.khala.event.v1", "com.khala.listening_mode.v1"];
-function readContent(input, path, type) {
+function readContent(input, path2, type) {
   switch (type) {
     case "m.room.create":
-      return readCreateContent(input, path);
+      return readCreateContent(input, path2);
     case "m.room.name":
-      return readNameContent(input, path);
+      return readNameContent(input, path2);
     case "m.room.member":
-      return readMemberContent(input, path);
+      return readMemberContent(input, path2);
     default: {
-      const content = contentObject(input, path);
+      const content = contentObject(input, path2);
       if (type === "m.room.message") {
-        literal(content["msgtype"], `${path}.msgtype`, ["m.text", "m.notice"]);
-        const body = text(content["body"], `${path}.body`, LOCAL_CONTENT_MAX_BYTES);
-        if (body.length === 0) fail(`${path}.body`, "empty");
-        if (body.length > LOCAL_BODY_MAX_CHARS) fail(`${path}.body`, "too_long");
+        literal(content["msgtype"], `${path2}.msgtype`, ["m.text", "m.notice"]);
+        const body = text(content["body"], `${path2}.body`, LOCAL_CONTENT_MAX_BYTES);
+        if (body.length === 0) fail(`${path2}.body`, "empty");
+        if (body.length > LOCAL_BODY_MAX_CHARS) fail(`${path2}.body`, "too_long");
       }
       return content;
     }
   }
 }
-function readEvent(input, path) {
-  const r = record(input, path, ["seq", "eventId", "roomId", "type", "sender", "ts", "content"], ["txnId", "previousContent"]);
+function readEvent(input, path2) {
+  const r = record(input, path2, ["seq", "eventId", "roomId", "type", "sender", "ts", "content"], ["txnId", "previousContent"]);
   const type = literal(r.field("type"), r.at("type"), EVENT_TYPES);
   return {
     seq: seq(r.field("seq"), r.at("seq")),
@@ -304,16 +310,16 @@ function readEvent(input, path) {
 function decodeLocalEvent(input) {
   return decodeWith(() => readEvent(input, ""));
 }
-function limitedArray(input, path, max, read) {
-  const values = array(input, path);
-  if (values.length > max) fail(path, "too_long");
-  return values.map((value, i) => read(value, elementPath(path, i)));
+function limitedArray(input, path2, max, read) {
+  const values = array(input, path2);
+  if (values.length > max) fail(path2, "too_long");
+  return values.map((value, i) => read(value, elementPath(path2, i)));
 }
-function readEvents(input, path, history) {
-  const events = limitedArray(input, path, history ? LOCAL_HISTORY_LIMIT_MAX : LOCAL_EVENTS_PAGE_MAX, readEvent);
+function readEvents(input, path2, history) {
+  const events = limitedArray(input, path2, history ? LOCAL_HISTORY_LIMIT_MAX : LOCAL_EVENTS_PAGE_MAX, readEvent);
   events.forEach((event, i) => {
-    if (i > 0 && event.seq <= events[i - 1].seq) fail(`${elementPath(path, i)}.seq`, "invalid_value");
-    if (history && event.type !== "m.room.message" && event.type !== "com.khala.event.v1") fail(`${elementPath(path, i)}.type`, "invalid_value");
+    if (i > 0 && event.seq <= events[i - 1].seq) fail(`${elementPath(path2, i)}.seq`, "invalid_value");
+    if (history && event.type !== "m.room.message" && event.type !== "com.khala.event.v1") fail(`${elementPath(path2, i)}.type`, "invalid_value");
   });
   return events;
 }
@@ -335,8 +341,8 @@ function decodeLocalHistoryPage(input) {
     };
   });
 }
-function readLocalMe(input, path) {
-  const r = record(input, path, ["userId", "roomId", "roomName", "membership", "displayName"], ["invitedBy"]);
+function readLocalMe(input, path2) {
+  const r = record(input, path2, ["userId", "roomId", "roomName", "membership", "displayName"], ["invitedBy"]);
   return {
     userId: readLocalUserId(r.field("userId"), r.at("userId")),
     roomId: readLocalRoomId(r.field("roomId"), r.at("roomId")),
@@ -349,8 +355,8 @@ function readLocalMe(input, path) {
 function decodeLocalMe(input) {
   return decodeWith(() => readLocalMe(input, ""));
 }
-function readLocalJoined(input, path) {
-  const r = record(input, path, ["seq", "ts"], []);
+function readLocalJoined(input, path2) {
+  const r = record(input, path2, ["seq", "ts"], []);
   return {
     seq: seq(r.field("seq"), r.at("seq")),
     ts: safeInteger(r.field("ts"), r.at("ts"))
@@ -359,8 +365,8 @@ function readLocalJoined(input, path) {
 function decodeLocalJoined(input) {
   return decodeWith(() => readLocalJoined(input, ""));
 }
-function readLocalSendResult(input, path) {
-  const r = record(input, path, ["eventId"], []);
+function readLocalSendResult(input, path2) {
+  const r = record(input, path2, ["eventId"], []);
   return {
     eventId: readLocalEventId(r.field("eventId"), r.at("eventId"))
   };
@@ -368,8 +374,8 @@ function readLocalSendResult(input, path) {
 function decodeLocalSendResult(input) {
   return decodeWith(() => readLocalSendResult(input, ""));
 }
-function readLocalErrorBody(input, path) {
-  const r = record(input, path, ["error"], []);
+function readLocalErrorBody(input, path2) {
+  const r = record(input, path2, ["error"], []);
   return {
     error: identifier(r.field("error"), r.at("error"))
   };
@@ -377,8 +383,8 @@ function readLocalErrorBody(input, path) {
 function decodeLocalErrorBody(input) {
   return decodeWith(() => readLocalErrorBody(input, ""));
 }
-function readOwnerProfile(input, path) {
-  const r = record(input, path, ["v", "username", "color", "initials", "updatedAt"]);
+function readOwnerProfile(input, path2) {
+  const r = record(input, path2, ["v", "username", "color", "initials", "updatedAt"]);
   return {
     v: version(r.field("v"), r.at("v")),
     username: readLocalUsername(r.field("username"), r.at("username")),
@@ -390,11 +396,11 @@ function readOwnerProfile(input, path) {
 function decodeOwnerProfile(input) {
   return decodeWith(() => readOwnerProfile(input, ""));
 }
-function nullableInitials(input, path) {
-  return nullable(input, (value) => readLocalInitials(value, path));
+function nullableInitials(input, path2) {
+  return nullable(input, (value) => readLocalInitials(value, path2));
 }
-function readMember(input, path) {
-  const r = record(input, path, ["userId", "participantId", "ownerId", "deviceId", "displayName", "kind", "membership"], ["harness", "ownerLabel", "listeningMode"]);
+function readMember(input, path2) {
+  const r = record(input, path2, ["userId", "participantId", "ownerId", "deviceId", "displayName", "kind", "membership"], ["harness", "ownerLabel", "listeningMode"]);
   const userId = readLocalUserId(r.field("userId"), r.at("userId"));
   const participantId = readLocalUserId(r.field("participantId"), r.at("participantId"));
   if (participantId !== userId) fail(r.at("participantId"), "invalid_value");
@@ -450,18 +456,18 @@ function decodeHelperFile(input) {
     };
   });
 }
-function readSha256(input, path) {
-  const value = identifier(input, path);
-  if (!/^[0-9a-f]{64}$/u.test(value)) fail(path, "invalid_value");
+function readSha256(input, path2) {
+  const value = identifier(input, path2);
+  if (!/^[0-9a-f]{64}$/u.test(value)) fail(path2, "invalid_value");
   return value;
 }
 function decodeChannelSecrets(input) {
   return decodeWith(() => {
     const r = object(input, "", ["v", "links", "members"]);
     const links = Object.fromEntries(Object.entries(plainObject(r.field("links"), r.at("links"))).map(([key, value]) => {
-      const path = `${r.at("links")}.${key}`;
-      readSha256(key, path);
-      const link = record(value, path, ["expiresAt", "kind"], ["consumedAt"]);
+      const path2 = `${r.at("links")}.${key}`;
+      readSha256(key, path2);
+      const link = record(value, path2, ["expiresAt", "kind"], ["consumedAt"]);
       return [key, {
         expiresAt: utcTimestamp(link.field("expiresAt"), link.at("expiresAt")),
         kind: literal(link.field("kind"), link.at("kind"), ["join"]),
@@ -469,9 +475,9 @@ function decodeChannelSecrets(input) {
       }];
     }));
     const members = Object.fromEntries(Object.entries(plainObject(r.field("members"), r.at("members"))).map(([key, value]) => {
-      const path = `${r.at("members")}.${key}`;
-      if (!isLocalAgentUserId(key)) fail(path, "invalid_value");
-      const member = record(value, path, ["tokenSha256"], ["sessionKey"]);
+      const path2 = `${r.at("members")}.${key}`;
+      if (!isLocalAgentUserId(key)) fail(path2, "invalid_value");
+      const member = record(value, path2, ["tokenSha256"], ["sessionKey"]);
       return [key, {
         tokenSha256: readSha256(member.field("tokenSha256"), member.at("tokenSha256")),
         ...has(value, "sessionKey") ? { sessionKey: readSha256(member.field("sessionKey"), member.at("sessionKey")) } : {}
@@ -481,6 +487,191 @@ function decodeChannelSecrets(input) {
   });
 }
 
+// src/local/lifecycle.ts
+import * as fs from "node:fs/promises";
+import { close as closeFd } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as sleepDefault } from "node:timers/promises";
+import { spawn as nodeSpawn } from "node:child_process";
+function helperPaths(env = process.env) {
+  const root = path.join(stateRoot(env), "local");
+  const candidate = /^\d{1,5}$/u.test(env.KHALA_LOCAL_PORT ?? "") ? Number(env.KHALA_LOCAL_PORT) : 0;
+  const port = candidate >= 1 && candidate <= 65535 ? candidate : LOCAL_DEFAULT_PORT;
+  return { root, helperFile: path.join(root, "helper.json"), logFile: path.join(root, "helper.log"), port, origin: `http://127.0.0.1:${port}` };
+}
+async function readHelperFile(env = process.env) {
+  const decoded = decodeHelperFile(await readJson(helperPaths(env).helperFile));
+  if (!decoded.ok) return null;
+  const file = decoded.value;
+  if (!Number.isSafeInteger(file.pid) || file.pid <= 0 || !Number.isSafeInteger(file.port) || file.port <= 0 || file.port > 65535 || file.origin !== `http://127.0.0.1:${file.port}` || !/^[A-Za-z0-9_-]{43}$/u.test(file.adminToken)) return null;
+  return file;
+}
+function helperBinPath() {
+  return fileURLToPath(bundle ? new URL("./khala.mjs", import.meta.url) : new URL("../../bin/khala.mjs", import.meta.url));
+}
+var HELPER_ENV_ALLOWLIST = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "LANG",
+  "LC_ALL",
+  "TMPDIR",
+  "XDG_STATE_HOME",
+  "NODE_OPTIONS",
+  "KHALA_EGRESS_LOG",
+  "KHALA_LOCAL_PORT",
+  "KHALA_LOCAL_IDLE_MS",
+  "KHALA_LOCAL_WEB_DIR"
+];
+function helperChildEnv(env) {
+  const childEnv = {};
+  for (const key of HELPER_ENV_ALLOWLIST) if (env[key] !== void 0) childEnv[key] = env[key];
+  return childEnv;
+}
+var attempts = /* @__PURE__ */ new Map();
+var restarted = false;
+var recovering = /* @__PURE__ */ new Map();
+function olderHelperVersion(version2) {
+  if (typeof version2 !== "string") return true;
+  const parse = (value) => /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value);
+  const helper = parse(version2), cli = parse(KHALA_AGENT_VERSION);
+  if (!helper || !cli) return true;
+  for (let i = 1; i <= 3; i++) {
+    if (Number(helper[i]) !== Number(cli[i])) return Number(helper[i]) < Number(cli[i]);
+  }
+  if (helper[4] === cli[4]) return false;
+  if (!helper[4] || !cli[4]) return Boolean(helper[4]);
+  const a = helper[4].split("."), b = cli[4].split(".");
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if (a[i] === b[i]) continue;
+    if (a[i] === void 0 || b[i] === void 0) return a[i] === void 0;
+    const an = /^\d+$/u.test(a[i]), bn = /^\d+$/u.test(b[i]);
+    if (an && bn) return Number(a[i]) < Number(b[i]);
+    if (an !== bn) return an;
+    return a[i] < b[i];
+  }
+  return false;
+}
+async function healthy(fetchImpl, file) {
+  try {
+    const response = await fetchImpl(`${file.origin}/healthz`, { signal: AbortSignal.timeout(500) });
+    if (response.status !== 200) {
+      await response.body?.cancel();
+      return null;
+    }
+    const body = await response.json();
+    return typeof body === "object" && body !== null && "ok" in body && body.ok === true && "pid" in body && body.pid === file.pid ? { version: "version" in body ? body.version : void 0 } : null;
+  } catch {
+    return null;
+  }
+}
+function connection(file) {
+  return { origin: file.origin, adminToken: file.adminToken };
+}
+async function attempt(env, deps, restartOrigin) {
+  const fetchImpl = deps.fetch ?? globalThis.fetch;
+  const spawn = deps.spawn ?? ((command, argv, options) => nodeSpawn(command, [...argv], options));
+  const sleep = deps.sleep ?? sleepDefault;
+  const now = deps.now ?? Date.now;
+  const existing = await readHelperFile(env);
+  const status = existing ? await healthy(fetchImpl, existing) : null;
+  if (existing && status) {
+    if (!olderHelperVersion(status.version) && restartOrigin === void 0 || restarted) return connection(existing);
+    if (restartOrigin !== void 0 && existing.origin !== restartOrigin) return connection(existing);
+    restarted = true;
+    recovering.set(helperPaths(env).helperFile, existing.origin);
+    try {
+      const response = await fetchImpl(`${existing.origin}/api/local/shutdown`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${existing.adminToken}` },
+        signal: AbortSignal.timeout(2e3)
+      });
+      await response.body?.cancel();
+      if (response.status !== 204) throw new Error("shutdown_failed");
+      const deadline = now() + 2e3;
+      for (let i = 0; i < 20; i++) {
+        if (!await healthy(fetchImpl, existing)) break;
+        if (now() >= deadline || i === 19) throw new Error("shutdown_timeout");
+        await sleep(100);
+      }
+    } catch {
+      const refreshed = await readHelperFile(env);
+      if (refreshed && await healthy(fetchImpl, refreshed)) return connection(refreshed);
+    }
+  }
+  const paths = helperPaths(env);
+  try {
+    await ensureStateDir(path.join(paths.root, "channels"));
+    let handle;
+    let fd;
+    let spawnFailed = false;
+    try {
+      if (deps.openLog) fd = await deps.openLog(paths.logFile);
+      else {
+        handle = await fs.open(paths.logFile, "a", 384);
+        await handle.chmod(384);
+        fd = handle.fd;
+      }
+      const child = spawn(process.execPath, [helperBinPath(), "local", "serve"], {
+        detached: true,
+        stdio: ["ignore", fd, fd],
+        env: helperChildEnv(existing && status ? { ...env, KHALA_LOCAL_PORT: String(existing.port) } : env),
+        cwd: paths.root,
+        shell: false
+      });
+      child.on("error", () => {
+        spawnFailed = true;
+      });
+      child.unref();
+    } finally {
+      if (handle) await handle.close();
+      else if (fd !== void 0) {
+        const descriptor = fd;
+        await new Promise((resolve) => {
+          closeFd(descriptor, () => resolve());
+        });
+      }
+    }
+    const deadline = now() + 5e3;
+    while (!spawnFailed && now() < deadline) {
+      const file = await readHelperFile(env);
+      if (file && await healthy(fetchImpl, file) && !spawnFailed && now() <= deadline) return connection(file);
+      if (spawnFailed || now() >= deadline) break;
+      await sleep(100);
+    }
+  } catch (error) {
+    if (error instanceof StateError) throw error;
+  }
+  throw new KhalaClientError("internal_error", "helper_unavailable");
+}
+function ensureHelper(env = process.env, deps = {}, restartOrigin) {
+  const key = helperPaths(env).helperFile;
+  const pending = attempts.get(key);
+  if (pending) return pending;
+  const promise = attempt(env, deps, restartOrigin).finally(() => {
+    attempts.delete(key);
+    recovering.delete(key);
+  });
+  attempts.set(key, promise);
+  return promise;
+}
+async function restartHelper(origin, env = process.env, deps = {}) {
+  const key = helperPaths(env).helperFile;
+  const pending = attempts.get(key);
+  if (pending) {
+    const shareRecovery = !restarted || recovering.get(key) === origin;
+    const connection2 = await pending;
+    if (shareRecovery && restarted && connection2.origin === origin) return true;
+  }
+  if (restarted) return false;
+  const file = await readHelperFile(env);
+  if (!file || file.origin !== origin) return false;
+  await ensureHelper(env, deps, origin);
+  return restarted;
+}
+
 export {
   KhalaClientError,
   isHumanColorId,
@@ -488,11 +679,9 @@ export {
   normalizeInitials,
   checkName,
   checkNewUsername,
-  MODEL_NAMES,
   defaultAgentName,
   isDefaultAgentName,
   LOCAL_OWNER_USER_ID,
-  LOCAL_DEFAULT_PORT,
   LOCAL_LINK_TTL_MS,
   LOCAL_LONG_POLL_MAX_S,
   LOCAL_IDLE_EXIT_MS,
@@ -518,6 +707,10 @@ export {
   decodeLocalErrorBody,
   decodeOwnerProfile,
   decodeLocalMembersResponse,
-  decodeHelperFile,
-  decodeChannelSecrets
+  decodeChannelSecrets,
+  helperPaths,
+  readHelperFile,
+  olderHelperVersion,
+  ensureHelper,
+  restartHelper
 };

package/dist/{chunk-CWHGNVZV.mjs → chunk-2VCAW4GH.mjs}

@@ -2,7 +2,7 @@ import { createRequire as __khalaCreateRequire } from 'node:module'; const requi
 import {
   decodeChannelEvent,
   formatChannelEventLine
-} from "./chunk-P5CP32X2.mjs";
+} from "./chunk-54XFVSEC.mjs";
 
 // src/events/receive.ts
 function toEventInboxEntry(base, rawContent) {

package/dist/{chunk-P5CP32X2.mjs → chunk-54XFVSEC.mjs}

@@ -9,7 +9,7 @@ import {
   utcTimestamp,
   utf8Length,
   version
-} from "./chunk-SN3STAO2.mjs";
+} from "./chunk-NKX3SLS7.mjs";
 
 // ../contracts/src/m1/channel-event.ts
 var CHANNEL_EVENT_TYPE = "com.khala.event.v1";