@xyagent/cli 0.0.1 → 1.1.0

package/src-ext/runtime/_shared/headlessCliBridge.mjs

@@ -0,0 +1,168 @@
+import path from "node:path";
+import process from "node:process";
+
+import { bootstrapAgentlinkTools } from "../../core/agentlinkToolsBootstrap.mjs";
+import { createActiveRunRegistry } from "../../core/activeRuns.mjs";
+import { installAutoTunnel } from "../../core/autoTunnelWiring.mjs";
+import { runWorkerWithRevokeHandling } from "../../core/bridgeSelfUninstall.mjs";
+import { ensureDefaultWorkspace } from "../../core/defaultWorkspace.mjs";
+import { resolveSession } from "../../core/pairCodeClient.mjs";
+import { createRelayWorker } from "../../core/relayWorker.mjs";
+import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
+import { scanWorkspacesByRuntime } from "../../core/scanWorkspaces.mjs";
+
+export function createHeadlessRuntimeController({ log } = {}) {
+  const activeRuns = createActiveRunRegistry({ log });
+
+  async function invoke(invokeImpl, args) {
+    let unregister = () => {};
+    try {
+      return await invokeImpl({
+        ...args,
+        onProcess: (control) => {
+          unregister();
+          unregister = activeRuns.register({
+            sessionKey: args.session_key ?? "",
+            threadId: args.thread_id ?? "",
+            runId: args.run_id ?? "",
+            kill: (reason) => control.terminate(reason),
+          });
+          args.onProcess?.(control);
+        },
+      });
+    } finally {
+      unregister();
+    }
+  }
+
+  function handleRPC(method, params = {}) {
+    if (method !== "sessions.abort" && method !== "chat.abort") return null;
+    const result = activeRuns.abort({
+      key: params.key ?? params.sessionKey ?? "",
+      runId: params.runId ?? "",
+    });
+    if (result.aborted === 0 && !result.status) {
+      return { ok: true, ...result, status: "no-active-run" };
+    }
+    return { ok: true, ...result };
+  }
+
+  return {
+    invoke,
+    handleRPC,
+    shutdown: (reason) => activeRuns.abortAll(reason),
+    size: () => activeRuns.size(),
+  };
+}
+
+/** Shared long-poll bridge for headless NDJSON runtimes such as Cursor/OpenCode. */
+export async function runHeadlessCliBridge({ runtime, options, log, preflight, createInvoke }) {
+  const pre = preflight({ log });
+  if (!pre.ok) {
+    process.stderr.write(`${runtime} preflight failed: ${pre.error}\n`);
+    if (pre.hint) process.stderr.write(`${pre.hint}\n`);
+    process.exitCode = 65;
+    return;
+  }
+
+  let session;
+  try {
+    session = await resolveSession({ runtime, options, log });
+  } catch (err) {
+    process.stderr.write(`${err?.message || err}\n`);
+    process.exitCode = 65;
+    return;
+  }
+  if (!session.bridgeToken) {
+    process.stderr.write(`缺少 bridge_token，请重新运行 agentlink pair <code> -r ${runtime}\n`);
+    process.exitCode = 65;
+    return;
+  }
+
+  const fallbackWorkspace = path.resolve(options.cwd || await ensureDefaultWorkspace(runtime));
+  const sessLog = log.child({ gw: session.gwId });
+  const worker = createRelayWorker({
+    relayUrl: session.relayUrl,
+    gwId: session.gwId,
+    bridgeToken: session.bridgeToken,
+    runtime,
+    log: sessLog,
+  });
+  installAutoTunnel({ relayUrl: session.relayUrl, log: sessLog });
+
+  let lastRequestId = null;
+  let toolsLifecycle = null;
+  try {
+    toolsLifecycle = await bootstrapAgentlinkTools({
+      runtime,
+      gwId: session.gwId,
+      relayUrl: session.relayUrl,
+      bridgeToken: session.bridgeToken,
+      worker,
+      log: sessLog,
+      version: pre.version || "",
+      getLastRequestId: () => lastRequestId,
+    });
+  } catch (err) {
+    sessLog.warn("agentlink_tools.bootstrap.failed", "continuing without tools", {
+      err: err?.message || String(err),
+    });
+  }
+
+  const controller = createHeadlessRuntimeController({ log: sessLog });
+  const invoke = createInvoke({ fallbackWorkspace, log: sessLog, preflightResult: pre });
+  const dispatch = createUnifiedDispatchHandler({
+    relayUrl: session.relayUrl,
+    bridgeToken: session.bridgeToken,
+    gatewayId: session.gwId,
+    log: sessLog,
+    openclawInvoke: (args) => controller.invoke(invoke, args),
+  });
+  async function handleRequest(request, ctx) {
+    lastRequestId = ctx.requestId;
+    if (request?.request?.__relayKind === "rpc") {
+      if (request.request.method === "workspaces.scan") {
+        const result = await scanWorkspacesByRuntime({
+          runtimeKind: runtime,
+          gatewayId: session.gwId,
+          params: request.request.params ?? {},
+        });
+        await ctx.publishEvent({ event: "response", statusCode: 200, contentType: "application/json; charset=utf-8", body: JSON.stringify(result) });
+        await ctx.publishEvent({ event: "end" });
+        return;
+      }
+      const result = controller.handleRPC(request.request.method, request.request.params ?? {});
+      if (result) {
+        await ctx.publishEvent({
+          event: "response",
+          statusCode: 200,
+          contentType: "application/json; charset=utf-8",
+          body: JSON.stringify(result),
+        });
+        await ctx.publishEvent({ event: "end" });
+        return;
+      }
+    }
+    const consumed = await dispatch(request, ctx);
+    if (!consumed) {
+      throw new Error(`${runtime} 暂不支持该请求类型`);
+    }
+  }
+
+  let shuttingDown = false;
+  async function shutdown(reason) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    controller.shutdown(reason);
+    worker.stop(reason);
+    try { await toolsLifecycle?.stop?.(); } catch {}
+  }
+  process.once("SIGINT", () => { void shutdown("SIGINT"); });
+  process.once("SIGTERM", () => { void shutdown("SIGTERM"); });
+
+  sessLog.info("bridge.loop.entered", `${runtime} worker entering long-poll loop`, {
+    cwd: fallbackWorkspace,
+    version: pre.version || "",
+  });
+  await runWorkerWithRevokeHandling({ worker, handler: handleRequest, runtime, log: sessLog });
+}

