@seamnet/client 0.18.2 → 0.20.0

package/bin/seam.js

@@ -57,11 +57,12 @@ function printHelp() {
     '  seam self schedule --id <id> --every <duration> --text <text>',
     '  seam self cancel --id <id>',
     '  seam self list',
-    '  seam cc list',
-    '  seam cc read --session <name> [--lines N]',
-    '  seam cc send --session <name> --text <msg>',
-    '  seam cc start --dir <path> [--session <name>]',
-    '  seam cc restart --session <name> [--no-continue]  重启某个 CC 实例',
+    '  seam term list',
+    '  seam term read --session <name> [--lines N | --full]',
+    '  seam term send --session <name> [--text <msg> [--no-enter]] [--key <K> ...]',
+    '  seam term start --kind cc|codex|shell [--session <name>] [--dir <path>] [--cmd "..."]',
+    '  seam term stop --session <name>',
+    '  seam term restart --session <name> [--no-continue]',
     '',
     '输出：JSON { ok: true, data } 或 { ok: false, error }。',
   ].join('\n');
@@ -401,15 +402,13 @@ async function cmdInvite(subAction, restArgs) {
   output(false, `Unknown invite action: ${subAction}. Try: seam invite generate`);
 }
 
-// === cc (Claude Code 管理) ===
+// === term (通用终端操作) ===
 
 const tmuxUtils = require('../lib/tmux-utils.cjs');
 
