@jennie-shawn/starwork 0.1.0-alpha.18 → 0.1.0-alpha.19

package/README.md

@@ -9,7 +9,7 @@ StarWork 是一套面向 AI 的工作台协议和工具集，用来帮助用户
 - **Packs**：场景模板包。当前 A 测阶段默认使用通用工作能力。
 - **Skills**：给 Codex 等 AI 工具使用的工作流说明，让 AI 能更可靠地帮用户设计和生成 StarWork 工作台。
 
-当前版本处于 A 测阶段。npm `latest` 为 `@jennie-shawn/starwork@0.1.0-alpha.17`，适合测试安装流程、基础命令、工作台结构、AI Skill 使用体验和 Codex 多会话协作链路。
+当前版本处于 A 测阶段。npm `latest` 为 `@jennie-shawn/starwork@0.1.0-alpha.18`，适合测试安装流程、基础命令、工作台结构、AI Skill 使用体验和 MultiAgent 会话协作链路。
 
 ## 安装 CLI
 
@@ -173,7 +173,7 @@ product/planning/features/<feature>/
 - `upgrade`：按 `starworkDoctor` skill 生成的升级蓝图，把历史模板或类似项目中心的旧工作区安全接入 StarWork 工作台。
 - `adapt`：生成 Claude Code、Cursor 等 AI 工具的适配文件。
 - `pack install`：向兼容工作台安装支持的场景能力。
-- `multiagent`：为同一项目建立自定义 AI 职责位、绑定会话、登记跨 lane 共享输出，并支持 Codex 多会话读取、launch 和格式化指令发送；未观察到目标 turn 完成时会返回 `started_unverified`，避免把未完成交付误说成已完成。
+- `multiagent`：为同一项目建立自定义 AI 职责位、绑定会话、登记跨 lane 共享输出，并支持会话观察、launch 和格式化跨会话指令；`instruct` 由 CLI 运行时判断宿主能力，不能标准投递时返回 `manual_handoff_required`。
 
 ## 仓库结构
 

package/cli/src/cli.js

@@ -731,6 +731,8 @@ function parseArgs(argv) {
       options.turns = readValue(argv, ++i, arg);
     } else if (arg === "--timeout") {
       options.timeout = readValue(argv, ++i, arg);
+    } else if (arg === "--wait" || arg === "--wait-completion") {
+      options.waitCompletion = true;
     } else if (arg === "--title") {
       options.title = readValue(argv, ++i, arg);
     } else if (arg === "--path") {
@@ -1232,7 +1234,8 @@ async function lanesInstruct(argv) {
   });
   const targetSession = lanesState.lanes?.[toLane]?.current_session || targetLane.current_session;
   const parsedSession = parseAdapterSession(targetSession);