package/src-ext/runtime/_shared/jsonMcpConfigAdapter.mjs

@@ -0,0 +1,70 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const SERVER_NAME = "agentlink";
+
+export function createJsonMcpConfigAdapter({ resolvePath, readServers, writeServers, desiredEntry }) {
+  async function read() {
+    return await fs.readFile(resolvePath(), "utf8");
+  }
+
+  async function register({ args, log } = {}) {
+    const configPath = resolvePath();
+    const config = await readConfig(configPath);
+    const servers = readServers(config);
+    const desired = desiredEntry(args || []);
+    if (JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(desired)) {
+      return { changed: false, configPath, mode: "noop_idempotent" };
+    }
+    servers[SERVER_NAME] = desired;
+    writeServers(config, servers);
+    await writeConfig(configPath, config);
+    log?.info?.("mcp.fanout.json.write", "wrote agentlink MCP entry", { configPath });
+    return { changed: true, configPath };
+  }
+
+  async function deregister() {
+    const configPath = resolvePath();
+    let config;
+    try {
+      config = await readConfig(configPath, { requireExisting: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") return { changed: false, configPath, mode: "noop_no_config" };
+      throw error;
+    }
+    const servers = readServers(config);
+    if (!(SERVER_NAME in servers)) return { changed: false, configPath, mode: "noop_not_registered" };
+    delete servers[SERVER_NAME];
+    writeServers(config, servers);
+    await writeConfig(configPath, config);
+    return { changed: true, configPath };
+  }
+
+  async function status() {
+    const configPath = resolvePath();
+    try {
+      const config = await readConfig(configPath, { requireExisting: true });
+      return { installed: true, registered: SERVER_NAME in readServers(config), configPath };
+    } catch (error) {
+      if (error?.code === "ENOENT") return { installed: true, registered: false, configPath };
+      return { installed: true, registered: false, configPath, error: error?.message };
+    }
+  }
+
+  return { read, register, deregister, status };
+}
+
+async function readConfig(configPath, { requireExisting = false } = {}) {
+  try {
+    const raw = await fs.readFile(configPath, "utf8");
+    return raw.trim() ? JSON.parse(raw) : {};
+  } catch (error) {
+    if (error?.code === "ENOENT" && !requireExisting) return {};
+    throw error;
+  }
+}
+
+async function writeConfig(configPath, config) {
+  await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}

package/src-ext/runtime/_shared/ndjsonProcess.mjs

@@ -0,0 +1,141 @@
+import { spawn, spawnSync } from "node:child_process";
+import readline from "node:readline";
+
+const VERSION_PROBE_TIMEOUT_MS = 5_000;
+const MAX_STDERR_CHARS = 8_000;
+export const PROCESS_TERMINATION_GRACE_MS = 3_000;
+// 子进程连续无任何 stdout/stderr 输出超过该上限视为卡死：kill 进程树并抛错，
+// 由 dispatch 层上报 run.failed —— 否则 run 永久 running，客户端只能无限转圈。
+export const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60_000;
+
+function signalProcessTree(child, signal) {
+  if (!child?.pid) return;
+  if (process.platform === "win32") {
+    const args = ["/pid", String(child.pid), "/t"];
+    if (signal === "SIGKILL") args.push("/f");
+    spawnSync("taskkill", args, { windowsHide: true, stdio: "ignore" });
+    return;
+  }
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try { child.kill(signal); } catch {}
+  }
+}
+
+export function probeBinary(binary) {
+  const result = spawnSync(binary, ["--version"], {
+    encoding: "utf8",
+    timeout: VERSION_PROBE_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    return {
+      ok: false,
+      error: result.error?.code === "ENOENT" ? `找不到 ${binary}` : String(result.stderr || result.error || "version probe failed").trim(),
+      hint: `请先安装 ${binary}，并确认它在 PATH 中。`,
+    };
+  }
+  return { ok: true, version: String(result.stdout || result.stderr || "").trim().split(/\r?\n/)[0] };
+}
+
+export async function runNdjsonProcess({
+  binary,
+  args,
+  cwd,
+  env,
+  parseEvent,
+  onChunk,
+  onSession,
+  onProcess,
+  terminationGraceMs = PROCESS_TERMINATION_GRACE_MS,
+  idleTimeoutMs = DEFAULT_IDLE_TIMEOUT_MS,
+}) {
+  const childEnv = env ? { ...process.env, ...env } : process.env;
+  const child = spawn(binary, args, {
+    cwd,
+    env: childEnv,
+    shell: false,
+    windowsHide: true,
+    detached: process.platform !== "win32",
+    // stdin 必须是 EOF：留 pipe 不关闭会让子进程（如 opencode run）等 stdin
+    // 读到 EOF 才开始干活 → 永久卡死（手动跑是 TTY 不受影响，headless 必挂）。
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let exited = false;
+  let aborted = false;
+  let timedOut = false;
+  let forceTimer = null;
+  const killTree = () => {
+    signalProcessTree(child, "SIGTERM");
+    forceTimer = setTimeout(() => {
+      if (!exited) signalProcessTree(child, "SIGKILL");
+    }, terminationGraceMs);
+    forceTimer.unref?.();
+  };
+  const terminate = () => {
+    if (exited || aborted) return;
+    aborted = true;
+    killTree();
+  };
+  // 空闲看门狗：任何 stdout/stderr 输出都会重置；超时视为子进程卡死。
+  let idleTimer = null;
+  const armIdleTimer = () => {
+    if (!idleTimeoutMs) return;
+    if (idleTimer) clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      if (exited || aborted || timedOut) return;
+      timedOut = true;
+      killTree();
+    }, idleTimeoutMs);
+    idleTimer.unref?.();
+  };
+  armIdleTimer();
+  onProcess?.({ pid: child.pid, terminate });
+  const exitPromise = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("close", (code, signal) => {
+      exited = true;
+      if (forceTimer) clearTimeout(forceTimer);
+      if (idleTimer) clearTimeout(idleTimer);
+      resolve({ code, signal });
+    });
+  });
+  let stderr = "";
+  let structuredError = "";
+  let reportedFailure = false;
+  child.stdout.on("data", armIdleTimer);
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    armIdleTimer();
+    stderr = (stderr + chunk).slice(-MAX_STDERR_CHARS);
+  });
+
+  const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let event;
+    try { event = JSON.parse(line); }
+    catch { continue; }
+    const eventError = event?.error?.message || event?.message?.error?.message;
+    if (eventError) structuredError = String(eventError);
+    const sessionId = event.sessionID || event.session_id;
+    if (sessionId) onSession?.(String(sessionId));
+    const chunks = parseEvent(event);
+    for (const chunk of Array.isArray(chunks) ? chunks : (chunks ? [chunks] : [])) {
+      if (chunk?.event === "response.failed") reportedFailure = true;
+      await onChunk(chunk);
+    }
+  }
+
+  const exit = await exitPromise;
+  if (aborted) return { aborted: true, exit };
+  if (timedOut) {
+    throw new Error(`${binary} 连续 ${Math.round(idleTimeoutMs / 1000)}s 无输出，判定卡死，已超时终止`);
+  }
+  if (exit.code !== 0) {
+    if (reportedFailure) return;
+    throw new Error(structuredError || stderr.trim() || `${binary} exited with code ${exit.code ?? "unknown"}${exit.signal ? ` (${exit.signal})` : ""}`);
+  }
+  return { aborted: false, exit };
+}

