@tencent-ai/agent-harness 0.2.0-beta.7 → 0.2.0-beta.8

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/daemon-channel-autoconnect.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Daemon Channel Auto-Connect — 自动连接已保存凭证的 channel 实例
+ *
+ * daemon 启动时：
+ * 1. 优先检查 CODEBUDDY_DAEMON_RESTORE_CHANNELS 环境变量（restart 恢复）
+ * 2. 否则扫描 ~/.codebuddy/channels/ 下的 instances.json，自动连接有凭证的实例
+ *
+ * 开关优先级（从高到低）：
+ * 1. 环境变量 CODEBUDDY_DAEMON_AUTO_CONNECT_CHANNELS=0/false → 全局禁用
+ * 2. settings.json daemonAutoConnectChannels: false → 全局禁用
+ * 3. 实例级别 autoConnect: false → 跳过该实例
+ * 4. 默认 → 自动连接
+ */
+import { type IDaemonChannelAutoConnect } from './daemon-protocol.js';
+export declare class DaemonChannelAutoConnectImpl implements IDaemonChannelAutoConnect {
+    private readonly logger;
+    private readonly remoteControlService?;
+    private readonly clientRegistry?;
+    private readonly settingsManager?;
+    connectSavedChannels(): Promise<void>;
+    restoreChannels(channelIds: string[]): Promise<void>;
+    getConnectedChannelIds(): string[];
+    /**
+     * 检查全局开关是否禁用了自动连接。
+     * 优先级：环境变量 > settings
+     */
+    private isGloballyDisabled;
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/daemon-enhancements-lifecycle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Daemon Enhancements Lifecycle
+ *
+ * 在 daemon 模式（ENV_SESSION_KIND=daemon）下自动启动增强功能：
+ * 1. WakeDetector — 防 idle sleep + 唤醒检测 → 重连所有长连接
+ * 2. DaemonAutoRestart — 更新安装后空闲自动重启
+ * 3. DaemonChannelAutoConnect — 自动连接已保存凭证的 channel 实例
+ *
+ * 生命周期:
+ *   - initialize: 检测 daemon 模式 → 延迟启动各模块（等待依赖就绪）
+ *   - onStop: 停止检测器和自动重启，清理订阅
+ */
+import { Application, ApplicationLifecycle } from '@celljs/core';
+export declare class DaemonEnhancementsLifecycle implements ApplicationLifecycle<Application> {
+    private logger?;
+    private wakeDetector?;
+    private autoRestart?;
+    private wakeSubscription?;
+    initialize(): void;
+    onStop(): Promise<void>;
+    private initAsync;
+    private startWakeDetector;
+    private startAutoRestart;
+    /**
+     * Daemon 启动时主动 "无人值守地" 走一遍完整 session 创建流程，让 webhook（微信/企微/HTTP runs）
+     * 一进来就能复用这个 primary session，无需等用户先打开 Web UI 创建对话。
+     *
+     * 关键：必须发真实的 `POST /internal/agent` 请求（body 不带 prompt），
+     * 而不是直接 `sessionManager.create()`。原因：
+     *   - 直接 create 只造一个对象，**不会触发** SessionMiddleware
+     *   - SessionMiddleware 是注入 cliRuntimeOptions / 触发 setCurrent / 启动 hooks /
+     *     初始化 ToolPermissionContext / 推送 sessionSubject 的统一入口
+     *   - sessionSubject.next 触发后，ServerModeStrategy 的 take(1) 监听才会调
+     *     `gatewayBridge.setPrimarySession(session)`，让后续 webhook 全部汇聚到此 session
+     *
+     * 等价于"daemon 自己代替无人值守的 Web UI 创建一个完整 session"。
+     */
+    private bootstrapPrimarySession;
+    private connectChannels;
+    /**
+     * 唤醒后重连所有长连接客户端。
+     * 等待 3 秒让网络栈恢复，然后逐个断开并重连。
+     */
+    private reconnectAllChannels;
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/daemon-process.d.ts

@@ -0,0 +1,77 @@
+import { type BgSessionOptions, type DaemonConfig, type IDaemonProcessManager } from './daemon-protocol.js';
+/**
+ * 子进程管理器 — fork detached 进程、信号处理、存活检测
+ *
+ * 负责 daemon supervisor 和后台会话的进程创建与管理。
+ * 所有 fork 出的子进程都是 detached 模式，父进程可以立即退出。
+ */
+export declare class DaemonProcessManagerImpl implements IDaemonProcessManager {
+    forkDaemon(config: DaemonConfig, extraEnv?: Record<string, string>): Promise<{
+        pid: number;
+        logPath: string;
+    }>;
+    /**
+     * 构造 daemon 子进程的 CLI 参数。抽离成独立方法是为了：
+     * 1) `forkDaemon` 主流程更清晰；
+     * 2) 单测可以直接覆盖参数装配规则（-y vs --permission-mode 优先级、startupArgs 回放等）
+     *    而无需 stub child_process.fork。
+     */
+    buildDaemonChildArgs(config: DaemonConfig): string[];
+    forkBgSession(args: string[], options: BgSessionOptions): Promise<{
+        pid: number;
+        logPath: string;
+    }>;
+    sendSignal(pid: number, signal: NodeJS.Signals): boolean;
+    isProcessRunning(pid: number): boolean;
+    waitForExit(pid: number, timeoutMs?: number): Promise<boolean>;
+    private getLogDir;
+    /**
+     * 确定 CLI 入口路径。
+     * 使用当前进程的启动脚本路径（process.argv[1]），确保 fork 出的子进程
+     * 使用和当前进程相同的入口文件，不受 __dirname 打包路径影响。
+     */
+    private getEntryPath;
+    /**
+     * 创建 detached 子进程的统一方法。
+     * stdout/stderr 重定向到日志文件，IPC 通道创建后立即断开。
+     *
+     * Bun SFE 下不能用 `fork()`：它无条件把「模块路径」塞进子进程 argv[1]
+     * （`fork(modulePath, args)` 等价于 `spawn(execPath, [modulePath, ...args])`），
+     * 而 Bun 编译出的可执行文件本身就是完整入口——那个「模块路径」在Bun SFE 下
+     * 是 `process.argv[1]` 的虚拟路径（`/$bunfs/root/<bin>`），被当成参数续传给
+     * 子进程后会落进 commander 的位置参数（`argv[2]` 起），子进程又把它当 CLI
+     * 入口重新拼进自己的 argv——递归下去 argv 逐代累积虚拟路径（对齐
+     * `PathUtils.buildRespawnArgs` 修复的同一类问题，issue #82398）。这里改用
+     * `spawn()` 手动带 `'ipc'` stdio（等价于 fork 的 IPC 语义），配合
+     * `PathUtils.buildRespawnArgs` 决定要不要把 entry 塞进 argv——本方法只调了
+     * `.unref()` + `.disconnect()`，从未用 `.send()`/`.on('message')`，
+     * 换成 `spawn` 不影响现有语义。
+     */
+    protected forkDetached(args: string[], opts: {
+        env: Record<string, string>;
+        logPath: string;
+        cwd: string;
+    }): Promise<{
+        pid: number;
+        logPath: string;
+    }>;
+    /**
+     * 从 args 中移除 --bg, --background, --name <value> 参数。
+     * 后台会话不需要这些标志 — 它们已经通过环境变量传递。
+     */
+    private filterBgArgs;
+    /** 确保 args 中包含指定参数（两个别名都检查） */
+    private ensureArg;
+    /**
+     * 判断 args 中是否已经传入了带值的 flag（同时支持 `--key value` 与 `--key=value` 两种形式）。
+     */
+    private hasFlagWithValue;
+    /**
+     * Extract inheritable CLI arguments from the parent process.
+     * Skips daemon-specific args and mode/lifecycle args that don't apply to the child.
+     *
+     * 公开为 public：`daemon-service` 在 `runAsSupervisor()` 时需要拿到这份"原始用户参数"
+     * 持久化到 PID 文件，供后续 `daemon restart` / auto-restart 还原。
+     */
+    getInheritableArgs(): string[];
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/daemon-protocol.d.ts

@@ -0,0 +1,324 @@
+/**
+ * Daemon 模块协议定义
+ *
+ * 遵循项目 protocol pattern：所有 DI Symbols 和 interface 定义在此文件中，
+ * 实现类在独立文件中 import 这些定义。
+ */
+import type { Subject } from 'rxjs';
+export declare const DaemonService: unique symbol;
+export declare const SessionRegistry: unique symbol;
+export declare const DaemonProcessManager: unique symbol;
+export declare const BgSessionHandler: unique symbol;
+export declare const WakeDetector: unique symbol;
+export declare const DaemonAutoRestart: unique symbol;
+export declare const DaemonChannelAutoConnect: unique symbol;
+export declare const SystemService: unique symbol;
+/** PID 文件名匹配模式：仅匹配 `<数字>.json` 和 `manual-<id>.json` 格式 */
+export declare const PID_FILE_PATTERN: RegExp;
+/** Worker 心跳间隔 (30s) */
+export declare const WORKER_HEARTBEAT_INTERVAL_MS = 30000;
+/** Worker 心跳超时 (2min) — 超时的手动 worker 视为已死 */
+export declare const WORKER_HEARTBEAT_TIMEOUT_MS: number;
+/** 后台会话管理子命令（BgSessionStrategy 匹配用） */
+export declare const BG_SESSION_COMMANDS: readonly ['ps', 'logs', 'attach', 'kill', 'stop', 'rm', 'respawn'];
+/** 不需要注册 PID 文件的短生命周期子命令 */
+export declare const SHORT_LIVED_COMMANDS: readonly ["ps", "logs", "attach", "kill", "stop", "rm", "respawn", "daemon", "project"];
+export declare const ENV_SESSION_KIND = "CODEBUDDY_SESSION_KIND";
+export declare const ENV_SESSION_NAME = "CODEBUDDY_SESSION_NAME";
+export declare const ENV_SESSION_LOG = "CODEBUDDY_SESSION_LOG";
+export declare const ENV_DAEMON_RESTORE_CHANNELS = "CODEBUDDY_DAEMON_RESTORE_CHANNELS";
+/** 设置为 '1' 或 'true' 禁用防休眠（允许系统正常进入 idle sleep） */
+export declare const ENV_DAEMON_ALLOW_SLEEP = "CODEBUDDY_DAEMON_ALLOW_SLEEP";
+/** 设置为 '0' 或 'false' 禁用 daemon 启动时自动连接 channel */
+export declare const ENV_DAEMON_AUTO_CONNECT_CHANNELS = "CODEBUDDY_DAEMON_AUTO_CONNECT_CHANNELS";
+/** daemon 启动时请求的原始端口；SERVER__PORT 在绑定后会被改写为实际端口 */
+export declare const ENV_DAEMON_CONFIGURED_PORT = "CODEBUDDY_DAEMON_CONFIGURED_PORT";
+/**
+ * 会话类型
+ * - interactive: 用户终端交互（默认）
+ * - bg: 后台会话（用户可管理：ps/attach/kill）
+ * - daemon: 守护进程 supervisor（长生命周期）
+ * - daemon-worker: daemon 分配的 worker 子进程（预留）
+ * - teammate: 独立进程 teammate（由 team leader fork）
+ * - prewarm: 已付清冷启动成本、挂起等待 IPC activate 的预热进程
+ *            （meta 暴露 prewarmId / socketPath / status，供 cbc-prewarm list 发现）
+ */
+export type SessionKind = 'interactive' | 'bg' | 'daemon' | 'daemon-worker' | 'teammate' | 'prewarm';
+export type SessionStatus = 'busy' | 'idle' | 'waiting' | 'stopped';
+export type DaemonStatus = 'stopped' | 'starting' | 'running' | 'stopping';
+/**
+ * 每个进程的 PID 注册信息，存储在 ~/.codebuddy/sessions/<pid>.json
+ */
+export interface PidFileEntry {
+    /** 进程 PID */
+    pid: number;
+    /** 会话唯一标识 */
+    sessionId: string;
+    /** 启动时的工作目录 */
+    cwd: string;
+    /** 启动时间戳 (ms) */
+    startedAt: number;
+    /** 最后更新时间戳 (ms) */
+    updatedAt?: number;
+    /** 会话类型 */
+    kind: SessionKind;
+    /** 用户可见名称（用于 ps/logs/kill 查找） */
+    name?: string;
+    /** 输出日志文件路径（bg 会话必填） */
+    logPath?: string;
+    /** 当前运行状态 */
+    status?: SessionStatus;
+    /** 等待描述（如 tool:Bash, user-input） */
+    waitingFor?: string;
+    /** HTTP 服务端口 */
+    port?: number;
+    /** HTTP endpoint URL */
+    endpoint?: string;
+    /** HTTP 服务完整 URL（含 host:port，用于跨实例访问） */
+    url?: string;
+    /** 网络模式 */
+    mode?: 'local' | 'tunnel';
+    /** 认证密码（手动添加的远程 worker） */
+    password?: string;
+    /** 是否手动添加的远程 worker（非本地进程） */
+    manual?: boolean;
+    /** CLI 版本号 */
+    version?: string;
+    /** 操作系统 */
+    os?: string;
+    /** CPU 架构 */
+    arch?: string;
+    /** 主机名 */
+    hostname?: string;
+    /** 自定义元数据（如 currentTopic） */
+    meta?: Record<string, string>;
+    /** 最后心跳时间戳 (ms) */
+    lastHeartbeat?: number;
+    /** 是否为当前进程（API 返回时动态计算，不持久化） */
+    isCurrent?: boolean;
+    /** daemon 启动时的原始端口配置（用于 restart 端口复用） */
+    configuredPort?: number;
+    /** daemon 启动时的原始 host 配置（用于 restart host 复用） */
+    configuredHost?: string;
+    /** daemon 已连接的 channel IDs（用于 restart 后恢复，格式：'wechat:id' | 'wecom:id'） */
+    connectedChannels?: string[];
+    /**
+     * daemon 首次启动时由用户传入的可继承 CLI 参数（已过滤掉子命令/lifecycle flag）。
+     *
+     * 用途：`daemon restart` 不带参数时从这里恢复，保证用户首次 `daemon start --model X -y`
+     * 设置的模型/权限模式等行为在重启后仍然生效，避免回退成默认权限模式 / 默认模型。
+     *
+     * 仅对 `kind === 'daemon'` 的条目有意义。
+     */
+    startupArgs?: string[];
+}
+/** Daemon 默认端口 */
+export declare const DEFAULT_DAEMON_PORT = 9527;
+/** Daemon supervisor 配置 */
+export interface DaemonConfig {
+    /** HTTP 端口（0 = 自动分配，默认 9527） */
+    port: number;
+    /** 绑定地址 */
+    host: string;
+    /** PID 文件目录（运行时填充） */
+    sessionsDir: string;
+    /** 日志文件目录（运行时填充） */
+    logDir: string;
+    /** Permission mode for daemon sessions (default: 'default') */
+    permissionMode?: string;
+    /**
+     * 显式提供给 daemon 子进程的启动参数（不再从 `process.argv` 推断）。
+     *
+     * - `daemon start` 路径：通常不传，由 `forkDaemon` 内部读取 `process.argv` 推断；
+     * - `daemon restart` / auto-restart 路径：必须传上一次持久化的 `startupArgs`，
+     *   保证重启后用户原始的 `--model` / `-y` 等参数得到继承。
+     */
+    startupArgs?: string[];
+}
+export declare const DEFAULT_DAEMON_CONFIG: DaemonConfig;
+/** daemon status 查询结果 */
+export interface DaemonInfo {
+    status: DaemonStatus;
+    pid?: number;
+    endpoint?: string;
+    startedAt?: number;
+}
+/** fork 后台会话的选项 */
+export interface BgSessionOptions {
+    /** 用户可见会话名 */
+    name?: string;
+    /** 工作目录 */
+    cwd?: string;
+    /** 不自动加 -y（用于 teammate Permission Bridge 场景） */
+    skipAutoApprove?: boolean;
+    /** 不自动加 -p（子进程需要完整 HTTP 服务，如 --serve 模式） */
+    skipPrintMode?: boolean;
+    /** 外层 detached 进程作为 PTY broker 托管完整交互会话 */
+    jobWorker?: boolean;
+    /** 附加环境变量（合并到子进程 env） */
+    extraEnv?: Record<string, string>;
+}
+/** Daemon supervisor 生命周期管理 */
+export interface IDaemonService {
+    /** 启动 daemon（如已运行则返回现有实例信息） */
+    start(config?: Partial<DaemonConfig>): Promise<DaemonInfo>;
+    /**
+     * 停掉 daemon。
+     *
+     * 默认连同 daemon 名下的 worker（prewarm / daemon-worker）与后台会话
+     * worker（bg）一起停；非 Windows 平台 `keepWorkers` 时保留 bg worker —— 它们是 detached
+     * 进程，下一个 daemon 靠 sessions/<pid>.json 注册表重连（对齐 Claude 的
+     * `daemon stop --keep-workers`）。
+     */
+    stop(options?: {
+        keepWorkers?: boolean;
+    }): Promise<void>;
+    /** 查询 daemon 运行状态 */
+    status(): Promise<DaemonInfo>;
+    /** 先 stop 再 start */
+    restart(config?: Partial<DaemonConfig>): Promise<DaemonInfo>;
+    /** 当前进程作为 daemon supervisor 运行（由 fork 出的子进程调用） */
+    runAsSupervisor(): Promise<void>;
+}
+/** PID 文件注册表 — 进程发现和管理 */
+export interface ISessionRegistry {
+    /** 注册当前进程，写入 PID 文件 */
+    register(entry: Omit<PidFileEntry, 'pid'>): Promise<void>;
+    /** 注销当前进程，删除 PID 文件 */
+    unregister(): Promise<void>;
+    /** 更新当前进程的字段（best-effort） */
+    update(patch: Partial<Pick<PidFileEntry, 'sessionId' | 'status' | 'waitingFor' | 'name' | 'updatedAt' | 'endpoint' | 'url' | 'mode' | 'meta' | 'lastHeartbeat' | 'version' | 'os' | 'arch' | 'hostname' | 'configuredPort' | 'configuredHost' | 'connectedChannels' | 'startupArgs'>>): Promise<void>;
+    /** 列出所有活跃会话（进程存活的） */
+    list(filter?: {
+        kind?: SessionKind;
+    }): Promise<PidFileEntry[]>;
+    /** 按 PID（纯数字）或 name/sessionId 查找 */
+    find(pidOrName: string): Promise<PidFileEntry | undefined>;
+    /** 清理已死进程的 PID 文件，返回清理数量 */
+    cleanup(): Promise<number>;
+    /** 获取 sessions 目录路径 */
+    getSessionsDir(): string;
+    /** 手动添加远程 worker（无本地进程，通过 URL 访问） */
+    addManual(entry: Omit<PidFileEntry, 'pid'> & {
+        url: string;
+    }): Promise<PidFileEntry>;
+    /** 删除手动添加的远程 worker */
+    removeManual(idOrName: string): Promise<void>;
+    /** 启动当前进程的心跳定时器（定期更新 lastHeartbeat） */
+    startHeartbeat(): void;
+    /** 停止心跳定时器 */
+    stopHeartbeat(): void;
+    /** 获取当前进程 PID（用于标记 isCurrent） */
+    getCurrentPid(): number;
+}
+/** 子进程 fork / 信号 / 存活检测 */
+export interface IDaemonProcessManager {
+    /** Fork detached daemon supervisor 子进程 */
+    forkDaemon(config: DaemonConfig, extraEnv?: Record<string, string>): Promise<{
+        pid: number;
+        logPath: string;
+    }>;
+    /** Fork detached 后台会话子进程 */
+    forkBgSession(args: string[], options: BgSessionOptions): Promise<{
+        pid: number;
+        logPath: string;
+    }>;
+    /** 向指定进程发送信号，返回是否成功 */
+    sendSignal(pid: number, signal: NodeJS.Signals): boolean;
+    /** 检查进程是否存活（通过 kill -0） */
+    isProcessRunning(pid: number): boolean;
+    /** 轮询等待进程退出，返回是否在超时前退出 */
+    waitForExit(pid: number, timeoutMs?: number): Promise<boolean>;
+    /**
+     * 从当前进程的 process.argv 中抽取出"可被 daemon 子进程继承"的 CLI 参数。
+     * 已剥离 daemon 子命令、模式 flag（--serve/--print/--acp 等）、生命周期 flag、
+     * 以及 `--port`/`--host`（由 env 变量传递）。
+     *
+     * 暴露此方法是为了让 `daemon-service` 在 `runAsSupervisor()` 时把这份"原始用户参数"
+     * 持久化到 PID 文件，从而 `daemon restart` / auto-restart 可以原样继承。
+     */
+    getInheritableArgs(): string[];
+    /**
+     * 构造 daemon 子进程的完整 CLI 参数（含 `--serve` 与权限兜底逻辑）。
+     * 对外暴露主要方便单测验证参数装配规则。
+     */
+    buildDaemonChildArgs(config: DaemonConfig): string[];
+}
+/** 后台会话命令处理器（ps / logs / attach / kill / stop / rm / respawn / --bg） */
+export interface IBgSessionHandler {
+    /** 列出所有活跃会话（codebuddy ps） */
+    ps(args: string[]): Promise<void>;
+    /** 查看会话日志输出（codebuddy logs <id>） */
+    logs(pidOrName: string): Promise<void>;
+    /** 附加到运行中的会话（codebuddy attach <id>） */
+    attach(pidOrName: string): Promise<void>;
+    /** 终止会话进程（codebuddy kill <id>） */
+    kill(pidOrName: string): Promise<void>;
+    /** 从 agent view 列表移除会话（codebuddy rm <id>），对话记录保留在本机 */
+    remove(idOrName: string): Promise<void>;
+    /** 保留对话重启会话（codebuddy respawn <id>） */
+    respawn(idOrName: string): Promise<void>;
+    /** 重启所有运行中的会话（codebuddy respawn --all），如换新二进制后整体迁移 */
+    respawnAll(): Promise<void>;
+    /** 处理 --bg 标志：fork 后台会话并输出信息 */
+    handleBgFlag(args: string[]): Promise<void>;
+}
+/** 唤醒检测 + 防 idle sleep */
+export interface IWakeDetector {
+    /** 启动检测（含平台防休眠 + 定时器跳跃检测） */
+    start(): void;
+    /** 停止检测并释放防休眠子进程 */
+    stop(): void;
+    /** 系统唤醒事件（携带估算休眠时长） */
+    readonly onWake: Subject<{
+        sleepDurationMs: number;
+    }>;
+}
+/** 更新后空闲自动重启 */
+export interface IDaemonAutoRestart {
+    /** 启动自动重启监听 */
+    start(): void;
+    /** 停止监听 */
+    stop(): void;
+    /** 触发待重启（由 AutoUpdateService 调用） */
+    schedulePendingRestart(): void;
+    /**
+     * 立即执行一次优雅自重启（不等 idle）：关闭 HTTP → 注销 PID → fork 新 daemon → exit。
+     *
+     * 供"restart 请求打到 daemon 自己身上"的路径使用（Web UI POST /api/v1/daemon/restart，
+     * issue #72979）：本进程不能 stop() 自己（sendSignal 的自身 PID 守卫，#73790），
+     * 必须先让当前 HTTP 响应发出，再在后台完成换进程。
+     * config 为显式覆盖项（port/host/startupArgs），未提供的字段从 PID 文件快照恢复。
+     */
+    restartNow(config?: Partial<DaemonConfig>): void;
+}
+/** Channel 自动连接与恢复 */
+export interface IDaemonChannelAutoConnect {
+    /** 自动连接所有有保存凭证的 channel 实例 */
+    connectSavedChannels(): Promise<void>;
+    /** 恢复指定的 channel 连接（从 restart 恢复） */
+    restoreChannels(channelIds: string[]): Promise<void>;
+    /** 获取当前已连接的 channel ID 列表（格式：'clientType:instanceId'） */
+    getConnectedChannelIds(): string[];
+}
+/** 系统服务状态 */
+export interface SystemServiceStatus {
+    /** 是否已安装为系统服务 */
+    installed: boolean;
+    /** 平台后端类型 */
+    backend: 'launchd' | 'systemd' | 'task-scheduler' | 'unsupported';
+    /** 服务配置文件路径（已安装时） */
+    configPath?: string;
+}
+/** 系统服务注册/注销 — 将 daemon 注册为操作系统级服务（登录自启） */
+export interface ISystemService {
+    /** 注册为系统服务（开机/登录自启） */
+    install(options?: {
+        port?: number;
+        permissionMode?: string;
+    }): Promise<void>;
+    /** 移除系统服务注册 */
+    uninstall(): Promise<void>;
+    /** 查询系统服务状态 */
+    status(): Promise<SystemServiceStatus>;
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/daemon-service.d.ts

@@ -0,0 +1,45 @@
+import { type DaemonConfig, type DaemonInfo, type IDaemonService } from './daemon-protocol.js';
+/**
+ * Daemon supervisor 生命周期管理
+ *
+ * start: fork detached 子进程 → 子进程以 --serve 模式启动 HTTP → 注册 PID 文件
+ * stop:  SIGTERM → 等待退出 → 超时则 SIGKILL → 清理 PID 文件
+ * runAsSupervisor: 由 fork 出的子进程内部调用，初始化 HTTP/ACP 服务并保持存活
+ */
+export declare class DaemonServiceImpl implements IDaemonService {
+    private readonly registry;
+    private readonly processManager;
+    private readonly endpointProvider?;
+    private readonly gatewayAuth?;
+    private readonly corsService?;
+    private readonly acpServer?;
+    private readonly autoRestart?;
+    start(config?: Partial<DaemonConfig>): Promise<DaemonInfo>;
+    stop(options?: {
+        keepWorkers?: boolean;
+    }): Promise<void>;
+    status(): Promise<DaemonInfo>;
+    restart(config?: Partial<DaemonConfig>): Promise<DaemonInfo>;
+    /**
+     * 当前进程作为 daemon supervisor 运行。
+     *
+     * 由 fork 出的子进程调用（启动参数为 --serve + CODEBUDDY_SESSION_KIND=daemon）。
+     * 流程：注册 PID → 等待 HTTP 就绪 → 初始化认证/CORS/ACP → 更新 endpoint → 保持存活。
+     *
+     * 注意：daemon 增强功能（防休眠/唤醒检测/自动重启/channel 自动连接）
+     * 由 DaemonEnhancementsLifecycle 自动管理，无需在此手动启动。
+     */
+    runAsSupervisor(): Promise<void>;
+    /** 当前进程是否就是注册表里的 daemon（restart/stop 打在自己身上的判定） */
+    private isRunningAsDaemon;
+    private findRunningDaemon;
+    private mergeConfig;
+    /**
+     * 在 `restart()` 中先于 `stop()` 调用，抓取当前在跑 daemon 的启动参数与端口快照。
+     *
+     * 没有 daemon 在跑、或 PID 文件里没记录 startupArgs（旧版本写出的 PID 文件）时返回空对象，
+     * 此时 restart 行为退化为"用当前 process.argv 重新计算"，与历史行为兼容。
+     */
+    private snapshotPreviousStartup;
+    private waitForPidFile;
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/index.d.ts

@@ -0,0 +1,10 @@
+export * from './daemon-protocol.js';
+export * from './daemon-service.js';
+export * from './session-registry.js';
+export * from './daemon-process.js';
+export * from './bg-session-handler.js';
+export * from './wake-detector.js';
+export * from './daemon-auto-restart.js';
+export * from './daemon-channel-autoconnect.js';
+export * from './daemon-enhancements-lifecycle.js';
+export * from './system-service.js';

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/session-registry.d.ts

@@ -0,0 +1,39 @@
+import { type ISessionRegistry, type PidFileEntry, type SessionKind } from './daemon-protocol.js';
+/**
+ * Worker 注册表 — 统一的进程发现和管理
+ *
+ * 存储位置: ~/.codebuddy/sessions/<pid>.json（本地进程）
+ *           ~/.codebuddy/sessions/manual-<id>.json（手动添加的远程 worker）
+ *
+ * 本地进程通过 kill -0 检测存活，手动远程 worker 通过心跳超时检测。
+ * 完全替代原有的 InstanceRegistryService。
+ */
+export declare class SessionRegistryImpl implements ISessionRegistry {
+    private registered;
+    private cleanupRegistered;
+    private heartbeatTimer;
+    /** 互斥锁——串行化 update() 调用，防止并发读-改-写损坏 JSON */
+    private updateMutex;
+    getSessionsDir(): string;
+    getCurrentPid(): number;
+    private getPidFilePath;
+    private getManualFilePath;
+    register(entry: Omit<PidFileEntry, 'pid'>): Promise<void>;
+    unregister(): Promise<void>;
+    update(patch: Partial<Pick<PidFileEntry, 'sessionId' | 'status' | 'waitingFor' | 'name' | 'updatedAt' | 'endpoint' | 'url' | 'mode' | 'meta' | 'lastHeartbeat' | 'version' | 'os' | 'arch' | 'hostname' | 'configuredPort' | 'configuredHost' | 'connectedChannels'>>): Promise<void>;
+    private doUpdate;
+    list(filter?: {
+        kind?: SessionKind;
+    }): Promise<PidFileEntry[]>;
+    find(pidOrName: string): Promise<PidFileEntry | undefined>;
+    cleanup(): Promise<number>;
+    addManual(entry: Omit<PidFileEntry, 'pid'> & {
+        url: string;
+    }): Promise<PidFileEntry>;
+    removeManual(idOrName: string): Promise<void>;
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    private registerExitCleanup;
+    private parsePidFromFilename;
+    private isProcessAlive;
+}

package/cli/dist-server/types/workspace/cbc-daemon/lib/node/daemon/system-service.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 系统服务注册 — 将 daemon 注册为操作系统级服务（登录自启）
+ *
+ * 跨平台策略（参照 wake-detector.ts）：单文件内 process.platform switch。
+ * - macOS: ~/Library/LaunchAgents/ plist + launchctl
+ * - Linux: ~/.config/systemd/user/ unit + systemctl --user
+ * - Windows: Task Scheduler (schtasks)
+ */
+import { type ISystemService, type SystemServiceStatus } from './daemon-protocol.js';
+export declare class SystemServiceImpl implements ISystemService {
+    install(options?: {
+        port?: number;
+        permissionMode?: string;
+    }): Promise<void>;
+    uninstall(): Promise<void>;
+    status(): Promise<SystemServiceStatus>;
+    private statusForPlatform;
+    /**
+     * 入口 guard：argv[1] 不是本产品 CLI 入口时拒绝注册系统服务。
+     *
+     * 动机（实测事故）：单测/嵌入式宿主走到 install() 时，resolvePaths() 取到的是宿主自己的
+     * 入口（vitest 的 forks.js、node_modules/.bin/mocha），照样被写进 LaunchAgent。launchd 的
+     * RunAtLoad + KeepAlive(SuccessfulExit=false) 于是把它变成永久崩溃重启循环——开发机上
+     * 累计 26.6 万次 MODULE_NOT_FOUND、200MB 的 daemon-launchd.err.log，且不会自愈。
+     * 注册系统服务是"难以自我恢复"的系统边界，入口对不上就必须拒绝而不是先写再说。
+     */
+    private assertInstallableEntry;
+    /** capability guard：systemDaemon=false 时拒绝注册/卸载系统服务。 */
+    private assertSystemDaemonCapability;
+    private getPlistPath;
+    private installLaunchd;
+    private uninstallLaunchd;
+    private statusLaunchd;
+    private isCurrentLaunchdRuntime;
+    private matchesCurrentProgramArguments;
+    generatePlist(options?: {
+        port?: number;
+        permissionMode?: string;
+    }): string;
+    private getSystemdUnitPath;
+    private installSystemd;
+    private uninstallSystemd;
+    private statusSystemd;
+    generateSystemdUnit(options?: {
+        port?: number;
+        permissionMode?: string;
+    }): string;
+    private installTaskScheduler;
+    private uninstallTaskScheduler;
+    private statusTaskScheduler;
+    /** 解析 node 和 cbc 的绝对路径 */
+    resolvePaths(): {
+        nodePath: string;
+        cbcPath: string;
+    };
+    /** 构建 daemon start 的参数列表 */
+    private buildProgramArgs;
+    private getLogDir;
+    private escapeXml;
+}