@syrkos/filaxis 0.1.0-alpha.10

package/src/stream-session-manager.ts

@@ -0,0 +1,296 @@
+/**
+ * stream-session-manager.ts — 观察流会话引擎（手眼分离：观察走独立真流式 channel）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/tools/runtime/session/stream-session-manager.ts`
+ * （源锚 8977ff3），按 REQ-0001 OSS 化改造：
+ * - SessionNotifier 队列投递 → onEvent 纯回调（内核零队列红线）
+ * - stderr 双流（FEAT-05）：源版刻意并入同一窗口——OSS 版行对象带 stream 标记，
+ *   onLine 桥与热窗口均按流可辨
+ * - spawn 注入化（spawnImpl）——零 I/O 假设，mock 全测（AC-06 逻辑面）
+ *
+ * 设计语义（源生产锤炼）：
+ *   - 每个观察流 = 一条独立 SSH channel 子进程（stdout 逐行直推本地，
+ *     无轮询、无漏行）；ControlMaster 多路复用共享主连接（连接是稀缺资源——
+ *     观察是廉价的）；Windows 无 mux 支持时自动退化直连
+ *   - 注意力衰减回收：无人问津且无 armed watcher 超 TTL → 自动收摊 + 事件广播
+ *   - 桥接消费方（onLine/onExit）异常不杀流
+ */
+import * as crypto from "node:crypto";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { spawn, type ChildProcess } from "node:child_process";
+import { OutputRingBuffer, WatchRegistry, type SessionLine } from "./session-buffer.js";
+import { Vt100Screen } from "./vt100-screen.js";
+import type { SessionEvent } from "./session-types.js";
+import { noopLogger, type FilaxisLogger } from "./logger.js";
+
+export interface StreamStartOptions {
+    name?: string;
+    ownerSessionId?: string;
+    /** 建立即挂 watcher（真流式命中——无需等轮询） */
+    watchPattern?: string;
+    watchOnce?: boolean;
+    contextLines?: number;
+    /** 观察窗流桥：每行对象原样回调（截断/入窗由窗侧自理） */
+    onLine?: (line: SessionLine) => void;
+    /** 流进程退出回调（观察窗 stale 语义） */
+    onExit?: (exitCode: number | null) => void;
+    /**
+     * TUI 屏桥（第五季灵感）：原始 chunk（含 ANSI 转义）喂 Vt100Screen 后回调
+     * snapshot（每 chunk 一帧——ncurses 增量包一包一帧）。观察 watch/htop/nvtop
+     * 这类无换行的全屏重绘流用 onScreen 截屏，行流用 onLine——两桥可并存。
+     */
+    onScreen?: (snap: string, frames: number) => void;
+}
+
+export type SpawnImpl = (cmd: string, argv: string[], opts: { stdio: unknown[] }) => ChildProcess;
+
+export interface StreamSessionManagerOptions {
+    /** 禁用 ControlMaster（测试/平台受限） */
+    disableMux?: boolean;
+    /** 无人消费且无 armed watcher 的回收 TTL（默认 30min；测试可注入短值） */
+    idleReapMs?: number;
+    /** spawn 注入（缺省 node:child_process.spawn）——mock 全测关键 */
+    spawnImpl?: SpawnImpl;
+    /** mux socket 目录（缺省 os.tmpdir()/filaxis-stream-mux） */
+    muxDir?: string;
+    logger?: FilaxisLogger;
+}
+
+/** 主连接注册表：destKey → ControlPath socket（进程级共享） */
+const masters = new Map<string, { path: string; refCount: number }>();
+
+export class StreamSessionManager {
+    onEvent: (ev: SessionEvent) => void = () => undefined;
+
+    private entries = new Map<string, StreamEntry>();
+    private readonly destKey: string;
+    private readonly destArgs: string[];
+    private readonly muxEnabled: boolean;
+    private readonly idleReapMs?: number;
+    private readonly spawnImpl: SpawnImpl;
+    private readonly muxDir: string;
+    private readonly log: FilaxisLogger;
+
+    private static readonly DEFAULT_IDLE_REAP_MS = 30 * 60 * 1000;
+
+    constructor(destArgs: string[], opts: StreamSessionManagerOptions = {}) {
+        this.destArgs = destArgs;
+        this.destKey = crypto.createHash("sha256").update(destArgs.join("\x00")).digest("hex").slice(0, 16);
+        // Windows OpenSSH 无 ControlMaster 支持（known limitation）——退化直连
+        this.muxEnabled = !opts.disableMux && process.platform !== "win32";
+        this.idleReapMs = opts.idleReapMs;
+        this.spawnImpl = opts.spawnImpl ?? ((cmd, argv, o) => spawn(cmd, argv, o as never) as ChildProcess);
+        this.muxDir = opts.muxDir ?? join(tmpdir(), "filaxis-stream-mux");
+        this.log = opts.logger ?? noopLogger;
+    }
+
+    /** ControlMaster flags：auto + Persist（首条流顺带建立主连接，无独立 -MNf 步骤） */
+    private muxFlags(): string[] {
+        if (!this.muxEnabled) return [];
+        let m = masters.get(this.destKey);
+        if (!m) {
+            m = { path: join(this.ensureMuxDir(), `cm-${this.destKey}`), refCount: 0 };
+            masters.set(this.destKey, m);
+        }
+        return [
+            "-o", `ControlPath=${m.path}`,
+            "-o", "ControlMaster=auto",
+            "-o", "ControlPersist=600", // 最后一条流关闭后主连接保留 10min（复用窗口）
+        ];
+    }
+
+    private ensureMuxDir(): string {
+        if (!existsSync(this.muxDir)) mkdirSync(this.muxDir, { recursive: true });
+        return this.muxDir;
+    }
+
+    /** 建立观察流：真流式子进程，stdout/stderr 双流逐行进 ring/watcher */
+    async start(command: string, opts: StreamStartOptions = {}): Promise<{ sessionId: string; name?: string }> {
+        const sessionId = `${opts.name ?? "stream"}-${crypto.randomBytes(3).toString("hex")}`;
+        const argv = ["-o", "StrictHostKeyChecking=accept-new", "-o", "ConnectTimeout=10",
+            ...this.muxFlags(), ...this.destArgs, "--", command];
+        const child = this.spawnImpl("ssh", argv, { stdio: ["ignore", "pipe", "pipe"] });
+
+        const entry: StreamEntry = {
+            sessionId, name: opts.name, command, destKey: this.destKey, child,
+            ring: new OutputRingBuffer({ maxLines: 50, maxLineBytes: 512 }),
+            watchers: new WatchRegistry(),
+            watcherMeta: new Map(),
+            startedAt: Date.now(),
+            running: true,
+            lastAttentionAt: Date.now(),
+            ownerSessionId: opts.ownerSessionId,
+            opts,
+        };
+        this.entries.set(sessionId, entry);
+        const m = masters.get(this.destKey);
+        if (m) m.refCount++;
+
+        child.stdout?.on("data", (d: Buffer) => {
+            const text = d.toString("utf-8");
+            if (entry.opts?.onScreen) {
+                if (!entry.screen) entry.screen = new Vt100Screen();
+                entry.screen.feed(text);
+                try { entry.opts.onScreen(entry.screen.snapshot(), entry.screen.frames); } catch { /* 桥异常不杀流 */ }
+            }
+            this.onChunk(entry, text, "stdout");
+        });
+        child.stderr?.on("data", (d: Buffer) => this.onChunk(entry, d.toString("utf-8"), "stderr"));
+        child.on("exit", (code) => {
+            if (!entry.running) return;
+            entry.running = false;
+            entry.exitCode = code;
+            try { opts.onExit?.(code); } catch { /* 桥接消费方异常不杀流 */ }
+            this.emit({
+                type: "exit", sessionId, ownerSessionId: opts.ownerSessionId,
+                exitCode: code, lastLines: entry.ring.tail(10),
+            });
+            this.releaseMaster();
+        });
+        child.on("error", (err) => {
+            entry.running = false;
+            this.emit({
+                type: "exit", sessionId, ownerSessionId: opts.ownerSessionId,
+                exitCode: null, lastLines: [err.message],
+            });
+            this.releaseMaster();
+        });
+
+        if (opts.watchPattern) {
+            this.watch(sessionId, {
+                pattern: opts.watchPattern, once: opts.watchOnce ?? true, contextLines: opts.contextLines,
+            });
+        }
+        this.log.info(`[StreamSession ${sessionId}] 流建立（mux=${this.muxEnabled}）`);
+        return { sessionId, name: opts.name };
+    }
+
+    /** 流式 watcher：行到达即匹配（真流，无轮询间隔） */
+    watch(sessionId: string, opts: { pattern: string | RegExp; once?: boolean; contextLines?: number }): { cancel(): void } {
+        const e = this.require(sessionId);
+        e.lastAttentionAt = Date.now();
+        const watcherId = `sw-${crypto.randomBytes(3).toString("hex")}`;
+        e.watchers.add({ id: watcherId, pattern: opts.pattern, once: opts.once });
+        e.watcherMeta.set(watcherId, { pattern: opts.pattern, contextLines: opts.contextLines, once: opts.once });
+        return {
+            cancel: () => {
+                e.watchers.cancel(watcherId);
+                e.watcherMeta.delete(watcherId);
+            },
+        };
+    }
+
+    tail(sessionId: string, n = 50): string[] {
+        const e = this.require(sessionId);
+        e.lastAttentionAt = Date.now();
+        return e.ring.tail(n);
+    }
+
+    /** 行对象视图（带 stream 标记——FEAT-05 按流过滤） */
+    tailLines(sessionId: string, n = 50): SessionLine[] {
+        const e = this.require(sessionId);
+        e.lastAttentionAt = Date.now();
+        return e.ring.tailLines(n);
+    }
+
+    stop(sessionId: string): void {
+        const e = this.require(sessionId);
+        e.running = false;
+        e.child.kill("SIGTERM");
+        this.entries.delete(sessionId);
+        this.log.info(`[StreamSession ${sessionId}] 已收摊`);
+    }
+
+    list(): Array<{ sessionId: string; name?: string; command: string; running: boolean; idleMs: number; armedWatchers: number }> {
+        const now = Date.now();
+        return Array.from(this.entries.values()).map((e) => ({
+            sessionId: e.sessionId, name: e.name, command: e.command,
+            running: e.running, idleMs: now - e.lastAttentionAt, armedWatchers: e.watcherMeta.size,
+        }));
+    }
+
+    /** 注意力衰减回收（时钟可注入——测试用）；armed watcher = 常驻注意力不回收 */
+    reapIdle(now: number = Date.now(), ttlMs?: number): void {
+        const ttl = ttlMs ?? this.idleReapMs ?? StreamSessionManager.DEFAULT_IDLE_REAP_MS;
+        for (const e of Array.from(this.entries.values())) {
+            if (!e.running) continue;
+            if (e.watcherMeta.size > 0) continue;
+            if (now - e.lastAttentionAt < ttl) continue;
+            this.log.warn(`[StreamSession ${e.sessionId}] 注意力衰减：自动回收`);
+            this.emit({
+                type: "exit", sessionId: e.sessionId, ownerSessionId: e.ownerSessionId,
+                exitCode: null, lastLines: e.ring.tail(5),
+            });
+            this.stop(e.sessionId);
+        }
+    }
+
+    private onChunk(entry: StreamEntry, text: string, stream: "stdout" | "stderr"): void {
+        for (const raw of text.split("\n")) {
+            if (raw === "") continue;
+            const clean = raw.replace(/\r$/, "");
+            entry.ring.push({ stream, text: clean });
+            try { entry.opts?.onLine?.({ stream, text: clean }); } catch { /* 桥接异常不杀流 */ }
+            const anchor = entry.ring.size - 1;
+            for (const watcherId of entry.watchers.match(clean)) {
+                entry.lastAttentionAt = Date.now(); // 命中=被消费的注意力
+                const meta = entry.watcherMeta.get(watcherId);
+                entry.watcherMeta.delete(watcherId);
+                this.emit({
+                    type: "match",
+                    sessionId: entry.sessionId,
+                    ownerSessionId: entry.ownerSessionId,
+                    watcherId,
+                    pattern: String(meta?.pattern ?? "?"),
+                    matchedLine: clean,
+                    stream,
+                    context: entry.ring.contextAround(anchor, meta?.contextLines ?? 5).map((l) => l.text),
+                } as SessionEvent);
+            }
+        }
+    }
+
+    private releaseMaster(): void {
+        const m = masters.get(this.destKey);
+        if (!m) return;
+        m.refCount = Math.max(0, m.refCount - 1);
+        if (m.refCount === 0 && this.entries.size === 0 && existsSync(m.path)) {
+            try { rmSync(m.path, { force: true }); } catch { /* 并发流重建 socket，容忍 */ }
+        }
+    }
+
+    private require(sessionId: string): StreamEntry {
+        const e = this.entries.get(sessionId);
+        if (!e) throw new Error(`stream 会话 '${sessionId}' 不存在`);
+        return e;
+    }
+
+    private emit(ev: SessionEvent): void {
+        try {
+            this.onEvent(ev);
+        } catch (err) {
+            this.log.warn(`stream event sink threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+
+interface StreamEntry {
+    sessionId: string;
+    name?: string;
+    command: string;
+    destKey: string;
+    child: ChildProcess;
+    ring: OutputRingBuffer;
+    watchers: WatchRegistry;
+    watcherMeta: Map<string, { pattern: string | RegExp; contextLines?: number; once?: boolean }>;
+    startedAt: number;
+    running: boolean;
+    lastAttentionAt: number;
+    ownerSessionId?: string;
+    exitCode?: number | null;
+    opts?: StreamStartOptions;
+    /** TUI 虚拟屏（onScreen 存在时惰性建） */
+    screen?: Vt100Screen;
+}

package/src/stream-window.ts

@@ -0,0 +1,309 @@
+/**
+ * stream-window.ts — 流式观察窗（远端拉模式流反转为本地推模式滚动窗）
+ *
+ * 净室平移自 Aethelum-Nexus `src/core/stream/stream-window.ts`
+ * （源锚 8977ff3）。OSS 化：logger 注入；引擎接 filaxis StreamSessionManager
+ * （onLine 行对象→text 投影）；local 窗 spawn 弃 shell:true（Windows cmd 会挂
+ * unix 命令）改 shell -c 与 exec 一致。
+ *
+ * 关键语义（源施工图定案，全保）：
+ * - 帧编号 per-window 单调递增，断连续编不归零（断点续读正确性依赖）
+ * - 双限缓冲：帧数环形覆盖（滚动=设计行为）+ 单帧字节截断
+ * - peek 三模式（last / window 时间窗 / since 增量），全部非破坏读
+ * - 多消费者游标：consumer_id → last_seq，互不干扰
+ * - 断流 stale 窗保留全部帧；重连续编；关窗收割流进程
+ * - 窗纯内存缓冲（不走消息路由——消费方自行桥接）
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { StreamSessionManager } from "./stream-session-manager.js";
+import { resolveLocalShell } from "./shell-discovery.js";
+import { noopLogger, type FilaxisLogger } from "./logger.js";
+
+/** 单帧截断后缀（与 session-buffer.ts TRUNC_SUFFIX 同语义） */
+const TRUNC_SUFFIX = "…[truncated]";
+
+export interface StreamFrame {
+    seq: number;
+    /** 帧到达本地时刻（时钟域统一本地） */
+    ts: number;
+    text: string;
+}
+
+export interface PeekResult {
+    name: string;
+    oldestSeq: number;
+    newestSeq: number;
+    stale: boolean;
+    frames: StreamFrame[];
+    /** since 模式且中间发生环形覆盖时置 true（空洞显式可见，不静默） */
+    gap?: boolean;
+}
+
+type Transport =
+    | { kind: "local"; child: ChildProcess }
+    | { kind: "remote"; manager: StreamSessionManager; sessionId: string };
+
+export class StreamWindow {
+    private frames: StreamFrame[] = [];
+    private nextSeq = 1;
+    private _stale = false;
+    private _closed = false;
+    private readonly consumers = new Map<string, number>();
+    private transport: Transport | null = null;
+    private lastActivityAt = Date.now();
+
+    constructor(
+        readonly name: string,
+        readonly layerAlias: string,
+        readonly source: string,
+        readonly command: string,
+        private readonly maxFrames = 200,
+        private readonly maxLineBytes = 1024,
+    ) {}
+
+    get stale(): boolean { return this._stale; }
+    get closed(): boolean { return this._closed; }
+    get frameCount(): number { return this.frames.length; }
+    get oldestSeq(): number { return this.frames.length ? this.frames[0]!.seq : 0; }
+    get newestSeq(): number { return this.frames.length ? this.frames[this.frames.length - 1]!.seq : 0; }
+    get lastActiveAt(): number { return this.lastActivityAt; }
+
+    /** 行入窗（截断+环形覆盖；不更新消费者游标——游标只在 peek since 时推进） */
+    push(text: string): void {
+        if (this._closed) return;
+        let line = text;
+        if (line.length > this.maxLineBytes) {
+            line = line.slice(0, this.maxLineBytes - TRUNC_SUFFIX.length) + TRUNC_SUFFIX;
+        }
+        this.frames.push({ seq: this.nextSeq++, ts: Date.now(), text: line });
+        if (this.frames.length > this.maxFrames) {
+            this.frames = this.frames.slice(-this.maxFrames);
+        }
+        this._stale = false; // 新帧到达 = 流复活
+        this.lastActivityAt = Date.now();
+    }
+
+    /** 最近 n 帧 */
+    peekLast(n = 20): PeekResult {
+        return this.snapshot(this.frames.slice(-Math.max(0, n)));
+    }
+
+    /** 最近 ms 毫秒内的帧 */
+    peekWindow(ms: number): PeekResult {
+        const cutoff = Date.now() - ms;
+        const frames = this.frames.filter((f) => f.ts >= cutoff);
+        return this.snapshot(frames);
+    }
+
+    /**
+     * 增量断点续读：返回 > sinceSeq 的帧（上限 n 兜底）。
+     * 带 consumerId 时推进该消费者游标；中间覆盖（oldestSeq > sinceSeq+1）置 gap。
+     */
+    peekSince(sinceSeq: number, n = 50, consumerId?: string): PeekResult {
+        const frames = this.frames.filter((f) => f.seq > sinceSeq).slice(0, Math.max(0, n));
+        const result = this.snapshot(frames);
+        if (this.oldestSeq > sinceSeq + 1 && sinceSeq > 0) result.gap = true;
+        if (consumerId) {
+            const lastSeq = frames.length ? frames[frames.length - 1]!.seq : sinceSeq;
+            this.consumers.set(consumerId, Math.max(lastSeq, sinceSeq));
+            this.lastActivityAt = Date.now();
+        }
+        return result;
+    }
+
+    /** 无状态读取消费者已知游标（未注册返回 0） */
+    consumerSeq(consumerId: string): number {
+        return this.consumers.get(consumerId) ?? 0;
+    }
+
+    /** 流进程退出/断连 → stale（保留全部帧，seq 冻结在 nextSeq 上，重连续编） */
+    markStale(): void {
+        if (this._closed) return;
+        this._stale = true;
+    }
+
+    attachTransport(t: Transport): void { this.transport = t; }
+
+    /** 关窗：收割流进程 + 内容清空（由 Registry 除名） */
+    close(): void {
+        if (this._closed) return;
+        this._closed = true;
+        try {
+            if (this.transport?.kind === "local") {
+                this.transport.child.kill("SIGTERM");
+            } else if (this.transport?.kind === "remote") {
+                void Promise.resolve(this.transport.manager.stop(this.transport.sessionId)).catch(() => {});
+            }
+        } catch { /* 收割尽力而为 */ }
+        this.frames = [];
+        this.consumers.clear();
+    }
+
+    private snapshot(frames: StreamFrame[]): PeekResult {
+        this.lastActivityAt = Date.now();
+        return {
+            name: this.name,
+            oldestSeq: this.oldestSeq,
+            newestSeq: this.newestSeq,
+            stale: this._stale,
+            frames,
+        };
+    }
+}
+
+/** 行切分器（跨 chunk 行缓冲，CRLF 容忍） */
+class LineSplitter {
+    private buf = "";
+    push(chunk: string, onLine: (line: string) => void): void {
+        this.buf += chunk;
+        const lines = this.buf.split("\n");
+        this.buf = lines.pop() ?? "";
+        for (const line of lines) {
+            const clean = line.replace(/\r$/, "");
+            if (clean !== "") onLine(clean);
+        }
+    }
+    flush(onLine: (line: string) => void): void {
+        const rest = this.buf.replace(/\r$/, "");
+        this.buf = "";
+        if (rest !== "") onLine(rest);
+    }
+}
+
+/** 远程流桥：StreamSessionManager 行回调 → 窗入帧 */
+class RemoteBridge {
+    constructor(
+        private readonly window: StreamWindow,
+        private readonly manager: StreamSessionManager,
+    ) {}
+
+    async start(command: string): Promise<void> {
+        const { sessionId } = await this.manager.start(command, {
+            name: this.window.name.replace(/[^A-Za-z0-9_-]/g, "_"),
+            onLine: (line) => this.window.push(line.text), // filaxis 行对象 → text 投影
+            onExit: () => this.window.markStale(),
+        });
+        this.window.attachTransport({ kind: "remote", manager: this.manager, sessionId });
+    }
+}
+
+export interface StreamWindowRegistryOptions {
+    /** 空引用窗延迟销毁 TTL（对齐 stream 注意力衰减语义） */
+    idleTtlMs?: number;
+    /** local 窗 shell（缺省 resolveLocalShell——与 exec 同源） */
+    shell?: string;
+    logger?: FilaxisLogger;
+}
+
+export class StreamWindowRegistry {
+    private readonly windows = new Map<string, StreamWindow>();
+    private readonly sweeper: ReturnType<typeof setInterval>;
+    private readonly idleTtlMs: number;
+    private readonly shell: string;
+    private readonly log: FilaxisLogger;
+
+    constructor(opts: StreamWindowRegistryOptions = {}) {
+        this.idleTtlMs = opts.idleTtlMs ?? 30 * 60_000;
+        this.shell = opts.shell ?? resolveLocalShell(undefined, opts.logger);
+        this.log = opts.logger ?? noopLogger;
+        this.sweeper = setInterval(() => this.sweep(), 60_000);
+        this.sweeper.unref();
+    }
+
+    /** 开窗（local 经 spawn shell -c；remote 经 StreamSessionManager 行桥） */
+    async open(opts: {
+        name: string;
+        layerAlias?: string;
+        command: string;
+        maxFrames?: number;
+        maxLineBytes?: number;
+        manager?: StreamSessionManager;
+    }): Promise<StreamWindow> {
+        const existing = this.windows.get(opts.name);
+        if (existing && !existing.closed) {
+            throw new Error(`观察窗 '${opts.name}' 已存在（stop 后可重建）`);
+        }
+        const layerAlias = opts.layerAlias ?? "local";
+        const source = opts.name.split(":").slice(-1)[0] ?? opts.name;
+        const win = new StreamWindow(
+            opts.name, layerAlias, source, opts.command, opts.maxFrames, opts.maxLineBytes,
+        );
+
+        if (layerAlias === "local") {
+            // shell -c（与 exec 同源——弃 shell:true：Windows 下 cmd 解释器会挂 unix 命令）
+            const child = spawn(this.shell, ["-c", opts.command], { stdio: ["ignore", "pipe", "pipe"] });
+            const splitter = new LineSplitter();
+            child.stdout?.on("data", (d: Buffer) => splitter.push(d.toString("utf-8"), (l) => win.push(l)));
+            child.stderr?.on("data", (d: Buffer) => splitter.push(d.toString("utf-8"), (l) => win.push(l)));
+            child.on("exit", () => { splitter.flush((l) => win.push(l)); win.markStale(); });
+            win.attachTransport({ kind: "local", child });
+        } else {
+            if (!opts.manager) throw new Error(`remote 窗需要 StreamSessionManager（layer='${layerAlias}'）`);
+            await new RemoteBridge(win, opts.manager).start(opts.command);
+        }
+        this.windows.set(opts.name, win);
+        this.log.info(`[StreamWindow] open '${opts.name}' (layer=${layerAlias})`);
+        return win;
+    }
+
+    stop(name: string): void {
+        const win = this.require(name);
+        win.close();
+        this.windows.delete(name);
+    }
+
+    /** 通配聚合 peek：glob 如 "vm-ai:*"（* 与 ?；无通配=精确名） */
+    peek(pattern: string): StreamWindow[] {
+        return this.matches(pattern);
+    }
+
+    get(name: string): StreamWindow | undefined {
+        return this.windows.get(name);
+    }
+
+    list(): Array<{ name: string; layer: string; frames: number; stale: boolean; command: string }> {
+        return [...this.windows.values()].map((w) => ({
+            name: w.name, layer: w.layerAlias, frames: w.frameCount, stale: w.stale, command: w.command,
+        }));
+    }
+
+    private require(name: string): StreamWindow {
+        const w = this.windows.get(name);
+        if (!w) throw new Error(`观察窗 '${name}' 不存在`);
+        return w;
+    }
+
+    private matches(pattern: string): StreamWindow[] {
+        const hasWildcard = pattern.includes("*") || pattern.includes("?");
+        if (!hasWildcard) {
+            const w = this.windows.get(pattern);
+            return w ? [w] : [];
+        }
+        const re = new RegExp(
+            "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$",
+        );
+        return [...this.windows.values()].filter((w) => re.test(w.name));
+    }
+
+    private sweep(): void {
+        const now = Date.now();
+        for (const [name, w] of this.windows) {
+            if (now - w.lastActiveAt > this.idleTtlMs) {
+                this.log.info(`[StreamWindow] '${name}' 空引用超时 → 销毁`);
+                this.stop(name);
+            }
+        }
+    }
+
+    dispose(): void {
+        clearInterval(this.sweeper);
+        for (const name of [...this.windows.keys()]) this.stop(name);
+    }
+}
+
+/** 模块级单例（消费方共享；多实例场景自行 new Registry） */
+let _registry: StreamWindowRegistry | null = null;
+export function getStreamWindowRegistry(): StreamWindowRegistry {
+    if (!_registry) _registry = new StreamWindowRegistry();
+    return _registry;
+}