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

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

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+/** 3 days expiry (ms) */
+export declare const CRON_EXPIRY_MS = 259200000;
+/** Scheduler main loop interval (ms) */
+export declare const SCHEDULER_TICK_MS = 500;
+/** Distributed lock retry interval (ms) */
+export declare const LOCK_RETRY_MS = 5000;
+/** Max scheduled jobs per session */
+export declare const MAX_SCHEDULED_JOBS = 50;
+/** Default /loop interval */
+export declare const DEFAULT_LOOP_INTERVAL = "10m";
+/** Persisted tasks file name */
+export declare const SCHEDULED_TASKS_FILE = "scheduled_tasks.json";
+/** Lock file name */
+export declare const SCHEDULED_TASKS_LOCK = "scheduled_tasks.scheduler.lock";
+/** Persisted execution history file name */
+export declare const SCHEDULED_TASK_EXECUTIONS_FILE = "scheduled_task_executions.json";
+/** Maximum retained executions per task */
+export declare const MAX_EXECUTIONS_PER_TASK = 50;
+/** Active execution ownership lease duration (ms) */
+export declare const EXECUTION_LEASE_TTL_MS = 30000;
+/** Active execution ownership lease renewal interval (ms) */
+export declare const EXECUTION_LEASE_RENEW_MS = 10000;
+export interface JitterConfig {
+    recurringFrac: number;
+    recurringCapMs: number;
+    oneShotMaxMs: number;
+    oneShotFloorMs: number;
+    oneShotMinuteMod: number;
+}
+export declare const DEFAULT_JITTER_CONFIG: JitterConfig;
+export interface CronTask {
+    id: string;
+    cron: string;
+    prompt: string;
+    createdAt: number;
+    recurring?: boolean;
+    durable?: boolean;
+    permanent?: boolean;
+    lastFiredAt?: number;
+    enabled?: boolean;
+}
+export interface CronTaskUpdate {
+    cron?: string;
+    prompt?: string;
+    recurring?: boolean;
+    durable?: boolean;
+    enabled?: boolean;
+}
+export type CronTaskExecutionStatus = 'queued' | 'running' | 'succeeded' | 'failed';
+export type CronTaskExecutionOwnerKind = 'daemon' | 'webui' | 'cli';
+export interface CronTaskExecutionOwner {
+    ownerKind: CronTaskExecutionOwnerKind;
+    ownerId: string;
+    ownerPid: number;
+    sessionId: string;
+}
+export interface CronTaskExecution {
+    id: string;
+    taskId: string;
+    schedule: string;
+    prompt: string;
+    durable?: boolean;
+    recurring?: boolean;
+    status: CronTaskExecutionStatus;
+    ownerKind?: CronTaskExecutionOwnerKind;
+    ownerId?: string;
+    ownerPid?: number;
+    sessionId?: string;
+    leaseExpiresAt?: number;
+    runId?: string;
+    startedAt: number;
+    completedAt?: number;
+    durationMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    error?: string;
+}
+export interface ScheduledTaskExecutionsFile {
+    executions: CronTaskExecution[];
+}
+export interface CronCreateOutput {
+    id: string;
+    humanSchedule: string;
+    recurring: boolean;
+    durable?: boolean;
+}
+export interface CronListOutput {
+    jobs: Array<{
+        id: string;
+        cron: string;
+        humanSchedule: string;
+        prompt: string;
+        recurring?: boolean;
+        durable?: boolean;
+        enabled?: boolean;
+    }>;
+}
+export interface ParsedCron {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+}
+export interface LockContent {
+    sessionId: string;
+    pid: number;
+    acquiredAt: number;
+}
+export interface ScheduledTasksFile {
+    tasks: CronTask[];
+}
+/** CronCreate schema. `durable` is model-visible but gated by tool approval. */
+export declare const CronCreateFullSchema: z.ZodObject<{
+    cron: z.ZodString;
+    prompt: z.ZodString;
+    recurring: z.ZodOptional<z.ZodBoolean>;
+    durable: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    cron: string;
+    prompt: string;
+    recurring?: boolean | undefined;
+    durable?: boolean | undefined;
+}, {
+    cron: string;
+    prompt: string;
+    recurring?: boolean | undefined;
+    durable?: boolean | undefined;
+}>;
+export declare const CronDeleteSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export declare const CronListSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export type CronSchedulerOwnerKind = 'daemon' | 'session';
+export interface CronSchedulerStartOptions {
+    ownerKind?: CronSchedulerOwnerKind;
+    shouldDeferToPreferredOwner?: (storageDir: string) => Promise<boolean>;
+}
+export type CronTaskFireResult = 'enqueued' | 'active' | 'already-completed' | 'rejected';
+export interface CronExecutionClaimResult {
+    status: 'inserted' | 'active' | 'already-completed';
+    execution?: CronTaskExecution;
+}
+export type CronExecutionDeleteResult = {
+    status: 'deleted';
+    deletedIds: string[];
+    missingIds: string[];
+} | {
+    status: 'active';
+    activeIds: string[];
+};
+export interface CronSchedulerOptions extends CronSchedulerStartOptions {
+    sessionId: string;
+    onFire: (prompt: string) => void;
+    isLoading: () => boolean;
+    onFireTask?: (task: CronTask, isLeadershipValid: () => boolean) => CronTaskFireResult | void | Promise<CronTaskFireResult | void>;
+    onMissed?: (tasks: CronTask[]) => void;
+    dir: string;
+    lockIdentity: {
+        sessionId: string;
+        pid: number;
+    };
+    getJitterConfig?: () => JitterConfig;
+    assistantMode?: boolean;
+    isKilled?: () => boolean;
+}
+export declare const CronSchedulerService: unique symbol;
+export declare const CronStateManagerService: unique symbol;
+export declare const CronStorageService: unique symbol;
+/**
+ * Per-session lifecycle manager for cron scheduler instances.
+ * Injected into SessionManager for start/stop on session transitions.
+ */
+export interface CronSchedulerServiceInterface {
+    /** Start the scheduler for a session (fire-and-forget) */
+    start(session: {
+        id: string;
+        agentState?: string;
+        abortSignal: AbortSignal;
+    }, options?: CronSchedulerStartOptions): boolean;
+    /** Stop the scheduler for a session */
+    stop(sessionId: string): void;
+    /** Get the next fire time for a session's scheduler */
+    getNextFireTime(sessionId: string): number | null;
+}

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

