@syrkos/filaxis 0.1.0-alpha.10

package/src/remote-session-manager.ts

@@ -0,0 +1,286 @@
+/**
+ * remote-session-manager.ts — 远端长跑会话引擎（nohup 双文件落盘 + 终态三态核实）
+ *
+ * 净室设计自 Aethelum-Nexus RemoteSessionManager（源锚 8977ff3）的 OSS 精简重实现：
+ * - 落盘协议直接按 FEAT-04 契约：`<base>.out` / `<base>.err` 双文件 + `<base>.code`
+ *   退出码文件（`{ cmd; }; echo $? > base.code`——nohup 后台进程退出码可核实）
+ * - 终态三态（FEAT-04）：exited（读到 .code）/ stopped（kill 后 kill -0 核实已死）/
+ *   unknown（核实不可达——exec 抛错/网络断）——发送终止≠确认死亡
+ * - watcher 轮询匹配（远端无推送通道，与源版同语义）；行到达序即 tail 读取序
+ * - exec 经注入回调（通常是 driver 的 exec 通道）——本模块零 I/O 假设、可 mock 全测
+ */
+import * as crypto from "node:crypto";
+import { LineAssembler } from "./session-buffer.js";
+import type {
+    SessionStartOptions,
+    SessionHandleInfo,
+    SessionEvent,
+    WatchOptions,
+    ReadLogOptions,
+    SessionFinalStatus,
+} from "./session-types.js";
+import type { ExecResult } from "./driver.js";
+import { noopLogger, type FilaxisLogger } from "./logger.js";
+
+export interface RemoteSessionManagerOptions {
+    /** 执行通道回调（远端命令落点） */
+    exec: (command: string) => Promise<Pick<ExecResult, "stdout" | "exitCode">>;
+    /** 远端会话日志目录（缺省 /tmp/filaxis-sessions） */
+    logDir?: string;
+    /** watcher 轮询间隔（默认 1500ms） */
+    pollMs?: number;
+    /** 无人消费且无 armed watcher 的回收 TTL（缺省 30min；时钟可注入测试） */
+    idleReapMs?: number;
+    logger?: FilaxisLogger;
+}
+
+interface RemoteEntry {
+    sessionId: string;
+    command: string;
+    base: string;
+    pid?: number;
+    startedAt: number;
+    ownerSessionId?: string;
+    running: boolean;
+    exitCode?: number | null;
+    /** 轮询读到的 .out 行偏移 */
+    outOffset: number;
+    assembler: LineAssembler;
+    watchers: Map<string, WatchOptions & { regex: RegExp }>;
+    pollTimer?: ReturnType<typeof setInterval>;
+    lastAttentionAt: number;
+}
+
+const q = (s: string) => `'${s.replace(/'/g, "'\\''")}'`;
+
+export class RemoteSessionManager {
+    onEvent: (ev: SessionEvent) => void = () => undefined;
+
+    private entries = new Map<string, RemoteEntry>();
+    private readonly exec: RemoteSessionManagerOptions["exec"];
+    private readonly logDir: string;
+    private readonly pollMs: number;
+    private readonly idleReapMs?: number;
+    private readonly log: FilaxisLogger;
+
+    constructor(opts: RemoteSessionManagerOptions) {
+        this.exec = opts.exec;
+        this.logDir = opts.logDir ?? "/tmp/filaxis-sessions";
+        this.pollMs = opts.pollMs ?? 1500;
+        this.idleReapMs = opts.idleReapMs;
+        this.log = opts.logger ?? noopLogger;
+    }
+
+    /** 启动远端长跑会话：nohup 双文件落盘 + 退出码文件；立即返回 */
+    async start(command: string, opts: SessionStartOptions = {}): Promise<SessionHandleInfo> {
+        const sessionId =
+            `${opts.name ? opts.name.replace(/[^a-zA-Z0-9_-]/g, "-") + "-" : "rsess-"}` +
+            crypto.randomBytes(4).toString("hex");
+        const base = `${this.logDir}/${sessionId}`;
+        const wrapped = `{ ${command}; }; echo $? > ${base}.code`;
+        const cd = opts.cwd ? `cd ${q(opts.cwd)} && ` : "";
+        // 环境经 env 前缀注入（nohup 继承当前 exec 通道环境）
+        const envPrefix = opts.env
+            ? Object.entries(opts.env).map(([k, v]) => `${k}=${q(v)}`).join(" ") + " "
+            : "";
+        const r = await this.exec(
+            `mkdir -p ${q(this.logDir)}; ${cd}${envPrefix}nohup sh -c ${q(wrapped)} > ${base}.out 2> ${base}.err < /dev/null & echo $!`,
+        );
+        const pid = parseInt((r.stdout || "").trim().split("\n").pop() ?? "", 10);
+
+        const entry: RemoteEntry = {
+            sessionId,
+            command,
+            base,
+            pid: Number.isFinite(pid) ? pid : undefined,
+            startedAt: Date.now(),
+            ownerSessionId: opts.ownerSessionId,
+            running: true,
+            outOffset: 0,
+            assembler: new LineAssembler(),
+            watchers: new Map(),
+            lastAttentionAt: Date.now(),
+        };
+        this.entries.set(sessionId, entry);
+        this.startPolling(entry);
+        this.log.info(`[RemoteSession ${sessionId}] started (pid=${entry.pid}): ${command.slice(0, 60)}`);
+        return { sessionId, logBase: base, pid: entry.pid };
+    }
+
+    /** 热窗口快照（远端 tail .out） */
+    async tail(sessionId: string, n = 50): Promise<string[]> {
+        const e = this.require(sessionId);
+        e.lastAttentionAt = Date.now();
+        const r = await this.exec(`tail -n ${n} ${e.base}.out 2>/dev/null || true`);
+        return (r.stdout || "").split("\n").filter((l, i, arr) => l !== "" || i < arr.length - 1).filter((l) => l !== "");
+    }
+
+    /** 落盘日志读取（按流分读——FEAT-04 双文件） */
+    async readLog(sessionId: string, opts: ReadLogOptions = {}): Promise<string> {
+        const e = this.require(sessionId);
+        const file = opts.stream === "stderr" ? `${e.base}.err` : `${e.base}.out`;
+        let cmd = `cat ${file} 2>/dev/null || true`;
+        if (opts.offsetLines) cmd = `tail -n +${opts.offsetLines + 1} ${file} 2>/dev/null || true`;
+        if (opts.lines) cmd += ` | tail -n ${opts.lines}`;
+        const r = await this.exec(cmd);
+        return (r.stdout || "").replace(/\n$/, "");
+    }
+
+    watch(sessionId: string, opts: WatchOptions): { cancel(): void } {
+        const e = this.require(sessionId);
+        e.lastAttentionAt = Date.now();
+        const id = `rw-${crypto.randomBytes(3).toString("hex")}`;
+        const regex = opts.pattern instanceof RegExp ? opts.pattern : new RegExp(opts.pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+        e.watchers.set(id, { ...opts, regex });
+        return {
+            cancel: () => { e.watchers.delete(id); },
+        };
+    }
+
+    /**
+     * 行对象视图（双流：.out + .err 各取最近 n 行，行对象带 stream 标记）——
+     * observe 工具族用（第五季反馈 #2：此前仅 tail() 投影 stdout，stderr 漏读）
+     */
+    async tailLines(sessionId: string, n = 50): Promise<Array<{ stream: "stdout" | "stderr"; text: string }>> {
+        const e = this.require(sessionId);
+        e.lastAttentionAt = Date.now();
+        const r = await this.exec(`tail -n ${n} ${e.base}.out 2>/dev/null; echo __FX_TL__; tail -n ${n} ${e.base}.err 2>/dev/null`);
+        const parts = (r.stdout || "").split("__FX_TL__");
+        const out: Array<{ stream: "stdout" | "stderr"; text: string }> = [];
+        for (const l of (parts[0] ?? "").split("\n")) {
+            if (l.trim() !== "") out.push({ stream: "stdout", text: l });
+        }
+        for (const l of (parts[1] ?? "").split("\n")) {
+            if (l.trim() !== "") out.push({ stream: "stderr", text: l });
+        }
+        return out;
+    }
+
+    /**
+     * 停止会话：发 kill -TERM → kill -0 核实。核实不可达（exec 抛错）→ 显式 unknown
+     * （终止即请求、死亡须核实——REQ §3.2 细则 6）。
+     */
+    async stop(sessionId: string): Promise<{ status: SessionFinalStatus; exitCode?: number | null }> {
+        const e = this.require(sessionId);
+        if (!e.running) return { status: e.exitCode != null ? "exited" : "stopped", exitCode: e.exitCode };
+        if (e.pid == null) return { status: "unknown" };
+        try {
+            // 第五季盲测反馈 #3：sh -c 的子进程（脚本/守护）收不到主 kill 的 TERM——
+            // pkill -P 杀直接子进程 + kill 主进程；SIGKILL 升级同理
+            await this.exec(`pkill -TERM -P ${e.pid} 2>/dev/null; kill -TERM ${e.pid} 2>/dev/null; sleep 1; kill -0 ${e.pid} 2>/dev/null && echo ALIVE || echo DEAD`);
+            const probe = await this.exec(`kill -0 ${e.pid} 2>/dev/null && echo ALIVE || echo DEAD`);
+            if (probe.stdout.includes("ALIVE")) {
+                await this.exec(`pkill -KILL -P ${e.pid} 2>/dev/null; kill -KILL ${e.pid} 2>/dev/null; true`);
+            }
+            return { status: "stopped" };
+        } catch {
+            return { status: "unknown" };
+        }
+    }
+
+    list(): Array<{ sessionId: string; command: string; running: boolean; startedAt: number }> {
+        return Array.from(this.entries.values()).map((e) => ({
+            sessionId: e.sessionId, command: e.command, running: e.running, startedAt: e.startedAt,
+        }));
+    }
+
+    /** 注意力衰减回收：无人消费且无 armed watcher 超 TTL → 自动收摊 + 事件广播（时钟可注入） */
+    reapIdle(now: number = Date.now(), ttlMs?: number): void {
+        const ttl = ttlMs ?? this.idleReapMs ?? 30 * 60 * 1000;
+        for (const e of Array.from(this.entries.values())) {
+            if (!e.running) continue;
+            if (e.watchers.size > 0) continue; // armed watcher = 常驻注意力
+            if (now - e.lastAttentionAt < ttl) continue;
+            this.emit({
+                type: "exit", sessionId: e.sessionId, ownerSessionId: e.ownerSessionId,
+                exitCode: null, lastLines: [],
+            });
+            void this.stop(e.sessionId).catch(() => undefined);
+        }
+    }
+
+    // ── 内部 ──
+
+    private require(sessionId: string): RemoteEntry {
+        const e = this.entries.get(sessionId);
+        if (!e) throw new Error(`remote session '${sessionId}' 不存在`);
+        return e;
+    }
+
+    private startPolling(entry: RemoteEntry): void {
+        entry.pollTimer = setInterval(() => void this.poll(entry).catch(() => undefined), this.pollMs);
+        entry.pollTimer.unref?.();
+    }
+
+    /** 轮询：增量读 .out 喂 watcher；读 .code 判定终态 */
+    private async poll(entry: RemoteEntry): Promise<void> {
+        if (!entry.running) return;
+        try {
+            // 增量输出（watcher 匹配用）
+            const r = await this.exec(
+                `tail -n +${entry.outOffset + 1} ${entry.base}.out 2>/dev/null || true`,
+            );
+            const text = r.stdout || "";
+            if (text) {
+                entry.outOffset += text.split("\n").filter((l, i, a) => i < a.length - 1 || l !== "").length;
+                for (const line of entry.assembler.feed(text)) this.onLine(entry, line);
+            }
+            // 终态：.code 文件在场 = 进程已退出（nohup 包装的 echo 已落盘）
+            const code = await this.exec(`cat ${entry.base}.code 2>/dev/null || true`);
+            const codeStr = (code.stdout || "").trim();
+            if (codeStr !== "" && /^\d+$/.test(codeStr)) {
+                this.finalize(entry, parseInt(codeStr, 10));
+            } else if (entry.pid != null) {
+                // 无 .code 但进程没了（被外部 kill -9）→ unknown 退出码
+                const alive = await this.exec(`kill -0 ${entry.pid} 2>/dev/null && echo Y || echo N`);
+                if (alive.stdout.includes("N")) this.finalize(entry, null);
+            }
+        } catch {
+            /* 轮询失败（exec 通道断）——下轮再试；终态核实属 stop()/result() 职责 */
+        }
+    }
+
+    private onLine(entry: RemoteEntry, line: string): void {
+        for (const [id, w] of entry.watchers) {
+            if (w.regex.test(line)) {
+                if (w.once !== false) entry.watchers.delete(id);
+                if (w.thenStop) void this.stop(entry.sessionId).catch(() => undefined);
+                this.emit({
+                    type: "match",
+                    sessionId: entry.sessionId,
+                    ownerSessionId: entry.ownerSessionId,
+                    watcherId: id,
+                    pattern: String(w.pattern),
+                    matchedLine: line,
+                    stream: "stdout",
+                    context: [line],
+                });
+                entry.lastAttentionAt = Date.now();
+            }
+        }
+    }
+
+    private finalize(entry: RemoteEntry, exitCode: number | null): void {
+        if (!entry.running) return;
+        entry.running = false;
+        entry.exitCode = exitCode;
+        if (entry.pollTimer) clearInterval(entry.pollTimer);
+        entry.watchers.clear();
+        this.emit({
+            type: "exit",
+            sessionId: entry.sessionId,
+            ownerSessionId: entry.ownerSessionId,
+            exitCode,
+            lastLines: [],
+        });
+        this.log.info(`[RemoteSession ${entry.sessionId}] exited code=${exitCode}`);
+    }
+
+    private emit(ev: SessionEvent): void {
+        try {
+            this.onEvent(ev);
+        } catch (err) {
+            this.log.warn(`remote session event sink threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/src/runtime-stack.ts

@@ -0,0 +1,128 @@
+/**
+ * runtime-stack.ts — 栈门面：连接拓扑指纹缓存 + Transport 注册 + 能力探测
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/runtime-stack.ts`
+ * （源锚 8977ff3，仅取内核性——list/promptSummary 展示层留消费方），OSS 化：
+ * - driverKey 连接拓扑指纹平移（身份白名单投影；enterSteps 待 ssh Transport 批次并入键）
+ * - 内核事件总线（FEAT-09，EventBus）
+ * - features() 能力探测（AC-02：降级不靠猜——mux/sftp/persistent 按平台与二进制探测）
+ */
+import { spawn } from "node:child_process";
+import type { RuntimeDriver, RuntimeDescriptor } from "./driver.js";
+import { RuntimeFactory } from "./factory.js";
+import { EventBus } from "./events.js";
+import type { SessionEvent } from "./session-types.js";
+import { noopLogger, type FilaxisLogger } from "./logger.js";
+
+export type FilaxisEvents = SessionEvent | { type: "layerState"; layer: string; state: string };
+
+export interface StackFeatures {
+    /** ControlMaster 多路复用可用（非 Windows + ssh 二进制存在） */
+    mux: boolean;
+    /** sftp 大文件快路径可用 */
+    sftp: boolean;
+    /** tmux 持久会话后端可用（缺席 → 持久层显式降级非持久） */
+    persistent: boolean;
+    /** 已注册 Transport 类型 */
+    transports: string[];
+    /** exec 通道 stderr 物理分离（平台默认；远端层的逐层标注属 driver 属性） */
+    stderrSeparated: boolean;
+}
+
+export interface RuntimeStackOptions {
+    logger?: FilaxisLogger;
+    factory?: RuntimeFactory;
+}
+
+export class RuntimeStack {
+    /** 进程级驱动缓存：同连接拓扑指纹复用既有连接（杜绝孤儿/重复建连） */
+    private static driverCache = new Map<string, RuntimeDriver>();
+
+    readonly events = new EventBus<FilaxisEvents>();
+    private readonly factory: RuntimeFactory;
+    private readonly log: FilaxisLogger;
+    private featuresCache: StackFeatures | null = null;
+
+    constructor(opts: RuntimeStackOptions = {}) {
+        this.factory = opts.factory ?? new RuntimeFactory();
+        this.log = opts.logger ?? noopLogger;
+    }
+
+    /**
+     * 连接拓扑指纹（净室移植自源版 driverKey，身份白名单投影）：
+     * 显示标签/运行态缓存等非身份字段不进键——不把既有连接挤出缓存、不误建重复连接。
+     * 注：ssh 层的 enterSteps 管线属 ssh Transport 批次，届时并入 cfg 投影。
+     */
+    static driverKey(d: RuntimeDescriptor): string {
+        const c = (d.config ?? {}) as Record<string, unknown>;
+        return JSON.stringify({
+            driver: d.driver,
+            target: d.target,
+            terminalId: d.terminalId,
+            cwd: d.cwd,
+            capabilities: d.capabilities,
+            cfg: {
+                launchCmd: c.launchCmd,
+                runtime: c.runtime,
+                shell: c.shell,
+                namespace: c.namespace,
+                sshOptions: c.sshOptions,
+                connParams: c.connParams,
+            },
+        });
+    }
+
+    /** 建立层连接：指纹命中即复用（AC-07 连接计数语义） */
+    async connect(descriptor: RuntimeDescriptor, fallbackCwd?: string): Promise<RuntimeDriver> {
+        const key = RuntimeStack.driverKey(descriptor);
+        const cached = RuntimeStack.driverCache.get(key);
+        if (cached) {
+            this.log.debug(`[Filaxis] 指纹命中复用连接: ${descriptor.driver}/${descriptor.target ?? "local"}`);
+            return cached;
+        }
+        const drv = this.factory.create(descriptor, fallbackCwd);
+        await drv.init();
+        RuntimeStack.driverCache.set(key, drv);
+        this.log.info(`[Filaxis] 新建连接: ${descriptor.driver}/${descriptor.target ?? "local"}`);
+        return drv;
+    }
+
+    /** 逐出缓存（销毁归调用方——先 evict 再 destroy，避免销毁竞态复用） */
+    static evictDriver(d: RuntimeDescriptor): RuntimeDriver | undefined {
+        const key = RuntimeStack.driverKey(d);
+        const drv = RuntimeStack.driverCache.get(key);
+        RuntimeStack.driverCache.delete(key);
+        return drv;
+    }
+
+    /** 开放注册（透传 factory；AC-09 第三方 Transport 同权） */
+    registerDriver(type: string, f: (descriptor: RuntimeDescriptor) => RuntimeDriver): void {
+        this.factory.registerDriver(type, f);
+        this.featuresCache = null;
+    }
+
+    /**
+     * 能力探测（AC-02：降级不靠猜）。结果缓存至注册表变化。
+     * Windows 无 ControlMaster → mux=false（自动退化直连为既定行为）。
+     */
+    async features(): Promise<StackFeatures> {
+        if (this.featuresCache) return this.featuresCache;
+        const has = (bin: string) =>
+            new Promise<boolean>((resolve) => {
+                const probe = process.platform === "win32"
+                    ? spawn("where", [bin], { stdio: "ignore" })
+                    : spawn("which", [bin], { stdio: "ignore" });
+                probe.on("close", (code) => resolve(code === 0));
+                probe.on("error", () => resolve(false));
+            });
+        const [sshOk, sftpOk, tmuxOk] = await Promise.all([has("ssh"), has("sftp"), has("tmux")]);
+        this.featuresCache = {
+            mux: process.platform !== "win32" && sshOk,
+            sftp: sftpOk,
+            persistent: tmuxOk,
+            transports: this.factory.registeredTypes(),
+            stderrSeparated: true,
+        };
+        return this.featuresCache;
+    }
+}

package/src/session-buffer.ts

@@ -0,0 +1,183 @@
+/**
+ * session-buffer.ts — 会话窗口基础件（纯逻辑，无 I/O）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/session-buffer.ts`
+ * （源锚点：Aethelum-Nexus dev @ 8977ff3）。
+ *
+ * LineAssembler     字节流按 \n 组行（CRLF 剥 \r；partial 暂存；flush 收尾）
+ * OutputRingBuffer  热窗口：maxLines × maxLineBytes 截断；截断仅发生在窗口副本
+ *                   ——落盘文件侧由调用方写完整行
+ *                   OSS 扩展（REQ-0001 FEAT-11）：evictedCount 逐出计数——
+ *                   ready() 滚出感知「有据」的机制件（>0 = 窗口历史不完整）
+ * WatchRegistry     行级 watcher：string=子串 / RegExp 命中；once 默认；每会话上限
+ */
+
+/** 无换行极端流的暂存硬上限（防 OOM）：超限强制切块成行 */
+const MAX_PENDING_BYTES = 2 * 1024 * 1024;
+
+export class LineAssembler {
+    private pending = '';
+
+    /** 喂入一段输出，返回其中已成行的部分（不含尾部的 partial） */
+    feed(chunk: string): string[] {
+        this.pending += chunk;
+        const lines: string[] = [];
+        let idx: number;
+        while ((idx = this.pending.indexOf('\n')) !== -1) {
+            let line = this.pending.slice(0, idx);
+            if (line.endsWith('\r')) line = line.slice(0, -1);
+            lines.push(line);
+            this.pending = this.pending.slice(idx + 1);
+        }
+        // 硬上限：极端无换行字节流强制切块（如失控输出/二进制误入），插入截断标记
+        if (this.pending.length > MAX_PENDING_BYTES) {
+            lines.push(this.pending.slice(0, MAX_PENDING_BYTES) + '[TRUNCATED_CHUNK]');
+            this.pending = '';
+        }
+        return lines;
+    }
+
+    /** 进程退出时调用：无换行的残余强制成行 */
+    flush(): string[] {
+        if (this.pending === '') return [];
+        const rest = this.pending.endsWith('\r') ? this.pending.slice(0, -1) : this.pending;
+        this.pending = '';
+        return rest === '' ? [] : [rest];
+    }
+}
+
+export interface RingBufferOptions {
+    maxLines?: number;
+    maxLineBytes?: number;
+}
+
+const TRUNC_SUFFIX = '[…truncated, see session log]';
+
+/** 输出流标记（定义于 session-types，此处 re-export 便利用户） */
+export type { OutputStream } from "./session-types.js";
+import type { OutputStream } from "./session-types.js";
+
+/** 热窗口行对象：跨流聚合序为到达序（不承诺进程真实写入序——REQ §3.2） */
+export interface SessionLine {
+    stream: OutputStream;
+    text: string;
+}
+
+export class OutputRingBuffer {
+    private readonly maxLines: number;
+    private readonly maxLineBytes: number;
+    private lines: SessionLine[] = [];
+    private evictedLines = 0;
+
+    constructor(opts: RingBufferOptions = {}) {
+        this.maxLines = opts.maxLines ?? 50;
+        this.maxLineBytes = opts.maxLineBytes ?? 512;
+    }
+
+    /** 完整行入窗（窗口侧按 maxLineBytes 硬截断 text 含标记；文件侧由调用方写原行） */
+    push(line: SessionLine): void {
+        let text = line.text;
+        if (text.length > this.maxLineBytes) {
+            // OSS 边界修复（源实现 bug）：源版 slice(0, maxLineBytes - suffix.length)
+            // 在 maxLineBytes < 后缀长度时为负索引，行为反转（越截越长）。keep 下限 0
+            // 保截断标记；此时行长为后缀长度（29）恒定，防 OOM 语义不破。
+            const keep = Math.max(0, this.maxLineBytes - TRUNC_SUFFIX.length);
+            text = text.slice(0, keep) + TRUNC_SUFFIX;
+        }
+        this.lines.push({ stream: line.stream, text });
+        if (this.lines.length > this.maxLines) {
+            const overflow = this.lines.length - this.maxLines;
+            this.lines = this.lines.slice(-this.maxLines);
+            this.evictedLines += overflow;
+        }
+    }
+
+    /** 最近 n 行的 text 投影（简洁消费） */
+    tail(n: number): string[] {
+        return this.lines.slice(-Math.max(0, n)).map((l) => l.text);
+    }
+
+    /** 最近 n 行对象（带 stream 标记——FEAT-05 按流过滤迭代用） */
+    tailLines(n: number): SessionLine[] {
+        return this.lines.slice(-Math.max(0, n));
+    }
+
+    /**
+     * 自创建以来被挤出窗口的行数（FEAT-11 滚出感知有据）：
+     * 0 = 窗口历史完整（标记若出现过必仍在窗内）；>0 = 历史可能不完整。
+     */
+    get evictedCount(): number {
+        return this.evictedLines;
+    }
+
+    /**
+     * 命中行 ± contextLines 的上下文切片（索引相对当前窗口，越界收敛）。
+     * 供 watcher 命中时组装通知上下文。
+     */
+    contextAround(index: number, contextLines: number): SessionLine[] {
+        const from = Math.max(0, index - contextLines);
+        const to = Math.min(this.lines.length, index + contextLines + 1);
+        return this.lines.slice(from, to);
+    }
+
+    /** 命中行的窗口索引（按 text 查找；找不到回退末行）——watch 上下文组装用 */
+    indexOfLine(text: string): number {
+        const i = this.lines.findIndex((l) => l.text === text);
+        return i === -1 ? this.lines.length - 1 : i;
+    }
+
+    get size(): number {
+        return this.lines.length;
+    }
+}
+
+export interface WatcherSpec {
+    id: string;
+    pattern: string | RegExp;
+    /** 命中一次即摘除（默认 true） */
+    once?: boolean;
+}
+
+interface WatcherEntry extends WatcherSpec {
+    regex: RegExp;
+}
+
+const MAX_WATCHERS_PER_SESSION = 8;
+
+export class WatchRegistry {
+    private watchers = new Map<string, WatcherEntry>();
+
+    add(spec: WatcherSpec): void {
+        if (this.watchers.size >= MAX_WATCHERS_PER_SESSION) {
+            throw new Error(`watcher 数量已达上限（${MAX_WATCHERS_PER_SESSION}/会话），先 cancel 旧的再注册`);
+        }
+        this.watchers.set(spec.id, { ...spec, regex: this.toRegex(spec.pattern) });
+    }
+
+    /** 匹配一行，返回命中的 watcher id（once 的命中即摘除） */
+    match(line: string): string[] {
+        const hits: string[] = [];
+        for (const [id, w] of this.watchers) {
+            if (w.regex.test(line)) {
+                hits.push(id);
+                if (w.once !== false) this.watchers.delete(id);
+            }
+        }
+        return hits;
+    }
+
+    cancel(id: string): boolean {
+        return this.watchers.delete(id);
+    }
+
+    get size(): number {
+        return this.watchers.size;
+    }
+
+    private toRegex(pattern: string | RegExp): RegExp {
+        if (pattern instanceof RegExp) return pattern;
+        // string 模式 = 子串语义：全文转义
+        const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(escaped);
+    }
+}

package/src/session-types.ts

@@ -0,0 +1,78 @@
+/**
+ * session-types.ts — 会话生命周期公共类型
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/local-session-manager.ts`
+ * 类型段（源锚点：Aethelum-Nexus dev @ 8977ff3），按 REQ-0001 OSS 化裁剪：
+ * - 剔除 notifyQueue（通知路由目标队列——消息队列路由属消费方桥，内核零队列红线）
+ * - ownerSessionId 保留（纯透传的归属上下文 ID，无业务语义负载）
+ * - 新增终态三态 SessionFinalStatus（FEAT-04：终止即请求、死亡须核实）
+ */
+
+export interface SessionStartOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** 会话名（sessionId 前缀，便于人读） */
+    name?: string;
+    /** 归属上下文 ID（事件通知时原样透传，供调用方关联自己的任务/请求） */
+    ownerSessionId?: string;
+}
+
+export interface SessionHandleInfo {
+    sessionId: string;
+    /** 落盘日志基名——实际双文件 `<logBase>.out` / `<logBase>.err`（FEAT-04 双文件协议） */
+    logBase: string;
+    pid?: number;
+}
+
+/**
+ * 会话终态三态（FEAT-04 / REQ §3.2 细则 6）：
+ * - exited   收到进程退出码（自然退出或终止后的确认退出）
+ * - stopped  终止请求已发出且清理核实通过
+ * - unknown  核实不可达（SSH 断线/网络分区/核实超时）——显式暴露，严禁当成功
+ */
+export type SessionFinalStatus = "exited" | "stopped" | "unknown";
+
+export interface SessionFinalState {
+    status: SessionFinalStatus;
+    exitCode?: number;
+}
+
+export type SessionEvent =
+    | {
+          type: "match";
+          sessionId: string;
+          watcherId: string;
+          pattern: string;
+          matchedLine: string;
+          /** 命中行所属流（FEAT-04/05 双流标记） */
+          stream: "stdout" | "stderr";
+          context: string[];
+          /** 归属上下文（调用方透传） */
+          ownerSessionId?: string;
+      }
+    | { type: "exit"; sessionId: string; exitCode: number | null; lastLines: string[]; ownerSessionId?: string };
+
+export interface WatchOptions {
+    pattern: string | RegExp;
+    /** 命中携带 命中行 ± N 行，默认 5 */
+    contextLines?: number;
+    /** 命中一次即摘除（默认 true） */
+    once?: boolean;
+    /**
+     * 命中即收摊：watcher 命中后自动 stop 会话——「观察对象结束 → 观察者退场」
+     * 从模型自觉变机制。观察型会话（tail -f 等永不退出的流）尤其需要，防遗忘泄漏。
+     */
+    thenStop?: boolean;
+}
+
+/** 输出流标记（FEAT-04/05：双流行对象——stdout/stderr 物理分离） */
+export type OutputStream = "stdout" | "stderr";
+
+export interface ReadLogOptions {
+    /** 取最近 N 行（缺省=全量） */
+    lines?: number;
+    /** 自文件头跳过 N 行 */
+    offsetLines?: number;
+    /** 读哪条流的落盘文件（FEAT-04 双文件协议；缺省 "stdout"） */
+    stream?: OutputStream;
+}