@yorz/cli 0.3.5 → 0.3.6

package/dist/cli/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { homedir, networkInterfaces } from "node:os";
+import { homedir, platform, networkInterfaces } from "node:os";
 import { Command, Option } from "commander";
-import { stat, readFile, writeFile, rm, mkdir, access, rename, readdir, copyFile, appendFile } from "node:fs/promises";
+import { stat, readFile, writeFile, rm, mkdir, access, rename, readdir, appendFile, copyFile } from "node:fs/promises";
 import { join, dirname, extname, resolve, sep, isAbsolute, basename as basename$1, relative, normalize } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { spawn, execFile } from "node:child_process";
-import { existsSync, statSync, mkdirSync, watch, createReadStream, readFileSync } from "node:fs";
+import { existsSync, statSync, mkdirSync, watch, createReadStream, openSync } from "node:fs";
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { promisify } from "node:util";
@@ -21,7 +21,7 @@ import { Codex } from "@openai/codex-sdk";
 import { createOpencode } from "@opencode-ai/sdk";
 import { createInterface as createInterface$1 } from "node:readline/promises";
 import MarkdownIt from "markdown-it";
-const version = "0.3.5";
+const version = "0.3.6";
 const pkg = {
   version
 };
@@ -1096,7 +1096,7 @@ function createSessionsRoutes(resolveProject) {
   });
   return app;
 }