@@ -0,0 +1,131 @@
+import { TelemetryService } from '../../../../../node/telemetry/telemetry-protocol.js';
+import { Session, SessionRunStateMachine } from '../../../../cbc-core/lib/node/index.js';
+import { Logger } from '../../../../telemetry/lib/common/index.js';
+import { type CronSchedulerStartOptions } from './cron-protocol.js';
+import { CronStateManager } from './cron-state-manager.js';
+interface ExecutionCompletion {
+    status: 'succeeded' | 'failed';
+    error?: string;
+}
+/**
+ * Correlates a scheduled-task execution with the physical run that actually
+ * admitted its input. PREPARING alone is deliberately insufficient: queue
+ * arbitration happens later, and the cron item may remain queued for another
+ * run. The inputSubject notification is emitted by History after arbitration,
+ * so it is the first authoritative admission signal visible to this package.
+ */
+export declare class CronExecutionRunTracker {
+    private readonly session;
+    private readonly stateMachine;
+    private readonly markExecutionRunning;
+    private readonly completeExecution;
+    private readonly pendingExecutions;
+    private readonly runStateSubscription;
+    private readonly historySubscription;
+    constructor(session: Session, stateMachine: SessionRunStateMachine, markExecutionRunning: (executionId: string, runId: string) => void, completeExecution: (executionId: string, result: ExecutionCompletion) => void);
+    track(executionId: string): void;
+    untrack(executionId: string): void;
+    fail(executionId: string, error: string): void;
+    finalizeAll(error: string): void;
+    dispose(): void;
+    private onHistoryItem;
+    private onRunStateChanged;
+    private continueRun;
+    private completeRun;
+    private complete;
+}
+/**
+ * Per-session lifecycle manager for the cron scheduler.
+ *
+ * Responsibilities:
+ * 1. Create/start a CronSchedulerInstance when a session starts
+ * 2. Stop/destroy it when the session is cleaned up or removed
+ * 3. Wire the `onFire` callback to inject isMeta messages via MessageQueueManager
+ * 4. Wire `isLoading` to check the session's agentState
+ */
+export declare class CronSchedulerServiceImpl {
+    protected readonly logger: Logger;
+    protected readonly stateManager: CronStateManager;
+    protected readonly telemetryService?: TelemetryService;
+    protected readonly stateMachine: SessionRunStateMachine;
+    /** Active scheduler instances keyed by session ID */
+    private schedulers;
+    private executionTrackers;
+    private schedulerLifecycles;
+    private executionOwnerIds;
+    private executionLeaseTimers;
+    private modeBIdleSubscriptions;
+    /**
+     * 任务会话注册表，按任务会话 id 索引。
+     *
+     * 生命周期是「进程级」而不是「调度器级」：任务会话不属于任何宿主会话，宿主
+     * 切换（/clear、setCurrent）会 stop 旧调度器再 start 新的，若跟着释放就会把
+     * 在途的定时任务执行误判为失败。规模由持久化任务数封顶，不随执行次数增长。
+     */
+    private taskSessions;
+    /** 同一 tick 内并发触发同一任务时复用的创建 promise，避免重复建会话。 */
+    private taskSessionResolutions;
+    private taskSessionTrackers;
+    /**
+     * Start the cron scheduler for a session.
+     * Called in SessionManager.setCurrent() when a new session is activated.
+     *
+     * This method is fire-and-forget (non-blocking).
+     */
+    start(session: Session, options?: CronSchedulerStartOptions): boolean;
+    /**
+     * Stop the cron scheduler for a session.
+     * Called during session cleanup in SessionManager.setCurrent() and remove().
+     */
+    stop(sessionId: string): void;
+    /**
+     * 解析持久化任务的执行会话。
+     *
+     * 会话 id 由 taskId 纯函数派生（uuid v5，见 cronTaskSessionId），因此任何进程
+     * （daemon / WebUI / CLI / TUI）对同一任务都落在同一条会话上：不需要把
+     * 「任务 → 会话」映射落盘，也不需要在各入口之间对齐归属。首次触发时懒创建，
+     * 之后按 id 从会话存储复原，所以会话数等于持久化任务数，不随执行次数增长。
+     */
+    private resolveTaskSession;
+    private loadOrCreateTaskSession;
+    /**
+     * 任务会话由 SessionManager 直建，不经过 SessionMiddleware，因此进程级 CLI 参数
+     * （-y / --permission-mode / --model / --tools）必须在此显式注入，否则权限模式会
+     * 兜底成 Default，而任务会话没有宿主可以应答审批，无人值守执行会直接挂死。
+     * 配方与 webhook 直建会话（GatewayAcpBridge.createSessionForConversation）一致。
+     *
+     * MCP 与技能是进程档能力（AgentScopedMcpManager 无 scoped state 时回落全局
+     * servers、mergeSessionSkills 无会话档绑定时 no-op），不随会话创建路径变化，
+     * 无需在此注入；已由 task-session-mcp-skill.spec.ts 覆盖。
+     */
+    private taskSessionOptions;
+    private taskSessionTracker;
+    private createExecutionTracker;
+    /**
+     * 把触发消息投递到任务会话。
+     *
+     * 任务会话没有 ACP 宿主来驱动队列排空，所以空闲时直接以本轮输入起 run；忙时
+     * 入队，由 AgentService 的空闲排空接管，避免两条排空路径抢跑同一轮。
+     */
+    private dispatchToTaskSession;
+    private runTaskSession;
+    /**
+     * Get the next fire time across all active schedulers.
+     */
+    getNextFireTime(sessionId: string): number | null;
+    /**
+     * Report telemetry when a scheduled task fires.
+     *
+     * NOTE: Full telemetry event types (scheduled_task_fire, scheduled_task_missed, scheduled_task_expired)
+     * are not yet defined in @genie/telemetry package. This is a placeholder for future integration.
+     *
+     * To fully implement telemetry:
+     * 1. Add ScheduledTaskFireTelemetry, ScheduledTaskMissedTelemetry, ScheduledTaskExpiredTelemetry
+     *    to packages/telemetry/src/common/event/types/
+     * 2. Add corresponding Events enum values
+     * 3. Update EventPayloadMapping in packages/telemetry/src/common/event/types/events.ts
+     * 4. Uncomment the report() calls below
+     */
+    private reportScheduledTaskFire;
+}
+export {};

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-scheduler.d.ts