-async function cmdCc(subAction, restArgs) {
+async function cmdTerm(subAction, restArgs) {
   if (!subAction || subAction === 'list') {
-    const sessions = tmuxUtils.listSessions();
-    if (sessions.length === 0) output(true, { sessions: [], message: 'no tmux sessions' });
-    output(true, { sessions });
+    output(true, { terms: tmuxUtils.listTerms() });
     return;
   }
 
@@ -419,12 +418,16 @@ async function cmdCc(subAction, restArgs) {
       options: {
         session: { type: 'string' },
         lines: { type: 'string', default: '20' },
+        full: { type: 'boolean' },
       },
       strict: false,
     });
     if (!values.session) output(false, '--session required');
     try {
-      const text = tmuxUtils.readOutput(values.session, parseInt(values.lines) || 20);
+      const text = tmuxUtils.readTerm(values.session, {
+        lines: parseInt(values.lines, 10) || 20,
+        full: !!values.full,
+      });
       output(true, { session: values.session, lines: text.trimEnd().split('\n') });
     } catch (e) {
       output(false, `read failed: ${e.message}`);
@@ -438,14 +441,23 @@ async function cmdCc(subAction, restArgs) {
       options: {
         session: { type: 'string' },
         text: { type: 'string' },
+        'no-enter': { type: 'boolean' },
+        key: { type: 'string', multiple: true },
       },
       strict: false,
     });
     if (!values.session) output(false, '--session required');
-    if (!values.text) output(false, '--text required');
+    const keys = values.key || [];
+    if (values.text == null && keys.length === 0) {
+      output(false, '需要 --text 或 --key 至少一个');
+    }
     try {
-      tmuxUtils.sendToCC(values.session, values.text);
-      output(true, { session: values.session, sent: values.text });
+      tmuxUtils.sendTerm(values.session, {
+        text: values.text,
+        noEnter: !!values['no-enter'],
+        keys,
+      });
+      output(true, { session: values.session, text: values.text ?? null, keys });
     } catch (e) {
       output(false, e.message);
     }
@@ -456,16 +468,51 @@ async function cmdCc(subAction, restArgs) {
     const { values } = parseArgs({
       args: restArgs,
       options: {
-        dir: { type: 'string' },
+        kind: { type: 'string' },
         session: { type: 'string' },
+        dir: { type: 'string' },
+        cmd: { type: 'string' },
       },
       strict: false,
     });
-    if (!values.dir) output(false, '--dir required');
-    const sessionName = values.session || values.dir.split('/').pop();
+    if (!values.kind) output(false, '--kind required (cc|codex|shell)');
     try {
-      tmuxUtils.startCC(values.dir, sessionName);
-      output(true, { session: sessionName, dir: values.dir, started: true });
+      const res = tmuxUtils.startTerm({
+        kind: values.kind,
+        cmd: values.cmd,
+        session: values.session,
+        dir: values.dir,
+      });
+      output(true, { ...res, started: true });
+    } catch (e) {
+      output(false, e.message);
+    }
+    return;
+  }
+
+  if (subAction === 'stop') {
+    const { values } = parseArgs({
+      args: restArgs,
+      options: { session: { type: 'string' } },
+      strict: false,
+    });
+    if (!values.session) output(false, '--session required');
+    // 关之前查 registry：这个 session 是否绑着一个 guardian
+    let guardianEntry = null;
+    try {
+      const { readAll } = await import('../lib/registry.js');
+      guardianEntry = readAll().find((e) => e.tmux_session === values.session) || null;
+    } catch {}
+    try {
+      const { kind } = tmuxUtils.stopTerm(values.session);
+      const result = { session: values.session, kind, stopped: true };
+      if (guardianEntry) {
+        result.guardian_killed = true;
+        result.warning = `注意：已一并终止该 home 的 guardian（userId=${guardianEntry.userId}, home=${guardianEntry.seam_home}）`;
+      } else if (kind === 'cc') {
+        result.warning = '注意：这是个 cc 会话——若它绑着 guardian，guardian 已随会话一并终止';
+      }
+      output(true, result);
     } catch (e) {
       output(false, e.message);
     }
@@ -485,11 +532,11 @@ async function cmdCc(subAction, restArgs) {
     if (!values.session) output(false, '--session required');
     const continueSession = values['no-continue'] ? false : true;
     try {
-      const ok = await tmuxUtils.restartCC(values.session, { continueSession });
+      const ok = await tmuxUtils.restartTerm(values.session, { continueSession });
       if (ok) {
         output(true, { session: values.session, restarted: true });
       } else {
-        output(false, 'restart failed: CC 未在超时内退出或重启');
+        output(false, 'restart failed: 终端未在超时内退出或重启');
       }
     } catch (e) {
       output(false, e.message);
@@ -497,7 +544,7 @@ async function cmdCc(subAction, restArgs) {
     return;
   }
 
-  output(false, `Unknown cc action: ${subAction}. Try: list, read, send, start, restart`);
+  output(false, `Unknown term action: ${subAction}. Try: list, read, send, start, stop, restart`);
 }
 
 function parseDuration(str) {
@@ -529,7 +576,7 @@ function parseDuration(str) {
     if (domain === 'inbox') return await cmdInbox(action, rest);
     if (domain === 'self') return await cmdSelf(action, rest);
     if (domain === 'invite') return await cmdInvite(action, rest);
-    if (domain === 'cc') return await cmdCc(action, rest);
+    if (domain === 'term') return await cmdTerm(action, rest);
     output(false, `Unknown domain: ${domain}. Try: seam --help`);
   } catch (e) {
     output(false, e.message);

package/lib/guardian.js

@@ -252,14 +252,14 @@ export async function guardianRun() {
     hub.inject(notice);
     setTimeout(async () => {
       try {
-        const { restartCC } = require('./tmux-utils.cjs');
-        const ok = await restartCC(safeSession, { socketPath: ccSocket, continueSession: true });
+        const { restartTerm } = require('./tmux-utils.cjs');
+        const ok = await restartTerm(safeSession, { socketPath: ccSocket, continueSession: true });
         if (ok) {
           guardianState.set('cc_restarted', new Date().toISOString());
           if (isUpgradeRestart) guardianState.delete('pending_upgrade_restart');
           hub.logger('guardian').info('cc_restart_injected');
         } else {
-          hub.logger('guardian').error('cc_restart_failed', new Error('restartCC returned false'));
+          hub.logger('guardian').error('cc_restart_failed', new Error('restartTerm returned false'));
         }
       } catch (e) {
         hub.logger('guardian').error('cc_restart_failed', e);

package/lib/init.js

@@ -225,8 +225,9 @@ function registerSeamHome() {
   }
 }
 
-export function patchClaudeMd() {
-  const claudeMdPath = join(process.cwd(), 'CLAUDE.md');
+export function patchClaudeMd(projectDir = process.cwd()) {
+  // 默认值 process.cwd() 仅对当前 home 有效；跨 home 调用必须显式传 projectDir
+  const claudeMdPath = join(projectDir, 'CLAUDE.md');
   const rulesRef = '@.seam/CHANNEL_RULES.md';
   const identityRef = '@.seam/IDENTITY.md';
   const contactsRef = '@.seam/contacts.json';
@@ -260,10 +261,11 @@ export function patchClaudeMd() {
  * 从 npm package 的 templates/ 拷贝 CHANNEL_RULES.md 到 .seam/。
  * 每次 init 和 guardian 启动都覆盖——确保老 AI 升级后获得最新规则。
  */
-export function syncChannelRules() {
+export function syncChannelRules(seamHome = SEAM_DIR) {
+  // 默认值 SEAM_DIR 仅对当前 home 有效；跨 home 调用必须显式传 seamHome
   const src = join(TEMPLATES_DIR, 'CHANNEL_RULES.md');
-  const dest = join(SEAM_DIR, 'CHANNEL_RULES.md');
-  if (!existsSync(SEAM_DIR)) mkdirSync(SEAM_DIR, { recursive: true });
+  const dest = join(seamHome, 'CHANNEL_RULES.md');
+  if (!existsSync(seamHome)) mkdirSync(seamHome, { recursive: true });
   const content = readFileSync(src, 'utf8');
   writeFileSync(dest, content);
   return dest;

package/lib/tell.js

@@ -1,7 +1,7 @@
 /**
  * seam tell：跨 AI 单条投递。
  *
- * 优先走 cross-AI registry —— 目标 AI 在本机 → 直接调 tmux sendToCC 注入；
+ * 优先走 cross-AI registry —— 目标 AI 在本机 → 直接调 tmux sendTerm 注入；
  * 不在或 socket 死 → fallback 走 IM 发到对方 userId。
  *
  * 入站 inject 加 from header：`💬 [本机 ← <from>] <text>`
@@ -40,9 +40,9 @@ export async function tell({ to, from, text, guardianRequest }) {
   const entry = findByAlias(to);
   if (entry?.tmux_session) {
     try {
-      const { sendToCC } = require('./tmux-utils.cjs');
+      const { sendTerm } = require('./tmux-utils.cjs');
       const injectText = formatLocalInject(fromName, text);
-      sendToCC(entry.tmux_session, injectText, { socketPath: entry.tmux_socket || undefined });
+      sendTerm(entry.tmux_session, { text: injectText, socketPath: entry.tmux_socket || undefined });
       return { ok: true, channel: 'local', target: entry.userId };
     } catch (e) {
       // 本机命中但 CC 不在线 / tmux session 死了 → 落 IM

package/lib/tmux-utils.cjs

@@ -1,157 +1,245 @@
 /**
- * tmux-utils — 可靠的 tmux 交互。
+ * tmux-utils — 通用 tmux 终端操作（transport 层）。
  *
- * CC 用 raw terminal mode，tmux send-keys 需要特殊处理：
- * 1. 文本用 -l (literal) 发，不解释特殊键
- * 2. Enter 单独发
- * 3. 发完验证是否被接收
+ * 只做 transport：读屏（capture-pane）、发键（send-keys）、起/停/重启会话。
+ * 这层与 pane 里跑什么无关。交互语义（审批流、idle 判断等）故意不抽象——
+ * 由操作者读屏自己决定按什么键。
+ *
+ * 唯一的 per-kind 知识：KIND_CMD 表（kind → 默认启动命令）；restart 时
+ * cc 走优雅 /exit（跑 Stop hook 保命），codex 走 kill 重起。
  */
 
 const { execSync } = require('node:child_process');
-const { existsSync, readFileSync } = require('node:fs');
-const { join } = require('node:path');
+const { existsSync } = require('node:fs');
+const { basename } = require('node:path');
 
 const EXEC_OPTS = { encoding: 'utf8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] };
 
+// kind → 默认启动命令。新增 kind 在这里加一行即可（kind 是数据，不是命令树）。
+const KIND_CMD = {
+  cc: 'claude --dangerously-skip-permissions',
+  codex: 'codex -m gpt-5.4',
+  shell: 'bash',
+};
+const KIND_PREFIX = { cc: 'cc', codex: 'codex', shell: 'sh' };
+
 function tmuxCmd(socketPath) {
   return socketPath ? `tmux -S "${socketPath}"` : 'tmux';
 }
 
-function listSessions(socketPath) {
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * 检测 session 里跑的是什么：'cc' | 'codex' | 'shell'。session 不存在返回 null。
+ * 按 pane 进程及其子进程的 comm 判断。
+ */
+function detectKind(session, socketPath) {
   const tmux = tmuxCmd(socketPath);
-  let lines;
+  let panePid;
   try {
-    lines = execSync(`${tmux} list-sessions -F "#{session_name}"`, EXEC_OPTS)
-      .trim().split('\n').filter(Boolean);
+    panePid = execSync(`${tmux} display-message -t "${session}" -p '#{pane_pid}'`, EXEC_OPTS).trim();
   } catch {
-    return [];
+    return null;
   }
-  return lines.map(name => {
-    const cc = isCCRunning(name, socketPath);
-    return { session: name, cc };
-  });
-}
-
-function isCCRunning(session, socketPath) {
-  const tmux = tmuxCmd(socketPath);
+  const comms = [];
   try {
-    const panePid = execSync(
-      `${tmux} display-message -t "${session}" -p '#{pane_pid}'`, EXEC_OPTS
-    ).trim();
-    const self = execSync(`ps -o comm= -p ${panePid} 2>/dev/null`, EXEC_OPTS).trim();
-    if (['claude', 'claude-code'].includes(self)) return true;
-    try {
-      const child = execSync(`ps -o comm= --ppid ${panePid} 2>/dev/null`, EXEC_OPTS)
-        .trim().split('\n').pop() || '';
-      if (['claude', 'claude-code'].includes(child)) return true;
-    } catch {}
+    comms.push(execSync(`ps -o comm= -p ${panePid} 2>/dev/null`, EXEC_OPTS).trim());
   } catch {}
-  return false;
+  try {
+    const children = execSync(`ps -o comm= --ppid ${panePid} 2>/dev/null`, EXEC_OPTS).trim();
+    if (children) comms.push(children);
+  } catch {}
+  const joined = comms.join(' ').toLowerCase();
+  if (joined.includes('claude')) return 'cc';
+  if (joined.includes('codex')) return 'codex';
+  return 'shell';
 }
 
 /**
- * 给 tmux session 里的 CC 发用户消息。
- * 用 -l (literal) 发文本 + 单独 Enter，保证 raw terminal mode 下不丢回车。
+ * 列出所有 tmux 会话 + 每个的 kind。
  */
-function sendToCC(session, text, { socketPath, skipCheck = false } = {}) {
+function listTerms(socketPath) {
   const tmux = tmuxCmd(socketPath);
-  if (!skipCheck && !isCCRunning(session, socketPath)) {
-    throw new Error(`session "${session}": CC not running`);
+  let lines;
+  try {
+    lines = execSync(`${tmux} list-sessions -F "#{session_name}"`, EXEC_OPTS)
+      .trim().split('\n').filter(Boolean);
+  } catch {
+    return [];
   }
-  // 用 -l 发纯文本（不解释特殊键）
-  execSync(`${tmux} send-keys -t "${session}" -l ${JSON.stringify(text)}`, EXEC_OPTS);
-  // 单独发 Enter 提交
-  execSync(`${tmux} send-keys -t "${session}" Enter`, EXEC_OPTS);
+  return lines.map((name) => ({ session: name, kind: detectKind(name, socketPath) }));
 }
 
 /**
- * 读 tmux session 的最后 N 行输出。
+ * 读 session 屏幕。默认 last N 行；full=true 读整屏 + scrollback 历史。
+ *
+ * 实现：一律 `capture-pane -p -S -` 抓全量，在 JS 里去掉尾部空行再切最后 N 行。
+ * 不用 shell `| tail`——capture-pane 会把光标下方的空 viewport 行也输出，
+ * shell 的 tail 先抓到那些空行，内容稀疏的会话（shell / 刚起的 codex）就读不到东西。
+ * capture-pane 受 tmux history-limit 限制（默认 2000 行），输出有界。
  */
-function readOutput(session, lines = 20, socketPath) {
+function readTerm(session, { lines = 20, full = false, socketPath } = {}) {
   const tmux = tmuxCmd(socketPath);
-  return execSync(
-    `${tmux} capture-pane -t "${session}" -p | tail -${parseInt(lines) || 20}`,
-    EXEC_OPTS
+  const raw = execSync(
+    `${tmux} capture-pane -t "${session}" -p -S -`,
+    { ...EXEC_OPTS, maxBuffer: 16 * 1024 * 1024 }
   );
+  if (full) return raw;
+  const n = parseInt(lines, 10) || 20;
+  return raw.replace(/\s+$/, '').split('\n').slice(-n).join('\n');
 }
 
 /**
- * 在新 tmux session 里启动 CC。
+ * 给 session 发文本和/或命名按键。
+ * - text：字面文本（-l）。默认末尾自动 Enter；noEnter 或同时有 keys 时抑制自动 Enter。
+ * - keys：tmux 命名按键（C-c / Enter / Escape / Up / Tab ...），按顺序发，不加 Enter。
+ * 二者可叠加：text 先发，再按顺序发 keys。
  */
-function startCC(dir, session, socketPath) {
+function sendTerm(session, { text, noEnter = false, keys = [], socketPath } = {}) {
   const tmux = tmuxCmd(socketPath);
-  if (!existsSync(dir)) throw new Error(`dir not found: ${dir}`);
+  const hasText = text != null && text !== '';
+  const hasKeys = Array.isArray(keys) && keys.length > 0;
+  if (!hasText && !hasKeys) {
+    throw new Error('sendTerm: 需要 text 或 keys 至少一个');
+  }
+  if (hasText) {
+    execSync(`${tmux} send-keys -t "${session}" -l ${JSON.stringify(text)}`, EXEC_OPTS);
+    // 自动 Enter：仅 text-only 且未抑制时。混发按键 = 手动模式，不惊喜回车。
+    if (!noEnter && !hasKeys) {
+      execSync(`${tmux} send-keys -t "${session}" Enter`, EXEC_OPTS);
+    }
+  }
+  for (const k of (hasKeys ? keys : [])) {
+    execSync(`${tmux} send-keys -t "${session}" ${JSON.stringify(k)}`, EXEC_OPTS);
+  }
+}
+
+/**
+ * 新建 tmux 会话并在里面起东西。会话名带 kind 前缀（cc-/codex-/sh-）。
+ * 会话先跑 bash，再 send 启动命令进去——这样程序退出后 bash 还在、
+ * 会话不死，restart 能在原会话里重起。
+ */
+function startTerm({ kind, cmd, session, dir, socketPath } = {}) {
+  const tmux = tmuxCmd(socketPath);
+  if (!kind || !(kind in KIND_CMD)) {
+    throw new Error(`startTerm: --kind 必须是 ${Object.keys(KIND_CMD).join('|')}`);
+  }
+  if (dir && !existsSync(dir)) throw new Error(`dir not found: ${dir}`);
+  const base = session || (dir ? basename(dir) : null);
+  if (!base) throw new Error('startTerm: 需要 --session 或 --dir');
+  const sessionName = `${KIND_PREFIX[kind]}-${base}`;
   try {
-    execSync(`${tmux} has-session -t "${session}" 2>/dev/null`, EXEC_OPTS);
-    throw new Error(`session "${session}" already exists`);
+    execSync(`${tmux} has-session -t "${sessionName}" 2>/dev/null`, EXEC_OPTS);
+    throw new Error(`session "${sessionName}" already exists`);
   } catch (e) {
     if (e.message.includes('already exists')) throw e;
   }
-  execSync(
-    `${tmux} new-session -d -s "${session}" -c "${dir}" 'claude --dangerously-skip-permissions'`,
-    { ...EXEC_OPTS, timeout: 10000 }
-  );
-}
-
-function sleep(ms) {
-  return new Promise((r) => setTimeout(r, ms));
+  const cwdArg = dir ? `-c "${dir}"` : '';
+  execSync(`${tmux} new-session -d -s "${sessionName}" ${cwdArg}`.trim(), { ...EXEC_OPTS, timeout: 10000 });
+  // kind=shell 且无 --cmd：new-session 本身就是 bash，不必再 send。
+  const startCmd = cmd || KIND_CMD[kind];
+  if (cmd || kind !== 'shell') {
+    execSync(`${tmux} send-keys -t "${sessionName}" -l ${JSON.stringify(startCmd)}`, EXEC_OPTS);
+    execSync(`${tmux} send-keys -t "${sessionName}" Enter`, EXEC_OPTS);
+  }
+  return { session: sessionName, kind, cmd: startCmd };
 }
 
 /**
- * 给 CC 发 /exit 然后重启（带 --continue）。
- * guardian 升级后自动重启 CC 用这个。
- *
- * 不再固定等 3s——有 Stop hook（auto-save / semantic_memory）的 AI 退出要
- * 60-90s，3s 时旧 claude 还活着，重启命令会被当成旧 TUI 的 queued message，
- * CC 永远没重启。改成轮询 isCCRunning 确认状态再动作。
+ * restart 通用骨架：停 → 轮询确认停了 → 起 → 轮询确认起了 → 失败 C-c 重试一次。
+ * 0.17.1 的「别在状态真变之前动作」教训对所有 kind 通用——差别只在「怎么停」。
  */
-async function restartCC(session, { socketPath, continueSession = true } = {}) {
+async function restartSkeleton(session, socketPath, { targetKind, stopAction, downTimeout, startCmd }) {
   const tmux = tmuxCmd(socketPath);
-  const restartCmd = continueSession
-    ? 'claude --dangerously-skip-permissions --continue'
-    : 'claude --dangerously-skip-permissions';
-
-  // 1. 发 /exit
-  execSync(`${tmux} send-keys -t "${session}" -l '/exit'`, EXEC_OPTS);
-  execSync(`${tmux} send-keys -t "${session}" Enter`, EXEC_OPTS);
-
-  // 2. 轮询直到 CC 退出（120s 覆盖 90s Stop hook + 余量）
-  const exitDeadline = Date.now() + 120000;
-  while (isCCRunning(session, socketPath)) {
-    if (Date.now() >= exitDeadline) {
-      // 旧 CC 还没退，发重启命令会变成 queued message 污染 TUI——放弃
-      return false;
-    }
+  stopAction();
+  // poll-down：轮询直到 kind 不再是 targetKind
+  const downDeadline = Date.now() + downTimeout;
+  while (detectKind(session, socketPath) === targetKind) {
+    if (Date.now() >= downDeadline) return false;
     await sleep(1000);
   }
-
-  // 3. 退出确认后等 shell prompt 落定
-  await sleep(500);
-
-  // 4-5. 发重启命令 + 轮询确认 CC 起来（30s 超时）
+  await sleep(500); // 等 shell prompt 落定
+  // 起 + poll-up（30s）
   const tryStart = async () => {
     try {
-      execSync(`${tmux} send-keys -t "${session}" -l ${JSON.stringify(restartCmd)}`, EXEC_OPTS);
+      execSync(`${tmux} send-keys -t "${session}" -l ${JSON.stringify(startCmd)}`, EXEC_OPTS);
       execSync(`${tmux} send-keys -t "${session}" Enter`, EXEC_OPTS);
     } catch {
       return false;
     }
     const upDeadline = Date.now() + 30000;
-    while (!isCCRunning(session, socketPath)) {
+    while (detectKind(session, socketPath) !== targetKind) {
       if (Date.now() >= upDeadline) return false;
       await sleep(1000);
     }
     return true;
   };
-
   if (await tryStart()) return true;
-
-  // 6. 超时没起来：C-c 清掉可能的半行，重试一次
-  try {
-    execSync(`${tmux} send-keys -t "${session}" C-c`, EXEC_OPTS);
-  } catch {}
+  // 没起来：C-c 清掉可能的半行，重试一次
+  try { execSync(`${tmux} send-keys -t "${session}" C-c`, EXEC_OPTS); } catch {}
   await sleep(500);
   return tryStart();
 }
 
-module.exports = { listSessions, isCCRunning, sendToCC, readOutput, startCC, restartCC, tmuxCmd };
+/**
+ * 重启 session 里跑的东西。只对 cc / codex 有意义——非 cc/codex（shell 或
+ * 自定义命令）直接报错，不静默重启成 bash。
+ *
+ * cc：优雅 /exit（跑 Stop hook，120s 超时覆盖 auto-save/semantic_memory）。
+ * codex：kill 进程（30s 短超时）。两者都轮询确认停了再起。
+ */
+async function restartTerm(session, { socketPath, continueSession = true } = {}) {
+  const tmux = tmuxCmd(socketPath);
+  const kind = detectKind(session, socketPath);
+  if (kind !== 'cc' && kind !== 'codex') {
+    throw new Error(
+      `"${session}" 不是 cc/codex 会话（检测到 kind=${kind === null ? '会话不存在' : kind}），`
+      + 'restart 不知道该用什么命令重启它。要重起请用 `seam term start --kind ... --cmd "..."`。'
+    );
+  }
+  if (kind === 'cc') {
+    const startCmd = continueSession ? `${KIND_CMD.cc} --continue` : KIND_CMD.cc;
+    return restartSkeleton(session, socketPath, {
+      targetKind: 'cc',
+      // cc 必须优雅退：发 /exit 跑 Stop hook，kill 会丢 AI 记忆
+      stopAction: () => {
+        execSync(`${tmux} send-keys -t "${session}" -l '/exit'`, EXEC_OPTS);
+        execSync(`${tmux} send-keys -t "${session}" Enter`, EXEC_OPTS);
+      },
+      downTimeout: 120000,
+      startCmd,
+    });
+  }
+  // codex：kill pane 进程的子进程（codex），bash 留着，会话不死
+  return restartSkeleton(session, socketPath, {
+    targetKind: 'codex',
+    stopAction: () => {
+      try {
+        const panePid = execSync(
+          `${tmux} display-message -t "${session}" -p '#{pane_pid}'`, EXEC_OPTS
+        ).trim();
+        execSync(`pkill -TERM -P ${panePid} 2>/dev/null || true`, EXEC_OPTS);
+      } catch {}
+    },
+    downTimeout: 30000,
+    startCmd: KIND_CMD.codex,
+  });
+}
+
+/**
+ * 关掉整个终端（kill-session）。返回关之前检测到的 kind（供调用方判断是否
+ * 连带杀了 guardian）。
+ */
+function stopTerm(session, { socketPath } = {}) {
+  const tmux = tmuxCmd(socketPath);
+  const kind = detectKind(session, socketPath);
+  execSync(`${tmux} kill-session -t "${session}"`, EXEC_OPTS);
+  return { kind };
+}
+
+module.exports = {
+  tmuxCmd, detectKind, listTerms, readTerm, sendTerm,
+  startTerm, restartTerm, stopTerm, KIND_CMD,
+};

package/lib/upgrade-all.js

@@ -1,31 +1,43 @@
 /**
- * Host-tool 模式：对所有已注册的 SEAM_HOME 滚动升级 + 重启 guardian。
+ * Host-tool 模式：对所有已注册的 SEAM_HOME 跑完整 applyHomeUpgrade。
  *
  * 流程：
  * 1. 全局升 npm 包（仅一次）
  * 2. 读 ~/.shared/seam-registry/*.json（当前在跑的 guardian 列表）
- * 3. 每个 entry spawn 子进程 stop → start guardian
- *    （SEAM_HOME / SEAM_CC_SESSION / SEAM_CC_SOCKET 从 entry 取，
- *     避免 guardianStart 回退到 `tmux display-message` 抓错 attached client。）
+ * 3. 逐个 entry 跑完整 applyHomeUpgrade（version.json / patch settings /
+ *    syncChannelRules / patchClaudeMd / 剥 .mcp.json / 重启 guardian）。
+ *    顺序执行，每个 entry try/catch——一个 home 失败不中断其余。
+ * 4. 末尾报告 ok/fail 计数 + 每个 home 结果。
  *
  * 仅升级"当前在跑的 guardian"——目录还在但 guardian 没开的，跳过。
- * 想拉那些上来，下次自己 `seam-client guardian start` 即可，
- * 那时已是新版 npm 包。
- *
+ * 想拉那些上来，下次自己 `seam-client guardian start` 即可（已是新版包）。
  * 路人 CC（没装 seam-client / 没 register）天然不在 registry，不会被碰。
  */
 
+import { existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { execSync, spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
 import { readAll } from './registry.js';
+import { applyHomeUpgrade } from './upgrade.js';
 
-const __filename = fileURLToPath(import.meta.url);
-const CLI_PATH = join(dirname(__filename), '..', 'bin', 'cli.js');
+/**
+ * 检测某 home 是否还残留本地 node_modules/@seamnet/client。
+ * 只警告，不删——删本地包是单独的迁移决定，由人手动做。
+ */
+function checkLocalInstallResidue(seamHome) {
+  const localPkg = join(dirname(seamHome), 'node_modules', '@seamnet', 'client');
+  if (existsSync(localPkg)) {
+    console.log(
+      `    ⚠️  ${dirname(seamHome)} 仍有本地包 node_modules/@seamnet/client——`
+      + '全局迁移未完成，建议手动删除本地 node_modules/@seamnet/client'
+    );
+  }
+}
 
 export async function upgradeAll() {
   console.log('Seam — host-tool upgrade-all\n');
 
+  // 1. 全局升包（一次）
   console.log('1. npm install -g @seamnet/client@latest');
   try {
     execSync('npm install -g @seamnet/client@latest', { stdio: 'inherit' });
@@ -34,35 +46,37 @@ export async function upgradeAll() {
     process.exit(1);
   }
 
+  // 2. 读 registry
   const entries = readAll();
   if (entries.length === 0) {
     console.log('\n2. registry 为空——没有正在运行的 guardian，结束。');
     return;
   }
-  console.log(`\n2. registry 里 ${entries.length} 个活 guardian，逐个重启`);
+  console.log(`\n2. registry 里 ${entries.length} 个活 guardian，逐个跑完整升级`);
 
-  let okCount = 0;
+  // 3. 逐个 applyHomeUpgrade（一个失败不中断其余）
+  const results = [];
   for (const entry of entries) {
     const { userId, seam_home, tmux_session, tmux_socket } = entry;
-    console.log(`\n  → ${userId}  (home=${seam_home}, session=${tmux_session || '?'})`);
-
-    const env = {
-      ...process.env,
-      SEAM_HOME: seam_home,
-      SEAM_CC_SESSION: tmux_session || '',
-      SEAM_CC_SOCKET: tmux_socket || '',
-    };
-    const stopRes = spawnSync('node', [CLI_PATH, 'stop'], { env, stdio: 'inherit' });
-    if (stopRes.status !== 0) {
-      console.log('    stop 非零退出（继续）');
-    }
-    const startRes = spawnSync('node', [CLI_PATH, 'guardian', 'start'], { env, stdio: 'inherit' });
-    if (startRes.status !== 0) {
-      console.error(`    start 失败 (exit ${startRes.status})`);
-    } else {
-      okCount += 1;
+    console.log(`\n  → ${userId}  (home=${seam_home})`);
+    checkLocalInstallResidue(seam_home);
+    try {
+      await applyHomeUpgrade({
+        seamHome: seam_home,
+        ccSession: tmux_session,
+        ccSocket: tmux_socket,
+      });
+      results.push({ userId, ok: true });
+    } catch (e) {
+      console.error(`    FAILED: ${e.message}`);
+      results.push({ userId, ok: false, error: e.message });
     }
   }
 
-  console.log(`\nDone. ${okCount}/${entries.length} 个 guardian 已重启。`);
+  // 4. 报告
+  const okCount = results.filter((r) => r.ok).length;
+  console.log(`\nDone. ${okCount}/${results.length} 个 home 升级成功。`);
+  for (const r of results) {
+    console.log(`  ${r.ok ? 'ok  ' : 'FAIL'} ${r.userId}${r.ok ? '' : '  — ' + r.error}`);
+  }
 }

package/lib/upgrade.js

@@ -1,121 +1,182 @@
 /**
  * 升级已入网 AI 的 seam-client 配置。
  *
- * 做：
- * 1. npm install @seamnet/client@latest
- * 2. patch .claude/settings.json：SessionStart hook 命令（老包名 → bin 名）
- *    + 预授权 seam CLI（permissions.allow 加 Bash(seam *)）
- * 3. 重新 patchClaudeMd（确保引用 @.seam/contacts.json 等新增的）
- * 3b. 清理 .mcp.json 里的 seam-im 条目（MCP server 已废弃）
- * 4. 重启 guardian（新 detached 后台进程生效）
+ * applyHomeUpgrade({ seamHome, ccSession, ccSocket })
+ *   —— 对指定 home 做 per-home 升级：写 version.json、patch settings.json、
+ *      syncChannelRules、patchClaudeMd、剥 .mcp.json 的 seam-im、
+ *      置 pending_upgrade_restart、spawn 重启该 home 的 guardian。
+ *      不含 npm install——caller 先装好包。所有路径基于 seamHome 参数，
+ *      不碰 process.cwd()、不碰 paths.js 的 SEAM_DIR 常量。
  *
- * 不做：
- * - 不动 credentials.json / IDENTITY.md（那些是 AI 自己的）
- * - 不重新 register（用原有 userId）
+ * upgrade()  —— per-project 命令：本地 npm install + applyHomeUpgrade(当前 home)。
+ *
+ * 不做：不动 credentials.json / IDENTITY.md（AI 自己的），不重新 register。
  */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync, spawnSync } from 'node:child_process';
 import { SEAM_DIR } from './paths.js';
+import { resolveTmuxSocketPath } from './guardian.js';
 
-export async function upgrade() {
-  console.log('Seam — upgrading...\n');
+const CLI_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'cli.js');
 
-  // 1. 升包
-  console.log('1. npm install @seamnet/client@latest');
-  try {
-    execSync('npm install @seamnet/client@latest', { stdio: 'inherit' });
-  } catch (e) {
-    console.error(`  npm install failed: ${e.message}`);
-    process.exit(1);
-  }
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
 
-  // 1b. 更新 version.json
+/**
+ * 读 upgrade.js 模块自身相邻的 package.json 版本号。
+ * caller 跑完 npm install（local 或 global）后该文件已被覆盖成新版，
+ * 此处运行时读取即拿到新版本号——不依赖 cwd/node_modules（host-tool
+ * 模式下非当前 home 没有本地 node_modules）。
+ */
+function readOwnVersion() {
   try {
-    const newPkg = JSON.parse(readFileSync(join(process.cwd(), 'node_modules', '@seamnet', 'client', 'package.json'), 'utf8'));
-    const versionPath = join(SEAM_DIR, 'version.json');
-    writeFileSync(versionPath, JSON.stringify({ version: newPkg.version, upgradedAt: new Date().toISOString() }, null, 2));
-    console.log(`  version.json updated to ${newPkg.version}`);
-  } catch (e) {
-    console.error(`  version.json update failed (non-fatal): ${e.message}`);
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+  } catch {
+    return null;
   }
+}
 
-  // 2. patch settings.json hook
-  console.log('2. patching .claude/settings.json SessionStart hook');
-  const settingsPath = join(process.cwd(), '.claude', 'settings.json');
-  if (existsSync(settingsPath)) {
+/**
+ * 检测当前 tmux session/socket。SEAM_CC_SESSION env 优先，否则回退
+ * `tmux display-message`。回退只对"当前 home"成立——AI 在自己的终端里
+ * 跑 upgrade，display-message 解析到的就是它自己。跨 home 的 caller
+ * （upgrade-all）不用这个，改从 registry entry 取 session/socket。
+ */
+function detectCurrentSession() {
+  const ccSocket = resolveTmuxSocketPath() || '';
+  const tmux = ccSocket ? `tmux -S "${ccSocket}"` : 'tmux';
+  let ccSession = process.env.SEAM_CC_SESSION || '';
+  if (!ccSession) {
     try {
-      const s = JSON.parse(readFileSync(settingsPath, 'utf8'));
-      let changed = false;
-      const oldCmd = 'npx @seamnet/client autostart';
-      const newCmd = 'npx seam-client autostart';
-      for (const group of s.hooks?.SessionStart || []) {
-        for (const h of group.hooks || []) {
-          if (h.command === oldCmd) {
-            h.command = newCmd;
-            changed = true;
-          }
+      ccSession = execSync(`${tmux} display-message -p '#S'`, { encoding: 'utf8' }).trim();
+    } catch {}
+  }
+  return { ccSession, ccSocket };
+}
+
+function patchSettings(settingsPath) {
+  if (!existsSync(settingsPath)) {
+    console.log('    no .claude/settings.json, skip');
+    return;
+  }
+  try {
+    const s = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    let changed = false;
+    const oldCmd = 'npx @seamnet/client autostart';
+    const newCmd = 'npx seam-client autostart';
+    for (const group of s.hooks?.SessionStart || []) {
+      for (const h of group.hooks || []) {
+        if (h.command === oldCmd) {
+          h.command = newCmd;
+          changed = true;
         }
       }
-      // 预授权 seam CLI：老 AI 升级后用 `seam` 发消息的路径立刻可用
-      if (!s.permissions) s.permissions = {};
-      if (!Array.isArray(s.permissions.allow)) s.permissions.allow = [];
-      if (!s.permissions.allow.includes('Bash(seam *)')) {
-        s.permissions.allow.push('Bash(seam *)');
-        changed = true;
-      }
-      if (changed) {
-        writeFileSync(settingsPath, JSON.stringify(s, null, 2));
-        console.log('  settings.json patched (hook command + seam CLI 预授权 Bash(seam *))');
-      } else {
-        console.log('  settings.json already up-to-date, skip');
-      }
-    } catch (e) {
-      console.error(`  failed to patch settings.json: ${e.message}`);
     }
+    // 预授权 seam CLI：老 AI 升级后用 `seam` 发消息的路径立刻可用
+    if (!s.permissions) s.permissions = {};
+    if (!Array.isArray(s.permissions.allow)) s.permissions.allow = [];
+    if (!s.permissions.allow.includes('Bash(seam *)')) {
+      s.permissions.allow.push('Bash(seam *)');
+      changed = true;
+    }
+    if (changed) {
+      writeFileSync(settingsPath, JSON.stringify(s, null, 2));
+      console.log('    settings.json patched (hook command + seam CLI 预授权 Bash(seam *))');
+    } else {
+      console.log('    settings.json already up-to-date, skip');
+    }
+  } catch (e) {
+    console.error(`    failed to patch settings.json: ${e.message}`);
   }
+}
 
-  // 3. 刷新 CLAUDE.md 引用（contacts.json 等新增的）
-  console.log('3. refreshing CLAUDE.md references + CHANNEL_RULES.md');
+function cleanMcpJson(mcpPath) {
   try {
-    const { patchClaudeMd, syncChannelRules } = await import('./init.js');
-    syncChannelRules();
-    patchClaudeMd();
+    if (!existsSync(mcpPath)) {
+      console.log('    no .mcp.json, skip');
+      return;
+    }
+    const mcp = JSON.parse(readFileSync(mcpPath, 'utf8'));
+    if (mcp.mcpServers && Object.prototype.hasOwnProperty.call(mcp.mcpServers, 'seam-im')) {
+      delete mcp.mcpServers['seam-im'];
+      writeFileSync(mcpPath, JSON.stringify(mcp, null, 2));
+      console.log('    removed seam-im entry from .mcp.json');
+    } else {
+      console.log('    no seam-im entry, skip');
+    }
   } catch (e) {
-    console.error(`  refresh failed (non-fatal): ${e.message}`);
+    console.error(`    .mcp.json cleanup failed (non-fatal): ${e.message}`);
   }
+}
+
+/**
+ * 对指定 home 做 per-home 升级。不含 npm install。
+ *
+ * guardian 重启一律 spawn 子进程（带 SEAM_HOME/SEAM_CC_SESSION/SEAM_CC_SOCKET
+ * env）——不在进程内调 guardianStop/Start，那俩认死的 SEAM_DIR/PID_PATH，
+ * 对非当前 home 会操作错对象。
+ *
+ * @param {object}  o
+ * @param {string}  o.seamHome   绝对路径，<project>/.seam
+ * @param {string} [o.ccSession] 该 home 的 tmux session（此处不回退 display-message）
+ * @param {string} [o.ccSocket]  该 home 的 tmux socket
+ */
+export async function applyHomeUpgrade({ seamHome, ccSession, ccSocket }) {
+  if (!seamHome) throw new Error('applyHomeUpgrade: seamHome required');
+  const projectDir = dirname(seamHome);
 
-  // 3b. 清理 .mcp.json 里的 seam-im 条目（MCP server 0.18.0 已废弃，删它指向的
-  //     mcp-serve 已不存在——必须在 CC restart 之前剥掉，否则重启会加载到死引用）
-  console.log('3b. cleaning seam-im from .mcp.json');
+  // version.json
   try {
-    const mcpPath = join(process.cwd(), '.mcp.json');
-    if (existsSync(mcpPath)) {
-      const mcp = JSON.parse(readFileSync(mcpPath, 'utf8'));
-      if (mcp.mcpServers && Object.prototype.hasOwnProperty.call(mcp.mcpServers, 'seam-im')) {
-        delete mcp.mcpServers['seam-im'];
-        writeFileSync(mcpPath, JSON.stringify(mcp, null, 2));
-        console.log('  removed seam-im entry from .mcp.json');
-      } else {
-        console.log('  no seam-im entry, skip');
-      }
-    } else {
-      console.log('  no .mcp.json, skip');
+    const version = readOwnVersion();
+    if (version) {
+      writeFileSync(
+        join(seamHome, 'version.json'),
+        JSON.stringify({ version, upgradedAt: new Date().toISOString() }, null, 2)
+      );
+      console.log(`    version.json → ${version}`);
     }
   } catch (e) {
-    console.error(`  .mcp.json cleanup failed (non-fatal): ${e.message}`);
+    console.error(`    version.json update failed (non-fatal): ${e.message}`);
   }
 
-  // 4. 重启 guardian（让新代码生效）+ 标记需要自动重启 CC
-  console.log('4. restarting guardian + scheduling CC auto-restart');
+  // patch .claude/settings.json
+  patchSettings(join(projectDir, '.claude', 'settings.json'));
+
+  // 刷新 CHANNEL_RULES.md + CLAUDE.md 引用（显式传 home/projectDir）
   try {
-    const { guardianStop, guardianStart } = await import('./guardian.js');
-    await guardianStop();
-    await new Promise((r) => setTimeout(r, 1000));
+    const { syncChannelRules, patchClaudeMd } = await import('./init.js');
+    syncChannelRules(seamHome);
+    patchClaudeMd(projectDir);
+    console.log('    CHANNEL_RULES + CLAUDE.md refreshed');
+  } catch (e) {
+    console.error(`    CHANNEL_RULES/CLAUDE.md refresh failed (non-fatal): ${e.message}`);
+  }
+
+  // 剥 .mcp.json 的 seam-im（CC restart 前剥掉指向已删 mcp-serve 的死引用）
+  cleanMcpJson(join(projectDir, '.mcp.json'));
 
-    // 打 pending_upgrade_restart 标记——新 guardian 启动时会读到并自动重启 CC
-    const statePath = join(SEAM_DIR, 'state.json');
+  // 重启 guardian：spawn 子进程 stop → 置 flag → start
+  const env = {
+    ...process.env,
+    SEAM_HOME: seamHome,
+    SEAM_CC_SESSION: ccSession || '',
+    SEAM_CC_SOCKET: ccSocket || '',
+  };
+  const stopRes = spawnSync(process.execPath, [CLI_PATH, 'stop'], { env, stdio: 'inherit' });
+  if (stopRes.status !== 0) {
+    // stop 非 0 不致命——guardian 可能本来就没在跑
+    console.log(`    guardian stop exited ${stopRes.status}（可能本来没跑，继续）`);
+  }
+  await sleep(1000);
+
+  // 置 pending_upgrade_restart——新 guardian 启动时读到会自动重启 CC
+  try {
+    const statePath = join(seamHome, 'state.json');
     let stateJson = {};
     if (existsSync(statePath)) {
       try { stateJson = JSON.parse(readFileSync(statePath, 'utf8')); } catch {}
@@ -123,10 +184,36 @@ export async function upgrade() {
     if (!stateJson.guardian) stateJson.guardian = {};
     stateJson.guardian.pending_upgrade_restart = true;
     writeFileSync(statePath, JSON.stringify(stateJson, null, 2));
+  } catch (e) {
+    console.error(`    state.json flag failed (non-fatal): ${e.message}`);
+  }
+
+  const startRes = spawnSync(process.execPath, [CLI_PATH, 'guardian', 'start'], { env, stdio: 'inherit' });
+  if (startRes.status !== 0) {
+    throw new Error(`guardian start failed (exit ${startRes.status})`);
+  }
+  console.log('    guardian restarted');
+}
+
+export async function upgrade() {
+  console.log('Seam — upgrading...\n');
+
+  // 1. 本地升包
+  console.log('1. npm install @seamnet/client@latest');
+  try {
+    execSync('npm install @seamnet/client@latest', { stdio: 'inherit' });
+  } catch (e) {
+    console.error(`  npm install failed: ${e.message}`);
+    process.exit(1);
+  }
 
-    await guardianStart();
+  // 2. 对当前 home 跑 applyHomeUpgrade（session 走 display-message 检测）
+  console.log('2. applying per-home upgrade');
+  const { ccSession, ccSocket } = detectCurrentSession();
+  try {
+    await applyHomeUpgrade({ seamHome: SEAM_DIR, ccSession, ccSocket });
   } catch (e) {
-    console.error(`  guardian restart failed: ${e.message}`);
+    console.error(`  upgrade failed: ${e.message}`);
     console.log('\n  请手动 /exit 并重新启动 Claude Code。');
     return;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamnet/client",
-  "version": "0.18.2",
+  "version": "0.20.0",
   "description": "One command to join Seam — the network where people and AI stay in sync.",
   "bin": {
     "seam-client": "bin/cli.js",