@sma1lboy/kobe 0.7.1 → 0.7.3

package/dist/cli/index.js

@@ -70,7 +70,7 @@ var init_package = __esm(() => {
   package_default = {
     $schema: "https://json.schemastore.org/package.json",
     name: "@sma1lboy/kobe",
-    version: "0.7.1",
+    version: "0.7.3",
     description: "TUI orchestrator for Claude Code (codename)",
     type: "module",
     packageManager: "bun@1.3.13",
@@ -748,7 +748,8 @@ function coerceTask(value) {
   if (!isTaskStatus(v.status))
     return null;
   const archived = typeof v.archived === "boolean" ? v.archived : false;
-  const healedStatus = v.status === "done" && !archived ? "in_progress" : v.status;
+  const kind = v.kind === "main" ? "main" : "task";
+  const healedStatus = kind === "main" ? v.status === "in_progress" || v.status === "done" ? "backlog" : v.status : v.status === "done" && !archived ? "in_progress" : v.status;
   return {
     id: toTaskId(v.id),
     title: v.title,
@@ -758,7 +759,7 @@ function coerceTask(value) {
     status: healedStatus,
     archived,
     pinned: typeof v.pinned === "boolean" ? v.pinned : false,
-    kind: v.kind === "main" ? "main" : "task",
+    kind,
     vendor: isVendorId(v.vendor) ? v.vendor : DEFAULT_TASK_VENDOR,
     prStatus: coercePRStatus(v.prStatus),
     createdAt: v.createdAt,
@@ -3227,6 +3228,111 @@ var init_protocol = __esm(() => {
   CHANNEL_NAMES = ["task.snapshot", "active-task", "update"];
 });
 
+// src/daemon/paths.ts
+import { createHash as createHash2 } from "crypto";
+import { homedir as homedir3, tmpdir } from "os";
+import { join as join3 } from "path";
+function shortHomeTag(homeDir2) {
+  return createHash2("sha1").update(homeDir2).digest("hex").slice(0, 8);
+}
+function fitSocketPath(naturalPath, homeDir2, role, pidTag) {
+  if (Buffer.byteLength(naturalPath, "utf8") <= SOCKET_PATH_SAFETY_LIMIT)
+    return naturalPath;
+  const tag = shortHomeTag(homeDir2);
+  const suffix = pidTag === undefined ? "" : `-${pidTag}`;
+  const fallback = join3(tmpdir(), `kobe-${tag}-${role}${suffix}.sock`);
+  if (Buffer.byteLength(fallback, "utf8") <= SOCKET_PATH_SAFETY_LIMIT)
+    return fallback;
+  throw new Error(`kobe socket path exceeds ${SOCKET_PATH_SAFETY_LIMIT} bytes even after fallback: ${fallback}`);
+}
+function defaultDaemonSocketPath(homeDir2) {
+  const override = process.env.KOBE_DAEMON_SOCKET_PATH;
+  if (override && override.length > 0)
+    return override;
+  const explicit = homeDir2 ?? process.env.KOBE_HOME_DIR;
+  if (explicit && explicit.length > 0) {
+    return fitSocketPath(join3(explicit, ".kobe", "daemon.sock"), explicit, "daemon");
+  }
+  const runtimeDir = process.env.XDG_RUNTIME_DIR;
+  if (runtimeDir && runtimeDir.length > 0) {
+    return fitSocketPath(join3(runtimeDir, "kobe.sock"), runtimeDir, "daemon");
+  }
+  const home = homedir3();
+  return fitSocketPath(join3(home, ".kobe", "daemon.sock"), home, "daemon");
+}
+function defaultDaemonPidPath(homeDir2 = process.env.KOBE_HOME_DIR ?? homedir3()) {
+  const override = process.env.KOBE_DAEMON_PID_PATH;
+  if (override && override.length > 0)
+    return override;
+  return join3(homeDir2, ".kobe", "daemon.pid");
+}
+function defaultDaemonLogPath(homeDir2 = process.env.KOBE_HOME_DIR ?? homedir3()) {
+  return join3(homeDir2, ".kobe", "daemon.log");
+}
+function defaultClientLogPath(homeDir2 = process.env.KOBE_HOME_DIR ?? homedir3()) {
+  return join3(homeDir2, ".kobe", "client.log");
+}
+var SOCKET_PATH_SAFETY_LIMIT = 100;
+var init_paths2 = () => {};
+
+// src/client/client-log.ts
+import { appendFile, mkdir as mkdir2 } from "fs/promises";
+import { dirname as dirname3 } from "path";
+function setClientLogContext(ctx) {
+  context = ctx;
+}
+function coerceError(err) {
+  if (err instanceof Error)
+    return { message: err.message, stack: err.stack };
+  let text;
+  try {
+    text = typeof err === "string" ? err : JSON.stringify(err);
+  } catch {
+    text = String(err);
+  }
+  return { message: text };
+}
+function formatClientEntry(subsystem, message, now = new Date) {
+  return `[${now.toISOString()}] client ${context} [${subsystem}] pid=${process.pid}: ${message}
+`;
+}
+function warnOnce() {
+  if (warnedOnce)
+    return;
+  warnedOnce = true;
+  try {
+    process.stderr.write(`[kobe] client log write failed; continuing without it
+`);
+  } catch {}
+}
+function append(line) {
+  const path3 = defaultClientLogPath();
+  writeChain = writeChain.then(async () => {
+    try {
+      await appendFile(path3, line);
+    } catch (err) {
+      if (err?.code === "ENOENT") {
+        await mkdir2(dirname3(path3), { recursive: true });
+        await appendFile(path3, line);
+      } else {
+        throw err;
+      }
+    }
+  }).catch(() => warnOnce());
+}
+function logClient(subsystem, message) {
+  append(formatClientEntry(subsystem, message));
+}
+function logClientError(subsystem, err) {
+  const e = coerceError(err);
+  append(formatClientEntry(subsystem, e.stack ?? e.message));
+}
+var context = "client", warnedOnce = false, writeChain;
+var init_client_log = __esm(() => {
+  init_paths2();
+  writeChain = Promise.resolve();
+});
+
 // src/client/index.ts
 import { connect } from "net";
 
@@ -3259,6 +3365,9 @@ class KobeDaemonClient {
     p.then(cleanup, cleanup);
     return p;
   }
+  get isDisposed() {
+    return this.disposed;
+  }
   close() {
     this.disposed = true;
     this.socket?.end();
@@ -3372,7 +3481,13 @@ class KobeDaemonClient {
     }
   }
   onLine(line) {
-    const frame = JSON.parse(line);
+    let frame;
+    try {
+      frame = JSON.parse(line);
+    } catch (err) {
+      logClientError("client-frame", err);
+      return;
+    }
     if (frame.type === "event") {
       this.emit(frame);
       return;
@@ -3397,6 +3512,7 @@ class KobeDaemonClient {
 }
 var init_client = __esm(() => {
   init_protocol();
+  init_client_log();
 });
 
 // src/engine/claude-code-local/normalize.ts
@@ -3446,8 +3562,8 @@ function normalizeClaudeContent(content) {
 }
 
 // src/engine/claude-code-local/history.ts
-import { appendFile, mkdir as mkdir2, readFile as readFile2, readdir, stat, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
-import { homedir as homedir3 } from "os";
+import { appendFile as appendFile2, mkdir as mkdir3, readFile as readFile2, readdir, stat, unlink as unlink2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir4 } from "os";
 import path3 from "path";
 function encodeCwd(cwd) {
   return cwd.replace(/[/.]/g, "-");
@@ -3455,7 +3571,7 @@ function encodeCwd(cwd) {
 async function listSessionFilesForWorktree(worktree) {
   if (!worktree)
     return [];
-  const dir = path3.join(homedir3(), ".claude", "projects", encodeCwd(worktree));
+  const dir = path3.join(homedir4(), ".claude", "projects", encodeCwd(worktree));
   let entries;
   try {
     entries = await readdir(dir);
@@ -3561,7 +3677,7 @@ var defaultDeps;
 var init_history = __esm(() => {
   defaultDeps = {
     projectsDir() {
-      return path3.join(homedir3(), ".claude", "projects");
+      return path3.join(homedir4(), ".claude", "projects");
     },
     async readdir(p) {
       try {
@@ -3663,7 +3779,7 @@ function validPositive(v) {
 
 // src/engine/codex-local/history.ts
 import { readFile as readFile3, readdir as readdir2, stat as stat2, unlink as unlink3 } from "fs/promises";
-import { homedir as homedir4 } from "os";
+import { homedir as homedir5 } from "os";
 import path4 from "path";
 async function listRolloutFiles(deps = defaultDeps2) {
   const root = deps.sessionsDir();
@@ -3994,7 +4110,7 @@ var init_history2 = __esm(() => {
   init_synthetic();
   defaultDeps2 = {
     sessionsDir() {
-      return path4.join(homedir4(), ".codex", "sessions");
+      return path4.join(homedir5(), ".codex", "sessions");
     },
     async readdir(p) {
       try {
@@ -4028,14 +4144,14 @@ function copilotUsageToSnapshot(value) {
     output += numberOr2(metrics.usage.outputTokens, 0);
     cached += numberOr2(metrics.usage.cacheReadTokens, 0);
   }
-  const context = numberOr2(value.currentTokens, 0);
-  if (input === 0 && output === 0 && cached === 0 && context === 0)
+  const context2 = numberOr2(value.currentTokens, 0);
+  if (input === 0 && output === 0 && cached === 0 && context2 === 0)
     return;
   return {
     input_tokens: input,
     output_tokens: output,
     ...cached > 0 ? { cache_read_input_tokens: cached } : {},
-    ...context > 0 ? { context_tokens: context } : {}
+    ...context2 > 0 ? { context_tokens: context2 } : {}
   };
 }
 function isObject4(v) {
@@ -4047,7 +4163,7 @@ function numberOr2(value, fallback) {
 
 // src/engine/copilot-local/history.ts
 import { readFile as readFile4, readdir as readdir3, rm, stat as stat3 } from "fs/promises";
-import { homedir as homedir5 } from "os";
+import { homedir as homedir6 } from "os";
 import path5 from "path";
 async function listSessionDirs(deps = defaultDeps3) {
   const root = path5.join(deps.copilotDir(), "session-state");
@@ -4216,7 +4332,7 @@ var init_history3 = __esm(() => {
       const override = process.env.COPILOT_HOME?.trim();
       if (override)
         return override;
-      return path5.join(homedir5(), ".copilot");
+      return path5.join(homedir6(), ".copilot");
     },
     async readdir(p) {
       try {
@@ -4409,7 +4525,7 @@ __export(exports_client, {
   CLAUDE_ROLE_OPTION: () => CLAUDE_ROLE_OPTION,
   CHAT_TAB_SESSION_ID_OPTION: () => CHAT_TAB_SESSION_ID_OPTION
 });
-import { homedir as homedir6 } from "os";
+import { homedir as homedir7 } from "os";
 function tmuxArgs(...args) {
   return ["tmux", "-L", KOBE_TMUX_SOCKET, ...args];
 }
@@ -4670,7 +4786,7 @@ var KOBE_TMUX_SOCKET, SAFE_SPAWN_CWD, PANE_ROLE_OPTION = "@kobe_role", CLAUDE_RO
 var init_client2 = __esm(() => {
   init_invocation();
   KOBE_TMUX_SOCKET = process.env.KOBE_TMUX_SOCKET?.trim() || "kobe";
-  SAFE_SPAWN_CWD = homedir6() || "/";
+  SAFE_SPAWN_CWD = homedir7() || "/";
   CLAUDE_ROLE_OPTION = PANE_ROLE_OPTION;
 });
 
@@ -4768,6 +4884,13 @@ function formatDaemonError(subsystem, err, now = new Date) {
 function logDaemonError(subsystem, err) {
   process.stderr.write(formatDaemonError(subsystem, err));
 }
+function formatDaemonInfo(subsystem, message, now = new Date) {
+  return `[${now.toISOString()}] daemon [${subsystem}]: ${message}
+`;
+}
+function logDaemonInfo(subsystem, message) {
+  process.stderr.write(formatDaemonInfo(subsystem, message));
+}
 function installDaemonCrashHandlers(log = (l) => process.stderr.write(l)) {
   if (onRejection || onException)
     return;
@@ -4843,54 +4966,10 @@ class DaemonEventBus {
   }
 }
 
-// src/daemon/paths.ts
-import { createHash as createHash2 } from "crypto";
-import { homedir as homedir7, tmpdir } from "os";
-import { join as join3 } from "path";
-function shortHomeTag(homeDir2) {
-  return createHash2("sha1").update(homeDir2).digest("hex").slice(0, 8);
-}
-function fitSocketPath(naturalPath, homeDir2, role, pidTag) {
-  if (Buffer.byteLength(naturalPath, "utf8") <= SOCKET_PATH_SAFETY_LIMIT)
-    return naturalPath;
-  const tag = shortHomeTag(homeDir2);
-  const suffix = pidTag === undefined ? "" : `-${pidTag}`;
-  const fallback = join3(tmpdir(), `kobe-${tag}-${role}${suffix}.sock`);
-  if (Buffer.byteLength(fallback, "utf8") <= SOCKET_PATH_SAFETY_LIMIT)
-    return fallback;
-  throw new Error(`kobe socket path exceeds ${SOCKET_PATH_SAFETY_LIMIT} bytes even after fallback: ${fallback}`);
-}
-function defaultDaemonSocketPath(homeDir2) {
-  const override = process.env.KOBE_DAEMON_SOCKET_PATH;
-  if (override && override.length > 0)
-    return override;
-  const explicit = homeDir2 ?? process.env.KOBE_HOME_DIR;
-  if (explicit && explicit.length > 0) {
-    return fitSocketPath(join3(explicit, ".kobe", "daemon.sock"), explicit, "daemon");
-  }
-  const runtimeDir = process.env.XDG_RUNTIME_DIR;
-  if (runtimeDir && runtimeDir.length > 0) {
-    return fitSocketPath(join3(runtimeDir, "kobe.sock"), runtimeDir, "daemon");
-  }
-  const home = homedir7();
-  return fitSocketPath(join3(home, ".kobe", "daemon.sock"), home, "daemon");
-}
-function defaultDaemonPidPath(homeDir2 = process.env.KOBE_HOME_DIR ?? homedir7()) {
-  const override = process.env.KOBE_DAEMON_PID_PATH;
-  if (override && override.length > 0)
-    return override;
-  return join3(homeDir2, ".kobe", "daemon.pid");
-}
-function defaultDaemonLogPath(homeDir2 = process.env.KOBE_HOME_DIR ?? homedir7()) {
-  return join3(homeDir2, ".kobe", "daemon.log");
-}
-var SOCKET_PATH_SAFETY_LIMIT = 100;
-var init_paths2 = () => {};
-
 // src/daemon/server.ts
-import { mkdir as mkdir3, readFile as readFile5, unlink as unlink4, writeFile as writeFile3 } from "fs/promises";
+import { mkdir as mkdir4, readFile as readFile5, unlink as unlink4, writeFile as writeFile3 } from "fs/promises";
 import { createServer } from "net";
-import { dirname as dirname3 } from "path";
+import { dirname as dirname4 } from "path";
 function resolveIdleGraceMs() {
   const raw = process.env.KOBE_DAEMON_IDLE_GRACE_MS;
   if (raw === undefined)
@@ -4924,10 +5003,12 @@ async function startDaemonServer(orch, options = {}) {
     if (stopping || guiCount() > 0)
       return;
     cancelIdleTimer();
+    logDaemonInfo("idle", `last gui gone \u2014 arming ${idleGraceMs}ms idle-stop grace`);
     idleTimer = setTimeout(() => {
       idleTimer = null;
       if (stopping || guiCount() > 0)
         return;
+      logDaemonInfo("idle", "grace elapsed with no gui \u2014 self-stopping");
       stopSoon().catch((err) => logDaemonError("daemon-idle-shutdown", err));
     }, idleGraceMs);
     idleTimer.unref?.();
@@ -4936,8 +5017,8 @@ async function startDaemonServer(orch, options = {}) {
   bus.onPublish((event) => {
     broadcast(clients, { type: "event", name: event.channel, payload: event.payload });
   });
-  await mkdir3(dirname3(socketPath), { recursive: true });
-  await mkdir3(dirname3(pidPath), { recursive: true });
+  await mkdir4(dirname4(socketPath), { recursive: true });
+  await mkdir4(dirname4(pidPath), { recursive: true });
   await unlink4(socketPath).catch(() => {});
   const server = createServer((socket) => {
     const client = {
@@ -4956,6 +5037,9 @@ async function startDaemonServer(orch, options = {}) {
     socket.on("error", () => {});
     socket.on("close", () => {
       clients.delete(client);
+      if (client.subscribed) {
+        logDaemonInfo("conn", `client #${client.id} (${client.holdsLifetime ? "gui" : "pane"}) disconnected \u2014 ${clients.size} client(s), ${guiCount()} gui left`);
+      }
       if (client.holdsLifetime)
         maybeArmIdleShutdown();
     });
@@ -5148,6 +5232,7 @@ async function startDaemonServer(orch, options = {}) {
         client.holdsLifetime = role === "gui";
         if (client.holdsLifetime)
           cancelIdleTimer();
+        logDaemonInfo("conn", `client #${client.id} subscribed as ${role} \u2014 ${clients.size} client(s), ${guiCount()} gui`);
         for (const event of bus.snapshot()) {
           writeFrame(client, { type: "event", name: event.channel, payload: event.payload });
         }
@@ -5327,13 +5412,13 @@ __export(exports_daemon_process, {
 });
 import { spawn } from "child_process";
 import { closeSync, existsSync, mkdirSync as mkdirSync2, openSync } from "fs";
-import { dirname as dirname4, resolve as resolve2 } from "path";
+import { dirname as dirname5, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function spawnDetachedDaemon(command, args, env, logPath) {
   let stdio = "ignore";
   let logFd;
   try {
-    mkdirSync2(dirname4(logPath), { recursive: true });
+    mkdirSync2(dirname5(logPath), { recursive: true });
     logFd = openSync(logPath, "a");
     stdio = ["ignore", logFd, logFd];
   } catch {
@@ -5400,7 +5485,7 @@ function resolveKobeSpawn(subcommand) {
   if (here.startsWith("/$bunfs") || here.startsWith("B:\\~BUN")) {
     return [process.execPath, ...subcommand];
   }
-  const dir = dirname4(here);
+  const dir = dirname5(here);
   const sourceEntry = resolve2(dir, "../cli/index.ts");
   if (existsSync(sourceEntry))
     return [process.execPath, sourceEntry, ...subcommand];
@@ -5946,7 +6031,7 @@ async function refreshKobeWorkspacePanes(session) {
         keepAlive(envPrefix + tasksPaneCommand(inv, { initialTaskId: taskId }))
       ], ["set-option", "-p", "-t", tasksPane.paneId, "@kobe_role", "tasks"], ["set-option", "-p", "-t", tasksPane.paneId, PANE_VERSION_OPTION, CURRENT_VERSION]);
     }
-    if (opsPane && claudePane) {
+    if (opsPane) {
       commands.push([
         "respawn-pane",
         "-k",
@@ -5957,7 +6042,7 @@ async function refreshKobeWorkspacePanes(session) {
         keepAlive(envPrefix + opsPaneCommand({
           cwd,
           taskId,
-          claudePaneId: claudePane,
+          claudePaneId: claudePane ?? null,
           cliInvocation: inv,
           vendor
         }))
@@ -6242,32 +6327,74 @@ var init_worktree_changes = __esm(() => {
 // src/cli/api-cmd.ts
 var exports_api_cmd = {};
 __export(exports_api_cmd, {
+  verbSchema: () => verbSchema,
+  verbHelp: () => verbHelp,
+  validateAgainstSpec: () => validateAgainstSpec,
+  schemaIndex: () => schemaIndex,
   runApiSubcommand: () => runApiSubcommand,
   parseFlags: () => parseFlags,
   parseAgentsSpec: () => parseAgentsSpec,
+  fullSchema: () => fullSchema,
+  findVerb: () => findVerb,
   apiUsage: () => apiUsage,
+  VERB_GROUPS: () => VERB_GROUPS,
+  VERBS: () => VERBS,
   FANOUT_CAP: () => FANOUT_CAP,
   ApiError: () => ApiError,
-  API_VERBS: () => API_VERBS
+  API_VERBS: () => API_VERBS,
+  API_SCHEMA_VERSION: () => API_SCHEMA_VERSION
 });
 import { resolve as resolve4 } from "path";
-function parseFlags(argv) {
+function groupOf(verbName) {
+  for (const [group, names] of Object.entries(VERB_GROUPS)) {
+    if (names.includes(verbName))
+      return group;
+  }
+  return "other";
+}
+async function handleSchema(_client, parsed) {
+  const { flags } = parsed;
+  const verbName = optional(flags, "verb");
+  if (verbName) {
+    const v = findVerb(verbName);
+    if (!v)
+      throw new ApiError(`unknown verb: ${verbName}`, "BAD_VERB");
+    return verbSchema(v);
+  }
+  const group = optional(flags, "group");
+  if (group)
+    return groupSchema(group);
+  if (optionalBool(flags, "all"))
+    return fullSchema();
+  return schemaIndex();
+}
+function findVerb(name) {
+  const canonical = VERB_ALIASES[name] ?? name;
+  return VERBS.find((v) => v.name === canonical);
+}
+function parseFlags(argv, booleanFlags = new Set) {
   const flags = new Map;
   let pretty = false;
+  let help = false;
   for (let i = 0;i < argv.length; i++) {
     const arg = argv[i];
-    if (!arg.startsWith("--")) {
+    if (!arg.startsWith("--") && arg !== "-h") {
       throw new ApiError(`unexpected positional arg: ${arg}`, "BAD_FLAG");
     }
+    if (arg === "-h") {
+      help = true;
+      continue;
+    }
     const eq = arg.indexOf("=");
     if (eq !== -1) {
       const key2 = arg.slice(2, eq);
       const value = arg.slice(eq + 1);
-      if (key2 === "pretty") {
+      if (key2 === "pretty")
         pretty = value !== "false" && value !== "0";
-      } else {
+      else if (key2 === "help")
+        help = value !== "false" && value !== "0";
+      else
         flags.set(key2, value);
-      }
       continue;
     }
     const key = arg.slice(2);
@@ -6275,6 +6402,14 @@ function parseFlags(argv) {
       pretty = true;
       continue;
     }
+    if (key === "help") {
+      help = true;
+      continue;
+    }
+    if (booleanFlags.has(key)) {
+      flags.set(key, "true");
+      continue;
+    }
     const next = argv[i + 1];
     if (next === undefined || next.startsWith("--")) {
       throw new ApiError(`flag --${key} requires a value`, "BAD_FLAG");
@@ -6282,19 +6417,50 @@ function parseFlags(argv) {
     flags.set(key, next);
     i += 1;
   }
-  return { flags, pretty };
+  return { flags, pretty, help };
+}
+function validateAgainstSpec(verb, flags) {
+  const known = new Set(verb.flags.map((f) => f.name));
+  for (const key of flags.keys()) {
+    if (!known.has(key)) {
+      throw new ApiError(`unknown flag --${key} for "${verb.name}". Run \`kobe api ${verb.name} --help\``, "BAD_FLAG");
+    }
+  }
+  for (const f of verb.flags) {
+    if (f.required && !flags.get(f.name))
+      throw new ApiError(`--${f.name} is required for "${verb.name}"`, "MISSING_FLAG");
+    if (f.type === "enum" && f.values) {
+      const raw = flags.get(f.name);
+      if (raw !== undefined && !f.values.includes(raw)) {
+        throw new ApiError(`--${f.name} must be one of ${f.values.join(", ")}`, "BAD_FLAG");
+      }
+    }
+    if (f.type === "int") {
+      const raw = flags.get(f.name);
+      if (raw !== undefined) {
+        const n = Number.parseInt(raw, 10);
+        if (!Number.isInteger(n) || n <= 0)
+          throw new ApiError(`--${f.name} must be a positive integer`, "BAD_FLAG");
+      }
+    }
+  }
 }
 function required(flags, key) {
   const v = flags.get(key);
-  if (v === undefined || v.length === 0) {
+  if (v === undefined || v.length === 0)
     throw new ApiError(`--${key} is required`, "MISSING_FLAG");
-  }
   return v;
 }
 function optional(flags, key) {
   const v = flags.get(key);
   return v && v.length > 0 ? v : undefined;
 }
+function requireEnum(flags, key, values) {
+  const v = required(flags, key);
+  if (!values.includes(v))
+    throw new ApiError(`--${key} must be one of ${values.join(", ")}`, "BAD_FLAG");
+  return v;
+}
 function optionalVendor2(flags) {
   const raw = optional(flags, "vendor");
   if (raw === undefined)
@@ -6304,16 +6470,28 @@ function optionalVendor2(flags) {
   }
   return raw;
 }
+function optionalBool(flags, key) {
+  const raw = optional(flags, key);
+  if (raw === undefined)
+    return;
+  if (["true", "1", "yes"].includes(raw))
+    return true;
+  if (["false", "0", "no"].includes(raw))
+    return false;
+  throw new ApiError(`--${key} must be a boolean (true/false)`, "BAD_FLAG");
+}
 function optionalPositiveInt(flags, key) {
   const raw = optional(flags, key);
   if (raw === undefined)
     return;
   const n = Number.parseInt(raw, 10);
-  if (!Number.isInteger(n) || n <= 0) {
+  if (!Number.isInteger(n) || n <= 0)
     throw new ApiError(`--${key} must be a positive integer`, "BAD_FLAG");
-  }
   return n;
 }
+function resolveRepoFlag(repo) {
+  return resolve4(process.cwd(), repo);
+}
 function parseAgentsSpec(spec) {
   const out = [];
   for (const part of spec.split(",")) {
@@ -6338,19 +6516,102 @@ function parseAgentsSpec(spec) {
     throw new ApiError('--agents specified no agents (e.g. "claude:2,codex:1")', "BAD_FLAG");
   return out;
 }
+function flagJson(f) {
+  return {
+    name: f.name,
+    type: f.type,
+    required: f.required ?? false,
+    ...f.values ? { values: f.values } : {},
+    ...f.default !== undefined ? { default: f.default } : {},
+    ...f.placeholder ? { placeholder: f.placeholder } : {},
+    description: f.description
+  };
+}
+function verbSchema(v) {
+  return {
+    name: v.name,
+    group: groupOf(v.name),
+    summary: v.summary,
+    offline: v.offline ?? false,
+    flags: v.flags.map(flagJson)
+  };
+}
+function schemaIndex() {
+  return {
+    apiVersion: API_SCHEMA_VERSION,
+    kobeVersion: CURRENT_VERSION,
+    hint: "Compact index. Drill into ONE verb: `kobe api schema --verb <name>` (or `kobe api <verb> --help`). One group: `--group <g>`. Whole spec: `--all`.",
+    groups: VERB_GROUPS,
+    verbs: VERBS.map((v) => ({ name: v.name, group: groupOf(v.name), summary: v.summary })),
+    globalFlags: GLOBAL_FLAGS,
+    aliases: VERB_ALIASES
+  };
+}
+function groupSchema(group) {
+  const names = VERB_GROUPS[group];
+  if (!names) {
+    throw new ApiError(`unknown group: ${group}. Groups: ${Object.keys(VERB_GROUPS).join(", ")}`, "BAD_FLAG");
+  }
+  return {
+    group,
+    verbs: names.map((n) => {
+      const v = findVerb(n);
+      return { name: n, summary: v?.summary ?? "" };
+    })
+  };
+}
+function fullSchema() {
+  return {
+    apiVersion: API_SCHEMA_VERSION,
+    kobeVersion: CURRENT_VERSION,
+    output: {
+      success: "one JSON object on stdout, newline-terminated, exit 0",
+      error: '{"error":{"message","code"}} on stderr, exit != 0',
+      pretty: "--pretty indents stdout JSON"
+    },
+    globalFlags: GLOBAL_FLAGS,
+    aliases: VERB_ALIASES,
+    groups: VERB_GROUPS,
+    verbs: VERBS.map(verbSchema)
+  };
+}
+function flagSignature(verb) {
+  return verb.flags.map((f) => {
+    const meta = f.type === "enum" && f.values ? f.values.join("|") : f.placeholder ?? (f.type === "bool" ? "" : "X");
+    const core = meta ? `--${f.name} ${meta}` : `--${f.name}`;
+    return f.required ? core : `[${core}]`;
+  }).join(" ");
+}
+function verbHelp(verb) {
+  const lines = [`kobe api ${verb.name} ${flagSignature(verb)}`.trimEnd(), "", verb.summary, ""];
+  const alias = Object.entries(VERB_ALIASES).find(([, canon]) => canon === verb.name)?.[0];
+  if (alias)
+    lines.push(`Alias: ${alias}`, "");
+  if (verb.flags.length > 0) {
+    lines.push("Flags:");
+    for (const f of verb.flags) {
+      const req = f.required ? " (required)" : "";
+      const def = f.default !== undefined ? ` [default: ${f.default}]` : "";
+      const vals = f.type === "enum" && f.values ? ` {${f.values.join("|")}}` : "";
+      lines.push(`  --${f.name}${vals}${req}${def}  ${f.description}`);
+    }
+    lines.push("");
+  }
+  lines.push("Global: [--pretty] [--help]");
+  return lines.join(`
+`);
+}
 function apiUsage() {
+  const rows = VERBS.map((v) => `  ${v.name.padEnd(18)} ${v.summary}`);
   return [
-    "usage: kobe api <verb> [flags] [--pretty]",
+    "usage: kobe api <verb> [flags] [--pretty] [--help]",
+    "",
+    "Explore the full surface (names, flags, types) with:  kobe api schema",
     "",
     "verbs:",
-    "  spawn-task  --repo PATH [--prompt TEXT] [--title T] [--base-branch B] [--vendor V]",
-    "  fan-out     --repo PATH --prompt TEXT [--count N | --agents claude:2,codex:1] [--base-branch B]",
-    "  send        [--task-id ID] --prompt TEXT",
-    "  get-task    --task-id ID",
-    "  collect     --task-ids a,b,c | --repo PATH",
-    "  list",
+    ...rows,
     "",
-    "Output is one JSON object on stdout (exit 0); errors are JSON on stderr (exit \u2260 0)."
+    "Output is one JSON object on stdout (exit 0); errors are JSON on stderr (exit != 0)."
   ].join(`
 `);
 }
@@ -6407,12 +6668,22 @@ async function resolveActiveTaskId(client) {
   }
   return activeId;
 }
-async function spawnTask(client, parsed) {
+async function simpleRpc(client, name, payload) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
+  return client.request(name, payload);
+}
+async function add(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
-  const payload = { repo: required(flags, "repo") };
+  const payload = { repo: resolveRepoFlag(required(flags, "repo")) };
   const title = optional(flags, "title");
   if (title)
     payload.title = title;
+  const branch = optional(flags, "branch");
+  if (branch)
+    payload.branch = branch;
   const baseRef = optional(flags, "base-branch");
   if (baseRef)
     payload.baseRef = baseRef;
@@ -6420,25 +6691,26 @@ async function spawnTask(client, parsed) {
   if (vendor)
     payload.vendor = vendor;
   const res = await client.request("task.create", payload);
-  const prompt = optional(flags, "prompt");
-  if (!prompt) {
-    return { taskId: res.taskId, task: res.task, started: false };
+  const taskId = res.taskId;
+  const status = optional(flags, "status");
+  if (status)
+    await client.request("task.status", { taskId, status: requireEnum(flags, "status", TASK_STATUSES) });
+  const pin = optionalBool(flags, "pin");
+  if (pin !== undefined)
+    await client.request("task.pin", { taskId, pinned: pin });
+  let task = res.task;
+  if (status || pin !== undefined) {
+    task = (await client.request("task.get", { taskId })).task;
   }
-  const delivered = await deliverPrompt(client, {
-    id: res.taskId,
-    worktreePath: res.task.worktreePath,
-    vendor: res.task.vendor,
-    repo: res.task.repo
-  }, prompt);
-  return {
-    taskId: res.taskId,
-    task: res.task,
-    started: delivered.started,
-    engineReady: delivered.engineReady,
-    session: delivered.session
-  };
+  const prompt = optional(flags, "prompt");
+  if (!prompt)
+    return { taskId, task, started: false };
+  const delivered = await deliverPrompt(client, { id: taskId, worktreePath: task.worktreePath, vendor: task.vendor, repo: task.repo }, prompt);
+  return { taskId, task, started: delivered.started, engineReady: delivered.engineReady, session: delivered.session };
 }
 async function send(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
   const prompt = required(flags, "prompt");
   let taskId = optional(flags, "task-id");
@@ -6465,17 +6737,50 @@ async function send(client, parsed) {
   };
 }
 async function getTask(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const taskId = required(parsed.flags, "task-id");
   const res = await client.request("task.get", { taskId });
   const running = await sessionExists(tmuxSessionName(taskId));
   return { task: res.task, running };
 }
 async function list(client) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   return client.request("task.list");
 }
+async function setActive(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
+  const none = optionalBool(parsed.flags, "none");
+  const taskId = none ? null : required(parsed.flags, "task-id");
+  await client.request("task.setActive", { taskId });
+  return { ok: true, activeTaskId: taskId };
+}
+async function adopt(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
+  const { flags } = parsed;
+  const input = {
+    repo: resolveRepoFlag(required(flags, "repo")),
+    worktreePath: resolveRepoFlag(required(flags, "worktree"))
+  };
+  const branch = optional(flags, "branch");
+  if (branch)
+    input.branch = branch;
+  const vendor = optionalVendor2(flags);
+  if (vendor)
+    input.vendor = vendor;
+  const title = optional(flags, "title");
+  if (title)
+    input.title = title;
+  return client.request("worktree.adopt", input);
+}
 async function fanOut(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
-  const repo = required(flags, "repo");
+  const repo = resolveRepoFlag(required(flags, "repo"));
   const prompt = required(flags, "prompt");
   const title = optional(flags, "title");
   const baseRef = optional(flags, "base-branch");
@@ -6504,6 +6809,8 @@ async function fanOut(client, parsed) {
   return { count: tasks.length, tasks };
 }
 async function collect(client, parsed) {
+  if (!client)
+    throw new ApiError("daemon required", "BAD_DAEMON");
   const { flags } = parsed;
   const idsFlag = optional(flags, "task-ids");
   const repoFlag = optional(flags, "repo");
@@ -6512,7 +6819,7 @@ async function collect(client, parsed) {
     taskIds = idsFlag.split(",").map((s) => s.trim()).filter(Boolean);
   } else if (repoFlag) {
     const { resolveRepoRoot: resolveRepoRoot2 } = await Promise.resolve().then(() => (init_repos(), exports_repos));
-    const target = resolveRepoRoot2(resolve4(process.cwd(), repoFlag));
+    const target = resolveRepoRoot2(resolveRepoFlag(repoFlag));
     const { tasks } = await client.request("task.list");
     taskIds = tasks.filter((t) => !t.archived && resolveRepoRoot2(t.repo) === target).map((t) => t.id);
   } else {
@@ -6538,72 +6845,67 @@ async function collect(client, parsed) {
   return { tasks: out };
 }
 async function runApiSubcommand(argv) {
-  const [verb, ...rest] = argv;
-  if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
-    if (!verb) {
+  const [verbName, ...rest] = argv;
+  if (!verbName || verbName === "--help" || verbName === "-h" || verbName === "help") {
+    if (!verbName)
       fail(apiUsage(), "MISSING_VERB", 2);
-    }
     process.stdout.write(`${apiUsage()}
 `);
     return;
   }
-  if (!API_VERBS.includes(verb)) {
-    fail(`unknown verb: ${verb}
+  const verb = findVerb(verbName);
+  if (!verb)
+    fail(`unknown verb: ${verbName}
 ${apiUsage()}`, "BAD_VERB", 2);
-  }
+  const booleanFlags = new Set(verb.flags.filter((f) => f.type === "bool").map((f) => f.name));
   let parsed;
   try {
-    parsed = parseFlags(rest);
+    parsed = parseFlags(rest, booleanFlags);
   } catch (err) {
     if (err instanceof ApiError)
       fail(err.message, err.code, 2);
     fail(err instanceof Error ? err.message : String(err), "BAD_FLAG", 2);
   }
-  let client;
+  if (parsed.help) {
+    process.stdout.write(`${verbHelp(verb)}
+`);
+    return;
+  }
   try {
-    client = await connectOrStartDaemon();
+    validateAgainstSpec(verb, parsed.flags);
   } catch (err) {
-    fail(`could not reach or start the kobe daemon: ${err instanceof Error ? err.message : String(err)}`, "BAD_DAEMON", 2);
+    if (err instanceof ApiError)
+      fail(err.message, err.code, 2);
+    fail(err instanceof Error ? err.message : String(err), "BAD_FLAG", 2);
   }
-  try {
-    let result;
-    switch (verb) {
-      case "spawn-task":
-        result = await spawnTask(client, parsed);
-        break;
-      case "fan-out":
-        result = await fanOut(client, parsed);
-        break;
-      case "send":
-        result = await send(client, parsed);
-        break;
-      case "get-task":
-        result = await getTask(client, parsed);
-        break;
-      case "collect":
-        result = await collect(client, parsed);
-        break;
-      case "list":
-        result = await list(client);
-        break;
+  let client = null;
+  if (!verb.offline) {
+    try {
+      client = await connectOrStartDaemon();
+    } catch (err) {
+      fail(`could not reach or start the kobe daemon: ${err instanceof Error ? err.message : String(err)}`, "BAD_DAEMON", 2);
     }
+  }
+  try {
+    const result = await verb.handler(client, parsed);
     emit(result, parsed.pretty);
   } catch (err) {
     if (err instanceof ApiError)
       fail(err.message, err.code, 1);
     fail(err instanceof Error ? err.message : String(err), "RPC_ERROR", 1);
   } finally {
-    client.close();
+    client?.close();
   }
 }
-var API_VERBS, FANOUT_CAP = 10, ApiError;
+var API_SCHEMA_VERSION = 2, FANOUT_CAP = 10, TASK_STATUSES, ApiError, F, VERB_ALIASES, VERB_GROUPS, VERBS, API_VERBS, GLOBAL_FLAGS;
 var init_api_cmd = __esm(() => {
   init_daemon_process();
   init_interactive_command();
   init_client2();
   init_prompt_delivery();
   init_vendor();
-  API_VERBS = ["spawn-task", "fan-out", "send", "get-task", "collect", "list"];
+  init_version();
+  TASK_STATUSES = ["backlog", "in_progress", "in_review", "done", "canceled", "error"];
   ApiError = class ApiError extends Error {
     code;
     constructor(message, code) {
@@ -6611,6 +6913,241 @@ var init_api_cmd = __esm(() => {
       this.code = code;
     }
   };
+  F = {
+    repo: (required = true) => ({
+      name: "repo",
+      type: "string",
+      required,
+      placeholder: "PATH",
+      description: "Repo root (git toplevel). Relative paths resolve against $PWD."
+    }),
+    taskId: (required = true) => ({
+      name: "task-id",
+      type: "string",
+      required,
+      placeholder: "ID",
+      description: "Target task id (from `list` / `add`)."
+    }),
+    vendor: () => ({
+      name: "vendor",
+      type: "enum",
+      values: ALL_VENDORS,
+      placeholder: "V",
+      description: "Engine vendor for the task."
+    }),
+    title: () => ({ name: "title", type: "string", placeholder: "T", description: "Human task title." }),
+    prompt: (required, desc) => ({
+      name: "prompt",
+      type: "string",
+      required,
+      placeholder: "TEXT",
+      description: desc
+    })
+  };
+  VERB_ALIASES = { "spawn-task": "add" };
+  VERB_GROUPS = {
+    discover: ["schema"],
+    read: ["list", "get-task", "collect"],
+    create: ["add", "fan-out"],
+    drive: ["send", "set-active"],
+    edit: ["rename", "set-branch", "set-vendor", "set-status"],
+    lifecycle: ["archive", "pin", "delete"],
+    worktree: ["ensure-worktree", "adopt", "discover-adoptable"]
+  };
+  VERBS = [
+    {
+      name: "schema",
+      summary: "Explore the API. Default = a COMPACT index (groups + verb summaries, no flags). Drill in with --verb / --group; --all for the full spec.",
+      flags: [
+        { name: "verb", type: "string", placeholder: "NAME", description: "Full flag detail for ONE verb." },
+        { name: "group", type: "string", placeholder: "G", description: "List the verbs in one group (compact)." },
+        {
+          name: "all",
+          type: "bool",
+          description: "The COMPLETE spec \u2014 every verb AND every flag (large; avoid by default)."
+        }
+      ],
+      offline: true,
+      handler: handleSchema
+    },
+    { name: "list", summary: "List all tasks (incl. archived). Returns { tasks }.", flags: [], handler: list },
+    {
+      name: "get-task",
+      summary: "Read one task's metadata. `.running` = its tmux session is live.",
+      flags: [F.taskId()],
+      handler: getTask
+    },
+    {
+      name: "add",
+      summary: "Create a task (shows in the sidebar immediately). With --prompt it also starts the engine and delivers it. Alias: spawn-task.",
+      flags: [
+        F.repo(),
+        F.title(),
+        {
+          name: "branch",
+          type: "string",
+          placeholder: "B",
+          description: "Explicit branch name (else auto kobe/<slug>-<id>)."
+        },
+        { name: "base-branch", type: "string", placeholder: "B", description: "Base ref the worktree branches from." },
+        F.vendor(),
+        {
+          name: "status",
+          type: "enum",
+          values: TASK_STATUSES,
+          default: "backlog",
+          description: "Initial lifecycle status."
+        },
+        { name: "pin", type: "bool", description: "Pin the task to the top of the sidebar." },
+        F.prompt(false, "Optional first message \u2014 when set, materializes the worktree, starts the engine, and pastes it.")
+      ],
+      handler: add
+    },
+    {
+      name: "fan-out",
+      summary: `Spawn N tasks of ONE prompt in a single call (parallel attempts). Capped at ${FANOUT_CAP}.`,
+      flags: [
+        F.repo(),
+        F.prompt(true, "Shared prompt delivered to every spawned task."),
+        { name: "count", type: "int", placeholder: "N", description: "Number of tasks of one vendor (with --vendor)." },
+        {
+          name: "agents",
+          type: "string",
+          placeholder: "claude:2,codex:1",
+          description: "Per-vendor counts (alternative to --count)."
+        },
+        F.vendor(),
+        F.title(),
+        { name: "base-branch", type: "string", placeholder: "B", description: "Base ref for every worktree." }
+      ],
+      handler: fanOut
+    },
+    {
+      name: "send",
+      summary: "Paste a follow-up prompt into a task's running engine (one full turn). Defaults to the active task.",
+      flags: [F.taskId(false), F.prompt(true, "Text pasted + submitted into the engine pane.")],
+      handler: send
+    },
+    {
+      name: "collect",
+      summary: "Read-only comparison snapshot of several tasks (identity, branch, .running, uncommitted .changes).",
+      flags: [
+        { name: "task-ids", type: "csv", placeholder: "a,b,c", description: "Comma-separated task ids." },
+        F.repo(false)
+      ],
+      handler: collect
+    },
+    {
+      name: "rename",
+      summary: "Set a task's title.",
+      flags: [F.taskId(), { name: "title", type: "string", required: true, placeholder: "T", description: "New title." }],
+      handler: (c, p) => simpleRpc(c, "task.rename", { taskId: required(p.flags, "task-id"), title: required(p.flags, "title") })
+    },
+    {
+      name: "set-branch",
+      summary: "Rename a task's branch (git branch -m if materialized, else recorded).",
+      flags: [
+        F.taskId(),
+        { name: "branch", type: "string", required: true, placeholder: "B", description: "New branch name." }
+      ],
+      handler: (c, p) => simpleRpc(c, "task.setBranch", { taskId: required(p.flags, "task-id"), branch: required(p.flags, "branch") })
+    },
+    {
+      name: "set-vendor",
+      summary: "Change a task's engine vendor (takes effect on next session rebuild).",
+      flags: [F.taskId(), { ...F.vendor(), required: true }],
+      handler: (c, p) => simpleRpc(c, "task.setVendor", {
+        taskId: required(p.flags, "task-id"),
+        vendor: requireEnum(p.flags, "vendor", ALL_VENDORS)
+      })
+    },
+    {
+      name: "set-status",
+      summary: "Set a task's lifecycle status.",
+      flags: [
+        F.taskId(),
+        { name: "status", type: "enum", required: true, values: TASK_STATUSES, description: "New status." }
+      ],
+      handler: (c, p) => simpleRpc(c, "task.status", {
+        taskId: required(p.flags, "task-id"),
+        status: requireEnum(p.flags, "status", TASK_STATUSES)
+      })
+    },
+    {
+      name: "archive",
+      summary: "Archive (or with --archived=false, unarchive) a task. Non-destructive: worktree/branch/history stay.",
+      flags: [
+        F.taskId(),
+        { name: "archived", type: "bool", default: "true", description: "true to archive, false to unarchive." }
+      ],
+      handler: (c, p) => simpleRpc(c, "task.archive", {
+        taskId: required(p.flags, "task-id"),
+        archived: optionalBool(p.flags, "archived") ?? true
+      })
+    },
+    {
+      name: "pin",
+      summary: "Pin (or with --pinned=false, unpin) a task to the top of the sidebar.",
+      flags: [F.taskId(), { name: "pinned", type: "bool", default: "true", description: "true to pin, false to unpin." }],
+      handler: (c, p) => simpleRpc(c, "task.pin", {
+        taskId: required(p.flags, "task-id"),
+        pinned: optionalBool(p.flags, "pinned") ?? true
+      })
+    },
+    {
+      name: "set-active",
+      summary: "Set the shared active task (the focus every Tasks pane highlights). Pass --none to clear.",
+      flags: [
+        F.taskId(false),
+        { name: "none", type: "bool", description: "Clear the active task instead of setting one." }
+      ],
+      handler: setActive
+    },
+    {
+      name: "ensure-worktree",
+      summary: "Materialize a task's git worktree on disk now (without starting an engine). Returns { worktreePath }.",
+      flags: [F.taskId()],
+      handler: (c, p) => simpleRpc(c, "task.ensureWorktree", { taskId: required(p.flags, "task-id") })
+    },
+    {
+      name: "delete",
+      summary: "Permanently remove a task (and its worktree). DESTRUCTIVE \u2014 prefer `archive`. Needs --force on a dirty worktree.",
+      flags: [F.taskId(), { name: "force", type: "bool", description: "Delete even with uncommitted changes." }],
+      handler: (c, p) => simpleRpc(c, "task.delete", {
+        taskId: required(p.flags, "task-id"),
+        force: optionalBool(p.flags, "force") ?? false
+      })
+    },
+    {
+      name: "discover-adoptable",
+      summary: "List existing git worktrees in a repo not yet tracked as kobe tasks. Returns { worktrees }.",
+      flags: [F.repo()],
+      handler: (c, p) => simpleRpc(c, "worktree.discoverAdoptable", { repo: resolveRepoFlag(required(p.flags, "repo")) })
+    },
+    {
+      name: "adopt",
+      summary: "Import an existing git worktree as a kobe task. Returns { task }.",
+      flags: [
+        F.repo(),
+        {
+          name: "worktree",
+          type: "string",
+          required: true,
+          placeholder: "PATH",
+          description: "Path of the worktree to adopt."
+        },
+        { name: "branch", type: "string", placeholder: "B", description: "Branch override (else the worktree's own)." },
+        F.vendor(),
+        F.title()
+      ],
+      handler: adopt
+    }
+  ];
+  API_VERBS = VERBS.map((v) => v.name);
+  GLOBAL_FLAGS = [
+    { name: "pretty", type: "bool", description: "Pretty-print stdout JSON." },
+    { name: "help", type: "bool", description: "Show usage for the verb and exit." }
+  ];
 });
 
 // src/cli/update.ts
@@ -7121,31 +7658,66 @@ var init_daemon_cmd = __esm(() => {
 });
 
 // src/lib/skill-install.ts
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
 import { homedir as homedir9 } from "os";
 import { join as join7 } from "path";
+function npxSkillsArgv(opts = {}) {
+  return ["skills", "add", SKILL_SOURCE_SLUG, "--skill", "kobe", "--agent", opts.agent ?? DEFAULT_SKILL_AGENT];
+}
+function npxSkillsCommand(opts = {}) {
+  return `npx ${npxSkillsArgv(opts).join(" ")}`;
+}
 function kobeSkillPaths(opts = {}) {
   const home = opts.home ?? homedir9();
   const cwd = opts.cwd ?? process.cwd();
   return [join7(home, SKILL_REL_PATH), join7(cwd, SKILL_REL_PATH)];
 }
-function isKobeSkillInstalled(opts) {
-  return kobeSkillPaths(opts).some((p) => existsSync4(p));
+function parseSkillVersion(content) {
+  const m = content.match(/kobe-skill-version:\s*(\d+)/);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
+function kobeSkillState(opts) {
+  const path6 = kobeSkillPaths(opts).find((p) => existsSync4(p));
+  if (!path6) {
+    return { installed: false, installedVersion: null, currentVersion: KOBE_SKILL_VERSION, stale: false };
+  }
+  let installedVersion = null;
+  try {
+    installedVersion = parseSkillVersion(readFileSync6(path6, "utf8"));
+  } catch {
+    installedVersion = null;
+  }
+  const stale = installedVersion === null || installedVersion < KOBE_SKILL_VERSION;
+  return { installed: true, installedVersion, currentVersion: KOBE_SKILL_VERSION, stale };
 }
 function maybeHintSkillInstall() {
-  if (isKobeSkillInstalled())
-    return;
-  if (getPersistedString(HINT_SEEN_KEY) === "1")
+  const state = kobeSkillState();
+  if (!state.installed) {
+    if (getPersistedString(HINT_SEEN_KEY) === "1")
+      return;
+    setPersistedString(HINT_SEEN_KEY, "1");
+    process.stderr.write(`
+kobe: the kobe agent skill isn't installed \u2014 install it so your coding agent can drive kobe via \`kobe api\`:
+  ${SKILL_INSTALL_COMMAND}
+  (wraps \`${npxSkillsCommand()}\`; check anytime with \`kobe doctor\`)
+
+`);
     return;
-  setPersistedString(HINT_SEEN_KEY, "1");
-  process.stderr.write(`
-kobe: the kobe agent skill isn't installed \u2014 install it so Claude Code can fan out parallel tasks via \`kobe api\`:
+  }
+  if (state.stale) {
+    const key = `${HINT_SEEN_KEY}:v${state.currentVersion}`;
+    if (getPersistedString(key) === "1")
+      return;
+    setPersistedString(key, "1");
+    const was = state.installedVersion === null ? "an older" : `v${state.installedVersion}`;
+    process.stderr.write(`
+kobe: your kobe agent skill is out of date (${was}; this kobe wants v${state.currentVersion}) \u2014 refresh it so \`kobe api\` guidance matches:
   ${SKILL_INSTALL_COMMAND}
-  (check anytime with \`kobe doctor\`)
 
 `);
+  }
 }
-var SKILL_REL_PATH = ".claude/skills/kobe/SKILL.md", SKILL_INSTALL_COMMAND = "npx skills add Sma1lboy/kobe --skill kobe --agent claude-code", HINT_SEEN_KEY = "skillHintSeen";
+var KOBE_SKILL_VERSION = 1, SKILL_REL_PATH = ".claude/skills/kobe/SKILL.md", SKILL_INSTALL_COMMAND = "kobe skill install", SKILL_SOURCE_SLUG = "Sma1lboy/kobe", DEFAULT_SKILL_AGENT = "claude-code", HINT_SEEN_KEY = "skillHintSeen";
 var init_skill_install = __esm(() => {
   init_repos();
 });
@@ -7154,9 +7726,10 @@ var init_skill_install = __esm(() => {
 var exports_maintenance = {};
 __export(exports_maintenance, {
   runResetSubcommand: () => runResetSubcommand,
+  runReloadSubcommand: () => runReloadSubcommand,
   runDoctorSubcommand: () => runDoctorSubcommand
 });
-import { existsSync as existsSync5, readFileSync as readFileSync6, statSync } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync7, statSync } from "fs";
 import { unlink as unlink6 } from "fs/promises";
 import { join as join8 } from "path";
 import { createInterface } from "readline";
@@ -7205,7 +7778,7 @@ function describeFile(path6) {
 }
 function taskCount(tasksPath) {
   try {
-    const parsed = JSON.parse(readFileSync6(tasksPath, "utf8"));
+    const parsed = JSON.parse(readFileSync7(tasksPath, "utf8"));
     return Array.isArray(parsed.tasks) ? parsed.tasks.length : null;
   } catch {
     return null;
@@ -7213,7 +7786,7 @@ function taskCount(tasksPath) {
 }
 function tailFile(path6, n) {
   try {
-    const lines = readFileSync6(path6, "utf8").split(`
+    const lines = readFileSync7(path6, "utf8").split(`
 `).filter((l) => l.trim().length > 0);
     return lines.slice(-n).join(`
 `);
@@ -7293,11 +7866,16 @@ async function runDoctorSubcommand(argv = []) {
     out.push("tmux:    \u2717 not found on PATH (task sessions need tmux)");
   }
   out.push("");
-  if (isKobeSkillInstalled()) {
-    out.push("skill:   \u2713 kobe agent skill installed");
-  } else {
-    out.push("skill:   \u2717 kobe agent skill not installed (optional \u2014 lets Claude Code drive `kobe api`)");
+  const skill = kobeSkillState();
+  if (!skill.installed) {
+    out.push("skill:   \u2717 kobe agent skill not installed (optional \u2014 lets a coding agent drive `kobe api`)");
+    out.push(`         \u2192 ${SKILL_INSTALL_COMMAND}`);
+  } else if (skill.stale) {
+    const was = skill.installedVersion === null ? "unstamped" : `v${skill.installedVersion}`;
+    out.push(`skill:   \u26A0 kobe agent skill out of date (${was}; this kobe wants v${skill.currentVersion})`);
     out.push(`         \u2192 ${SKILL_INSTALL_COMMAND}`);
+  } else {
+    out.push(`skill:   \u2713 kobe agent skill installed (v${skill.installedVersion})`);
   }
   out.push("");
   const count = taskCount(tasksPath);
@@ -7407,6 +7985,54 @@ Stop daemon and kill kobe sessions? [y/N] `);
   console.log(`
 kobe: reset complete. Relaunch kobe to start fresh.`);
 }
+async function runReloadSubcommand(argv = []) {
+  if (argv.includes("--help") || argv.includes("-h") || argv.includes("help")) {
+    process.stdout.write([
+      "Usage: kobe reload",
+      "",
+      "Restart kobe's Tasks + Ops panes in every live session, in place.",
+      "Picks up new kobe code without `kobe reset` \u2014 the engine (claude)",
+      "panes and your running turns are never touched. Takes no options.",
+      ""
+    ].join(`
+`));
+    return;
+  }
+  const unknown = argv.find((a) => a.length > 0);
+  if (unknown !== undefined) {
+    process.stderr.write(`kobe reload: unexpected argument "${unknown}"
+
+Usage: kobe reload   (takes no options)
+`);
+    process.exit(2);
+  }
+  if (!await tmuxAvailable()) {
+    console.log("kobe reload: tmux is not installed \u2014 no panes to reload");
+    return;
+  }
+  const { code, stdout } = await tmuxQuiet(["list-sessions", "-F", "#{session_name}"]);
+  if (code !== 0) {
+    console.log(`kobe reload: no kobe tmux sessions on the \`${KOBE_TMUX_SOCKET}\` socket`);
+    return;
+  }
+  const sessions = stdout.split(`
+`).map((l) => l.trim()).filter((l) => l.length > 0);
+  if (sessions.length === 0) {
+    console.log(`kobe reload: no kobe tmux sessions on the \`${KOBE_TMUX_SOCKET}\` socket`);
+    return;
+  }
+  const { refreshKobeWorkspacePanes: refreshKobeWorkspacePanes2 } = await Promise.resolve().then(() => (init_tmux(), exports_tmux));
+  let reloaded = 0;
+  for (const session of sessions) {
+    try {
+      await refreshKobeWorkspacePanes2(session);
+      reloaded++;
+    } catch (err) {
+      console.error(`  failed to reload session "${session}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  console.log(`kobe: reloaded Tasks/Ops panes in ${reloaded}/${sessions.length} session(s) \u2014 engine panes untouched`);
+}
 var init_maintenance = __esm(() => {
   init_client();
   init_lifecycle();
@@ -7417,6 +8043,106 @@ var init_maintenance = __esm(() => {
   init_client2();
 });
 
+// src/cli/skill-cmd.ts
+var exports_skill_cmd = {};
+__export(exports_skill_cmd, {
+  runSkillSubcommand: () => runSkillSubcommand
+});
+function skillUsage() {
+  return [
+    "usage: kobe skill <verb>",
+    "",
+    "verbs:",
+    "  install [--agent NAME]   Install the kobe agent skill (wraps `npx skills add`)",
+    "  status                   Show whether the skill is installed",
+    "  command [--agent NAME]   Print the underlying npx command without running it",
+    "",
+    `The skill teaches a coding agent how to drive \`kobe api\`. Default agent: ${DEFAULT_SKILL_AGENT}.`
+  ].join(`
+`);
+}
+function parseAgent(rest) {
+  let agent = DEFAULT_SKILL_AGENT;
+  for (let i = 0;i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--agent") {
+      const v = rest[i + 1];
+      if (!v || v.startsWith("--")) {
+        process.stderr.write(`kobe skill: --agent requires a value
+`);
+        process.exit(2);
+      }
+      agent = v;
+      i++;
+    } else if (arg.startsWith("--agent=")) {
+      agent = arg.slice("--agent=".length);
+    } else {
+      process.stderr.write(`kobe skill: unknown flag "${arg}"
+
+${skillUsage()}
+`);
+      process.exit(2);
+    }
+  }
+  return agent;
+}
+async function runSkillSubcommand(argv) {
+  const [verb, ...rest] = argv;
+  if (!verb || verb === "--help" || verb === "-h" || verb === "help") {
+    process.stdout.write(`${skillUsage()}
+`);
+    if (!verb)
+      process.exitCode = 2;
+    return;
+  }
+  if (!SKILL_VERBS.includes(verb)) {
+    process.stderr.write(`kobe skill: unknown verb "${verb}"
+
+${skillUsage()}
+`);
+    process.exit(2);
+  }
+  if (verb === "status") {
+    const state = kobeSkillState();
+    const [userPath, projectPath] = kobeSkillPaths();
+    const head = !state.installed ? "\u2717 not installed" : state.stale ? `\u26A0 out of date (installed ${state.installedVersion === null ? "unstamped" : `v${state.installedVersion}`}, this kobe wants v${state.currentVersion})` : `\u2713 installed (v${state.installedVersion})`;
+    process.stdout.write([
+      `kobe skill: ${head}`,
+      `  looked in: ${userPath}`,
+      `             ${projectPath}`,
+      state.installed && !state.stale ? "" : "  \u2192 run `kobe skill install` to install / refresh",
+      ""
+    ].join(`
+`));
+    return;
+  }
+  if (verb === "command") {
+    process.stdout.write(`${npxSkillsCommand({ agent: parseAgent(rest) })}
+`);
+    return;
+  }
+  const agent = parseAgent(rest);
+  const args = npxSkillsArgv({ agent });
+  process.stdout.write(`kobe skill: running \`npx ${args.join(" ")}\`
+`);
+  const proc = Bun.spawn(["npx", ...args], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+  const code = await proc.exited;
+  if (code !== 0) {
+    process.stderr.write(`
+kobe skill install failed (npx exited ${code}). Is \`npx\` on PATH and are you online?
+` + `You can run it yourself: ${npxSkillsCommand({ agent })}
+`);
+    process.exit(code || 1);
+  }
+  process.stdout.write(`kobe skill: installed.
+`);
+}
+var SKILL_VERBS;
+var init_skill_cmd = __esm(() => {
+  init_skill_install();
+  SKILL_VERBS = ["install", "status", "command"];
+});
+
 // ../../node_modules/.bun/entities@7.0.1/node_modules/entities/dist/esm/decode-codepoint.js
 function replaceCodePoint(codePoint) {
   var _a2;
@@ -8706,6 +9432,7 @@ class RemoteOrchestrator {
   setConnectionState;
   ensureReachable;
   role;
+  reconnecting = false;
   constructor(client, options = {}) {
     this.client = client;
     const [tasks, setTasks] = createSignal([]);
@@ -8723,7 +9450,37 @@ class RemoteOrchestrator {
     this.ensureReachable = options.ensureReachable ?? ensureDaemonReachable;
     this.role = options.role ?? "pane";
     this.client.on("*", (frame) => this.handleEvent(frame.name, frame.payload));
-    this.client.onLifecycle("close", () => this.setConnectionState("disconnected"));
+    this.client.onLifecycle("close", () => {
+      this.setConnectionState("disconnected");
+      if (this.role === "pane") {
+        logClient("orch", "daemon socket closed \u2014 starting non-spawning reconnect loop");
+        this.reconnectLoop();
+      }
+    });
+  }
+  async reconnectLoop() {
+    if (this.reconnecting)
+      return;
+    this.reconnecting = true;
+    let delayMs = 500;
+    let attempt = 0;
+    while (!this.client.isDisposed) {
+      await new Promise((r) => setTimeout(r, delayMs));
+      if (this.client.isDisposed)
+        break;
+      attempt++;
+      try {
+        await this.init();
+        logClient("orch", `reconnected and re-subscribed after ${attempt} attempt(s) \u2014 task list re-synced`);
+        this.reconnecting = false;
+        return;
+      } catch (err) {
+        if (attempt === 1 || attempt % 10 === 0)
+          logClientError("orch-reconnect", err);
+        delayMs = Math.min(delayMs * 2, 3000);
+      }
+    }
+    this.reconnecting = false;
   }
   async init() {
     const hello = await this.client.request("hello", {
@@ -8744,6 +9501,7 @@ class RemoteOrchestrator {
       this.setTasks(hello.tasks.map(deserializeTask));
     await this.client.subscribe({ role: this.role });
     this.setConnectionState("online");
+    logClient("orch", `subscribed as ${this.role} (${this.tasksAcc().length} tasks)`);
   }
   connectionStateSignal() {
     return this.connectionStateAcc;
@@ -8877,6 +9635,7 @@ function deserializeTask(s) {
 var init_remote_orchestrator = __esm(() => {
   init_dev();
   init_protocol();
+  init_client_log();
   init_daemon_process();
 });
 
@@ -12854,7 +13613,7 @@ var init_binary3 = __esm(() => {
 });
 
 // src/engine/account-detect.ts
-import { readFileSync as readFileSync7, statSync as statSync6 } from "fs";
+import { readFileSync as readFileSync8, statSync as statSync6 } from "fs";
 import { homedir as homedir14 } from "os";
 import path10 from "path";
 function claudeGlobalConfigPath(env, home) {
@@ -13067,7 +13826,7 @@ var init_account_detect = __esm(() => {
           return null;
         throw err;
       }
-      return readFileSync7(p, "utf8");
+      return readFileSync8(p, "utf8");
     },
     env(name) {
       return process.env[name];
@@ -14618,12 +15377,12 @@ var init_focus = __esm(() => {
 });
 
 // src/tui/context/kv.tsx
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname5 } from "path";
+import { mkdirSync as mkdirSync4, readFileSync as readFileSync9, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "fs";
+import { dirname as dirname6 } from "path";
 function loadInitial() {
   const statePath2 = kvStatePath();
   try {
-    const text = readFileSync8(statePath2, "utf8");
+    const text = readFileSync9(statePath2, "utf8");
     const parsed = JSON.parse(text);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       return parsed;
@@ -14647,7 +15406,7 @@ var init_kv = __esm(() => {
       function writeNow(label) {
         const statePath2 = kvStatePath();
         try {
-          mkdirSync4(dirname5(statePath2), {
+          mkdirSync4(dirname6(statePath2), {
             recursive: true
           });
           const tmp = `${statePath2}.tmp`;
@@ -14702,7 +15461,7 @@ var init_kv = __esm(() => {
           }
           const statePath2 = kvStatePath();
           try {
-            mkdirSync4(dirname5(statePath2), {
+            mkdirSync4(dirname6(statePath2), {
               recursive: true
             });
             const tmp = `${statePath2}.tmp`;
@@ -14719,10 +15478,10 @@ var init_kv = __esm(() => {
 });
 
 // src/tui/lib/persisted-ui-prefs.ts
-import { readFileSync as readFileSync9 } from "fs";
+import { readFileSync as readFileSync10 } from "fs";
 function readPersistedUiPrefs(fallbackTheme) {
   try {
-    const parsed = JSON.parse(readFileSync9(kvStatePath(), "utf8"));
+    const parsed = JSON.parse(readFileSync10(kvStatePath(), "utf8"));
     const theme = typeof parsed.activeTheme === "string" && hasTheme(parsed.activeTheme) ? parsed.activeTheme : fallbackTheme;
     const transparent = parsed.transparentBackground === true;
     const focusAccent = typeof parsed.focusAccent === "string" && FOCUS_ACCENT_SLOTS.includes(parsed.focusAccent) ? parsed.focusAccent : null;
@@ -16102,7 +16861,7 @@ function Sidebar(props) {
           return readWorktreeChanges(task.worktreePath);
         });
         const titleText = isMain ? repoBasename(task.repo) : task.title;
-        const loading = () => isLive() || task.status === "in_progress";
+        const loading = () => isLive() || !isMain && task.status === "in_progress";
         const subtitleText = createMemo(() => {
           if (task.branch.length > 0)
             return truncateBranchLabel(task.branch, subtitleBudget());
@@ -17042,6 +17801,7 @@ function ShortcutHints() {
   })();
 }
 async function startTasksPane(opts = {}) {
+  setClientLogContext("tasks");
   for (const {
     name,
     theme
@@ -17056,21 +17816,28 @@ async function startTasksPane(opts = {}) {
   const [fileTasks, setFileTasks] = createSignal(store2.list());
   let orch = null;
   try {
-    const client = await connectOrStartDaemon();
-    const remote = new RemoteOrchestrator(client);
-    await remote.init();
-    orch = remote;
+    const client = await connectIfRunning();
+    if (client) {
+      const remote = new RemoteOrchestrator(client);
+      await remote.init();
+      orch = remote;
+    } else {
+      logClient("tasks-boot", "no daemon running \u2014 polling tasks.json (a gui owns daemon lifecycle)");
+    }
   } catch (err) {
-    console.error("[kobe tasks] daemon subscribe unavailable, polling tasks.json:", err);
+    logClientError("tasks-boot", err);
+    logClient("tasks-boot", "daemon subscribe failed \u2014 polling tasks.json");
   }
-  const tasks = orch ? orch.tasksSignal() : fileTasks;
+  const tasks = () => orch && orch.connectionStateSignal()() === "online" ? orch.tasksSignal()() : fileTasks();
   const reload = async () => {
-    if (orch)
-      return;
     await store2.load();
     setFileTasks(store2.list());
   };
-  const timer = orch ? undefined : setInterval(() => void reload(), RELOAD_MS);
+  const timer = setInterval(() => {
+    if (orch && orch.connectionStateSignal()() === "online")
+      return;
+    reload();
+  }, RELOAD_MS);
   await render(() => createComponent2(ThemeProvider, {
     mode: "dark",
     get theme() {
@@ -17130,6 +17897,7 @@ var init_host = __esm(() => {
   init_client2();
   init_solid();
   init_dev();
+  init_client_log();
   init_daemon_process();
   init_remote_orchestrator();
   init_interactive_command();
@@ -19387,6 +20155,7 @@ function OpsApp(props) {
   });
 }
 async function startOpsHost(args) {
+  setClientLogContext("ops");
   for (const {
     name,
     theme
@@ -19658,6 +20427,7 @@ var init_host5 = __esm(() => {
   init_solid();
   init_solid();
   init_invocation();
+  init_client_log();
   init_turn_detector();
   init_activity();
   init_client2();
@@ -19728,6 +20498,7 @@ async function ensureRepos(orchestrator) {
   return repos[0] ?? resolve6(process.cwd());
 }
 async function startDirectTmux() {
+  setClientLogContext("gui");
   if (!await tmuxAvailable()) {
     console.error("kobe: tmux not found on PATH \u2014 install tmux to use kobe 0.6 direct mode");
     process.exitCode = 1;
@@ -19797,6 +20568,7 @@ async function startDirectTmux() {
   }
 }
 var init_direct = __esm(() => {
+  init_client_log();
   init_daemon_process();
   init_remote_orchestrator();
   init_interactive_command();
@@ -22080,9 +22852,11 @@ function topLevelUsage() {
     "  api <verb>              Scriptable RPC surface for agents (see `kobe api --help`)",
     "  daemon <verb>           Manage the daemon (start|stop|status|restart)",
     "  theme <verb>            Manage user themes (list|add|remove)",
+    "  skill <verb>            Install the kobe agent skill (install|status|command)",
     "  update [target]         Self-update kobe",
     "  doctor                  Diagnose daemon / tmux / state (read-only)",
     "  reset [--hard]          Recover a wedged install",
+    "  reload                  Restart Tasks/Ops panes in place (engine untouched)",
     "  kill-sessions           Tear down kobe's tmux server (dev reset)",
     "",
     "Options:",
@@ -22335,6 +23109,16 @@ async function main() {
     await runResetSubcommand2(rest);
     return;
   }
+  if (subcommand === "reload") {
+    const { runReloadSubcommand: runReloadSubcommand2 } = await Promise.resolve().then(() => (init_maintenance(), exports_maintenance));
+    await runReloadSubcommand2(rest);
+    return;
+  }
+  if (subcommand === "skill") {
+    const { runSkillSubcommand: runSkillSubcommand2 } = await Promise.resolve().then(() => (init_skill_cmd(), exports_skill_cmd));
+    await runSkillSubcommand2(rest);
+    return;
+  }
   if (subcommand === "new-chattab") {
     const flags = parseOpsFlags(rest);
     const session = flags.session;