@@ -0,0 +1,20 @@
+import { CronSchedulerOptions } from './cron-protocol.js';
+import { CronStateManager } from './cron-state-manager.js';
+export interface CronSchedulerInstance {
+    start(): void;
+    stop(): void;
+    getNextFireTime(): number | null;
+}
+/**
+ * Create a cron scheduler with a 4-layer timer architecture:
+ * 1. Enablement check: polls scheduledTasksEnabled every 500ms
+ * 2. Main loop: checks expired tasks every 500ms
+ * 3. Lock retry: retries lock acquisition every 5s
+ * 4. File watcher: chokidar monitors scheduled_tasks.json
+ *
+ * State machine:
+ * STOPPED → ENABLEMENT_CHECK → LOCK_ACQUIRING → RUNNING → STOPPING → STOPPED
+ *
+ * All setInterval calls use .unref() to not block process exit.
+ */
+export declare function createCronScheduler(options: CronSchedulerOptions, stateManager: CronStateManager): CronSchedulerInstance;

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-state-manager.d.ts

@@ -0,0 +1,50 @@
+import { CronExecutionClaimResult, CronExecutionDeleteResult, CronTask, CronTaskExecution, CronTaskExecutionOwner, CronTaskUpdate } from './cron-protocol.js';
+export declare class CronStateManager {
+    private scheduledTasksEnabled;
+    private sessionCronTasksMap;
+    private durableCronTasks;
+    private taskExecutions;
+    private executionWriteQueue;
+    private failedExecutionWrites;
+    private deletingExecutionIds;
+    private executionRetryTimer;
+    private executionPersistenceError;
+    private storageDir;
+    setEnabled(enabled: boolean): void;
+    isScheduledTasksEnabled(): boolean;
+    setStorageDir(dir: string): void;
+    getStorageDir(): string | undefined;
+    getSessionTasks(sessionId: string): CronTask[];
+    getDurableTasks(): CronTask[];
+    readDurableTasks(): Promise<CronTask[]>;
+    replaceDurableTasks(tasks: CronTask[]): void;
+    refreshDurableTasks(): Promise<CronTask[]>;
+    addSessionTask(sessionId: string, task: CronTask): void;
+    removeSessionTasks(sessionId: string, ids: string[]): number;
+    clearSessionTasks(sessionId: string): void;
+    createTask(sessionId: string, cron: string, prompt: string, recurring: boolean, durable: boolean): Promise<string>;
+    getAllTasks(sessionId: string): Promise<CronTask[]>;
+    updateTask(sessionId: string, id: string, updates: CronTaskUpdate): Promise<CronTask | undefined>;
+    private applyTaskUpdates;
+    tryQueueExecution(task: CronTask, owner: CronTaskExecutionOwner): Promise<CronTaskExecution | undefined>;
+    tryQueueExecutionDetailed(task: CronTask, owner: CronTaskExecutionOwner): Promise<CronExecutionClaimResult>;
+    markExecutionRunning(id: string, runId: string): void;
+    hasActiveExecution(taskId: string): boolean;
+    renewExecutionLeases(ownerId: string): Promise<number>;
+    completeExecution(id: string, result: {
+        status: 'succeeded' | 'failed';
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        error?: string;
+    }): Promise<void>;
+    getTaskExecutions(taskId: string): Promise<CronTaskExecution[]>;
+    deleteTaskExecutions(taskId: string, executionIds: readonly string[]): Promise<CronExecutionDeleteResult>;
+    private findActiveExecutionIds;
+    private pruneTaskExecutions;
+    recoverInterruptedExecutions(error?: string): Promise<number>;
+    flushExecutionPersistence(): Promise<void>;
+    private persistExecution;
+    private scheduleExecutionPersistenceRetry;
+    removeTasks(sessionId: string, ids: string[]): Promise<number>;
+}

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-storage.d.ts