package/src-ext/runtime/_shared/relayObjectToBlock.mjs

@@ -12,9 +12,9 @@
  *   { type: "image"|"attachment", source: { kind: "url", url, media_type, attachment_kind }, name?, mime?, size? }
  *
  * @param {object} opts
- * @param {string}   opts.runtimeHint          - "claude"|"openclaw"|"picoclaw"|"codex"|"hermes"
+ * @param {string}   opts.runtimeHint          - "claude"|"openclaw"|"codex"|"hermes"
  * @param {string[]|null} opts.modelCaps        - modalities 数组（如 ["text","image","pdf"]）。
- *                                               null 表示跳过 caps 检查（picoclaw）。
+ *                                               null 表示跳过 caps 检查。
  *                                               缺失时默认 ["text"]。
  * @param {Function} opts.fetchAndBase64Encode  - async (url, opts) => { base64, mediaType, bytes }
  * @param {Function} [opts.fetchAndDecodeText]  - async (url, opts) => string
@@ -26,7 +26,6 @@
  *   { type: "input_image",   source: { type: "base64", media_type, data } }
  *   { type: "input_file",    source: { type: "base64", media_type: "application/pdf", filename, data } }
  *   { type: "input_text",    text }
- *   { type: "url_ref",       url, media_type }   // picoclaw only
  *
  * ErrorResult:
  *   { error: { code: "caps_mismatch",    message, model?, missing_modality } }