-const execFileP = promisify(execFile);
+const execFileP$1 = promisify(execFile);
 class GitError extends Error {
   code;
   stderr;
@@ -1151,7 +1151,7 @@ function assertSafeRelativePath(cwd, p) {
 }
 async function runGit(cwd, args) {
   try {
-    const result = await execFileP("git", args, {
+    const result = await execFileP$1("git", args, {
       cwd,
       encoding: "utf8",
       maxBuffer: 16 * 1024 * 1024
@@ -1170,7 +1170,7 @@ async function runGitChecked(cwd, args) {
 }
 async function runGitRaw(cwd, args) {
   try {
-    const result = await execFileP("git", args, {
+    const result = await execFileP$1("git", args, {
       cwd,
       encoding: "utf8",
       maxBuffer: 16 * 1024 * 1024
@@ -1463,6 +1463,365 @@ function buildGitOpsPrompt(action, specId, specRel, reviewRel) {
 `;
   }
 }
+const CURRENT_VERSION$1 = 1;
+const DEFAULT_GLOBAL_AGENT = { defaultKind: "claude" };
+const DEFAULT_NOTIFICATIONS = {
+  sessionEnd: { banner: false, sound: false }
+};
+function resolveGlobalConfigDir(env = process.env) {
+  if (env.YORZ_HOME && env.YORZ_HOME.trim()) return env.YORZ_HOME.trim();
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
+  return join(base, "yorz");
+}
+function resolveGlobalConfigPath(env = process.env) {
+  return join(resolveGlobalConfigDir(env), "projects.json");
+}
+async function loadGlobalConfig(filePath) {
+  const fp = filePath ?? resolveGlobalConfigPath();
+  if (!existsSync(fp)) return defaultGlobalConfig();
+  let raw;
+  try {
+    raw = await readFile(fp, "utf8");
+  } catch {
+    return defaultGlobalConfig();
+  }
+  if (!raw.trim()) return defaultGlobalConfig();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return defaultGlobalConfig();
+  }
+  return normalizeConfig$1(parsed);
+}
+async function saveGlobalConfig(config, filePath) {
+  const fp = filePath ?? resolveGlobalConfigPath();
+  await mkdir(dirname(fp), { recursive: true });
+  const normalized = normalizeConfig$1(config);
+  const body = `${JSON.stringify(normalized, null, 2)}
+`;
+  const tmp = `${fp}.tmp-${process.pid}-${Date.now().toString(36)}`;
+  await writeFile(tmp, body, "utf8");
+  await rename(tmp, fp);
+}
+function normalizeConfig$1(value) {
+  if (!value || typeof value !== "object") return defaultGlobalConfig();
+  const obj = value;
+  const projectsRaw = Array.isArray(obj.projects) ? obj.projects : [];
+  const projects = [];
+  for (const item of projectsRaw) {
+    if (!item || typeof item !== "object") continue;
+    const it = item;
+    const id = typeof it.id === "string" ? it.id : "";
+    const path = typeof it.path === "string" ? it.path : "";
+    if (!id || !path) continue;
+    const addedAt = typeof it.addedAt === "string" ? it.addedAt : "";
+    const lastActivityAt = typeof it.lastActivityAt === "string" ? it.lastActivityAt : null;
+    const worktree = normalizeWorktree(it.worktree);
+    const entry = { id, path, addedAt, lastActivityAt };
+    if (worktree) entry.worktree = worktree;
+    projects.push(entry);
+  }
+  return {
+    version: CURRENT_VERSION$1,
+    projects,
+    agent: normalizeAgent$1(obj.agent),
+    notifications: normalizeNotifications(obj.notifications)
+  };
+}
+function defaultGlobalConfig() {
+  return {
+    version: CURRENT_VERSION$1,
+    projects: [],
+    agent: { defaultKind: DEFAULT_GLOBAL_AGENT.defaultKind },
+    notifications: {
+      sessionEnd: {
+        banner: DEFAULT_NOTIFICATIONS.sessionEnd.banner,
+        sound: DEFAULT_NOTIFICATIONS.sessionEnd.sound
+      }
+    }
+  };
+}
+function normalizeAgent$1(value) {
+  if (!value || typeof value !== "object") return { defaultKind: DEFAULT_GLOBAL_AGENT.defaultKind };
+  const obj = value;
+  const defaultKind = obj.defaultKind;
+  if (defaultKind === "opencode" || defaultKind === "codex") return { defaultKind };
+  return { defaultKind: "claude" };
+}
+function normalizeNotifications(value) {
+  if (!value || typeof value !== "object") return defaultGlobalConfig().notifications;
+  const obj = value;
+  const sessionEndRaw = obj.sessionEnd;
+  if (!sessionEndRaw || typeof sessionEndRaw !== "object")
+    return defaultGlobalConfig().notifications;
+  const sessionEndObj = sessionEndRaw;
+  return {
+    sessionEnd: {
+      banner: typeof sessionEndObj.banner === "boolean" ? sessionEndObj.banner : DEFAULT_NOTIFICATIONS.sessionEnd.banner,
+      sound: typeof sessionEndObj.sound === "boolean" ? sessionEndObj.sound : DEFAULT_NOTIFICATIONS.sessionEnd.sound
+    }
+  };
+}
+function normalizeWorktree(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const it = value;
+  const mainProjectId = typeof it.mainProjectId === "string" ? it.mainProjectId : "";
+  const mainPath = typeof it.mainPath === "string" ? it.mainPath : "";
+  const branch = typeof it.branch === "string" ? it.branch : "";
+  const specId = typeof it.specId === "string" ? it.specId : "";
+  const createdAt = typeof it.createdAt === "string" ? it.createdAt : "";
+  if (!mainProjectId || !mainPath || !branch) return void 0;
+  const cleanSlug = typeof it.cleanSlug === "string" ? it.cleanSlug : void 0;
+  const meta = { mainProjectId, mainPath, branch, specId, createdAt };
+  if (cleanSlug) meta.cleanSlug = cleanSlug;
+  return meta;
+}
+function generateProjectId(absPath) {
+  const base = basename$1(absPath);
+  const slug = slugify(base) || "proj";
+  const hash = createHash("sha256").update(absPath).digest("hex").slice(0, 6);
+  return `${slug}-${hash}`;
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
+}
+async function addProject(absPath, filePath, now = () => /* @__PURE__ */ new Date()) {
+  const config = await loadGlobalConfig(filePath);
+  const existing = config.projects.find((p) => p.path === absPath);
+  if (existing) return { entry: existing, created: false };
+  const entry = {
+    id: generateProjectId(absPath),
+    path: absPath,
+    addedAt: now().toISOString(),
+    lastActivityAt: null
+  };
+  config.projects.push(entry);
+  await saveGlobalConfig(config, filePath);
+  return { entry, created: true };
+}
+async function setProjectWorktree(id, worktree, filePath) {
+  const config = await loadGlobalConfig(filePath);
+  const target = config.projects.find((p) => p.id === id);
+  if (!target) return false;
+  if (worktree) target.worktree = worktree;
+  else delete target.worktree;
+  await saveGlobalConfig(config, filePath);
+  return true;
+}
+async function removeProject(id, filePath) {
+  const config = await loadGlobalConfig(filePath);
+  const before = config.projects.length;
+  config.projects = config.projects.filter((p) => p.id !== id);
+  if (config.projects.length === before) return false;
+  await saveGlobalConfig(config, filePath);
+  return true;
+}
+async function prepareProjectDir(input, cwd) {
+  if (typeof input !== "string" || !input.trim()) {
+    throw new Error("path required");
+  }
+  const trimmed = input.trim();
+  const abs = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd ?? process.cwd(), trimmed);
+  if (!existsSync(abs)) {
+    throw new Error(`path does not exist: ${abs}`);
+  }
+  const stats = await stat(abs);
+  if (!stats.isDirectory()) {
+    throw new Error(`path is not a directory: ${abs}`);
+  }
+  await mkdir(join(abs, ".yorz", "specs"), { recursive: true });
+  return abs;
+}
+const LEVEL_WEIGHT = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+const LOG_LEVELS = Object.keys(LEVEL_WEIGHT);
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_ARCHIVES = 1;
+const DEFAULT_LOG_FILE = "serve.log";
+const STDIO_LOG_FILE = "serve-stdio.log";
+function resolveLogDir(env = process.env) {
+  return join(resolveGlobalConfigDir(env), "logs");
+}
+function resolveLogLevel(env = process.env) {
+  const raw = env.YORZ_LOG_LEVEL?.trim().toLowerCase();
+  if (raw && LOG_LEVELS.includes(raw)) return raw;
+  return "info";
+}
+function defaultOptions(env = process.env) {
+  return {
+    dir: resolveLogDir(env),
+    fileName: DEFAULT_LOG_FILE,
+    maxBytes: DEFAULT_MAX_BYTES,
+    maxArchives: DEFAULT_MAX_ARCHIVES,
+    level: resolveLogLevel(env),
+    mirrorConsole: true
+  };
+}
+class RotatingFileSink {
+  constructor(dir, fileName, maxBytes, maxArchives) {
+    this.dir = dir;
+    this.fileName = fileName;
+    this.maxBytes = maxBytes;
+    this.maxArchives = maxArchives;
+  }
+  currentSize = 0;
+  initialized = false;
+  queue = Promise.resolve();
+  get filePath() {
+    return join(this.dir, this.fileName);
+  }
+  archivePath(index) {
+    return `${this.filePath}.${index}`;
+  }
+  /** Enqueue a line; returns immediately, never throws. */
+  write(line) {
+    this.queue = this.queue.then(() => this.writeNow(line)).catch(() => {
+    });
+  }
+  /** Resolve once every queued line has been flushed to disk. */
+  async flush() {
+    await this.queue.catch(() => {
+    });
+  }
+  async writeNow(line) {
+    try {
+      await this.ensureInit();
+      const bytes = Buffer.byteLength(line, "utf8");
+      if (this.currentSize > 0 && this.currentSize + bytes > this.maxBytes) {
+        await this.rotate();
+      }
+      await appendFile(this.filePath, line, "utf8");
+      this.currentSize += bytes;
+    } catch {
+    }
+  }
+  /** Lazily create the dir and recover `currentSize` from an existing file. */
+  async ensureInit() {
+    if (this.initialized) return;
+    await mkdir(this.dir, { recursive: true });
+    try {
+      const st = await stat(this.filePath);
+      this.currentSize = st.size;
+    } catch {
+      this.currentSize = 0;
+    }
+    this.initialized = true;
+  }
+  async rotate() {
+    if (this.maxArchives <= 0) {
+      await writeFile(this.filePath, "", "utf8");
+      this.currentSize = 0;
+      return;
+    }
+    for (let i = this.maxArchives - 1; i >= 1; i--) {
+      try {
+        await rename(this.archivePath(i), this.archivePath(i + 1));
+      } catch {
+      }
+    }
+    await rename(this.filePath, this.archivePath(1));
+    this.currentSize = 0;
+  }
+}
+function createSink(options) {
+  return new RotatingFileSink(options.dir, options.fileName, options.maxBytes, options.maxArchives);
+}
+function formatMeta(meta) {
+  if (!meta) return "";
+  const keys = Object.keys(meta);
+  if (keys.length === 0) return "";
+  try {
+    return ` ${JSON.stringify(meta, jsonReplacer)}`;
+  } catch {
+    return "";
+  }
+}
+function jsonReplacer(_key, value) {
+  if (value instanceof Error) return { message: value.message, stack: value.stack };
+  if (typeof value === "bigint") return value.toString();
+  return value;
+}
+class Logger {
+  constructor(core, scope) {
+    this.core = core;
+    this.scope = scope;
+  }
+  get level() {
+    return this.core.options.level;
+  }
+  get filePath() {
+    return this.core.sink.filePath;
+  }
+  get dir() {
+    return this.core.options.dir;
+  }
+  /** Derive a logger that prefixes every line with `[scope]`. */
+  child(scope) {
+    const next = this.scope && this.scope !== "yorz" ? `${this.scope}:${scope}` : scope;
+    return new Logger(this.core, next);
+  }
+  debug(msg, meta) {
+    this.emit("debug", msg, meta);
+  }
+  info(msg, meta) {
+    this.emit("info", msg, meta);
+  }
+  warn(msg, meta) {
+    this.emit("warn", msg, meta);
+  }
+  error(msg, meta) {
+    this.emit("error", msg, meta);
+  }
+  /** Replace options in place; every existing child logger picks the change up. */
+  configure(patch) {
+    const prev = this.core.options;
+    const next = { ...prev, ...patch };
+    this.core.options = next;
+    const sinkChanged = next.dir !== prev.dir || next.fileName !== prev.fileName || next.maxBytes !== prev.maxBytes || next.maxArchives !== prev.maxArchives;
+    if (sinkChanged) this.core.sink = createSink(next);
+  }
+  async flush() {
+    await this.core.sink.flush();
+  }
+  emit(level, msg, meta) {
+    const { options } = this.core;
+    if (LEVEL_WEIGHT[level] < LEVEL_WEIGHT[options.level]) return;
+    const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] [${level}] [${this.scope}] ${msg}${formatMeta(meta)}
+`;
+    if (options.mirrorConsole) mirror(level, line);
+    this.core.sink.write(line);
+  }
+}
+function mirror(level, line) {
+  const text = line.endsWith("\n") ? line.slice(0, -1) : line;
+  try {
+    if (level === "error") console.error(text);
+    else if (level === "warn") console.warn(text);
+    else console.log(text);
+  } catch {
+  }
+}
+function createLogger(patch = {}) {
+  const options = { ...defaultOptions(), ...patch };
+  return new Logger({ options, sink: createSink(options) }, "yorz");
+}
+let singleton = null;
+function getLogger() {
+  if (!singleton) singleton = createLogger();
+  return singleton;
+}
+function configureLogger(patch) {
+  const logger = getLogger();
+  logger.configure(patch);
+  return logger;
+}
+const sseLog = () => getLogger().child("sse");
 const HEARTBEAT_INTERVAL_MS = 5e3;
 function attachHeartbeat(stream, intervalMs = HEARTBEAT_INTERVAL_MS) {
   const timer = setInterval(() => {
@@ -1626,7 +1985,7 @@ class EventsHub {
         s.queue.push(frame);
       }
     } catch (err) {
-      console.error("[yorz] SSE emit error:", err);
+      sseLog().warn("emit failed", { topic, err });
     }
   }
   async flush(s) {
@@ -1812,10 +2171,10 @@ function createProjectRoutes(registry, worktreeManager) {
   });
   return app;
 }
-const CURRENT_VERSION$1 = 1;
+const CURRENT_VERSION = 1;
 const DEFAULT_SPECS_DIR = ".yorz/specs";
 function defaultProjectConfig() {
-  return { version: CURRENT_VERSION$1, agent: { kind: "claude" }, specsDir: DEFAULT_SPECS_DIR };
+  return { version: CURRENT_VERSION, agent: { kind: "inherit" }, specsDir: DEFAULT_SPECS_DIR };
 }
 function configPath(cwd) {
   return join(cwd, ".yorz", "config.json");
@@ -1836,12 +2195,12 @@ async function loadProjectConfig(cwd) {
   } catch {
     return defaultProjectConfig();
   }
-  return normalizeConfig$1(parsed);
+  return normalizeConfig(parsed);
 }
 async function saveProjectConfig(cwd, cfg) {
   const fp = configPath(cwd);
   await mkdir(dirname(fp), { recursive: true });
-  const normalized = normalizeConfig$1(cfg);
+  const normalized = normalizeConfig(cfg);
   const body = `${JSON.stringify(normalized, null, 2)}
 `;
   const tmp = `${fp}.tmp-${process.pid}-${Date.now().toString(36)}`;
@@ -1861,12 +2220,12 @@ function resolveSpecsDir(cwd, cfg) {
 async function ensureSpecsDirExists(absSpecsDir) {
   await mkdir(absSpecsDir, { recursive: true });
 }
-function normalizeConfig$1(value) {
+function normalizeConfig(value) {
   if (!value || typeof value !== "object") return defaultProjectConfig();
   const obj = value;
   const agent = normalizeAgent(obj.agent);
   const specsDir = normalizeSpecsDir(obj.specsDir);
-  return { version: CURRENT_VERSION$1, agent, specsDir };
+  return { version: CURRENT_VERSION, agent, specsDir };
 }
 function normalizeAgent(value) {
   if (typeof value === "string") {
@@ -1877,6 +2236,7 @@ function normalizeAgent(value) {
   if (!value || typeof value !== "object") return { kind: "claude" };
   const obj = value;
   const kind = obj.kind;
+  if (kind === "inherit") return { kind: "inherit" };
   if (kind === "opencode") return { kind: "opencode" };
   if (kind === "codex") return { kind: "codex" };
   if (kind === "custom") {
@@ -1912,7 +2272,7 @@ function createProjectConfigRoutes(registry) {
     } catch {
       return c.json({ error: "invalid JSON body" }, 400);
     }
-    const parsed = parseBody(raw);
+    const parsed = parseBody$1(raw);
     if ("error" in parsed) return c.json({ error: parsed.error }, 400);
     const cfg = {
       version: 1,
@@ -1940,7 +2300,7 @@ function createProjectConfigRoutes(registry) {
   });
   return app;
 }
-function parseBody(value) {
+function parseBody$1(value) {
   if (!value || typeof value !== "object") return { error: "body must be an object" };
   const obj = value;
   const agent = parseAgent(obj.agent);
@@ -1955,6 +2315,7 @@ function parseAgent(value) {
   }
   const obj = value;
   const kind = obj.kind;
+  if (kind === "inherit") return { value: { kind: "inherit" } };
   if (kind === "claude") return { value: { kind: "claude" } };
   if (kind === "opencode") return { value: { kind: "opencode" } };
   if (kind === "codex") return { value: { kind: "codex" } };
@@ -1978,7 +2339,7 @@ function parseAgent(value) {
     }
     return { value: { kind: "custom", cmd: cmd.trim(), args } };
   }
-  return { error: "agent.kind must be claude | opencode | codex | custom" };
+  return { error: "agent.kind must be inherit | claude | opencode | codex | custom" };
 }
 function parseSpecsDir(value) {
   const fallback = defaultProjectConfig().specsDir;
@@ -1992,6 +2353,62 @@ function parseSpecsDir(value) {
   }
   return { value: trimmed };
 }
+function createGlobalConfigRoutes(globalConfigPath) {
+  const app = new Hono();
+  app.get("/global-config", async (c) => {
+    const cfg = await loadGlobalConfig(globalConfigPath);
+    return c.json({ agent: cfg.agent, notifications: cfg.notifications });
+  });
+  app.put("/global-config", async (c) => {
+    let raw;
+    try {
+      raw = await c.req.json();
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+    const parsed = parseBody(raw);
+    if ("error" in parsed) return c.json({ error: parsed.error }, 400);
+    const cfg = await loadGlobalConfig(globalConfigPath);
+    cfg.agent = parsed.agent;
+    cfg.notifications = parsed.notifications;
+    await saveGlobalConfig(cfg, globalConfigPath);
+    return c.json({ ok: true, config: { agent: cfg.agent, notifications: cfg.notifications } });
+  });
+  return app;
+}
+function parseBody(value) {
+  if (!value || typeof value !== "object") return { error: "body must be an object" };
+  const obj = value;
+  const agent = obj.agent;
+  if (!agent || typeof agent !== "object") {
+    return { error: "agent must be an object" };
+  }
+  const agentObj = agent;
+  const defaultKind = agentObj.defaultKind;
+  if (defaultKind !== "claude" && defaultKind !== "opencode" && defaultKind !== "codex") {
+    return { error: "agent.defaultKind must be claude | opencode | codex" };
+  }
+  const notifications = obj.notifications;
+  if (!notifications || typeof notifications !== "object") {
+    return { error: "notifications must be an object" };
+  }
+  const n = notifications;
+  const sessionEnd = n.sessionEnd;
+  if (!sessionEnd || typeof sessionEnd !== "object") {
+    return { error: "notifications.sessionEnd must be an object" };
+  }
+  const s = sessionEnd;
+  if (typeof s.banner !== "boolean") {
+    return { error: "notifications.sessionEnd.banner must be a boolean" };
+  }
+  if (typeof s.sound !== "boolean") {
+    return { error: "notifications.sessionEnd.sound must be a boolean" };
+  }
+  return {
+    agent: { defaultKind },
+    notifications: { sessionEnd: { banner: s.banner, sound: s.sound } }
+  };
+}
 function createSpecDraftsRoutes(resolveProject) {
   const app = new Hono();
   const need = async (c) => {
@@ -2393,6 +2810,7 @@ async function serveFile(c, file) {
   return c.body(body);
 }
 const DEBOUNCE_MS = 200;
+const registryLog = () => getLogger().child("registry");
 class RegistryEventBus {
   subs = /* @__PURE__ */ new Set();
   watcher = null;
@@ -2425,7 +2843,7 @@ class RegistryEventBus {
         this.scheduleEmit();
       });
     } catch (err) {
-      console.warn(`[registry-events] watch failed: ${err.message}`);
+      registryLog().warn("projects.json watch failed", { dir, message: err.message });
     }
   }
   stop() {
@@ -2445,134 +2863,7 @@ class RegistryEventBus {
     this.debounceTimer.unref?.();
   }
 }
-const CURRENT_VERSION = 1;
-function resolveGlobalConfigDir(env = process.env) {
-  if (env.YORZ_HOME && env.YORZ_HOME.trim()) return env.YORZ_HOME.trim();
-  const xdg = env.XDG_CONFIG_HOME?.trim();
-  const base = xdg && xdg.length > 0 ? xdg : join(homedir(), ".config");
-  return join(base, "yorz");
-}
-function resolveGlobalConfigPath(env = process.env) {
-  return join(resolveGlobalConfigDir(env), "projects.json");
-}
-async function loadGlobalConfig(filePath) {
-  const fp = filePath ?? resolveGlobalConfigPath();
-  if (!existsSync(fp)) return { version: CURRENT_VERSION, projects: [] };
-  let raw;
-  try {
-    raw = await readFile(fp, "utf8");
-  } catch {
-    return { version: CURRENT_VERSION, projects: [] };
-  }
-  if (!raw.trim()) return { version: CURRENT_VERSION, projects: [] };
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return { version: CURRENT_VERSION, projects: [] };
-  }
-  return normalizeConfig(parsed);
-}
-async function saveGlobalConfig(config, filePath) {
-  const fp = filePath ?? resolveGlobalConfigPath();
-  await mkdir(dirname(fp), { recursive: true });
-  const normalized = normalizeConfig(config);
-  const body = `${JSON.stringify(normalized, null, 2)}
-`;
-  const tmp = `${fp}.tmp-${process.pid}-${Date.now().toString(36)}`;
-  await writeFile(tmp, body, "utf8");
-  await rename(tmp, fp);
-}
-function normalizeConfig(value) {
-  if (!value || typeof value !== "object") return { version: CURRENT_VERSION, projects: [] };
-  const obj = value;
-  const projectsRaw = Array.isArray(obj.projects) ? obj.projects : [];
-  const projects = [];
-  for (const item of projectsRaw) {
-    if (!item || typeof item !== "object") continue;
-    const it = item;
-    const id = typeof it.id === "string" ? it.id : "";
-    const path = typeof it.path === "string" ? it.path : "";
-    if (!id || !path) continue;
-    const addedAt = typeof it.addedAt === "string" ? it.addedAt : "";
-    const lastActivityAt = typeof it.lastActivityAt === "string" ? it.lastActivityAt : null;
-    const worktree = normalizeWorktree(it.worktree);
-    const entry = { id, path, addedAt, lastActivityAt };
-    if (worktree) entry.worktree = worktree;
-    projects.push(entry);
-  }
-  return { version: CURRENT_VERSION, projects };
-}
-function normalizeWorktree(value) {
-  if (!value || typeof value !== "object") return void 0;
-  const it = value;
-  const mainProjectId = typeof it.mainProjectId === "string" ? it.mainProjectId : "";
-  const mainPath = typeof it.mainPath === "string" ? it.mainPath : "";
-  const branch = typeof it.branch === "string" ? it.branch : "";
-  const specId = typeof it.specId === "string" ? it.specId : "";
-  const createdAt = typeof it.createdAt === "string" ? it.createdAt : "";
-  if (!mainProjectId || !mainPath || !branch) return void 0;
-  const cleanSlug = typeof it.cleanSlug === "string" ? it.cleanSlug : void 0;
-  const meta = { mainProjectId, mainPath, branch, specId, createdAt };
-  if (cleanSlug) meta.cleanSlug = cleanSlug;
-  return meta;
-}
-function generateProjectId(absPath) {
-  const base = basename$1(absPath);
-  const slug = slugify(base) || "proj";
-  const hash = createHash("sha256").update(absPath).digest("hex").slice(0, 6);
-  return `${slug}-${hash}`;
-}
-function slugify(text) {
-  return text.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40).replace(/-+$/, "");
-}
-async function addProject(absPath, filePath, now = () => /* @__PURE__ */ new Date()) {
-  const config = await loadGlobalConfig(filePath);
-  const existing = config.projects.find((p) => p.path === absPath);
-  if (existing) return { entry: existing, created: false };
-  const entry = {
-    id: generateProjectId(absPath),
-    path: absPath,
-    addedAt: now().toISOString(),
-    lastActivityAt: null
-  };
-  config.projects.push(entry);
-  await saveGlobalConfig(config, filePath);
-  return { entry, created: true };
-}
-async function setProjectWorktree(id, worktree, filePath) {
-  const config = await loadGlobalConfig(filePath);
-  const target = config.projects.find((p) => p.id === id);
-  if (!target) return false;
-  if (worktree) target.worktree = worktree;
-  else delete target.worktree;
-  await saveGlobalConfig(config, filePath);
-  return true;
-}
-async function removeProject(id, filePath) {
-  const config = await loadGlobalConfig(filePath);
-  const before = config.projects.length;
-  config.projects = config.projects.filter((p) => p.id !== id);
-  if (config.projects.length === before) return false;
-  await saveGlobalConfig(config, filePath);
-  return true;
-}
-async function prepareProjectDir(input, cwd) {
-  if (typeof input !== "string" || !input.trim()) {
-    throw new Error("path required");
-  }
-  const trimmed = input.trim();
-  const abs = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd ?? process.cwd(), trimmed);
-  if (!existsSync(abs)) {
-    throw new Error(`path does not exist: ${abs}`);
-  }
-  const stats = await stat(abs);
-  if (!stats.isDirectory()) {
-    throw new Error(`path is not a directory: ${abs}`);
-  }
-  await mkdir(join(abs, ".yorz", "specs"), { recursive: true });
-  return abs;
-}
+const worktreeLog = () => getLogger().child("worktree");
 class WorktreeManager {
   registry;
   globalConfigPath;
@@ -2620,6 +2911,13 @@ class WorktreeManager {
     };
     await setProjectWorktree(entry.id, meta, this.globalConfigPath);
     const updated = await this.registry.findEntry(entry.id) ?? { ...entry, worktree: meta };
+    worktreeLog().info("worktree created", {
+      mainProjectId: main.id,
+      worktreeProjectId: entry.id,
+      branch,
+      path: wtPath,
+      baseRef
+    });
     return { entry: updated, branch, path: wtPath, baseRef };
   }
   /** Update the `specId` on a worktree entry once the spec has been created. */
@@ -2660,6 +2958,12 @@ class WorktreeManager {
         globalConfigPath: this.globalConfigPath ?? resolveGlobalConfigPath(),
         now: input.now ?? (() => /* @__PURE__ */ new Date())
       });
+      worktreeLog().warn("merge back hit conflicts", {
+        worktreeProjectId: entry.id,
+        branch,
+        mainPath,
+        conflictSpecId: "conflictSpecId" in conflict ? conflict.conflictSpecId : void 0
+      });
       return conflict;
     }
     const head = await runGitChecked(mainPath, ["rev-parse", "HEAD"]);
@@ -2674,6 +2978,12 @@ class WorktreeManager {
       await this.registry.reload(mainEntry.id);
     }
     this.onProjectsChanged?.();
+    worktreeLog().info("worktree merged back", {
+      worktreeProjectId: entry.id,
+      mainProjectId: mainEntry?.id ?? entry.worktree.mainProjectId,
+      branch,
+      mergeCommit
+    });
     return {
       status: "merged",
       mainProjectId: mainEntry?.id ?? entry.worktree.mainProjectId,
@@ -2701,6 +3011,7 @@ class WorktreeManager {
     }
     await this.registry.remove(worktreeProjectId);
     this.onProjectsChanged?.();
+    worktreeLog().info("worktree removed", { worktreeProjectId, branch, path: wtPath });
   }
   async listWorktreesOf(mainProjectId) {
     const config = await loadGlobalConfig(this.globalConfigPath);
@@ -2711,7 +3022,7 @@ class WorktreeManager {
     const files = unmerged.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
     const commitsByFile = {};
     for (const file of files) {
-      const log = await runGitRaw(mainPath, [
+      const log2 = await runGitRaw(mainPath, [
         "log",
         "--since=30 days ago",
         "--pretty=format:%h%x09%ad%x09%an%x09%s",
@@ -2719,7 +3030,7 @@ class WorktreeManager {
         "--",
         file
       ]);
-      commitsByFile[file] = parseCommitLines(log.stdout);
+      commitsByFile[file] = parseCommitLines(log2.stdout);
     }
     const merges = await runGitRaw(mainPath, [
       "log",
@@ -2767,9 +3078,10 @@ class WorktreeManager {
     if (this.triggerConflictAgent) {
       await this.triggerConflictAgent(args.mainProjectId, specId);
     } else {
-      console.warn(
-        `[worktree] triggerConflictAgent not configured; conflict spec ${specId} created at ${specPath} but no Agent was launched`
-      );
+      worktreeLog().warn("triggerConflictAgent not configured; no Agent launched", {
+        specId,
+        specPath
+      });
     }
     return {
       status: "conflict",
@@ -2916,8 +3228,25 @@ _暂无_
 function pad2(n) {
   return n < 10 ? `0${n}` : String(n);
 }
+const SLOW_REQUEST_MS = 1e3;
 function createApp(opts) {
   const app = new Hono();
+  const httpLog = getLogger().child("http");
+  const worktreeLog2 = getLogger().child("worktree");
+  app.use("*", async (c, next) => {
+    const startedAt = Date.now();
+    await next();
+    const durationMs = Date.now() - startedAt;
+    const meta = {
+      method: c.req.method,
+      path: c.req.path,
+      status: c.res.status,
+      durationMs
+    };
+    if (c.res.status >= 400) httpLog.warn("request failed", meta);
+    else if (durationMs >= SLOW_REQUEST_MS) httpLog.warn("slow request", meta);
+    else httpLog.debug("request", meta);
+  });
   const api = new Hono();
   const resolveProject = (id) => opts.registry.getOrCreate(id);
   const projectsBus = new RegistryEventBus();
@@ -2928,9 +3257,10 @@ function createApp(opts) {
     triggerConflictAgent: async (mainProjectId, specId) => {
       const main = await opts.registry.getOrCreate(mainProjectId);
       if (!main) {
-        console.warn(
-          `[worktree] cannot launch conflict Agent: main project ${mainProjectId} not resolvable`
-        );
+        worktreeLog2.warn("cannot launch conflict Agent: main project not resolvable", {
+          mainProjectId,
+          specId
+        });
         return;
       }
       const { sessionId } = await main.sessions.ensureSessionForSpec(specId);
@@ -2941,6 +3271,7 @@ function createApp(opts) {
     }
   });
   api.route("/", createProjectRoutes(opts.registry, worktreeManager));
+  api.route("/", createGlobalConfigRoutes(opts.registry.configPath()));
   api.route("/", createProjectConfigRoutes(opts.registry));
   api.route("/", createSpecsRoutes(resolveProject));
   api.route("/", createSessionsRoutes(resolveProject));
@@ -2952,7 +3283,13 @@ function createApp(opts) {
   app.route("/api", api);
   app.route("/", createStaticRoutes(opts.guiRoot));
   app.onError((err, c) => {
-    console.error("[yorz] route error:", err);
+    httpLog.error("route error", {
+      method: c.req.method,
+      path: c.req.path,
+      status: 500,
+      message: err.message,
+      stack: err.stack
+    });
     return c.json({ error: "Internal Server Error", message: err.message }, 500);
   });
   return app;
@@ -3404,6 +3741,7 @@ function placeholderSummary(requirement) {
   if (!firstParagraph) return "（待 Agent 补全）";
   return firstParagraph.length > 200 ? `${firstParagraph.slice(0, 199)}…` : firstParagraph;
 }
+const watcherLog = () => getLogger().child("watcher");
 const UNLINK_SETTLE_MS = 80;
 class SpecWatcher {
   root;
@@ -3427,13 +3765,15 @@ class SpecWatcher {
       depth: 2,
       ...usePolling ? { usePolling: true, interval: 100 } : {}
     });
-    this.watcher.on("add", (p) => this.handle(p, "updated"));
-    this.watcher.on("change", (p) => this.handle(p, "updated"));
-    this.watcher.on("unlink", (p) => this.handle(p, "removed"));
+    this.watcher.on("add", (p) => this.handle(p, "updated", "add"));
+    this.watcher.on("change", (p) => this.handle(p, "updated", "change"));
+    this.watcher.on("unlink", (p) => this.handle(p, "removed", "unlink"));
+    this.watcher.on("error", (err) => watcherLog().warn("watch error", { root: this.root, err }));
     await new Promise((resolve2, reject) => {
       this.watcher.once("ready", () => resolve2());
       this.watcher.once("error", (err) => reject(err));
     });
+    watcherLog().debug("watching specs dir", { root: this.root, usePolling });
   }
   async close() {
     for (const timer of this.pendingUnlinks.values()) clearTimeout(timer);
@@ -3462,10 +3802,11 @@ class SpecWatcher {
     this.listListeners.add(cb);
     return () => this.listListeners.delete(cb);
   }
-  async handle(filePath, evt) {
+  async handle(filePath, evt, raw) {
     if (basename$1(filePath) !== "spec.md") return;
     const id = this.idForPath(filePath);
     if (!id) return;
+    watcherLog().debug("spec file event", { event: raw, specId: id, path: filePath });
     if (evt === "removed") {
       this.scheduleUnlink(id, filePath);
       return;
@@ -4072,6 +4413,7 @@ class AdapterRegistry {
     this.byKind.clear();
   }
 }
+const agentLog = () => getLogger().child("agent");
 const SESSION_LIST_LIMIT = 30;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const TITLE_MAX_LENGTH = 64;
@@ -4086,10 +4428,11 @@ function summarizePromptForTitle(prompt) {
   return cleaned.length > TITLE_MAX_LENGTH ? `${cleaned.slice(0, TITLE_MAX_LENGTH - 1)}…` : cleaned;
 }
 class SessionManager {
-  constructor(cwd, defaultKind, store) {
+  constructor(cwd, defaultKind, store, opts = {}) {
     this.cwd = cwd;
     this.defaultKind = defaultKind;
     this.store = store;
+    this.opts = opts;
     this.adapters = new AdapterRegistry(cwd);
     this.statusEmitter.setMaxListeners(0);
   }
@@ -4215,9 +4558,11 @@ class SessionManager {
     const runId = randomUUID();
     const emitter = this.emitterFor(sid);
     let currentSid = sid;
+    const startedAt = Date.now();
     await this.maybeUpdateTitleFromPrompt(currentSid, prompt).catch(() => {
     });
     this.setRunning(sid, true);
+    agentLog().info("dispatch start", { sessionId: sid, runId, promptLength: prompt.length });
     void (async () => {
       try {
         const ls = await this.ensureLive(sid);
@@ -4230,14 +4575,28 @@ class SessionManager {
           emitter.emit("event", ev);
         }
       } catch (err) {
+        agentLog().error("dispatch failed", {
+          sessionId: currentSid,
+          runId,
+          durationMs: Date.now() - startedAt,
+          message: err instanceof Error ? err.message : String(err),
+          stack: err instanceof Error ? err.stack : void 0
+        });
         emitter.emit("event", {
           type: "error",
           message: err instanceof Error ? err.message : String(err)
         });
       } finally {
+        agentLog().info("dispatch end", {
+          sessionId: currentSid,
+          runId,
+          durationMs: Date.now() - startedAt
+        });
         await this.store.touch(currentSid).catch(() => {
         });
         this.setRunning(currentSid, false);
+        void Promise.resolve(this.opts.onSessionEnd?.(currentSid)).catch(() => {
+        });
         emitter.emit("done");
       }
     })();
@@ -4261,6 +4620,7 @@ class SessionManager {
     return () => emitter.off("event", onEvent);
   }
   async reconcile(oldId, newId) {
+    agentLog().debug("reconcile sessionId", { from: oldId, to: newId });
     const ls = this.live.get(oldId);
     if (ls) {
       this.live.delete(oldId);
@@ -4365,30 +4725,78 @@ class SessionStore {
     await this.persist();
   }
 }
-function resolveAgentKind(cwd) {
-  const path = join(cwd, ".yorz", "config.json");
-  if (!existsSync(path)) return "claude";
-  let raw;
-  try {
-    raw = readFileSync(path, "utf8");
-  } catch {
-    return "claude";
+const execFileP = promisify(execFile);
+const COMMAND_TIMEOUT_MS = 4e3;
+function createSessionEndNotifier(opts = {}) {
+  return async function notifySessionEnded() {
+    const cfg = await loadGlobalConfig(opts.globalConfigPath);
+    const sessionEnd = cfg.notifications.sessionEnd;
+    if (!sessionEnd.banner && !sessionEnd.sound) return;
+    const os = opts.platform ?? platform();
+    const run = opts.runCommand ?? defaultRunCommand;
+    const tasks = [];
+    if (sessionEnd.banner) tasks.push(showBanner(os, run));
+    if (sessionEnd.sound) tasks.push(playSound(os, run));
+    await Promise.all(tasks.map((task) => task.catch(() => {
+    })));
+  };
+}
+async function defaultRunCommand(cmd, args) {
+  await execFileP(cmd, args, {
+    timeout: COMMAND_TIMEOUT_MS,
+    windowsHide: true
+  });
+}
+async function showBanner(os, run) {
+  if (os === "darwin") {
+    await run("osascript", ["-e", 'display notification "" with title "YorZ"']);
+    return;
   }
-  if (!raw.trim()) return "claude";
-  let data;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    return "claude";
+  if (os === "win32") {
+    await run("powershell.exe", [
+      "-NoProfile",
+      "-NonInteractive",
+      "-Command",
+      [
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "Add-Type -AssemblyName System.Drawing",
+        "$n = New-Object System.Windows.Forms.NotifyIcon",
+        "$n.Icon = [System.Drawing.SystemIcons]::Information",
+        "$n.Visible = $true",
+        "$n.ShowBalloonTip(5000, 'YorZ', '', [System.Windows.Forms.ToolTipIcon]::Info)",
+        "Start-Sleep -Milliseconds 5500",
+        "$n.Dispose()"
+      ].join("; ")
+    ]);
+    return;
   }
-  if (!data || typeof data !== "object") return "claude";
-  const agent = data.agent;
-  if (typeof agent === "string") {
-    return agent === "codex" || agent === "opencode" ? agent : "claude";
+  await run("notify-send", ["YorZ", ""]);
+}
+async function playSound(os, run) {
+  if (os === "darwin") {
+    await run("afplay", ["/System/Library/Sounds/Submarine.aiff"]);
+    return;
+  }
+  if (os === "win32") {
+    await run("powershell.exe", [
+      "-NoProfile",
+      "-NonInteractive",
+      "-Command",
+      "[console]::beep(440, 180)"
+    ]);
+    return;
+  }
+  for (const [cmd, args] of [
+    ["paplay", ["/usr/share/sounds/freedesktop/stereo/complete.oga"]],
+    ["canberra-gtk-play", ["-i", "complete"]],
+    ["aplay", ["/usr/share/sounds/alsa/Front_Center.wav"]]
+  ]) {
+    try {
+      await run(cmd, args);
+      return;
+    } catch {
+    }
   }
-  if (!agent || typeof agent !== "object") return "claude";
-  const kind = agent.kind;
-  return kind === "codex" || kind === "opencode" ? kind : "claude";
 }
 class ProjectRegistry {
   globalConfigPath;
@@ -4488,6 +4896,7 @@ class ProjectRegistry {
   }
   async materialize(input) {
     const cfg = await loadProjectConfig(input.path);
+    const globalCfg = await loadGlobalConfig(this.globalConfigPath);
     const specsDir = resolveSpecsDir(input.path, cfg);
     const specsDirRelative = posixRelative(input.path, specsDir);
     await ensureSpecsDirExists(specsDir);
@@ -4499,7 +4908,11 @@ class ProjectRegistry {
     });
     const attachments = new AttachmentStore({ cwd: input.path });
     const sessionStore = new SessionStore(input.path);
-    const sessions = new SessionManager(input.path, resolveAgentKind(input.path), sessionStore);
+    const notifySessionEnded = createSessionEndNotifier({ globalConfigPath: this.globalConfigPath });
+    const defaultKind = resolveProjectAgentKind(cfg.agent, globalCfg.agent.defaultKind);
+    const sessions = new SessionManager(input.path, defaultKind, sessionStore, {
+      onSessionEnd: notifySessionEnded
+    });
     let closed = false;
     const instance = {
       id: input.id,
@@ -4530,6 +4943,11 @@ class ProjectRegistry {
     return instance;
   }
 }
+function resolveProjectAgentKind(projectAgent, globalDefault) {
+  if (projectAgent.kind === "inherit") return globalDefault;
+  if (projectAgent.kind === "codex" || projectAgent.kind === "opencode") return projectAgent.kind;
+  return "claude";
+}
 function basename(p) {
   const parts = p.split(/[/\\]/).filter(Boolean);
   return parts[parts.length - 1] ?? p;
@@ -4556,6 +4974,7 @@ async function maxSpecUpdatedAt(projectPath) {
 }
 const DEFAULT_PORT = 7423;
 const MAX_PORT_TRIES = 10;
+const log$1 = () => getLogger().child("serve");
 async function start(opts = {}) {
   const registry = new ProjectRegistry({ globalConfigPath: opts.globalConfigPath });
   const cwd = opts.cwd ?? process.cwd();
@@ -4577,6 +4996,15 @@ async function start(opts = {}) {
     console.log(`  - ${p.name} -> ${p.path}`);
   }
   console.log(`agent heartbeat enabled (interval=${HEARTBEAT_INTERVAL_MS / 1e3}s)`);
+  log$1().info("service ready", {
+    pid: process.pid,
+    port: port.port,
+    url,
+    projects: projects.length,
+    node: process.version,
+    cli: pkg.version,
+    logFile: getLogger().filePath
+  });
   installGlobalErrorHandlers();
   if (opts.open) await tryOpenBrowser(url);
   return {
@@ -4618,10 +5046,18 @@ async function listen(fetchHandler, preferredPort) {
       );
     } catch (err) {
       lastErr = err;
-      if (err.code !== "EADDRINUSE") break;
+      const code = err.code;
+      if (code === "EADDRINUSE") {
+        log$1().warn("port in use, retrying", { port: tryPort, attempt: i + 1, max: MAX_PORT_TRIES });
+      } else {
+        log$1().warn("listen failed", { port: tryPort, code, err: lastErr });
+        break;
+      }
     }
   }
-  throw lastErr ?? new Error(`failed to bind port near ${preferredPort}`);
+  const fatal = lastErr ?? new Error(`failed to bind port near ${preferredPort}`);
+  log$1().error("failed to bind any port", { preferredPort, tries: MAX_PORT_TRIES, err: fatal });
+  throw fatal;
 }
 function listLanUrls(port) {
   const urls = [];
@@ -4643,23 +5079,9 @@ async function tryOpenBrowser(url) {
   } catch {
   }
 }
-let errorLogReady = false;
-async function ensureErrorLogDir() {
-  const dir = join(resolveGlobalConfigDir(), "logs");
-  if (!errorLogReady) {
-    await mkdir(dir, { recursive: true });
-    errorLogReady = true;
-  }
-  return join(dir, "serve-errors.log");
-}
 function logCrash(kind, payload) {
-  const ts = (/* @__PURE__ */ new Date()).toISOString();
   const body = payload instanceof Error ? payload.stack ?? payload.message : String(payload);
-  const line = `[${ts}] [${kind}] ${body}
-`;
-  console.error(`[yorz] ${kind}:`, payload);
-  void ensureErrorLogDir().then((fp) => appendFile(fp, line, "utf8")).catch(() => {
-  });
+  log$1().error(kind, { detail: body });
 }
 function installGlobalErrorHandlers() {
   if (process.listenerCount("uncaughtException") > 0) return;
@@ -4670,10 +5092,25 @@ function installGlobalErrorHandlers() {
     logCrash("unhandledRejection", reason);
   });
 }
+const log = () => getLogger().child("serve");
+function silenceConsoleMirror() {
+  configureLogger({ mirrorConsole: false });
+}
 const DEFAULT_SERVE_PORT = 7423;
 const RUNTIME_FILE = "runtime.json";
 const START_LOCK_DIR = "serve.lock";
 const START_WAIT_MS = 5e3;
+function backgroundStdio() {
+  try {
+    const dir = resolveLogDir();
+    mkdirSync(dir, { recursive: true });
+    const filePath = join(dir, STDIO_LOG_FILE);
+    const fd = openSync(filePath, "w");
+    return { stdio: ["ignore", fd, fd], path: filePath };
+  } catch {
+    return { stdio: "ignore", path: null };
+  }
+}
 async function runServe(opts) {
   if (!opts.skipSkillCheck) {
     await ensureSkillsInstalledWithLog(opts.cwd ?? process.cwd());
@@ -4708,6 +5145,7 @@ async function runServe(opts) {
   return handle;
 }
 function startBackgroundServe(opts) {
+  silenceConsoleMirror();
   return withStartLock(async () => {
     const live = await readLiveProcesses();
     if (live.length > 0) {
@@ -4725,12 +5163,24 @@ function startBackgroundServe(opts) {
     }
     const entry = process.argv[1];
     if (!entry) throw new Error("Cannot resolve CLI entrypoint for background service");
+    const stdio = backgroundStdio();
     const child = spawn(process.execPath, [entry, "serve", ...backgroundArgs(opts)], {
       detached: true,
-      stdio: "ignore"
+      stdio: stdio.stdio
     });
     child.unref();
+    log().info("background service spawned", {
+      pid: child.pid,
+      stdioFile: stdio.path,
+      logFile: getLogger().filePath
+    });
     const runtime = await waitForRuntime(child.pid, START_WAIT_MS);
+    if (!runtime) {
+      log().warn("timed out waiting for runtime.json", {
+        pid: child.pid,
+        timeoutMs: START_WAIT_MS
+      });
+    }
     const port = runtime?.port ?? opts.port ?? DEFAULT_SERVE_PORT;
     const url = runtime?.url ?? `http://localhost:${port}/`;
     console.log(`YorZ Service started in background (pid=${child.pid ?? "unknown"}).`);
@@ -4766,6 +5216,7 @@ async function ensureSkillsInstalledWithLog(cwd) {
   }
 }
 async function runStopServe() {
+  silenceConsoleMirror();
   const all = await readAllProcesses();
   if (all.length === 0) {
     return {
@@ -4779,6 +5230,7 @@ async function runStopServe() {
   const dead = all.filter((p) => !isProcessAlive(p.pid));
   if (alive.length === 0) {
     await removeRuntime();
+    log().warn("cleared stale runtime records", { pids: dead.map((p) => p.pid) });
     const deadPidList = dead.map((p) => `pid=${p.pid}`).join(", ");
     return {
       stopped: false,
@@ -4793,12 +5245,15 @@ async function runStopServe() {
   for (const proc of alive) {
     try {
       process.kill(proc.pid, "SIGTERM");
-    } catch {
+      log().info("sent SIGTERM", { pid: proc.pid, url: proc.url });
+    } catch (err) {
+      log().warn("SIGTERM failed", { pid: proc.pid, err });
       failedPids.push(proc.pid);
       continue;
     }
     let stopped = await waitForProcessExit(proc.pid, 2e3);
     if (!stopped) {
+      log().warn("still alive after SIGTERM, escalating to SIGKILL", { pid: proc.pid });
       try {
         process.kill(proc.pid, "SIGKILL");
       } catch {
@@ -4809,6 +5264,7 @@ async function runStopServe() {
       stoppedPids.push(proc.pid);
       stoppedUrls.push(proc.url);
     } else {
+      log().warn("process did not exit", { pid: proc.pid });
       failedPids.push(proc.pid);
     }
   }