-  const canAutoSend = !options.manualHandoff && parsedSession.host === "codex" && parsedSession.id;
+  const route = resolveHostRuntimeCapability({ workspaceRoot, parsedSession, command: "instruct" });
+  const canAutoSend = !options.manualHandoff && route.action === "auto_send";
   const dryRunRequest = buildSharedRequestRow({
     id: requestId,
     from: fromLane,
@@ -1249,24 +1252,35 @@ async function lanesInstruct(argv) {
     agreements: shared.agreements
   });
   if (options.json && options.dryRun) {
-    console.log(JSON.stringify({ schema: "starwork.agent_lanes.instruct.v0.2", dry_run: true, request: dryRunRequest, formatted_message: message }, null, 2));
+    console.log(JSON.stringify({ schema: "starwork.agent_lanes.instruct.v0.4", dry_run: true, request: dryRunRequest, host: renderHostRoute(route), formatted_message: message }, null, 2));
     return;
   }
   if (!options.json) {
     printGenericPlan(options.dryRun ? "跨会话指令预览（dry run）：" : "跨会话指令计划：", dryPlan.actions);
-    if (canAutoSend) console.log(`将发送到 Codex thread：${parsedSession.id}`);
-    else console.log(`目标 lane 绑定的是 ${parsedSession.host}，当前不能后台自动发送；将生成人工交付消息并记录为 ${MANUAL_HANDOFF_STATUS}。`);
+    if (canAutoSend) console.log(`将通过宿主标准能力发送到 ${parsedSession.host}:${parsedSession.id}`);
+    else console.log(`目标 lane 路由结果：${route.status}；将按 CLI 返回状态记录。`);
     console.log("");
   }
   if (options.dryRun) return;
   await confirmOrThrow(options, `是否向 Lane ${toLane} 发送指令？`);
-  const delivery = canAutoSend
-    ? await sendCodexInstruction({ threadId: parsedSession.id, message, timeout: parsePositiveInt(options.timeout, 300000) })
-    : createManualHandoffDelivery({
-        parsedSession,
+  let delivery;
+  if (options.manualHandoff) {
+    delivery = createManualHandoffDelivery({
+      parsedSession,
+      message,
+      reason: "Manual handoff requested"
+    });
+  } else if (canAutoSend) {
+    delivery = await sendCodexInstruction({
+        threadId: parsedSession.id,
         message,
-        reason: "Target host does not support StarWork background message delivery in v0.1"
+        timeout: parsePositiveInt(options.timeout, 300000),
+        waitCompletion: Boolean(options.waitCompletion)
       });
+    delivery.mode = "host_standard_api";
+  } else {
+    delivery = createDeliveryFromRoute({ route, parsedSession, message, workspaceRoot });
+  }
   const finalRequest = buildSharedRequestRow({
     id: requestId,
     from: fromLane,
@@ -1299,7 +1313,7 @@ async function lanesInstruct(argv) {
     ]
   });
   if (options.json) {
-    console.log(JSON.stringify({ schema: "starwork.agent_lanes.instruct.v0.2", request: finalRequest, host_delivery: delivery }, null, 2));
+    console.log(JSON.stringify({ schema: "starwork.agent_lanes.instruct.v0.4", request: finalRequest, host: renderHostRoute(route), host_delivery: delivery }, null, 2));
     return;
   }
   console.log("");
@@ -1364,33 +1378,53 @@ async function lanesLaunch(argv) {
   const launchResults = [];
   if (options.dryRun) {
     for (const lane of lanes) {
-      launchResults.push({ lane: lane.lane, dry_run: true, message: renderMultiagentLaunchMessage({ lane, fromLane: options.from || "user", workspaceRoot, collaboration }) });
+      const sessionName = buildLaneLaunchSessionName({ lane, workspaceRoot, explicitName: options.sessionName });
+      launchResults.push({
+        lane: lane.lane,
+        dry_run: true,
+        session_name: sessionName,
+        launch_status: "dry_run",
+        rename_status: sessionName ? "dry_run" : "not_requested",
+        binding_status: "dry_run",
+        message: renderMultiagentLaunchMessage({ lane, fromLane: options.from || "user", workspaceRoot, collaboration })
+      });
     }
     if (options.json) {
-      console.log(JSON.stringify({ schema: "starwork.agent_lanes.launch.v0.2", dry_run: true, launches: launchResults }, null, 2));
+      console.log(JSON.stringify({ schema: "starwork.agent_lanes.launch.v0.3", dry_run: true, launches: launchResults }, null, 2));
       return;
     }
     console.log("");
     console.log("Codex lane launch 预览（dry run）：");
-    lanes.forEach((lane) => console.log(`- ${lane.lane}`));
+    launchResults.forEach((result) => console.log(`- ${result.lane}${result.session_name ? ` -> ${result.session_name}` : ""}`));
     return;
   }
   await confirmOrThrow(options, `是否 launch ${lanes.length} 个 Codex lane thread？`);
   let nextRegistryLanes = registry.lanes;
   let lanesState = readAgentLanesState(workspaceRoot);
   for (const lane of lanes) {
+    const sessionName = buildLaneLaunchSessionName({ lane, workspaceRoot, explicitName: options.sessionName });
     const launchMessage = renderMultiagentLaunchMessage({ lane, fromLane: options.from || "user", workspaceRoot, collaboration });
     const launch = await launchCodexLane({ message: launchMessage, workspaceRoot, timeout: parsePositiveInt(options.timeout, 90000) });
-    const session = launch.thread_id ? `codex:${launch.thread_id}` : "unbound";
+    const launchedThreadId = launch.thread_id || launch.created_thread_id || "";
+    const session = launchedThreadId ? `codex:${launchedThreadId}` : "unbound";
+    const sessionNameSync = launchedThreadId
+      ? await renameHostSessionBestEffort({ session, sessionName })
+      : createSessionNameSyncResult({
+        requested: Boolean(sessionName),
+        supported: false,
+        status: sessionName ? "skipped" : "not_requested",
+        name: sessionName,
+        warning: sessionName ? "No host thread was created to rename." : null
+      });
+    const bindingStatus = launch.thread_id && launch.status === "completed" ? "bound" : "unbound";
     if (launch.thread_id && launch.status === "completed") {
-      const sessionNameSync = await renameHostSessionBestEffort({ session, sessionName: normalizeMarkdownCell(options.sessionName || "") });
       const pinSync = pinHostThreadBestEffort({ session, requested: Boolean(options.pin) });
       nextRegistryLanes = nextRegistryLanes.map((item) => item.lane === lane.lane ? { ...item, current_session: session } : item);
       lanesState = updateAgentLaneHostState(lanesState, lane.lane, {
         host: "codex",
         current_session: session,
         thread_id: launch.thread_id,
-        session_name: normalizeMarkdownCell(options.sessionName || ""),
+        session_name: sessionName,
         pinned: pinSync.status === "ok",
         pin_status: pinSync.status,
         created_by: "starwork multiagent launch",
@@ -1403,17 +1437,32 @@ async function lanesLaunch(argv) {
       launch.session_name_sync = sessionNameSync;
       launch.pin_sync = pinSync;
     }
-    launchResults.push({ lane: lane.lane, ...launch });
+    launchResults.push({
+      lane: lane.lane,
+      ...launch,
+      session,
+      session_id: launchedThreadId || undefined,
+      session_name: sessionName,
+      launch_status: launch.status,
+      rename_status: sessionNameSync.status,
+      rename_warning: sessionNameSync.warning || undefined,
+      binding_status: bindingStatus,
+      session_name_sync: sessionNameSync
+    });
   }
   actions.push(...buildLanesRegistryPlan(workspaceRoot, nextRegistryLanes).actions);
   actions.push(stateFileAction(workspaceRoot, lanesState));
   applyPlan({ targetDir: workspaceRoot, actions: dedupeActions(actions) });
   if (options.json) {
-    console.log(JSON.stringify({ schema: "starwork.agent_lanes.launch.v0.2", launches: launchResults }, null, 2));
+    console.log(JSON.stringify({ schema: "starwork.agent_lanes.launch.v0.3", launches: launchResults }, null, 2));
     return;
   }
   console.log("");
-  launchResults.forEach((result) => console.log(`Lane ${result.lane}: ${result.status}${result.thread_id ? ` (${result.thread_id})` : ""}${result.warning ? ` - ${result.warning}` : ""}`));
+  launchResults.forEach((result) => {
+    console.log(`Lane ${result.lane}: ${result.status}${result.thread_id ? ` (${result.thread_id})` : ""}${result.session_name ? ` -> ${result.session_name}` : ""}${result.warning ? ` - ${result.warning}` : ""}`);
+    if (result.rename_warning) console.log(`  Warning: host session rename skipped: ${result.rename_warning}`);
+    if (result.binding_status !== "bound") console.log("  Warning: lane was not bound because launch did not complete.");
+  });
 }
 
 async function lanesShare(argv) {
@@ -1582,7 +1631,7 @@ function collectDoctorResult(targetDir, options = {}) {
       if (trace) {
         addCheck(result, "workspace.state.exists", "fail", "疑似 StarWork 工作台，但缺少 .starwork/workspace.json。", trace);
       } else {
-        addCheck(result, "workspace.state.exists", "fail", "当前目录不是 StarWork 工作台。请先运行 starwork init。");
+        addCheck(result, "workspace.state.exists", "fail", "当前目录不是 StarWork 工作台。请让 Agent 使用 starworkInit Skill 完成接入；CLI 只作为确认方案后的执行工具。");
       }
     }
     return result;
@@ -1656,7 +1705,7 @@ function requireWorkspaceRoot(targetDir) {
   }
   const workspaceRoot = findWorkspaceRoot(targetDir);
   if (!workspaceRoot) {
-    throw new Error("当前目录不是 StarWork 工作台。请先运行 starwork init。");
+    throw new Error("当前目录不是 StarWork 工作台。请让 Agent 使用 starworkInit Skill 完成接入；CLI 只作为确认方案后的执行工具。");
   }
   return workspaceRoot;
 }
@@ -7043,6 +7092,13 @@ function parseLaneList(value) {
     .map((item) => normalizeLaneId(item, "lanes"));
 }
 
+function buildLaneLaunchSessionName({ lane, workspaceRoot, explicitName }) {
+  const requestedName = normalizeMarkdownCell(explicitName || "");
+  if (requestedName) return requestedName;
+  const roleName = normalizeMarkdownCell(lane?.purpose || lane?.lane || "");
+  return normalizeMarkdownCell(`${roleName || "Agent"} Agent`);
+}
+
 function normalizeLaneId(value, label) {
   if (typeof value !== "string" || !value.trim()) {
     throw new Error(`${label} 必须是非空 lane ID。`);
@@ -7289,6 +7345,7 @@ function createManualHandoffDelivery({ parsedSession, message, reason }) {
   return {
     adapter: parsedSession.host,
     status: MANUAL_HANDOFF_STATUS,
+    mode: "manual_handoff",
     session: parsedSession.session,
     session_id: parsedSession.id,
     formatted_message: message,
@@ -7296,6 +7353,127 @@ function createManualHandoffDelivery({ parsedSession, message, reason }) {
   };
 }
 
+function resolveHostRuntimeCapability({ workspaceRoot, parsedSession, command }) {
+  if (!parsedSession?.id || parsedSession.host === "none") {
+    return {
+      host: parsedSession?.host || "none",
+      session: parsedSession?.session || "unbound",
+      command,
+      status: "unbound",
+      action: "none",
+      warning: "Target lane is not bound to a host session."
+    };
+  }
+  let profile = null;
+  try {
+    profile = loadAdapterProfile(parsedSession.host);
+  } catch (error) {
+    return {
+      host: parsedSession.host,
+      session: parsedSession.session,
+      command,
+      status: "unsupported",
+      action: "none",
+      warning: error.message
+    };
+  }
+  const adaptersState = readAdaptersState(workspaceRoot);
+  const adapterRecord = adaptersState.adapters?.[profile.host] || null;
+  const adapterEnabled = Boolean(adapterRecord?.enabled);
+  if (profile.host !== "codex" && !adapterEnabled) {
+    return {
+      host: profile.host,
+      session: parsedSession.session,
+      command,
+      profile_level: profile.sessions?.send_message || "unknown",
+      adapter_enabled: false,
+      status: "needs_adapt",
+      action: "none",
+      warning: `Target host is not adapted. Run starwork adapt ${profile.host} --target <path> --dry-run before automatic routing.`
+    };
+  }
+  const profileLevel = profile.sessions?.send_message || "unknown";
+  if (profileLevel === "unsupported") {
+    return {
+      host: profile.host,
+      session: parsedSession.session,
+      command,
+      profile_level: profileLevel,
+      adapter_enabled: adapterEnabled,
+      status: "unsupported",
+      action: "none",
+      warning: `${profile.label} does not support background message delivery.`
+    };
+  }
+  const runtime = probeHostStandardSendCapability(profile.host);
+  if (runtime.available) {
+    return {
+      host: profile.host,
+      session: parsedSession.session,
+      command,
+      profile_level: profileLevel,
+      adapter_enabled: adapterEnabled,
+      runtime_available: true,
+      status: "delivered",
+      action: "auto_send",
+      mode: runtime.mode
+    };
+  }
+  return {
+    host: profile.host,
+    session: parsedSession.session,
+    command,
+    profile_level: profileLevel,
+    adapter_enabled: adapterEnabled,
+    runtime_available: false,
+    status: MANUAL_HANDOFF_STATUS,
+    action: "manual_handoff",
+    warning: runtime.warning || `${profile.label} standard background delivery capability is not available in this CLI runtime.`
+  };
+}
+
+function probeHostStandardSendCapability(host) {
+  return {
+    host,
+    available: false,
+    mode: null,
+    warning: `${host} standard background delivery capability is not available in this CLI runtime; low-level turn APIs are not used for multiagent instruct.`
+  };
+}
+
+function renderHostRoute(route) {
+  return {
+    id: route.host,
+    session: route.session,
+    command: route.command,
+    profile_level: route.profile_level,
+    adapter_enabled: route.adapter_enabled,
+    runtime_available: route.runtime_available,
+    action: route.action,
+    status: route.status,
+    warning: route.warning || null
+  };
+}
+
+function createDeliveryFromRoute({ route, parsedSession, message, workspaceRoot }) {
+  if (route.status === MANUAL_HANDOFF_STATUS) {
+    return createManualHandoffDelivery({
+      parsedSession,
+      message,
+      reason: route.warning || "Target host requires manual handoff."
+    });
+  }
+  return {
+    adapter: route.host || parsedSession.host,
+    status: route.status,
+    mode: route.action || "none",
+    session: parsedSession.session,
+    session_id: parsedSession.id,
+    message_path: path.relative(workspaceRoot, path.join(workspaceRoot, "_系统", "协作", "shared.md")) || "_系统/协作/shared.md",
+    warning: route.warning || null
+  };
+}
+
 function buildHostContinueResult(parsedSession) {
   if (parsedSession.host === "claude-code" && parsedSession.id) {
     return {
@@ -7555,7 +7733,12 @@ async function resumeCodexThread(threadId) {
 }
 
 async function startCodexTurn(threadId, formattedMessage, options = {}) {
-  return sendCodexInstruction({ threadId, message: formattedMessage, timeout: options.timeout || 300000 });
+  return sendCodexInstruction({
+    threadId,
+    message: formattedMessage,
+    timeout: options.timeout || 300000,
+    waitCompletion: Boolean(options.waitCompletion)
+  });
 }
 
 async function listCodexThreads(options = {}) {
@@ -7569,7 +7752,7 @@ async function listCodexThreads(options = {}) {
   return { ok: true, threads: response.result?.data || response.result?.threads || response.result || [] };
 }
 
-async function sendCodexInstruction({ threadId, message, timeout }) {
+async function sendCodexInstruction({ threadId, message, timeout, waitCompletion = false }) {
   const messages = [
     codexInitializeMessage(1),
     {
@@ -7592,23 +7775,26 @@ async function sendCodexInstruction({ threadId, message, timeout }) {
         threadId,
         input: [codexTextInput(message)]
       }
-    },
-    {
+    }
+  ];
+  if (waitCompletion) {
+    messages.push({
       jsonrpc: "2.0",
       id: 5,
       method: "thread/read",
       optional: true,
       params: { threadId, includeTurns: true }
-    }
-  ];
-  const result = await runCodexAppServer(messages, {
+    });
+  }
+  const runOptions = waitCompletion ? {
     timeout,
     waitAfter: {
       id: 4,
       method: "turn/completed",
       timeout: Math.max(1000, parsePositiveInt(timeout, 300000))
     }
-  });
+  } : { timeout };
+  const result = await runCodexAppServer(messages, runOptions);
   if (!result.ok) {
     return { adapter: "codex", status: "failed", thread_id: threadId, warning: result.warning };
   }
@@ -7620,8 +7806,21 @@ async function sendCodexInstruction({ threadId, message, timeout }) {
   if (!start || start.error) {
     return { adapter: "codex", status: "failed", thread_id: threadId, warning: start?.error?.message || "Codex turn/start failed" };
   }
-  const completed = result.events.find((item) => item.method === "turn/completed");
   const started = result.events.find((item) => item.method === "turn/started");
+  if (!waitCompletion) {
+    return {
+      adapter: "codex",
+      status: "delivered",
+      thread_id: threadId,
+      turn_id: started?.params?.turnId || started?.params?.turn?.id || start.result?.turnId || null,
+      completion_status: "not_waited",
+      completed_at: null,
+      verified_by_thread_read: false,
+      warning: "Delivery only; target task completion must be verified by multiagent read, worklog, or a return instruction.",
+      ui_visibility: "not_guaranteed"
+    };
+  }
+  const completed = result.events.find((item) => item.method === "turn/completed");
   const finalRead = result.responses.find((item) => item.id === 5);
   return {
     adapter: "codex",
@@ -8764,7 +8963,7 @@ Subcommands:
   instruct   向另一个 lane 发送格式化跨会话指令。
   handoff    生成并记录人工交付消息，不后台发送。
   continue   输出继续某个 lane 宿主会话的人工命令或步骤。
-  launch     为已有 lane 创建并绑定 Codex thread。
+  launch     为已有 lane 创建并绑定独立宿主会话。
   share      登记一个跨 lane 可读输出。
 
 示例：
@@ -8826,8 +9025,8 @@ Options:
 
 说明：
   --session-name 会在绑定成功后 best-effort 同步宿主工具的会话名称。
-  --pin 会尝试置顶 Codex thread；当前无稳定接口时只输出 warning，不回滚绑定。
-  Codex 支持自动观察和派发；Claude Code 支持 CLAUDE_CODE_SESSION_ID 自动识别和 resume 命令；Cursor / Trae v0.1 走人工交付。
+  --pin 会请求宿主置顶；不支持时只输出 warning，不回滚绑定。
+  instruct 的自动投递由 CLI 运行时判断；没有标准后台投递能力时返回 manual_handoff_required。
 `);
 }
 
@@ -8884,7 +9083,8 @@ Options:
   --target <path>
   --from <lane-id>
   --message <text>
-  --timeout <ms>  默认最多等待 300000ms，未完成时返回 started_unverified
+  --timeout <ms>
+  --wait, --wait-completion  显式等待目标 turn completed；默认只确认投递
   --json
   --dry-run
   --yes, -y
@@ -8935,7 +9135,7 @@ Usage:
 Options:
   --target <path>
   --lanes <lane1,lane2>
-  --session-name <name>
+  --session-name <name>  覆盖默认 "<职责名> Agent" 会话名
   --pin
   --timeout <ms>
   --json

package/cli/test/init.test.js

@@ -56,7 +56,7 @@ function listFiles(dir) {
   return result;
 }
 
-function fakeCodexBin({ exitCode = 0, stderr = "", inputPath, failTurnStart = false, omitFinalRead = false, omitTurnCompleted = false } = {}) {
+function fakeCodexBin({ exitCode = 0, stderr = "", inputPath, failTurnStart = false, failThreadNameSet = false, omitFinalRead = false, omitTurnCompleted = false } = {}) {
   const dir = tempDir();
   const binDir = path.join(dir, "bin");
   fs.mkdirSync(binDir, { recursive: true });
@@ -77,6 +77,12 @@ rl.on("line", (line) => {
   if (request.method === "thread/read") {
     if (${Boolean(omitFinalRead)} && request.id >= 4) return;
     console.log(JSON.stringify({ jsonrpc: "2.0", id: request.id, result: { thread: { id: request.params.threadId, name: "Fake Codex Thread", cwd: "/fake/project", status: "idle", turns: [{ id: "turn-1", status: "completed" }, { id: "turn-2", status: "completed" }] } } }));
+  } else if (request.method === "thread/name/set") {
+    if (${Boolean(failThreadNameSet)}) {
+      console.log(JSON.stringify({ jsonrpc: "2.0", id: request.id, error: { message: "rename failed" } }));
+      return;
+    }
+    console.log(JSON.stringify({ jsonrpc: "2.0", id: request.id, result: {} }));
   } else if (request.method === "thread/start") {
     console.log(JSON.stringify({ jsonrpc: "2.0", id: request.id, result: { threadId: "launched-thread-1" } }));
   } else if (request.method === "thread/list") {
@@ -117,6 +123,17 @@ test("prints version and product-oriented help", () => {
   assert.match(help.stdout, /starwork init --help/);
 });
 
+test("starworkMultiagent skill delegates host routing to CLI", () => {
+  const skill = fs.readFileSync(path.join(root, "skills", "starworkMultiagent", "SKILL.md"), "utf8");
+
+  assert.doesNotMatch(skill, /\| Host \|/);
+  assert.doesNotMatch(skill, /Codex app-server/);
+  assert.doesNotMatch(skill, /Claude Code \|/);
+  assert.match(skill, /CLI 返回/);
+  assert.match(skill, /manual_handoff_required/);
+  assert.match(skill, /needs_adapt/);
+});
+
 test("dry-run does not write files", () => {
   const dir = tempDir();
   const output = runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--dry-run"]);
@@ -844,7 +861,7 @@ test("multiagent status --host and read expose Codex observations", () => {
   assert.match(input, /"method":"thread\/resume"/);
 });
 
-test("multiagent instruct records shared request and sends formatted Codex instruction", () => {
+test("multiagent instruct returns manual handoff for Codex when standard send is unavailable", () => {
   const dir = tempDir();
   const inputPath = path.join(tempDir(), "codex-input.jsonl");
   runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
@@ -865,27 +882,28 @@ test("multiagent instruct records shared request and sends formatted Codex instr
   const result = JSON.parse(instruct.stdout);
   const shared = fs.readFileSync(path.join(dir, "_系统", "协作", "shared.md"), "utf8");
   const state = readJson(path.join(dir, ".starwork", "agent-lanes", "state.json"));
-  const input = fs.readFileSync(inputPath, "utf8");
 
   assert.equal(instruct.status, 0);
-  assert.equal(result.host_delivery.status, "completed");
+  assert.equal(result.schema, "starwork.agent_lanes.instruct.v0.4");
+  assert.equal(result.host_delivery.status, "manual_handoff_required");
+  assert.equal(result.host_delivery.mode, "manual_handoff");
+  assert.match(result.host_delivery.warning, /standard background delivery capability is not available/);
   assert.match(shared, /Cross-Lane Requests/);
-  assert.match(shared, /product-planning \| development \| 请开始实现 v0\.2。 \| completed \| completed/);
-  assert.equal(state.requests[0].host_delivery.thread_id, "dev-thread-3");
-  assert.match(input, /"method":"thread\/resume"/);
-  assert.match(input, /"method":"turn\/start"/);
-  assert.match(input, /STARWORK:MULTIAGENT_MESSAGE v1/);
+  assert.match(shared, /product-planning \| development \| 请开始实现 v0\.2。 \| manual_handoff_required \| manual_handoff_required/);
+  assert.equal(state.requests[0].host_delivery.status, "manual_handoff_required");
+  assert.equal(fs.existsSync(inputPath), false);
 });
 
-test("multiagent instruct marks incomplete delivery as started_unverified", () => {
+test("multiagent instruct does not use low-level Codex turn APIs even with wait requested", () => {
   const dir = tempDir();
+  const inputPath = path.join(tempDir(), "codex-input.jsonl");
   runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
   runCommand(["multiagent", "init", "--target", dir, "--yes"]);
   runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
   runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
   runCommand(["multiagent", "bind", "development", "--session", "codex:dev-thread-4", "--target", dir, "--yes"], { env: fakeCodexBin().env });
 
-  const fakeCodex = fakeCodexBin({ omitTurnCompleted: true });
+  const fakeCodex = fakeCodexBin({ inputPath, omitTurnCompleted: true });
   const instruct = runCommand([
     "multiagent", "instruct", "development",
     "--from", "product-planning",
@@ -893,6 +911,7 @@ test("multiagent instruct marks incomplete delivery as started_unverified", () =
     "--target", dir,
     "--json",
     "--yes",
+    "--wait-completion",
     "--timeout", "1000"
   ], { env: fakeCodex.env });
   const result = JSON.parse(instruct.stdout);
@@ -900,10 +919,84 @@ test("multiagent instruct marks incomplete delivery as started_unverified", () =
   const state = readJson(path.join(dir, ".starwork", "agent-lanes", "state.json"));
 
   assert.equal(instruct.status, 0);
-  assert.equal(result.host_delivery.status, "started_unverified");
-  assert.match(result.host_delivery.verification_warning, /turn\/completed was not observed/);
-  assert.match(shared, /product-planning \| development \| 请开始实现 v0\.3。 \| started_unverified \| started_unverified/);
-  assert.equal(state.requests[0].host_delivery.status, "started_unverified");
+  assert.equal(result.host_delivery.status, "manual_handoff_required");
+  assert.match(shared, /product-planning \| development \| 请开始实现 v0\.3。 \| manual_handoff_required \| manual_handoff_required/);
+  assert.equal(state.requests[0].host_delivery.status, "manual_handoff_required");
+  assert.equal(fs.existsSync(inputPath), false);
+});
+
+test("multiagent instruct returns unbound when target lane has no session", () => {
+  const dir = tempDir();
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "init", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
+
+  const instruct = runCommand([
+    "multiagent", "instruct", "development",
+    "--from", "product-planning",
+    "--message", "请开始实现 v0.4。",
+    "--target", dir,
+    "--json",
+    "--yes"
+  ]);
+  const result = JSON.parse(instruct.stdout);
+  const shared = fs.readFileSync(path.join(dir, "_系统", "协作", "shared.md"), "utf8");
+  const state = readJson(path.join(dir, ".starwork", "agent-lanes", "state.json"));
+
+  assert.equal(instruct.status, 0);
+  assert.equal(result.host_delivery.status, "unbound");
+  assert.match(result.host_delivery.warning, /Target lane is not bound/);
+  assert.match(shared, /product-planning \| development \| 请开始实现 v0\.4。 \| unbound \| unbound/);
+  assert.equal(state.requests[0].host_delivery.status, "unbound");
+});
+
+test("multiagent instruct returns needs_adapt when a non-Codex host is not adapted", () => {
+  const dir = tempDir();
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "init", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "bind", "development", "--session", "cursor:cursor-thread-1", "--target", dir, "--yes"]);
+
+  const instruct = runCommand([
+    "multiagent", "instruct", "development",
+    "--from", "product-planning",
+    "--message", "请继续处理运行时路由。",
+    "--target", dir,
+    "--json",
+    "--yes"
+  ]);
+  const result = JSON.parse(instruct.stdout);
+
+  assert.equal(instruct.status, 0);
+  assert.equal(result.host_delivery.status, "needs_adapt");
+  assert.equal(result.host.id, "cursor");
+  assert.match(result.host_delivery.warning, /starwork adapt cursor/);
+});
+
+test("multiagent instruct returns manual handoff when adapted host lacks standard send", () => {
+  const dir = tempDir();
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--adapter", "cursor", "--yes"]);
+  runCommand(["multiagent", "init", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "bind", "development", "--session", "cursor:cursor-thread-2", "--target", dir, "--yes"]);
+
+  const instruct = runCommand([
+    "multiagent", "instruct", "development",
+    "--from", "product-planning",
+    "--message", "请继续处理运行时路由。",
+    "--target", dir,
+    "--json",
+    "--yes"
+  ]);
+  const result = JSON.parse(instruct.stdout);
+
+  assert.equal(instruct.status, 0);
+  assert.equal(result.host_delivery.status, "manual_handoff_required");
+  assert.equal(result.host_delivery.mode, "manual_handoff");
+  assert.match(result.host_delivery.formatted_message, /STARWORK:MULTIAGENT_MESSAGE v1/);
 });
 
 test("multiagent bind detects Claude Code session from environment and outputs resume command", () => {
@@ -964,7 +1057,7 @@ test("multiagent read summarizes Claude Code transcript without dumping full tra
 
 test("multiagent instruct returns manual handoff for Trae lane instead of fake delivery", () => {
   const dir = tempDir();
-  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--adapter", "trae", "--yes"]);
   runCommand(["multiagent", "init", "--target", dir, "--yes"]);
   runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
   runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
@@ -1027,6 +1120,59 @@ test("multiagent launch creates and binds Codex threads with launch message", ()
   assert.match(input, /StarWork MultiAgent Launch/);
 });
 
+test("multiagent launch names each batch-created Codex thread by lane role", () => {
+  const dir = tempDir();
+  const inputPath = path.join(tempDir(), "codex-input.jsonl");
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "init", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "product-planning", "--purpose", "产品规划", "--write", "product/planning/**", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
+
+  const fakeCodex = fakeCodexBin({ inputPath });
+  const launch = runCommand([
+    "multiagent", "launch",
+    "--lanes", "product-planning,development",
+    "--target", dir,
+    "--json",
+    "--yes",
+    "--timeout", "1000"
+  ], { env: fakeCodex.env });
+  const result = JSON.parse(launch.stdout);
+  const state = readJson(path.join(dir, ".starwork", "agent-lanes", "state.json"));
+  const input = fs.readFileSync(inputPath, "utf8");
+
+  assert.equal(launch.status, 0);
+  assert.equal(result.launches[0].session_name, "产品规划 Agent");
+  assert.equal(result.launches[0].rename_status, "ok");
+  assert.equal(result.launches[0].binding_status, "bound");
+  assert.equal(result.launches[1].session_name, "功能开发 Agent");
+  assert.equal(result.launches[1].rename_status, "ok");
+  assert.equal(result.launches[1].binding_status, "bound");
+  assert.equal(state.lanes["product-planning"].session_name, "产品规划 Agent");
+  assert.equal(state.lanes.development.session_name, "功能开发 Agent");
+  assert.match(input, /"name":"产品规划 Agent"/);
+  assert.match(input, /"name":"功能开发 Agent"/);
+  assert.doesNotMatch(result.launches[0].session_name, new RegExp(path.basename(dir)));
+});
+
+test("multiagent launch warns when host session rename fails after creation", () => {
+  const dir = tempDir();
+  runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "init", "--target", dir, "--yes"]);
+  runCommand(["multiagent", "add", "development", "--purpose", "功能开发", "--write", "product/cli/**", "--target", dir, "--yes"]);
+
+  const fakeCodex = fakeCodexBin({ failThreadNameSet: true });
+  const launch = runCommand(["multiagent", "launch", "development", "--target", dir, "--json", "--yes", "--timeout", "1000"], { env: fakeCodex.env });
+  const result = JSON.parse(launch.stdout);
+  const registry = fs.readFileSync(path.join(dir, "_系统", "协作", "agent-lanes.md"), "utf8");
+
+  assert.equal(launch.status, 0);
+  assert.equal(result.launches[0].binding_status, "bound");
+  assert.equal(result.launches[0].rename_status, "warning");
+  assert.match(result.launches[0].rename_warning, /rename failed/);
+  assert.match(registry, /codex:launched-thread-1/);
+});
+
 test("multiagent launch does not bind when launch message delivery fails", () => {
   const dir = tempDir();
   runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);
@@ -1043,10 +1189,24 @@ test("multiagent launch does not bind when launch message delivery fails", () =>
   assert.equal(result.launches[0].status, "failed");
   assert.equal(result.launches[0].created_thread_id, "launched-thread-1");
   assert.equal(result.launches[0].thread_id, undefined);
+  assert.equal(result.launches[0].binding_status, "unbound");
   assert.match(registry, /\| development \| 功能开发 \| unbound \|/);
   assert.equal(state.lanes.development?.thread_id, undefined);
 });
 
+test("multiagent launch refuses non-StarWork targets without sidecar initialization", () => {
+  const dir = tempDir();
+  fs.writeFileSync(path.join(dir, "AGENTS.md"), "# Existing project rules\n", "utf8");
+
+  const launch = runCommand(["multiagent", "launch", "development", "--target", dir, "--json", "--yes"]);
+
+  assert.notEqual(launch.status, 0);
+  assert.match(launch.stderr, /starworkInit/);
+  assert.doesNotMatch(launch.stderr, /请先运行 starwork init/);
+  assert.equal(fs.existsSync(path.join(dir, "AGENTS.starwork-new.md")), false);
+  assert.equal(fs.readFileSync(path.join(dir, "AGENTS.md"), "utf8"), "# Existing project rules\n");
+});
+
 test("multiagent launch binds when final verification read times out after completion", () => {
   const dir = tempDir();
   runInit(["--type", "single-light", "--pack", "general", "--target", dir, "--yes"]);

package/docs/alpha-test-guide.md

@@ -120,9 +120,9 @@ starwork spawn \
 starwork doctor --target ~/Desktop/starwork-alpha-project
 ```
 
-### 4. 可选：验证 Codex 多会话协作
+### 4. 可选：验证 MultiAgent 会话创建与跨会话交付
 
-这一步只适合正在使用 Codex，并且希望测试多个 Codex 会话协作的用户。
+这一步适合希望测试多个 Agent 职责位、独立会话创建和跨会话交付降级的用户。
 
 先初始化项目内的职责位：
 
@@ -133,15 +133,18 @@ starwork multiagent init \
   --yes
 ```
 
-为 development 职责位创建 Codex 会话并发送启动消息：
+为 product-planning 和 development 职责位批量创建独立会话并发送启动消息：
 
 ```bash
-starwork multiagent launch development \
+starwork multiagent launch \
+  --lanes product-planning,development \
   --target ~/Desktop/starwork-alpha-project \
   --json \
   --yes
 ```
 
+检查 JSON 中每个 lane 的 `binding_status`。只有 `bound` 表示该 Agent 已创建并绑定可工作的独立会话；`rename_status` 为 `warning` 时，说明宿主会话自动命名失败，需要按返回信息处理。
+
 向 development 职责位发送一条跨会话指令：
 
 ```bash
@@ -153,6 +156,8 @@ starwork multiagent instruct development \
   --yes
 ```
 
+当前 CLI 只有在运行时发现宿主标准后台投递能力时才会返回 `delivered`。如果返回 `manual_handoff_required`，表示已生成可复制交付消息，需要用户手动发给目标会话；这不是失败。
+
 读取目标职责位当前可观察状态：
 
 ```bash
@@ -162,7 +167,7 @@ starwork multiagent read development \
   --json
 ```
 
-预期：`launch` 和简单 `instruct` 应返回 `completed`。如果返回 `started_unverified`，说明 CLI 没观察到目标会话完成，应继续用 `read` 复核，不要把它当作已完成交付。
+预期：`launch` 成功时返回 `completed`；`instruct` 会根据 CLI 运行时宿主路由返回 `delivered`、`manual_handoff_required`、`needs_adapt`、`unbound` 等状态。`delivered` 只表示消息已投递，不表示目标任务完成；`manual_handoff_required` 表示需要手动复制交付消息。
 
 ### 5. 可选：验证 Host Adapter
 
@@ -198,6 +203,10 @@ starwork multiagent init \
   --target ~/Desktop/starwork-alpha-project \
   --yes
 
+starwork adapt trae \
+  --target ~/Desktop/starwork-alpha-project \
+  --yes
+
 starwork multiagent bind development \
   --session trae:manual-dev-session \
   --target ~/Desktop/starwork-alpha-project \
@@ -243,11 +252,11 @@ Cursor / Trae 写入 Skill 目录后，宿主 UI 是否立即发现需要继续
 - 系统 skills 是否能被 Codex 识别和调用：`starworkInit`、`starworkDoctor`、`starworkMultiagent`、`starworkKnowledge`。
 - `starworkMultiagent` 是否能把“登记当前会话为常用智能体”正确转换成 `starwork multiagent init/add/bind` 建议。
 - `starwork multiagent bind --session-name` 是否能正确同步 Codex 宿主会话名；失败时是否能看懂 warning。
-- `starwork multiagent launch/instruct/read` 在 Codex 中是否能完成多会话读取和指令交付；如果未完成，`started_unverified` 是否容易理解。
+- `starwork multiagent launch/instruct/read` 是否能清楚区分会话创建、宿主观察、标准投递和人工交付；`manual_handoff_required` / `needs_adapt` / `unbound` 是否容易理解。
 - `starwork adapt --capabilities` 是否能帮助 Agent 判断不同宿主能力，而不是把内部字段甩给用户。
 - `starwork doctor --host <host>` 是否能区分“工作台结构问题”和“宿主入口 / Skill 目录问题”。
 - Cursor / Trae 在写入 `.cursor/skills/` / `.trae/skills/` 后是否需要重启、刷新窗口或重新打开项目。
-- 非 Codex 宿主返回 `manual_handoff_required` 时，用户是否能理解“已生成交付消息，不等于已自动送达”。
+- 返回 `manual_handoff_required` 时，用户是否能理解“已生成交付消息，不等于已自动送达”。
 - 项目中心自带的 `starworkSpawn`、`starworkAudit` 与项目工作台自带的 `neat-freak` 是否能在对应工作台内被发现。
 
 ## 发布前检查

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jennie-shawn/starwork",
-  "version": "0.1.0-alpha.18",
+  "version": "0.1.0-alpha.19",
   "description": "StarWork Core、CLI、Packs 和 Agent skills，用于构建 AI 工作台。",
   "type": "commonjs",
   "bin": {

package/skills/README.md

@@ -23,10 +23,10 @@ Skill 的安装、项目中心管理、Pack 推荐和项目分发规则见 `prod
 
 - `starworkInit/`：帮助 Agent 设计 `starwork init` 初始化方案和 init blueprint。详细 SPEC 见 `starworkInit-spec.md`。
 - `starworkDoctor/`：帮助 Agent 基于 `starwork doctor --json` 的探测结果，对当前工作区或历史模板做理性诊断；用户明确要求升级时，继续确认目录语义并生成 `starwork upgrade --blueprint` 升级施工图。详细 SPEC 见 `starworkDoctor-spec.md`。
-- `starworkMultiagent/`：帮助 Agent 把“常用智能体 / 当前会话职责 / 多 Agent 分工 / 共享输出 / 跨会话指令 / Codex lane thread 编排”翻译成安全的 `starwork multiagent` 命令组合。详细 SPEC 见 `starworkMultiagent-spec.md` 和 `product/planning/features/multiagent/specs/v0.2-codex-orchestration.md`。
+- `starworkMultiagent/`：帮助 Agent 把“常用智能体 / 当前会话职责 / 多 Agent 分工 / 共享输出 / 跨会话指令 / lane session 编排”翻译成安全的 `starwork multiagent` 命令组合；宿主能力由 CLI 运行时判断。详细 SPEC 见 `starworkMultiagent-spec.md` 和 `product/planning/features/multiagent/specs/v0.4-runtime-host-routing.md`。
 - `starworkKnowledge/`：帮助 Agent 通过 `starwork knowledge` 开启、检查和维护项目本地知识库；负责判断哪些内容值得长期沉淀，区分 `pages/` 和 `synthesis/`，不默认提交项目中心。
 
-Host Adapter v0.1 已进入系统级 Skill：`starworkInit`、`starworkDoctor`、`starworkMultiagent`、`starworkKnowledge` 会引用 `starwork adapt` / `doctor --host` 的宿主能力结果，避免把 Codex 的自动会话能力误当成 Claude Code、Cursor 或 Trae 都支持。`starworkMultiagent` 对 Claude Code 可生成 resume 命令和 transcript 摘要，对 Cursor / Trae 默认生成人工交付消息。
+Host Adapter v0.1 已进入系统级 Skill：`starworkInit`、`starworkDoctor`、`starworkMultiagent`、`starworkKnowledge` 会引用 `starwork adapt` / `doctor --host` 的宿主准备结果。具体业务命令能否自动执行由 CLI 运行时判断；不支持标准后台投递时，`starworkMultiagent` 解释 CLI 返回的 `manual_handoff_required`、`needs_adapt`、`unbound` 等状态。
 
 `starworkAudit` 是项目中心工作台模板自带 skill，源码在 `product/kit-skills/starworkAudit/`；规格仍保留在 `starworkAudit-spec.md`。
 `starworkKnowledgeProject` 是知识库能力的项目内业务 skill，源码在 `product/core/capabilities/knowledge/skills/starworkKnowledgeProject/`；它不参与全局安装。

package/skills/starworkMultiagent/SKILL.md

@@ -46,6 +46,18 @@ _system/collaboration/shared.md
 
 如果用户指定了目标目录，所有命令都加 `--target <path>`。如果没有指定，默认目标是当前工作区。
 
+## 前置边界：只在 StarWork 工作台内创建团队
+
+`starworkInit` 负责把普通项目变成 StarWork 工作台；`starworkMultiagent` 只负责已有 StarWork 工作台里的团队协作。
+
+开始任何 `multiagent init/add/bind/launch` 写入前，先确认目标目录是 StarWork 工作台：
+
+```bash
+starwork doctor --target <path> --json
+```
+
+如果目标不是 StarWork 工作台，立即停止 multiagent 写入，不要尝试局部初始化，不要新建 `AGENTS.starwork-new.md` 或只补 `_系统/协作/`。下一步是切换到 `starworkInit` Skill，由它采访用户、选择工作台类型和 Pack、处理已有规则入口，并在用户确认后调用 CLI。`starworkInit` 完成且 `starwork doctor --target <path>` 通过后，才继续 multiagent 流程。
+
 ## 判断用户意图
 
 优先把用户话语归到一个入口，不要一开始讲 CLI 子命令。
@@ -55,16 +67,34 @@ _system/collaboration/shared.md
 | “把当前会话创建为常用智能体，负责 X” | 登记当前会话为一个稳定职责位 | 必要时 `init`，再 `add`，再 `bind` |
 | “初始化多 Agent 协作层” | 创建 Agent Lanes 协议文件 | `multiagent init` |
 | “增加一个负责 X 的 Agent / lane” | 新增职责位，暂不一定绑定会话 | `multiagent add` |
-| “把当前 Codex / Claude Code 绑定到 X” | 将具体 session 绑定到已有 lane | `multiagent bind` |
+| “把当前工具会话绑定到 X” | 将具体 session 绑定到已有 lane | `multiagent bind` |
 | “这个会话不再负责 X” | 释放 lane 当前绑定 | `multiagent release` |
 | “看看现在有哪些 Agent 分工” | 读取协作状态 | `multiagent status --json` |
 | “这个输出给其他 Agent 看” | 登记共享输出索引 | `multiagent share` |
 | “让开发 lane 开始开发” | 向目标 lane 发送格式化跨会话指令 | `multiagent instruct <lane>` |
 | “看看开发 lane 做到哪了” | 读取目标 lane 可用的宿主观察结果 | `multiagent read <lane>` 或 `multiagent status --host` |
 | “把这条消息交给另一个工具里的会话” | 生成并记录人工交付消息 | `multiagent handoff <lane>` |
-| “继续 Claude Code 里的这个 lane” | 输出 resume 命令或人工继续步骤 | `multiagent continue <lane>` |
-| “帮我创建产品、开发、验收三个智能体” | 为已有 lanes 创建并绑定 Codex threads | `multiagent launch --lanes ...` |
-| “把这个 lane 固定起来” | 绑定 lane 后 best-effort 置顶 Codex thread | `multiagent bind --pin` |
+| “继续这个 lane” | 输出 resume 命令或人工继续步骤 | `multiagent continue <lane>` |
+| “帮我创建产品、开发、验收三个智能体” | 设计 lanes 后创建并绑定可工作的独立会话 | `multiagent add ...` + `multiagent launch --lanes ...` |
+| “把这个 lane 固定起来” | 绑定 lane 后请求宿主置顶；是否支持由 CLI 返回 | `multiagent bind --pin` |
+
+## 常用流程：创建 Agent 团队
+
+“创建 Agent 团队 / 创建多个智能体 / 产品、开发、验收三个智能体”不是只创建 lane。完整成功标准是：每个目标职责都有 lane、每个 lane 已绑定可工作的独立 session，或者输出中明确说明哪些 lane 未完成以及阻塞原因。
+
+1. 先按“前置边界”确认目标是 StarWork 工作台；非 StarWork 目标转 `starworkInit`，不要运行 `multiagent init` 做局部初始化。
+2. 读取 `agent-lanes.md` 和 `state.json`，判断哪些 lane 已存在，哪些需要新增。
+3. 对缺失 lane 先 dry-run `multiagent add`，确认 `lane-id`、职责和写入范围；用户确认后执行 `--yes`。
+4. 对需要独立 session 的 lanes，执行：
+
+```bash
+starwork multiagent launch --lanes <lane1,lane2,lane3> --target <path> --json --yes
+```
+
+5. 检查 JSON 中每个 lane 的 `launch_status`、`rename_status` 和 `binding_status`。只有 `binding_status: "bound"` 才能告诉用户该 Agent 已创建并可工作；`unbound` 必须带 warning 和下一步。
+6. 默认会话名由 CLI 自动生成：`<职责名> Agent`。如果 `rename_status` 是 `warning`，说明宿主命名失败但 StarWork 绑定结果仍以 `binding_status` 为准。
+
+只有用户明确说“先只初始化协作层 / 先只建职责位 / lane-only”时，才可以停在 `multiagent init/add`。
 
 ## 常用流程：登记当前会话为常用智能体
 
@@ -83,7 +113,7 @@ starwork multiagent init --target <path> --dry-run
    - 可主动修改的路径范围。
    - 该 lane 的过程工作区，中文项目默认是 `_系统/协作/lanes/<lane-id>/workspace/`，英文项目默认是 `_system/collaboration/lanes/<lane-id>/workspace/`。
    - 当前 session ID；无法自动识别时，请用户提供 `agent:session-id`。
-   - 宿主会话显示名称；仅当用户希望在 Codex 等宿主会话列表中同步改名时使用。
+   - 宿主会话显示名称；仅当用户希望在宿主会话列表中同步改名时使用。
 4. 生成 dry-run 命令：
 
 ```bash
@@ -99,32 +129,20 @@ starwork multiagent bind <lane> --session <agent:session-id> --session-name "<di
 
 ## 子命令使用规则
 
-## 宿主能力分支
-
-开始跨会话操作前，先看当前工作台是否已有 adapter state：
-
-```bash
-starwork doctor --target <path> --host all --json
-```
-
-不同宿主能力不同，不能把 Codex 的能力当成所有工具都支持：
+## 宿主能力路由
 
-| Host | 使用方式 |
-|---|---|
-| Codex | 可以自动读取、创建和发送跨会话指令，但仍以 StarWork worklog 和 shared context 为准。 |
-| Claude Code | 可以绑定当前会话、读取 transcript 候选摘要、resume；不能后台发消息给非当前会话。 |
-| Cursor | 先按 partial 能力处理；自动化不可确认时生成可复制交付消息。 |
-| Trae | 默认是人工交付宿主；读取 StarWork worklog / handoff，不读加密数据库，不说自动送达。 |
+Skill 不维护宿主能力矩阵，不根据工具名称自行判断能否自动发送、读取、创建或改名。凡是依赖宿主能力的动作，都调用 StarWork CLI，并根据 CLI 返回的结构化状态解释下一步。
 
-如果用户要给 Claude Code、Cursor 或 Trae 做多会话协作，先确认对应宿主已经适配：
+常见 CLI 返回：
 
-```bash
-starwork adapt <host> --target <path> --dry-run
-starwork adapt <host> --target <path> --yes
-starwork doctor --target <path> --host <host>
-```
+- `delivered`：消息已通过宿主标准能力投递；不代表目标任务完成。
+- `manual_handoff_required`：CLI 已生成可复制交付消息，需要用户手动发给目标会话。
+- `needs_adapt`：目标宿主还没准备好；引导用户先运行 `starwork adapt <host> --target <path> --dry-run`，确认后再执行。
+- `unbound`：目标 lane 尚未绑定 session；先 `bind` 或 `launch`。
+- `unsupported`：当前宿主明确不支持该能力。
+- `failed`：CLI 尝试执行失败；保留项目记录，提示用户可重试或走 handoff。
 
-不要把 `adapter profile`、`host_native_dirs`、`capabilities` 等内部词直接讲给用户；说“这个工具能自动做什么、哪些需要你手动复制”。
+解释时只说用户下一步，不展开宿主私有路径、数据库、transcript 或底层 API 细节。
 
 ### init
 
@@ -191,7 +209,7 @@ starwork multiagent bind <lane> --session <agent:session-id> --session-name "<di
 <项目或产品名> <职责> Agent
 ```
 
-例如 `StarWork CLI 维护 Agent`。当前只有 Codex session 支持同步宿主会话名；Claude Code、Cursor、Trae 绑定时不要承诺能改宿主会话标题。失败只作为 warning，不影响绑定。
+例如 `StarWork CLI 维护 Agent`。是否能同步宿主标题由 CLI 返回；失败只作为 warning，不影响 StarWork binding。
 
 如果用户要求置顶这个 lane，可加入：
 
@@ -241,7 +259,7 @@ starwork multiagent status --host --target <path> --json
 starwork multiagent read <lane> --turns 5 --target <path> --json
 ```
 
-解释时必须提醒：这是 Codex host observation，正式交接仍以 lane worklog 和 shared outputs 为准。Codex 前端不刷新不等于发送失败。
+解释时必须提醒：这是宿主观察结果，正式交接仍以 lane worklog 和 shared outputs 为准。宿主前端不刷新不等于发送失败。
 
 ### share
 
@@ -281,15 +299,15 @@ starwork multiagent share <from-lane> --title "<title>" --path "<relative-path>"
 starwork multiagent instruct <to-lane> --from <from-lane> --message "<text>" --target <path> --dry-run
 ```
 
-用户确认后再执行 `--yes`。CLI 会先把请求写入 shared context，再通过 Codex app-server 发送格式化消息；发送失败时，项目内记录仍保留。
+用户确认后再执行 `--yes`。CLI 会先把请求写入 shared context，再判断宿主运行时能力：可标准投递则发送；不可标准投递则返回 handoff、needs_adapt、unbound、unsupported 或 failed 等状态。发送失败时，项目内记录仍保留。
 
-默认情况下，`instruct` 会等待目标 Codex turn 完成，避免过早关闭连接导致目标 turn 被打断。若返回 `started_unverified`，说明消息已经启动但 CLI 没有观察到完成；此时不要告诉用户“已经完成交付”，应立即运行：
+默认情况下，`instruct` 只确认消息已投递到目标 lane，返回 `delivered`。`delivered` 不等于目标任务完成，不要告诉用户“对方已经完成”。后续用 `read`、目标 lane worklog 或回传指令追踪：
 
 ```bash
 starwork multiagent read <to-lane> --turns 3 --target <path> --json
 ```
 
-只有看到目标 turn 为 `completed`，或目标 lane 后续明确回报，才把这次跨会话指令视为完成。
+只有看到目标 turn 为 `completed`，或目标 lane 后续明确回报，才把这次跨会话指令视为完成。如果用户明确要求同步等待，再加 `--wait-completion`；若返回 `started_unverified`，只能说明已启动但未观察到完成。
 
 对非 Codex 宿主：
 
@@ -311,7 +329,7 @@ starwork multiagent continue <lane> --target <path> --json
 
 ### launch
 
-为已有 lane 创建 Codex thread，并发送 StarWork 格式化 Launch Message。
+为已有 lane 创建独立宿主会话，并发送 StarWork 格式化 Launch Message。
 
 命令：
 
@@ -322,6 +340,12 @@ starwork multiagent launch --lanes product-planning,development,review --target
 
 不要自动创建 lane。lane 不存在时，先用 `multiagent add` 设计职责和写入范围。
 
+正式执行时优先使用 `--json`，并按结果判断：
+
+- `launch_status` 表示宿主会话和 Launch Message 是否完成。
+- `rename_status` 表示宿主会话命名是否完成；warning 需要告诉用户。
+- `binding_status` 表示 StarWork lane 是否已绑定可工作的 session；不是 `bound` 时不能说团队创建完成。
+
 ## Lane Workspace 与正式输出
 
 每个 lane 默认有自己的过程工作区：