@@ -70,8 +69,12 @@ function resolveAttachmentKind(block) {
 
 export async function relayObjectToBlock(block, opts = {}) {
   const {
-    runtimeHint,
-    modelCaps,       // null = skip caps check (picoclaw); undefined/missing = default ["text"]
+    // 曾经唯一消费 runtimeHint 的分支(url_ref 直通)是移除硬件方案时删掉的
+    // 专属逻辑;所有真实 runtime(openclaw/claude/hermes)现在走同一条
+    // fetch+base64 路径,不再需要按 runtime 分叉。保留在签名里是为了不动调用方
+    // (openclaw/claude/hermes 三处仍显式传它),留作未来按 runtime 差异化的挂钩点。
+    runtimeHint: _runtimeHint,
+    modelCaps,       // null = skip caps check; undefined/missing = default ["text"]
     fetchAndBase64Encode,
     fetchAndDecodeText,
   } = opts;
@@ -107,12 +110,7 @@ export async function relayObjectToBlock(block, opts = {}) {
       };
     }
 
-    // 2. picoclaw → url_ref（无 fetch）
-    if (runtimeHint === "picoclaw") {
-      return { type: "url_ref", url, media_type: mediaType };
-    }
-
-    // 3. fetch + base64
+    // 2. fetch + base64
     try {
       const { base64, mediaType: resolvedMime, bytes } = await fetchAndBase64Encode(url, {
         expectedMime: mediaType,

package/src-ext/runtime/_shared/resolveWorkspaceCwd.mjs

@@ -0,0 +1,47 @@
+/**
+ * resolveWorkspaceCwd.mjs — headless NDJSON runtime 的 spawn cwd 解析。
+ *
+ * 与 claude/codex handleRequest 的解析链对齐：
+ *   1. workspace_path 非空 → expandHome + existsSync → 用它（线程绑定工作区）
+ *   2. workspace_path 给定但无效/目录不存在 → 稳定失败，绝不 fallback
+ *   3. workspace_path 未给 → 默认工作区
+ */
+
+import { statSync } from "node:fs";
+import path from "node:path";
+
+import { expandHome } from "../../core/pathExpand.mjs";
+
+/**
+ * @param {{
+ *   workspacePath?: string | null,
+ *   fallbackWorkspace: string,
+ *   runtime: string,
+ *   log?: { info?: Function, warn?: Function },
+ * }} opts
+ * @returns {{ cwd: string, source: "workspace_path" | "default" }}
+ */
+export function resolveWorkspaceCwd({ workspacePath, fallbackWorkspace, runtime, log }) {
+  const requested = typeof workspacePath === "string" ? workspacePath.trim() : "";
+  if (requested) {
+    const resolved = expandHome(requested);
+    const requestedAbsolute = path.isAbsolute(requested) || requested === "~" || requested.startsWith("~/");
+    if (requestedAbsolute && path.isAbsolute(resolved)) {
+      let isDirectory = false;
+      try { isDirectory = statSync(resolved).isDirectory(); } catch {}
+      if (isDirectory) {
+        log?.info?.(`${runtime}.spawn.cwd.workspace`, "using workspace_path as cwd", { cwd: resolved });
+        return { cwd: resolved, source: "workspace_path" };
+      }
+    }
+    log?.warn?.(`${runtime}.spawn.cwd.unavailable`, "requested workspace context is unavailable", {
+      requested: true,
+    });
+    const error = new Error(`${runtime}: requested workspace context is unavailable`);
+    error.code = "workspace_context_unavailable";
+    throw error;
+  }
+  const fallback = path.resolve(fallbackWorkspace);
+  log?.info?.(`${runtime}.spawn.cwd.default`, "no workspace_path, using default workspace", { cwd: fallback });
+  return { cwd: fallback, source: "default" };
+}

package/src-ext/runtime/_shared/slashCommandRouter.mjs

@@ -115,6 +115,16 @@ export async function classifySlashCommand(input, runtime, bridgeCtx) {
     // 命中（用户自定义 ~/.claude/commands / skill 命令）→ 透传真跑；
     // 未命中 → __default__ 合成提示，避免英文 "Unknown command" 直出。
     const bare = command.slice(1);
+    // system/init 在部分 Claude/Node 组合下会复用 CLI 进程级缓存，刚创建的
+    // workspace command 即使 forceFresh 也可能暂时缺席。磁盘 marker 是这里的
+    // 权威兜底，且只检查由 SLASH_RE 限定过的安全文件名。
+    const workspaceCommand = ctx?.cwd
+      ? join(ctx.cwd, ".claude", "commands", `${bare}.md`)
+      : null;
+    const userCommand = join(homedir(), ".claude", "commands", `${bare}.md`);
+    if ((workspaceCommand && existsSync(workspaceCommand)) || existsSync(userCommand)) {
+      return { kind: "passthrough", command };
+    }
     const hitKnown = (init) => {
       const known = Array.isArray(init?.slash_commands) ? init.slash_commands : [];
       return known.some((c) => String(c).toLowerCase() === bare);

package/src-ext/runtime/_shared/todoTranslatorUtils.mjs

@@ -72,7 +72,7 @@ export function normalizeStatus(raw) {
  * rawItems 中每项支持字段：
  *   - id?:         string（有则保留，无则生成 td_{idx}）
  *   - content?:    string（主内容字段，Claude/Hermes 用）
- *   - step?:       string（Codex/picoclaw 用，作为 content 的 fallback）
+ *   - step?:       string（Codex 用，作为 content 的 fallback）
  *   - status?:     string（经 normalizeStatus 归一）
  *
  * @param {Array<{id?: string, content?: string, step?: string, status?: string}>} rawItems

package/src-ext/runtime/claude/handleRequest.mjs

@@ -24,8 +24,8 @@ import { probeClaudeSystemInit } from "../_shared/cliExec.mjs";
 import { normalizeClaudeLine, createLineStreamParser } from "./stdoutParser.mjs";
 import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
 import { scanWorkspacesByRuntime } from "../../core/scanWorkspaces.mjs";
-import { expandHome } from "../../core/pathExpand.mjs";
 import { ensureDefaultWorkspace, defaultWorkspacePath } from "../../core/defaultWorkspace.mjs";
+import { resolveWorkspaceCwd } from "../_shared/resolveWorkspaceCwd.mjs";
 import { createWorkspace as _defaultCreateWorkspace } from "../../core/createWorkspace.mjs";
 import { createClaudeTodoTranslator } from "./todoTranslator.mjs";
 import { createAskUserQuestionTranslator, aggregateAnswers, buildOptionMaps } from "./askUserQuestionTranslator.mjs";
@@ -257,38 +257,22 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
 
   // 默认 openclawInvoke：spawn claude --print 子进程，解析 stdout，翻译事件
   // Task 3.5: 加入 blocks 参数（来自 dispatch payload），透传给 writeUserMessage 以支持多模态
-  // workspace-aware cwd: 若 workspace_path 非空且目录存在，spawn 用它作 cwd；
-  // 否则 fallback 到 defaultWorkspace（不再用工厂 cwd，修 service 模式 "/" bug）。
-  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, session_key = null, onChunk: _rawOnChunk }) => {
-    // per-request cwd 解析（align-runtime-default-workspace）:
-    //   1. workspace_path 非空 → expandHome + existsSync → 用它
-    //   2. workspace_path 给定但不存在 → fallback 到 defaultWorkspace，emit cwd_fallback 可观测
-    //   3. workspace_path 未给 → 直接用 defaultWorkspace
-    //   注：factory cwd 不再作为兜底（保留作显式 --cwd 入口）
+  // workspace-aware cwd：显式 workspace_path 必须是可用绝对目录；缺失时才使用
+  // defaultWorkspace（不再用工厂 cwd，修 service 模式 "/" bug）。
+  const defaultOpenclawInvoke = async ({ thread_id, run_id, input, blocks = [], workspace_path: reqWorkspacePath, resume_session_id: resumeSessionIDFromRelay = null, session_key = null, onChunk: _rawOnChunk }) => {
+    // v2 workspace_path 是强约束：不可用时稳定失败，不得退回默认目录。
+    // route shell 未带 workspace_path 时继续使用原默认工作区。
     let spawnCwd;
-    let cwdFallback = null;
 
     const { existsSync } = await import("node:fs");
 
     if (reqWorkspacePath && typeof reqWorkspacePath === "string" && reqWorkspacePath.trim()) {
-      const resolved = expandHome(reqWorkspacePath.trim());
-      if (existsSync(resolved)) {
-        spawnCwd = resolved;
-        log.info?.("claude.spawn.cwd.workspace", "using workspace_path as cwd", {
-          cwd: resolved, source: "workspace_path",
-        });
-      } else {
-        // workspace_path 给定但不存在 → fallback 到默认工作区，fallback 可观测
-        spawnCwd = await ensureDefaultWorkspace("claude");
-        cwdFallback = {
-          actual_cwd: spawnCwd,
-          requested_cwd: reqWorkspacePath,
-          reason: `workspace_path '${reqWorkspacePath}' does not exist after expand, falling back to default workspace`,
-        };
-        log.warn?.("claude.spawn.cwd.not_found", "workspace_path does not exist, falling back to default workspace", {
-          workspace_path: reqWorkspacePath, fallback_cwd: spawnCwd,
-        });
-      }
+      ({ cwd: spawnCwd } = resolveWorkspaceCwd({
+        workspacePath: reqWorkspacePath,
+        fallbackWorkspace: cwd,
+        runtime: "claude",
+        log,
+      }));
     } else {
       // 未给 workspace_path → 用默认工作区（lazy ensure，兜底 service 模式 "/" bug）
       spawnCwd = await ensureDefaultWorkspace("claude");
@@ -320,14 +304,6 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
         }
       : _rawOnChunk;
 
-    // fallback 可观测：workspace_path 给定但不存在时，emit run.started 含 cwd_fallback
-    if (cwdFallback) {
-      await onChunk({
-        event: "__envelopes",
-        envelopes: [buildRunStarted(run_id, { options: { cwd_fallback: cwdFallback } })],
-      });
-    }
-
     // approval 模式资源（在 try 块外声明，以便 finally 块访问）
     let _approvalPermServer = null;
     let _approvalMcpConfigPath = null;
@@ -977,6 +953,7 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
                     });
                     resumeHandle.child.once("error", () => resolve(-1));
                   });
+                  await resumeParser.drain();
 
                   // 新 session_id 写入 threadSessionMap
                   if (resumeCode === 0 && resumeSawNonSynthetic && resumePendingSessionId && thread_id) {
@@ -1036,6 +1013,7 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
         });
         handle.child.once("error", () => resolve(-1));
       });