@@ -0,0 +1,61 @@
+import { CronExecutionClaimResult, CronExecutionDeleteResult, CronTask, CronTaskExecution } from './cron-protocol.js';
+export declare class CronStorage {
+    private static taskWriteQueues;
+    private static schedulerLockReleases;
+    private static activeExecutionOwners;
+    private static withFileLock;
+    private static atomicWrite;
+    private static mutateTasks;
+    /**
+     * Read tasks from the persisted JSON file.
+     * Returns empty array on any error (file not found, parse error, etc.)
+     */
+    static readTasks(dir: string): Promise<CronTask[]>;
+    static readTasksConsistent(dir: string): Promise<CronTask[]>;
+    /**
+     * Write tasks to the persisted JSON file.
+     * Strips the `durable` property before writing.
+     */
+    static writeTasks(tasks: CronTask[], dir: string): Promise<void>;
+    static addTask(task: CronTask, dir: string): Promise<void>;
+    static updateTask(id: string, update: (task: CronTask) => CronTask, dir: string): Promise<CronTask | undefined>;
+    static takeTask(id: string, dir: string): Promise<CronTask | undefined>;
+    /** Remove tasks by ID from the persisted file. */
+    static removeTasks(ids: string[], dir: string): Promise<void>;
+    /**
+     * Update the lastFiredAt timestamp for tasks in the persisted file.
+     * Used to track recurring task fire times so restarts don't re-fire immediately.
+     */
+    static updateTaskLastFiredAt(taskIds: string[], timestamp: number, dir: string): Promise<void>;
+    static readExecutions(dir: string): Promise<CronTaskExecution[]>;
+    static writeExecutions(executions: CronTaskExecution[], dir: string): Promise<void>;
+    static registerExecutionOwner(ownerId: string): void;
+    static unregisterExecutionOwner(ownerId: string): void;
+    static tryInsertActiveExecution(execution: CronTaskExecution, dir: string): Promise<CronExecutionClaimResult>;
+    static renewExecutionLeases(ownerId: string, executionIds: ReadonlySet<string>, leaseExpiresAt: number, dir: string): Promise<number>;
+    static deleteExecutions(taskId: string, executionIds: readonly string[], dir: string): Promise<CronExecutionDeleteResult>;
+    static upsertExecution(execution: CronTaskExecution, dir: string): Promise<void>;
+    static failActiveExecutions(error: string, dir: string, excludedIds?: ReadonlySet<string>): Promise<number>;
+    private static isExecutionOwnerAlive;
+    /** Acquire the long-lived durable scheduler leader lock. */
+    static acquireLock(dir: string, identity: {
+        sessionId: string;
+        pid: number;
+        ownerId?: string;
+    }, onCompromised?: (error: Error) => void): Promise<boolean>;
+    /** Release the durable scheduler leader lock owned by this scheduler instance. */
+    static releaseLock(_dir: string, identity: {
+        sessionId: string;
+        pid: number;
+        ownerId?: string;
+    }): Promise<void>;
+    /**
+     * Watch the tasks file for changes using Node.js built-in fs.watch.
+     * Returns a watcher object with a `.close()` method.
+     *
+     * Uses a debounce timer (200ms) to coalesce rapid file changes.
+     */
+    static watchTasksFile(dir: string, onChange: () => void): {
+        close: () => void;
+    };
+}

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/cron-task-session.d.ts

