c0de-agent 1.5.0 → 1.6.0

package/dist/server/routes/terminal.js

@@ -17,8 +17,9 @@ function createTerminalRoute(ctx) {
         const rows = Number.isFinite(body.rows) ? Number(body.rows) : undefined;
         const title = typeof body.title === 'string' ? body.title : undefined;
         const shell = typeof body.shell === 'string' && body.shell.length > 0 ? body.shell : undefined;
+        const projectId = typeof body.projectId === 'string' && body.projectId.length > 0 ? body.projectId : undefined;
         try {
-            const info = mgr.create({ cwd, cols, rows, title, shell });
+            const info = mgr.create({ cwd, cols, rows, title, shell, projectId });
             return c.json(info, 201);
         }
         catch (err) {

package/dist/server/routes/todo.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import type { ServerContext } from '../types.js';
+declare function createTodoRoute(ctx: ServerContext): Hono;
+export { createTodoRoute };

package/dist/server/routes/todo.js

@@ -0,0 +1,107 @@
+// src/server/routes/todo.ts
+import { Hono } from 'hono';
+import { getMessages, appendMessage } from '../../session/message.js';
+import { getSession } from '../../session/session.js';
+import { generateId } from '../../shared/index.js';
+import { todoTool, getLatestTodoPhasesFromMessages } from '../../tools/builtin/todo.js';
+import { apiError } from '../middleware/error.js';
+/** 构造仅供 todo tool execute 使用的最小 ToolContext。 */
+function makeTodoCtx(phases, abort) {
+    let state = phases;
+    return {
+        cwd: '/',
+        session: { id: '', cwd: '/' },
+        abort,
+        todoState: {
+            get: () => state,
+            set: (p) => {
+                state = p;
+            },
+        },
+    };
+}
+function createTodoRoute(ctx) {
+    const app = new Hono();
+    // GET /:sessionId — 获取当前 todo 状态
+    app.get('/:sessionId', async (c) => {
+        const sessionId = c.req.param('sessionId');
+        const run = ctx.agentManager.get(sessionId);
+        let phases;
+        if (run) {
+            // 活跃 agent：直接从内存状态读取
+            phases = run.state.todoPhases;
+        }
+        else {
+            // 无活跃 agent：从历史消息恢复
+            const messages = await getMessages(ctx.db, sessionId);
+            phases = getLatestTodoPhasesFromMessages(messages);
+        }
+        return c.json({ phases });
+    });
+    // POST /:sessionId — 执行一个 todo 操作（UI 手动操作入口）
+    app.post('/:sessionId', async (c) => {
+        const sessionId = c.req.param('sessionId');
+        const body = await c.req.json().catch(() => ({}));
+        // 校验 session 存在
+        const session = await getSession(ctx.db, sessionId);
+        if (!session) {
+            return apiError(c, 404, 'NOT_FOUND', 'Session not found');
+        }
+        // 恢复当前 phases
+        const run = ctx.agentManager.get(sessionId);
+        let currentPhases;
+        if (run) {
+            currentPhases = run.state.todoPhases;
+        }
+        else {
+            const messages = await getMessages(ctx.db, sessionId);
+            currentPhases = getLatestTodoPhasesFromMessages(messages);
+        }
+        // 执行 todo 操作
+        const todoCtx = makeTodoCtx(currentPhases, c.req.raw.signal);
+        const result = await todoTool.execute(body, todoCtx);
+        // 从 todoState 读取操作后的 phases
+        const updatedPhases = todoCtx.todoState.get();
+        // 如果操作成功且 phases 有变化，持久化为 tool 消息
+        if (result._tag === 'success' && body.op !== 'view') {
+            // 构造 tool_result 消息内容
+            const toolResultContent = {
+                _tag: 'tool_result',
+                id: generateId(),
+                tool: 'todo',
+                output: {
+                    _tag: 'success',
+                    output: result.output,
+                    metadata: result.metadata,
+                },
+            };
+            const toolCallContent = {
+                _tag: 'tool_call',
+                id: generateId(),
+                tool: 'todo',
+                input: body,
+            };
+            // 存储为一条 tool 消息（tool_call + tool_result 合并）
+            await appendMessage(ctx.db, sessionId, {
+                role: 'tool',
+                content: [toolCallContent, toolResultContent],
+            });
+            // 更新活跃 agent 的内存状态
+            if (run) {
+                run.state.todoPhases = updatedPhases;
+            }
+        }
+        return c.json({
+            phases: updatedPhases,
+            output: result._tag === 'success'
+                ? result.output
+                : result._tag === 'error'
+                    ? result.error
+                    : result._tag === 'permission_required'
+                        ? result.reason
+                        : 'truncated',
+        });
+    });
+    return app;
+}
+export { createTodoRoute };

package/dist/server/routes/workflows.js

@@ -4,20 +4,37 @@ import { streamSSE } from 'hono/streaming';
 import { createAgent } from '../../core/agent.js';
 import { executeWorkflow } from '../../core/workflows/runtime.js';
 import { reloadRegistry } from '../../core/workflows/registry.js';
-import { saveWorkflow } from '../../core/workflows/discovery.js';
+import { discoverWorkflows, saveWorkflow } from '../../core/workflows/discovery.js';
+import { getProject } from '../../project/project.js';
 import { createSession } from '../../session/session.js';
 import { autoAllowChecker } from '../../tools/permission.js';
 import { apiError } from '../middleware/error.js';
 /** 创建工作流 REST API 路由。 */
 function createWorkflowsRoute(ctx) {
     const app = new Hono();
-    // GET / — 列出所有工作流
-    app.get('/', (c) => {
+    // GET / — 列出所有工作流。可选 ?projectId=xxx 合并项目级 .c0de/workflows/*.js。
+    app.get('/', async (c) => {
         const registry = ctx.workflowRegistry;
         if (!registry) {
             return c.json({ workflows: [] });
         }
-        const workflows = registry.list().map((entry) => ({
+        // 注册表已有 builtin + global + server-cwd；以 name 为 key 去重。
+        const byName = new Map();
+        for (const entry of registry.list()) {
+            byName.set(entry.meta.name, entry);
+        }
+        // 项目级工作流：从 project.worktree/.c0de/workflows/ 动态发现，同名覆盖。
+        const projectId = c.req.query('projectId');
+        if (projectId) {
+            const project = await getProject(ctx.db, projectId);
+            if (project) {
+                const projectWorkflows = await discoverWorkflows(project.worktree);
+                for (const wf of projectWorkflows) {
+                    byName.set(wf.meta.name, wf);
+                }
+            }
+        }
+        const workflows = Array.from(byName.values()).map((entry) => ({
             name: entry.meta.name,
             description: entry.meta.description,
             argsHint: entry.meta.argsHint,
@@ -57,14 +74,25 @@ function createWorkflowsRoute(ctx) {
             source: entry?.source ?? 'project',
         });
     });
-    // GET /:name — 元数据 + 源码
-    app.get('/:name', (c) => {
+    // GET /:name — 元数据 + 源码。可选 ?projectId=xxx 查找项目级工作流。
+    app.get('/:name', async (c) => {
         const name = c.req.param('name');
         const registry = ctx.workflowRegistry;
         if (!registry) {
             return apiError(c, 500, 'NOT_INITIALIZED', 'Workflow registry not initialized');
         }
-        const entry = registry.get(name);
+        let entry = registry.get(name);
+        // 项目级 fallback
+        if (!entry) {
+            const projectId = c.req.query('projectId');
+            if (projectId) {
+                const project = await getProject(ctx.db, projectId);
+                if (project) {
+                    const discovered = await discoverWorkflows(project.worktree);
+                    entry = discovered.find((w) => w.meta.name === name);
+                }
+            }
+        }
         if (!entry) {
             return apiError(c, 404, 'NOT_FOUND', `Workflow "${name}" not found`);
         }
@@ -77,14 +105,25 @@ function createWorkflowsRoute(ctx) {
             sourceCode: entry.sourceCode,
         });
     });
-    // POST /:name/run — 执行工作流（SSE 推送进度）
+    // POST /:name/run — 执行工作流（SSE 推送进度）。可选 ?projectId=xxx 执行项目级工作流。
     app.post('/:name/run', async (c) => {
         const name = c.req.param('name');
         const registry = ctx.workflowRegistry;
         if (!registry) {
             return apiError(c, 500, 'NOT_INITIALIZED', 'Workflow registry not initialized');
         }
-        const entry = registry.get(name);
+        let entry = registry.get(name);
+        // 项目级 fallback + 解析项目 worktree 作为 agent cwd
+        let agentCwd = ctx.cwd;
+        const projectId = c.req.query('projectId');
+        if (!entry && projectId) {
+            const project = await getProject(ctx.db, projectId);
+            if (project) {
+                agentCwd = project.worktree;
+                const discovered = await discoverWorkflows(project.worktree);
+                entry = discovered.find((w) => w.meta.name === name);
+            }
+        }
         if (!entry) {
             return apiError(c, 404, 'NOT_FOUND', `Workflow "${name}" not found`);
         }
@@ -104,7 +143,7 @@ function createWorkflowsRoute(ctx) {
             toolRegistry: ctx.toolRegistry,
             permission: autoAllowChecker,
             config: ctx.config,
-            cwd: ctx.cwd,
+            cwd: agentCwd,
             agentRegistry: ctx.agentRegistry,
         });
         return streamSSE(c, async (stream) => {
@@ -114,13 +153,14 @@ function createWorkflowsRoute(ctx) {
                 toolRegistry: ctx.toolRegistry,
                 permission: autoAllowChecker,
                 config: ctx.config,
-                cwd: ctx.cwd,
+                cwd: agentCwd,
                 agentRegistry: ctx.agentRegistry,
             };
             try {
                 const result = await executeWorkflow({
                     registry,
                     name,
+                    entry,
                     args,
                     deps,
                     parent,

package/dist/server/server.d.ts

@@ -36,6 +36,11 @@ declare function buildRegistryFromConfig(config: Config): Registry;
  * 使运行中的 ServerContext 立即生效，无需重启。
  */
 declare function syncRegistryFromConfig(registry: Registry, config: Config): void;
+/** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则全局数据根下 pglite 子目录。
+ *
+ * 历史上数据库放在 <cwd>/.c0de/pglite（项目级），但项目 DB schema 通过 projectId
+ * 区分项目，设计本意是全局共享单库。旧路径已在 migrateLegacyPglite 中自动迁移。 */
+declare function resolveDbDir(): string;
 /**
  * 围绕已有 DB handle 组装 ServerContext（不建/不关闭 DB）。
  *
@@ -47,10 +52,12 @@ declare function buildServerContext(db: DB, opts?: StartServerOptions): Promise<
     ctx: ServerContext;
     dispose: () => Promise<void>;
 }>;
+/** Release the dev DB lock (best-effort, stale-detection covers missed calls). */
+declare function releaseDevDbLock(dataDir: string): void;
 /** dev 专用：创建 + migrate PGLite，跨热重载复用（单写者，只建一次）。 */
 declare function createDevDb(cwd: string): Promise<DB>;
 /** 初始化 DB + 配置 + 注册表，返回 ServerContext + 清理函数（dev 与独立后端共用）。 */
 declare function bootstrapServerContext(opts?: StartServerOptions): Promise<BootstrappedServer>;
 declare function startServer(opts?: StartServerOptions): Promise<RunningServer>;
 export type { BootstrappedServer, RunningServer, StartServerOptions };
-export { bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, startServer, syncRegistryFromConfig, };
+export { bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveDbDir, startServer, syncRegistryFromConfig, };

package/dist/server/server.js

@@ -1,13 +1,14 @@
 // src/server/server.ts
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
 import { connect as tcpConnect } from 'node:net';
-import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { serve } from '@hono/node-server';
 import { WebSocketServer } from 'ws';
 import { BUILTIN_AGENTS, createAgentRegistry } from '../core/agents/index.js';
 import { loadConfig } from '../core/config.js';
 import { decryptSecret } from '../core/secret.js';
-import { BUILTIN_WORKFLOWS, createWorkflowRegistry } from '../core/workflows/index.js';
+import { createAndPopulateRegistry } from '../core/workflows/index.js';
 import { createDB, migrateDB } from '../db/index.js';
 import { createRegistry, overrideToCapabilities, registerProvider, } from '../llm/registry.js';
 import { initPlugins } from '../plugins/index.js';
@@ -53,12 +54,53 @@ function syncRegistryFromConfig(registry, config) {
         registerProviderFromConfig(registry, p);
     }
 }
-/** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则 <cwd>/.c0de/pglite。 */
-function resolveDbDir(cwd) {
+/** 全局数据根目录：XDG_DATA_HOME 优先，否则 ~/.local/share/c0de。
+ * 与 opencode (~/.local/share/opencode/)、oh-my-pi (~/.omp/agent/) 同约定——
+ * 数据库等运行时数据放全局，项目 .c0de/ 只留配置和扩展。 */
+function resolveGlobalDataRoot() {
+    const xdg = process.env.XDG_DATA_HOME;
+    if (xdg && xdg.trim() !== '')
+        return join(xdg, 'c0de');
+    return join(homedir(), '.local', 'share', 'c0de');
+}
+/** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则全局数据根下 pglite 子目录。
+ *
+ * 历史上数据库放在 <cwd>/.c0de/pglite（项目级），但项目 DB schema 通过 projectId
+ * 区分项目，设计本意是全局共享单库。旧路径已在 migrateLegacyPglite 中自动迁移。 */
+function resolveDbDir() {
     const envDir = process.env.C0DE_DB_DIR;
     if (envDir && envDir.trim() !== '')
         return envDir;
-    return join(cwd, '.c0de', 'pglite');
+    return join(resolveGlobalDataRoot(), 'pglite');
+}
+/** 一次性迁移：<cwd>/.c0de/pglite → 全局路径。仅当目标不存在时执行。
+ *
+ * 多个项目各有 .c0de/pglite 时只迁移第一个遇到的（首次启动即触发）；
+ * 其余项目的旧数据保留在原地（已被 .gitignore 覆盖，不影响 git，但不再读取）。
+ * 用户可用 C0DE_DB_DIR 手动指向旧路径访问遗留数据。 */
+function migrateLegacyPglite(cwd, targetDir) {
+    const legacy = join(cwd, '.c0de', 'pglite');
+    if (!existsSync(legacy))
+        return;
+    if (existsSync(targetDir))
+        return; // 全局目录已有数据，不覆盖
+    const parent = dirname(targetDir);
+    if (!existsSync(parent))
+        mkdirSync(parent, { recursive: true });
+    try {
+        renameSync(legacy, targetDir);
+        return;
+    }
+    catch {
+        // 跨文件系统 rename 失败，fallback 到 copy
+    }
+    try {
+        cpSync(legacy, targetDir, { recursive: true });
+        rmSync(legacy, { recursive: true, force: true });
+    }
+    catch {
+        // 迁移失败：旧数据留在项目目录（已 gitignore，无害），用户可手动迁移
+    }
 }
 /**
  * 围绕已有 DB handle 组装 ServerContext（不建/不关闭 DB）。
@@ -83,8 +125,9 @@ async function buildServerContext(db, opts = {}) {
         toolRegistry,
         llmRegistry,
     });
-    // workflowRegistry 惰性初始化 backing field（见下方 ctx getter）。
-    let _workflowRegistry;
+    // 工作流注册表：三级发现（builtin → global → project），eager 初始化。
+    // 此前是惰性 getter 只注册 builtin，导致项目级 .c0de/workflows/*.js 永远不可见。
+    const workflowRegistry = await createAndPopulateRegistry(cwd);
     const ctx = {
         db,
         config,
@@ -103,16 +146,7 @@ async function buildServerContext(db, opts = {}) {
                 reg.register(def);
             return reg;
         })(),
-        // 工作流注册表：惰性初始化，只含内置（项目级 discovery 由 bootstrap 或 API 触发热加载）。
-        // 与 context.ts 的 createServerContext 保持一致的模式。
-        get workflowRegistry() {
-            if (!_workflowRegistry) {
-                _workflowRegistry = createWorkflowRegistry();
-                for (const wf of BUILTIN_WORKFLOWS)
-                    _workflowRegistry.register(wf);
-            }
-            return _workflowRegistry;
-        },
+        workflowRegistry,
         // spec §18.1 后台版本检查调度器；config.update.enabled 控制是否启动。
         updateScheduler: createUpdateScheduler({
             checkFn: opts.checkForUpdateFn ?? checkForUpdate,
@@ -149,18 +183,74 @@ async function buildServerContext(db, opts = {}) {
         },
     };
 }
+const DEV_LOCK_FILE = '.dev.lock';
+/**
+ * Cross-process guard for PGLite dataDir.
+ *
+ * PGLite is single-writer WASM Postgres — two processes on the same dataDir
+ * always abort (`RuntimeError: Aborted()`). This lock prevents silent
+ * corruption when multiple dev servers (e.g. different ports) target the
+ * same project.
+ *
+ * - Live PID in lock → throw clear error instead of cryptic WASM abort.
+ * - Dead PID in lock → stale: remove `.dev.lock` + `postmaster.pid`, proceed.
+ */
+function acquireDevDbLock(dataDir) {
+    const lockPath = join(dataDir, DEV_LOCK_FILE);
+    if (existsSync(lockPath)) {
+        const oldPid = parseInt(readFileSync(lockPath, 'utf8').trim(), 10);
+        let stale = false;
+        if (oldPid && oldPid !== process.pid) {
+            try {
+                process.kill(oldPid, 0); // signal 0 = liveness check
+            }
+            catch (err) {
+                // ESRCH = process dead → stale lock, fall through to cleanup.
+                // Any other error (EPERM etc.) re-throws — don't clobber a live lock.
+                if (err.code !== 'ESRCH')
+                    throw err;
+                stale = true;
+            }
+            if (!stale) {
+                throw new Error(`Database is locked by another c0de process (PID ${oldPid}).\n` +
+                    `PGLite is single-writer — only one process may use:\n  ${dataDir}\n` +
+                    `Kill the other process and retry:\n  kill ${oldPid}`);
+            }
+        }
+        // Stale lock cleanup
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* best-effort */ }
+        try {
+            unlinkSync(join(dataDir, 'postmaster.pid'));
+        }
+        catch { /* best-effort */ }
+    }
+    writeFileSync(lockPath, String(process.pid));
+}
+/** Release the dev DB lock (best-effort, stale-detection covers missed calls). */
+function releaseDevDbLock(dataDir) {
+    try {
+        unlinkSync(join(dataDir, DEV_LOCK_FILE));
+    }
+    catch { /* best-effort */ }
+}
 /** dev 专用：创建 + migrate PGLite，跨热重载复用（单写者，只建一次）。 */
 async function createDevDb(cwd) {
-    const dataDir = resolveDbDir(cwd);
+    const dataDir = resolveDbDir();
+    migrateLegacyPglite(cwd, dataDir);
     if (!existsSync(dataDir))
         mkdirSync(dataDir, { recursive: true });
+    acquireDevDbLock(dataDir);
     const db = await createDB({ driver: 'pglite', dataDir });
-    // migrateDB 失败必须 close，否则 WASM 实例泄漏锁住 dataDir。
+    // migrateDB 失败必须 close + release lock，否则 WASM 实例泄漏锁住 dataDir。
     try {
         await migrateDB(db);
     }
     catch (err) {
         await db.close().catch(() => { });
+        releaseDevDbLock(dataDir);
         throw err;
     }
     return db;
@@ -169,8 +259,8 @@ async function createDevDb(cwd) {
 async function bootstrapServerContext(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const ownsDb = !opts.db;
-    // 持久化 PGLite 数据：默认 <cwd>/.c0de/pglite（与 .c0de/cache、.c0de/config.json 同约定），
-    // 可用 C0DE_DB_DIR 覆盖。此前默认 in-memory，进程重启即丢全部会话/消息/调用详情。
+    // 持久化 PGLite 数据：全局路径 ~/.local/share/c0de/pglite（可用 C0DE_DB_DIR 覆盖）。
+    // 跨项目共享单库，通过 projects/sessions 表的 projectId 区分。
     // 测试注入 opts.db 时跳过（保持 in-memory 隔离）。
     let db;
     if (opts.db) {
@@ -282,4 +372,4 @@ async function startServer(opts = {}) {
     };
     return { app, port, close };
 }
-export { bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, startServer, syncRegistryFromConfig, };
+export { bootstrapServerContext, buildRegistryFromConfig, buildServerContext, createDevDb, releaseDevDbLock, resolveDbDir, startServer, syncRegistryFromConfig, };

package/dist/server/terminal/pty-manager.d.ts

@@ -9,6 +9,8 @@ export interface PTYInfo {
     cwd: string;
     /** shell 程序路径。 */
     shell: string;
+    /** 所属项目 id（未归属时为 undefined）。 */
+    projectId?: string;
 }
 export interface CreatePTYOptions {
     cwd: string;
@@ -17,7 +19,19 @@ export interface CreatePTYOptions {
     title?: string;
     /** 覆盖默认 shell；不传则自动检测。 */
     shell?: string;
+    /** 所属项目 id。 */
+    projectId?: string;
 }
+/**
+ * 检测当前平台默认 shell。
+ *
+ * 优先级：process.env.SHELL → os.userInfo().shell（/etc/passwd 登录 shell）→ /bin/bash。
+ * 仅依赖 process.env.SHELL 是不可靠的：当 server 经 npm 脚本（sh -c 包装）、
+ * 热更新重启或 IDE 启动器等链路启动时，SHELL 往往未被 export 到环境，
+ * 导致 node 进程读不到而错误回退到 /bin/bash。userInfo().shell 直接读取
+ * /etc/passwd（getpwuid），是用户真实登录 shell 的可靠来源。
+ */
+export declare function detectShell(): string;
 /**
  * PTY 生命周期管理器。
  *

package/dist/server/terminal/pty-manager.js

@@ -1,16 +1,94 @@
 // src/server/terminal/pty-manager.ts
-import { spawn } from 'node-pty';
 import { randomUUID } from 'node:crypto';
-/** 检测当前平台默认 shell。 */
-function detectShell() {
+import { mkdirSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir, userInfo } from 'node:os';
+import { basename, join } from 'node:path';
+import { spawn } from 'node-pty';
+/**
+ * 为指定 shell 创建 OSC 133 prompt 标记注入脚本。
+ *
+ * shell 在每次显示 prompt 前发送 \x1b]133;A\x07（OSC 133;A），
+ * 前端 xterm.js parser 捕获后精确记录命令块起始行。
+ * 标记嵌入 PTY 输出流 → scrollback 回放时自动重建，无需正则猜测。
+ *
+ * 支持的 shell：bash（--init-file）、zsh（ZDOTDIR）。
+ * 其他 shell 不注入，退化到前端正则启发式。
+ */
+function setupShellIntegration(shell) {
+    const base = basename(shell);
+    // printf 的 \x1b / \x07 由 shell 自行解释，JS 中双反斜杠确保写入字面量
+    const mark = "printf '\\x1b]133;A\\x07'";
+    if (base === 'bash') {
+        const script = join(tmpdir(), `c0de-bash-${randomUUID()}.sh`);
+        writeFileSync(script, [
+            '[ -f /etc/bash.bashrc ] && source /etc/bash.bashrc',
+            '[ -f ~/.bashrc ] && source ~/.bashrc',
+            `__c0de_prompt_mark() { ${mark}; }`,
+            // 追加到已有 PROMPT_COMMAND 而非覆盖
+            'if [ -n "$PROMPT_COMMAND" ]; then',
+            '  PROMPT_COMMAND=\'__c0de_prompt_mark;\'"$PROMPT_COMMAND"',
+            'else',
+            '  PROMPT_COMMAND=__c0de_prompt_mark',
+            'fi',
+        ].join('\n'));
+        return {
+            spawnArgs: ['--init-file', script],
+            env: {},
+            cleanup: () => {
+                try {
+                    unlinkSync(script);
+                }
+                catch {
+                    // 文件可能已被清理
+                }
+            },
+        };
+    }
+    if (base === 'zsh') {
+        const dir = join(tmpdir(), `c0de-zsh-${randomUUID()}`);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, '.zshrc'), [
+            '[ -f ~/.zshrc ] && source ~/.zshrc',
+            `__c0de_prompt_mark() { ${mark}; }`,
+            'autoload -Uz add-zsh-hook',
+            'add-zsh-hook precmd __c0de_prompt_mark',
+        ].join('\n'));
+        return {
+            spawnArgs: [],
+            env: { ZDOTDIR: dir },
+            cleanup: () => {
+                try {
+                    rmSync(dir, { recursive: true });
+                }
+                catch {
+                    // 目录可能已被清理
+                }
+            },
+        };
+    }
+    // fish / 其他 shell 暂不支持，退化到前端正则
+    return { spawnArgs: [], env: {}, cleanup: () => { } };
+}
+/**
+ * 检测当前平台默认 shell。
+ *
+ * 优先级：process.env.SHELL → os.userInfo().shell（/etc/passwd 登录 shell）→ /bin/bash。
+ * 仅依赖 process.env.SHELL 是不可靠的：当 server 经 npm 脚本（sh -c 包装）、
+ * 热更新重启或 IDE 启动器等链路启动时，SHELL 往往未被 export 到环境，
+ * 导致 node 进程读不到而错误回退到 /bin/bash。userInfo().shell 直接读取
+ * /etc/passwd（getpwuid），是用户真实登录 shell 的可靠来源。
+ */
+export function detectShell() {
     if (process.platform === 'win32') {
         return process.env.COMSPEC ?? 'cmd.exe';
     }
-    return process.env.SHELL ?? '/bin/bash';
+    return process.env.SHELL ?? userInfo().shell ?? '/bin/bash';
 }
 const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
 const MAX_TITLE_LEN = 100;
+/** scrollback 环形缓冲最大字节数（约 50KB）。 */
+const SCROLLBACK_MAX = 50_000;
 function truncateTitle(title) {
     const clean = title.replace(/[\r\n]/g, ' ').trim();
     return clean.length > MAX_TITLE_LEN ? `${clean.slice(0, MAX_TITLE_LEN)}…` : clean;
@@ -30,13 +108,15 @@ export class PTYManager {
         const cols = opts.cols ?? DEFAULT_COLS;
         const rows = opts.rows ?? DEFAULT_ROWS;
         const shell = opts.shell ?? detectShell();
-        const pty = spawn(shell, [], {
+        const integration = setupShellIntegration(shell);
+        const pty = spawn(shell, integration.spawnArgs, {
             name: 'xterm-256color',
             cols,
             rows,
             cwd: opts.cwd,
             env: {
                 ...process.env,
+                ...integration.env,
                 TERM: 'xterm-256color',
                 COLORTERM: 'truecolor',
             },
@@ -49,10 +129,21 @@ export class PTYManager {
             rows,
             cwd: opts.cwd,
             shell,
+            projectId: opts.projectId,
+        };
+        const entry = {
+            pty,
+            info,
+            sockets: new Set(),
+            scrollback: '',
+            integrationCleanup: integration.cleanup,
         };
-        const entry = { pty, info, sockets: new Set() };
-        // PTY 输出 → 广播到所有挂载的 WebSocket
+        // PTY 输出 → 广播到所有挂载的 WebSocket + 追加 scrollback
         pty.onData((data) => {
+            entry.scrollback += data;
+            if (entry.scrollback.length > SCROLLBACK_MAX) {
+                entry.scrollback = entry.scrollback.slice(-SCROLLBACK_MAX);
+            }
             for (const ws of entry.sockets) {
                 if (ws.readyState === ws.OPEN) {
                     ws.send(data);
@@ -113,6 +204,7 @@ export class PTYManager {
         catch {
             // 进程可能已退出
         }
+        entry.integrationCleanup?.();
         this.entries.delete(id);
     }
     /** 获取 PTY 信息。 */
@@ -134,6 +226,12 @@ export class PTYManager {
         if (!entry)
             return false;
         entry.sockets.add(ws);
+        // 先回放 scrollback，让前端恢复终端历史画面。
+        // 先 add 再 send 避免漏数据：add 之后 onData 的新输出会广播到此 WS，
+        // 而 scrollback 覆盖 add 之前的所有历史输出。Node 单线程保证无竞态。
+        if (entry.scrollback) {
+            ws.send(entry.scrollback);
+        }
         ws.on('message', (data) => {
             const text = typeof data === 'string' ? data : data.toString('utf8');
             try {