+      await parser.drain();
       childExited = true;
       unregister();
 
@@ -1048,7 +1026,7 @@ export function createClaudeHandleRequest({ cwd, log, usage, bridgeCtx, dispatch
     }
 
     // 第一次尝试：用现有 session_id（如果有）
-    let resumeSessionId = thread_id ? threadSessionMap.get(thread_id) : null;
+    let resumeSessionId = thread_id ? threadSessionMap.get(thread_id) || resumeSessionIDFromRelay : resumeSessionIDFromRelay;
     let result = await attemptOnce({ resumeSessionId, isRetry: false });
 
     // 兜底 1：spawn 失败直接报。

package/src-ext/runtime/claude/launcher.mjs

@@ -285,12 +285,6 @@ export async function writeUserMessage(child, text, blocks = [], { _fetchAndBase
       case "input_text":
         content.push({ type: "text", text: result.text });
         break;
-      case "url_ref":
-        // picoclaw only — claude runtime never returns url_ref from relayObjectToBlock;
-        // if this branch is somehow hit, drop to a safe description with NO URL in LLM context
-        // (铁律 #1: signed URL must not appear in LLM input). (CR-003)
-        content.push({ type: "text", text: `[image] (preview unavailable for this runtime)` });
-        break;
       default:
         break;
     }

package/src-ext/runtime/claude/stdoutParser.mjs

@@ -258,6 +258,10 @@ export function normalizeClaudeLine(line) {
 export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit = 1 << 20 }) {
   const decoder = new TextDecoder("utf-8");
   let buf = "";
+  // stdout 的 data 回调是同步的，但 onObject 会异步发布 relay envelope。
+  // 必须串行排队并允许调用方在 child exit 后 drain，否则 run.completed 可能
+  // 越过仍在途的 delta，relay 按状态机拒绝后 App 就永久停在 streaming。
+  let pending = Promise.resolve();
   const pLog = log ? log.child({ comp: "stdout" }) : null;
 
   function feedLine(line) {
@@ -281,13 +285,12 @@ export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit =
     pLog?.debug("stdout.line.parsed", "line parsed", {
       type: obj.type || "", has_message: !!obj.message,
     });
-    try { onObject(obj); }
-    catch (err) {
+    pending = pending.then(() => onObject(obj)).catch((err) => {
       pLog?.error("error.caught", "onObject threw", {
         where: "stdoutParser.onObject",
         err: err?.message || String(err),
       });
-    }
+    });
   }
 
   return {
@@ -316,6 +319,8 @@ export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit =
         buf = "";
       }
     },
+    /** 等待已解析行的异步 onObject 全部按输入顺序处理完。 */
+    drain() { return pending; },
   };
 }