@@ -0,0 +1 @@
+export declare function cronTaskSessionId(taskId: string): string;

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

@@ -0,0 +1,8 @@
+export * from './cron-protocol.js';
+export * from './cron-parser.js';
+export * from './cron-state-manager.js';
+export * from './cron-scheduler.js';
+export * from './cron-scheduler-service.js';
+export * from './cron-storage.js';
+export * from './cron-task-session.js';
+export * from './loop-skill-provider.js';

package/cli/dist-server/types/workspace/cbc-cron/lib/node/cron/loop-skill-provider.d.ts

@@ -0,0 +1,36 @@
+import { ProductConfiguration, ProductProvider } from '../../../../product/lib/common/index.js';
+/**
+ * Marker prefix embedded at the front of every wrapped /loop prompt
+ * (`${LOOP_JOB_MARKER_PREFIX}<LOOP_ID>]`). CronListTool truncates each
+ * job's prompt preview to 80 chars, so this must stay at the very front to
+ * survive the fallback lookup — see the "## Action" instructions below.
+ *
+ * `<LOOP_ID>` is a short opaque token the model makes up itself (not a real
+ * timestamp). Deriving it from anything precise (an ISO timestamp) used to
+ * force a `Bash(date …)` call on every /loop invocation, which blocks on a
+ * permission prompt in default mode and reads as a "hang" — see
+ * loop-hang-after-reschedule.spec.ts. The id only needs to be unique per
+ * loop and stable across reschedules; it does not need to encode the time.
+ */
+export declare const LOOP_JOB_MARKER_PREFIX = "[/loop:";
+/**
+ * ProductProvider that injects the /loop bundled skill.
+ *
+ * Aligns with Claude Code's registerBundledSkill pattern (WH() + qgz()).
+ * Uses the standard ProductProvider mechanism to inject the skill into the
+ * product configuration, avoiding the need for a separate registerBundledSkill API.
+ *
+ * The skill instructions use $ARGUMENTS placeholder which is replaced by
+ * SkillTool.executeSkill → customCommandRenderer.processContent when args are provided.
+ * When no args are provided, $ARGUMENTS stays as-is in the text, and the AI
+ * recognizes the empty input condition from the template instructions.
+ */
+export declare class LoopSkillProductProvider implements ProductProvider {
+    scope: 'runtime';
+    /**
+     * Use a priority lower than WORKSPACE (SkillProductProvider) so that
+     * bundled skills can be overridden by user/project skills with the same name.
+     */
+    priority: number;
+    provide(): Promise<ProductConfiguration>;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * @genie/cbc-cron — CodeBuddy Code Cron 调度运行时。
+ *
+ * 目录布局镜像 agent-cli：`src/node/cron/**` 与拆分前保持一致，git 历史通过 `git mv` 继承。
+ * agent-cli 侧对 `../cron/*` 相对 import 改为主入口 `@genie/cbc-cron`；本包内部对 agent-cli
+ * 的引用一律走 `@genie/agent-cli/node/<子路径>` 精确 subpath（走 src 源码），与 workflow / tui 一致。
+ *
+ * 与 `@genie/agent-cli` 之间允许循环依赖：本包顶层不允许直接消费 agent-cli 运行时值。
+ */
+export * from './cron/index.js';

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

@@ -0,0 +1,88 @@
+import { type IBgSessionHandler } from './daemon-protocol.js';
+/**
+ * 后台会话命令处理器 — ps / logs / attach / kill / --bg
+ *
+ * 所有命令都是轻量级短生命周期操作，直接读取 PID 注册表完成。
+ */
+export declare class BgSessionHandlerImpl implements IBgSessionHandler {
+    private readonly registry;
+    private readonly processManager;
+    private readonly consoleManager;
+    private readonly jobStore;
+    ps(args: string[]): Promise<void>;
+    logs(pidOrName: string): Promise<void>;
+    /**
+     * `codebuddy attach <id>` —— 接管一个后台会话。
+     *
+     * 先按 job 找：agent view 派发出来的会话是 broker 托管的，能连上它自己
+     * 持有的 PTY，拿到的是一个**可以打字的完整交互会话**。
+     * 以前这里对 bg session 一律 `tailFollow(logPath)`，那只是只读地看日志，
+     * 与命令名承诺的「接管」完全是两回事。
+     *
+     * 进程已经退出的 job 也走这条路：broker.attach() 会按 `--resume` 把它
+     * 重新拉起来再接管，对话不丢。只有压根不是 job 的后台进程
+     * （旧的 `--bg`、`--serve` 之类没有 PTY 的）才退回日志。
+     */
+    attach(pidOrName: string): Promise<void>;
+    /**
+     * detach 后**在当前进程原地**打开 agent view，并让 Esc/← 回到刚 attach 的会话。
+     *
+     * 绝不fork 子进程：`codebuddy attach` 是控制终端的前台进程组 leader，
+     * spawn 出来的子进程不在前台组，Ink 挂载时对 tty 做 `setRawMode`
+     * （tcsetattr）会被内核 EIO 拒绝——无论子进程继承 fd0 还是自开
+     * `/dev/tty` 都拒（fd 有效但不是它前台组的控制终端）。而本进程刚才
+     * 在 pipeTerminal 里 setRawMode 是成功的，说明它就是前台、就握着终端，
+     * 所以直接在这里挂载 agent view。复用 `codebuddy agents` 那条同一渲染路径。
+     */
+    private openAgentViewAfterDetach;
+    kill(pidOrName: string): Promise<void>;
+    handleBgFlag(args: string[]): Promise<void>;
+    remove(idOrName: string | undefined): Promise<void>;
+    respawn(idOrName: string | undefined): Promise<void>;
+    /**
+     * `codebuddy respawn --all` —— 重启每个运行中的会话。
+     *
+     * 典型用途：升级 CLI 二进制后把所有后台会话一次性搬到新版。
+     * 只重启进程还活着的会话（对齐文档 "every running session"）；
+     * shell 作业（state.exec）不是模型会话，跳过。单个失败不中断其余。
+     */
+    respawnAll(): Promise<void>;
+    /**
+     * 和 {@link resolveJob} 一样按 id/name/sessionId 找，但找不到时不报错。
+     *
+     * `attach` 要先试 job、再退回 PID 注册表，中途不能先喷一句
+     * "Session not found" 又接着成功 —— 那比不打印还让人困惑。
+     */
+    private resolveJobQuietly;
+    /** 按 job 短 id / 会话名 / sessionId 定位一个 job，并合并进程存活信息 */
+    private resolveJob;
+    private resolveSession;
+    /** 断言 entry 非空，用于流式调用链中（resolve 后立即 require） */
+    private requireSession;
+    private log;
+    private error;
+    private formatRow;
+    private truncatePath;
+    private formatTimeAgo;
+    /** 从 args 中提取 --session-id 的值（用户可能自己传了一个） */
+    private extractSessionIdArg;
+    /**
+     * 确保 args 里带上 --session-id。
+     *
+     * agent view 需要在 fork 之前就知道会话 id 才能建好 job 目录，
+     * 所以这里主动把它固定下来而不是让子进程自己随机生成。
+     */
+    private ensureSessionIdArg;
+    /** 取第一个非 flag 位置参数作为原始 prompt（用于 job 的 intent） */
+    private extractPromptArg;
+    /** 从 args 里抽 `--exec <cmd>` / `--exec=<cmd>`（未给出时返回 undefined） */
+    private extractExecArg;
+    /** 从 args 中提取 --name <value> 或 --name=<value> */
+    private extractNameArg;
+    /**
+     * 持续跟踪日志文件输出（类似 tail -f）。
+     * 使用 fs.watch 监听文件变化，增量读取新内容。
+     * Ctrl+C 断开时只退出当前进程，不影响后台会话。
+     */
+    private tailFollow;
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Daemon Auto-Restart — 更新后空闲自动重启
+ *
+ * 由 AutoUpdateService 安装更新成功后调用 schedulePendingRestart()，
+ * 然后每 10 秒轮询空闲状态，确认空闲后执行 graceful restart：
+ * 保存端口 + channel 列表 → stop 长连接 → 注销 PID → 非托管时 fork，systemd 下交回 supervisor
+ */
+import { ServerAware } from '@celljs/web/lib/node';
+import type { Server } from 'http';
+import { type DaemonConfig, type IDaemonAutoRestart } from './daemon-protocol.js';
+export declare class DaemonAutoRestartImpl implements IDaemonAutoRestart, ServerAware {
+    private readonly logger;
+    private readonly registry;
+    private readonly processManager;
+    private readonly acpAgentManager?;
+    private readonly gatewayAcpBridge?;
+    private readonly wakeDetector?;
+    private readonly channelAutoConnect?;
+    private pendingRestart;
+    private idleCheckTimer;
+    private pendingSince;
+    private restartInFlight;
+    private httpServer?;
+    private readonly sockets;
+    setServer(server: Server): Promise<void>;
+    start(): void;
+    stop(): void;
+    schedulePendingRestart(): void;
+    /**
+     * 立即优雅自重启（Web UI "重启 daemon" 按钮路径，#72979）。
+     *
+     * 延迟 RESTART_RESPONSE_FLUSH_DELAY_MS 再动手，让调用方（daemon 自己）
+     * 先把当前 restart 的 HTTP 响应发出去。真正的互斥在 performGracefulRestart
+     * 入口（覆盖 auto-update idle 路径与本路径的交叉竞态）；这里的检查只是
+     * 提前挡掉明显重复的调用。
+     */
+    restartNow(config?: Partial<DaemonConfig>): void;
+    private startIdleCheck;
+    private clearIdleCheck;
+    /**
+     * 判断 daemon 是否空闲。daemon 自身的注册状态只在启动时写一次，不能代表
+     * 它承载的会话；这里检查所有活跃 session/job 的权威注册状态。未知状态按忙处理，
+     * 防止状态上报暂时缺失时误切正在运行的任务。
+     */
+    private isIdle;
+    private isSystemdManaged;
+    private isLegacySystemdUnit;
+    /**
+     * Graceful Restart:
+     * 1. 读取端口配置（override 优先，其次 PID 文件快照）
+     * 2. 收集已连接 channel
+     * 3. 停止唤醒检测和防休眠
+     * 4. 注销 PID
+     * 5. Fork 新 daemon（相同端口 + channel 恢复列表）
+     * 6. 退出旧进程
+     */
+    private performGracefulRestart;
+    private releaseHttpServerForRestart;
+    private destroyTrackedSockets;
+    private parseUrl;
+}