@love-moon/tui-driver 0.2.11 → 0.2.13

package/src/driver/TuiDriver.ts

@@ -1,4 +1,9 @@
 import { EventEmitter } from "events";
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
 import { PtySession } from "../pty/PtySession.js";
 import { HeadlessScreen } from "../term/HeadlessScreen.js";
 import { ScreenSnapshot } from "../term/ScreenSnapshot.js";
@@ -8,9 +13,12 @@ import { OutputExtractor } from "../extract/OutputExtractor.js";
 import { computeLineDiff } from "../extract/Diff.js";
 import { TuiProfile, TuiSignals } from "./TuiProfile.js";
 import { StateMachine, TuiState } from "./StateMachine.js";
+import { defaultTuiDriverBehavior } from "./behavior/index.js";
+import type { TuiDriverBehavior } from "./behavior/index.js";
 
 export interface TuiDriverOptions {
   profile: TuiProfile;
+  cwd?: string;
   debug?: boolean;
   onSnapshot?: (snapshot: ScreenSnapshot, state: TuiState) => void;
   onSignals?: (signals: TuiScreenSignals, snapshot: ScreenSnapshot, state: TuiState) => void;
@@ -30,6 +38,8 @@ export interface AskResult {
   replyInProgress?: boolean;
   statusLine?: string;
   statusDoneLine?: string;
+  sessionId?: string;
+  sessionFilePath?: string;
 }
 
 export type HealthReason =
@@ -57,32 +67,81 @@ export interface TuiScreenSignals {
   statusDoneLine?: string;
 }
 
+export interface TuiSessionInfo {
+  backend: string;
+  sessionId: string;
+  sessionFilePath: string;
+}
+
+export interface TuiSessionUsageSummary {
+  backend: string;
+  sessionId: string;
+  sessionFilePath: string;
+  tokenUsagePercent?: number;
+  contextUsagePercent?: number;
+}
+
+interface SessionFileCheckpoint {
+  sessionInfo: TuiSessionInfo;
+  size: number;
+  mtimeMs: number;
+}
+
+interface SessionUsageCacheEntry {
+  backend: string;
+  sessionId: string;
+  sessionFilePath: string;
+  size: number;
+  mtimeMs: number;
+  summary: TuiSessionUsageSummary;
+}
+
+const DEFAULT_STAGE_TIMEOUT_MAX_MS = 15 * 60 * 1000;
+const ABSOLUTE_STAGE_TIMEOUT_MAX_MS = 60 * 60 * 1000;
+const MIN_STAGE_TIMEOUT_MS = 100;
+const DEFAULT_SESSION_DISCOVERY_TIMEOUT_MS = 15_000;
+const DEFAULT_SESSION_POLL_INTERVAL_MS = 2_000;
+
+const execFileAsync = promisify(execFile);
+
 export class TuiDriver extends EventEmitter {
   private pty: PtySession;
   private screen: HeadlessScreen;
   private expect: ExpectEngine;
   private stateMachine: StateMachine;
   private profile: TuiProfile;
+  private behavior: TuiDriverBehavior;
   private debug: boolean;
   private onSnapshot?: (snapshot: ScreenSnapshot, state: TuiState) => void;
   private onSignals?: (signals: TuiScreenSignals, snapshot: ScreenSnapshot, state: TuiState) => void;
   private isBooted = false;
+  private isKilled = false;
+  private sessionCwd: string;
+  private sessionInfo: TuiSessionInfo | null = null;
+  private lastSessionInfo: TuiSessionInfo | null = null;
+  private sessionUsageCache: SessionUsageCacheEntry | null = null;
+  private initialCommand: string;
+  private initialArgs: string[];
 
   constructor(options: TuiDriverOptions) {
     super();
     this.profile = options.profile;
+    this.behavior = options.profile.behavior ?? defaultTuiDriverBehavior;
     this.debug = options.debug ?? false;
     this.onSnapshot = options.onSnapshot;
     this.onSignals = options.onSignals;
+    this.sessionCwd = options.cwd ?? process.cwd();
+    this.initialCommand = this.profile.command;
+    this.initialArgs = Array.isArray(this.profile.args) ? [...this.profile.args] : [];
 
     const cols = this.profile.cols ?? 120;
     const rows = this.profile.rows ?? 40;
     const scrollback = this.profile.scrollback ?? 5000;
 
     this.pty = new PtySession(
-      this.profile.command,
-      this.profile.args,
-      { cols, rows, env: this.profile.env }
+      this.initialCommand,
+      this.initialArgs,
+      { cols, rows, env: this.profile.env, cwd: this.sessionCwd }
     );
 
     this.screen = new HeadlessScreen({
@@ -108,6 +167,7 @@ export class TuiDriver extends EventEmitter {
     this.pty.onExit((code, signal) => {
       this.log(`PTY exited: code=${code}, signal=${signal}`);
       this.isBooted = false;
+      this.sessionInfo = null;
       this.emit("exit", code, signal);
     });
 
@@ -136,12 +196,71 @@ export class TuiDriver extends EventEmitter {
     return this.pty.isRunning;
   }
 
+  getSessionInfo(): TuiSessionInfo | null {
+    const current = this.sessionInfo ?? this.lastSessionInfo;
+    return current ? { ...current } : null;
+  }
+
+  async ensureSessionInfo(timeoutMs = DEFAULT_SESSION_DISCOVERY_TIMEOUT_MS): Promise<TuiSessionInfo | null> {
+    if (!this.supportsSessionFileTracking()) {
+      return null;
+    }
+    if (this.sessionInfo) {
+      return { ...this.sessionInfo };
+    }
+
+    const boundedTimeoutMs = this.resolveTimeout(timeoutMs, DEFAULT_SESSION_DISCOVERY_TIMEOUT_MS);
+    const discovered = await this.discoverSessionInfo(boundedTimeoutMs);
+    return discovered ? { ...discovered } : null;
+  }
+
+  async getSessionUsageSummary(): Promise<TuiSessionUsageSummary | null> {
+    if (!this.supportsSessionFileTracking()) {
+      return null;
+    }
+
+    const sessionInfo = this.sessionInfo ?? this.lastSessionInfo ?? (await this.ensureSessionInfo());
+    if (!sessionInfo) {
+      return null;
+    }
+
+    const { size, mtimeMs } = await this.readSessionFileStat(sessionInfo.sessionFilePath);
+    if (
+      this.sessionUsageCache &&
+      this.sessionUsageCache.backend === sessionInfo.backend &&
+      this.sessionUsageCache.sessionId === sessionInfo.sessionId &&
+      this.sessionUsageCache.sessionFilePath === sessionInfo.sessionFilePath &&
+      this.sessionUsageCache.size === size &&
+      this.sessionUsageCache.mtimeMs === mtimeMs
+    ) {
+      return { ...this.sessionUsageCache.summary };
+    }
+
+    const lines = await this.readSessionFileJsonLines(sessionInfo.sessionFilePath, 0);
+    const summary = this.extractSessionUsageSummaryFromJsonLines(lines, sessionInfo);
+    this.sessionUsageCache = {
+      backend: sessionInfo.backend,
+      sessionId: sessionInfo.sessionId,
+      sessionFilePath: sessionInfo.sessionFilePath,
+      size,
+      mtimeMs,
+      summary,
+    };
+
+    return { ...summary };
+  }
+
   async boot(): Promise<void> {
+    if (this.isKilled) {
+      throw this.createSessionClosedError();
+    }
+
     if (this.isBooted) {
       return;
     }
 
     this.stateMachine.transition("BOOT");
+    this.sessionInfo = null;
     this.pty.spawn();
 
     const bootTimeout = this.resolveTimeout(this.profile.timeouts?.boot, 15000);
@@ -234,6 +353,7 @@ export class TuiDriver extends EventEmitter {
 
     this.isBooted = true;
     this.stateMachine.transition("WAIT_READY");
+    await this.ensureSessionInfo();
     this.captureSnapshot("boot_complete");
   }
 
@@ -245,10 +365,14 @@ export class TuiDriver extends EventEmitter {
 
     const readyMatcher = Matchers.anyOf(this.profile.anchors.ready);
     const readyTimeout = this.resolveTimeout(this.profile.timeouts?.ready, 10000);
+    const guardedReadyMatcher = Matchers.custom((snapshot) => {
+      this.assertAliveOrThrow();
+      return readyMatcher(snapshot);
+    });
 
     const result = await this.expect.until({
       name: "ENSURE_READY",
-      match: readyMatcher,
+      match: guardedReadyMatcher,
       stableMs: 200,
       timeoutMs: readyTimeout,
     });
@@ -261,6 +385,7 @@ export class TuiDriver extends EventEmitter {
 
   async ask(prompt: string): Promise<AskResult> {
     const startTime = Date.now();
+    let sessionInfo: TuiSessionInfo | null = null;
 
     try {
       await this.ensureReady();
@@ -279,6 +404,16 @@ export class TuiDriver extends EventEmitter {
             (error as any).matchedPattern = health.matchedPattern;
             throw error;
           }
+        } else if (health.reason === "process_exited") {
+          this.log("Health check detected exited process, attempting forced restart");
+          await this.restart();
+          const healthAfterRestart = this.healthCheck();
+          if (!healthAfterRestart.healthy) {
+            const error = new Error(`Cannot proceed: ${healthAfterRestart.message || healthAfterRestart.reason}`);
+            (error as any).reason = healthAfterRestart.reason;
+            (error as any).matchedPattern = healthAfterRestart.matchedPattern;
+            throw error;
+          }
         } else if (health.reason === "login_required") {
           const error = new Error(`Cannot proceed: ${health.message}`);
           (error as any).reason = health.reason;
@@ -299,6 +434,8 @@ export class TuiDriver extends EventEmitter {
         }
       }
 
+      sessionInfo = await this.ensureSessionInfo();
+
       this.stateMachine.transition("PREPARE_TURN");
       await this.prepareTurn();
 
@@ -313,17 +450,28 @@ export class TuiDriver extends EventEmitter {
 
       // 在 submit 之后保存快照，这样 diff 只包含 AI 的回答，不包含 prompt
       const beforeSnapshot = this.captureSnapshot("after_submit");
+      const sessionCheckpoint = await this.captureSessionFileCheckpoint(sessionInfo);
 
       this.stateMachine.transition("WAIT_STREAM_START");
-      await this.waitStreamStart(preSubmitSnapshot);
+      if (sessionCheckpoint) {
+        await this.waitForSessionFileGrowth(sessionCheckpoint);
+      } else {
+        await this.waitStreamStart(preSubmitSnapshot);
+      }
 
       this.stateMachine.transition("WAIT_STREAM_END");
-      await this.waitStreamEnd();
+      if (sessionCheckpoint) {
+        await this.waitForSessionFileIdle(sessionCheckpoint);
+      } else {
+        await this.waitStreamEnd(beforeSnapshot);
+      }
 
       this.stateMachine.transition("CAPTURE");
       const afterSnapshot = this.captureSnapshot("after_response");
 
-      const answer = this.extractAnswer(beforeSnapshot, afterSnapshot);
+      const answer = sessionCheckpoint
+        ? await this.extractAnswerFromSessionFile(sessionCheckpoint)
+        : this.extractAnswer(beforeSnapshot, afterSnapshot);
       const signals = this.getSignals(afterSnapshot);
 
       this.stateMachine.transition("DONE");
@@ -341,6 +489,8 @@ export class TuiDriver extends EventEmitter {
         replyInProgress: signals.replyInProgress,
         statusLine: signals.statusLine,
         statusDoneLine: signals.statusDoneLine,
+        sessionId: sessionInfo?.sessionId,
+        sessionFilePath: sessionInfo?.sessionFilePath,
       };
     } catch (error) {
       this.stateMachine.error(error as Error);
@@ -359,6 +509,8 @@ export class TuiDriver extends EventEmitter {
         replyInProgress: signals.replyInProgress,
         statusLine: signals.statusLine,
         statusDoneLine: signals.statusDoneLine,
+        sessionId: sessionInfo?.sessionId,
+        sessionFilePath: sessionInfo?.sessionFilePath,
       };
     }
   }
@@ -378,24 +530,886 @@ export class TuiDriver extends EventEmitter {
     await this.pty.sendKeys(this.profile.keys.submit, 50);
   }
 
+  private supportsSessionFileTracking(): boolean {
+    const backend = String(this.profile.name || "").toLowerCase();
+    return backend === "codex" || backend === "claude-code" || backend === "copilot";
+  }
+
+  private async discoverSessionInfo(timeoutMs: number): Promise<TuiSessionInfo | null> {
+    const startedAt = Date.now();
+    const deadline = startedAt + Math.max(MIN_STAGE_TIMEOUT_MS, timeoutMs);
+
+    while (Date.now() < deadline) {
+      this.assertAliveOrThrow();
+      const discovered = await this.detectSessionInfoByBackend();
+      if (discovered) {
+        const changed =
+          !this.sessionInfo ||
+          this.sessionInfo.sessionId !== discovered.sessionId ||
+          this.sessionInfo.sessionFilePath !== discovered.sessionFilePath;
+        this.sessionInfo = discovered;
+        this.lastSessionInfo = discovered;
+        if (changed) {
+          this.emit("session", { ...discovered });
+          this.log(
+            `session discovered: id=${discovered.sessionId} file=${discovered.sessionFilePath}`,
+          );
+        }
+        return discovered;
+      }
+      await this.sleep(250);
+    }
+
+    return this.sessionInfo ? { ...this.sessionInfo } : null;
+  }
+
+  private async detectSessionInfoByBackend(): Promise<TuiSessionInfo | null> {
+    if (!this.supportsSessionFileTracking()) {
+      return null;
+    }
+    try {
+      switch (this.profile.name) {
+        case "codex":
+          return this.detectCodexSessionInfo();
+        case "claude-code":
+          return this.detectClaudeSessionInfo();
+        case "copilot":
+          return this.detectCopilotSessionInfo();
+        default:
+          return null;
+      }
+    } catch (error) {
+      this.log(`session detect failed: ${(error as Error)?.message || error}`);
+      return null;
+    }
+  }
+
+  private async detectCodexSessionInfo(): Promise<TuiSessionInfo | null> {
+    const dbPath = join(homedir(), ".codex", "state_5.sqlite");
+    if (!(await this.pathExists(dbPath))) {
+      return null;
+    }
+
+    const parseRowAsSessionInfo = async (row: string | null): Promise<TuiSessionInfo | null> => {
+      if (!row) {
+        return null;
+      }
+      const [sessionIdRaw, sessionFilePathRaw] = row.split("|");
+      const sessionId = String(sessionIdRaw || "").trim();
+      const sessionFilePath = String(sessionFilePathRaw || "").trim();
+      if (!sessionId || !sessionFilePath || !(await this.pathExists(sessionFilePath))) {
+        return null;
+      }
+      return {
+        backend: "codex",
+        sessionId,
+        sessionFilePath,
+      };
+    };
+
+    const pinnedSessionId = String(this.sessionInfo?.sessionId || this.lastSessionInfo?.sessionId || "").trim();
+    if (pinnedSessionId) {
+      const escapedSessionId = pinnedSessionId.replace(/'/g, "''");
+      const pinnedRow = await this.querySqliteRow(
+        dbPath,
+        `select id, rollout_path from threads where source='cli' and model_provider='openai' and id='${escapedSessionId}' limit 1;`,
+      );
+      const pinnedSession = await parseRowAsSessionInfo(pinnedRow);
+      if (pinnedSession) {
+        return pinnedSession;
+      }
+    }
+
+    const escapedCwd = this.sessionCwd.replace(/'/g, "''");
+    const row = await this.querySqliteRow(
+      dbPath,
+      `select id, rollout_path from threads where source='cli' and model_provider='openai' and cwd='${escapedCwd}' order by updated_at desc limit 1;`,
+    );
+    return parseRowAsSessionInfo(row);
+  }
+
+  private async detectClaudeSessionInfo(): Promise<TuiSessionInfo | null> {
+    const projectDir = join(
+      homedir(),
+      ".claude",
+      "projects",
+      this.encodeClaudeProjectPath(this.sessionCwd),
+    );
+    if (!(await this.pathExists(projectDir))) {
+      return null;
+    }
+
+    const indexPath = join(projectDir, "sessions-index.json");
+    if (await this.pathExists(indexPath)) {
+      try {
+        const raw = await fs.readFile(indexPath, "utf8");
+        const parsed = JSON.parse(raw) as {
+          entries?: Array<{
+            sessionId?: string;
+            fullPath?: string;
+            fileMtime?: number;
+            modified?: string;
+            projectPath?: string;
+          }>;
+        };
+        const entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+        const candidates = entries
+          .filter((entry) => {
+            const entrySessionId = String(entry?.sessionId || "").trim();
+            if (!entrySessionId) {
+              return false;
+            }
+            const entryProjectPath = String(entry?.projectPath || "").trim();
+            return !entryProjectPath || entryProjectPath === this.sessionCwd;
+          })
+          .sort((a, b) => {
+            const scoreA = Number(a?.fileMtime || Date.parse(String(a?.modified || "")) || 0);
+            const scoreB = Number(b?.fileMtime || Date.parse(String(b?.modified || "")) || 0);
+            return scoreB - scoreA;
+          });
+
+        for (const entry of candidates) {
+          const sessionId = String(entry.sessionId || "").trim();
+          const sessionFilePath = String(entry.fullPath || "").trim() || join(projectDir, `${sessionId}.jsonl`);
+          if (sessionId && sessionFilePath && (await this.pathExists(sessionFilePath))) {
+            return {
+              backend: "claude-code",
+              sessionId,
+              sessionFilePath,
+            };
+          }
+        }
+      } catch (error) {
+        this.log(`claude session index parse failed: ${(error as Error)?.message || error}`);
+      }
+    }
+
+    try {
+      const dirents = await fs.readdir(projectDir, { withFileTypes: true });
+      const jsonlFiles = dirents
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl"))
+        .map((entry) => join(projectDir, entry.name));
+      const stats = await Promise.all(
+        jsonlFiles.map(async (filePath) => ({
+          filePath,
+          mtimeMs: (await fs.stat(filePath)).mtimeMs,
+        })),
+      );
+      stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+      const latest = stats[0];
+      if (!latest) {
+        return null;
+      }
+      const sessionId = basename(latest.filePath, ".jsonl");
+      return {
+        backend: "claude-code",
+        sessionId,
+        sessionFilePath: latest.filePath,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private async detectCopilotSessionInfo(): Promise<TuiSessionInfo | null> {
+    const baseDir = join(homedir(), ".copilot", "session-state");
+    if (!(await this.pathExists(baseDir))) {
+      return null;
+    }
+
+    try {
+      const dirents = await fs.readdir(baseDir, { withFileTypes: true });
+      const candidates: Array<{ sessionId: string; sessionFilePath: string; mtimeMs: number }> = [];
+
+      for (const entry of dirents) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+        const sessionDir = join(baseDir, entry.name);
+        const workspacePath = join(sessionDir, "workspace.yaml");
+        const eventsPath = join(sessionDir, "events.jsonl");
+        if (!(await this.pathExists(eventsPath))) {
+          continue;
+        }
+
+        let workspaceCwd = "";
+        let workspaceId = "";
+        if (await this.pathExists(workspacePath)) {
+          workspaceCwd = (await this.readWorkspaceYamlValue(workspacePath, "cwd")) || "";
+          workspaceId = (await this.readWorkspaceYamlValue(workspacePath, "id")) || "";
+        }
+
+        if (workspaceCwd && workspaceCwd !== this.sessionCwd) {
+          continue;
+        }
+
+        const sessionId = workspaceId || entry.name;
+        const mtimeMs = (await fs.stat(eventsPath)).mtimeMs;
+        candidates.push({
+          sessionId,
+          sessionFilePath: eventsPath,
+          mtimeMs,
+        });
+      }
+
+      candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+      const latest = candidates[0];
+      if (!latest) {
+        return null;
+      }
+      return {
+        backend: "copilot",
+        sessionId: latest.sessionId,
+        sessionFilePath: latest.sessionFilePath,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private async querySqliteRow(dbPath: string, query: string): Promise<string | null> {
+    try {
+      const { stdout } = await execFileAsync("sqlite3", [dbPath, query], {
+        timeout: 3000,
+        maxBuffer: 1024 * 1024,
+      });
+      const lines = String(stdout || "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+      return lines[0] ?? null;
+    } catch (error) {
+      this.log(`sqlite query failed: ${(error as Error)?.message || error}`);
+      return null;
+    }
+  }
+
+  private encodeClaudeProjectPath(cwd: string): string {
+    return String(cwd || "").replace(/\//g, "-");
+  }
+
+  private async readWorkspaceYamlValue(filePath: string, key: string): Promise<string | null> {
+    try {
+      const raw = await fs.readFile(filePath, "utf8");
+      const matcher = new RegExp(`^${key}:\\s*(.+)\\s*$`, "m");
+      const match = raw.match(matcher);
+      if (!match) {
+        return null;
+      }
+      const value = match[1].trim();
+      if (!value) {
+        return null;
+      }
+      return value.replace(/^['"]|['"]$/g, "");
+    } catch {
+      return null;
+    }
+  }
+
+  private async pathExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async captureSessionFileCheckpoint(
+    sessionInfo: TuiSessionInfo | null,
+  ): Promise<SessionFileCheckpoint | null> {
+    if (!sessionInfo) {
+      return null;
+    }
+    const { size, mtimeMs } = await this.readSessionFileStat(sessionInfo.sessionFilePath);
+    return {
+      sessionInfo,
+      size,
+      mtimeMs,
+    };
+  }
+
+  private async readSessionFileStat(
+    sessionFilePath: string,
+  ): Promise<{ size: number; mtimeMs: number }> {
+    try {
+      const stats = await fs.stat(sessionFilePath);
+      return {
+        size: stats.size,
+        mtimeMs: stats.mtimeMs,
+      };
+    } catch {
+      return {
+        size: 0,
+        mtimeMs: 0,
+      };
+    }
+  }
+
+  private async waitForSessionFileGrowth(checkpoint: SessionFileCheckpoint): Promise<void> {
+    const timeoutMs = this.resolveTimeout(this.profile.timeouts?.streamStart, 10000);
+    const startedAt = Date.now();
+    let lastSize = checkpoint.size;
+    let lastMtimeMs = checkpoint.mtimeMs;
+
+    while (Date.now() - startedAt < timeoutMs) {
+      this.assertAliveOrThrow();
+      const current = await this.readSessionFileStat(checkpoint.sessionInfo.sessionFilePath);
+      const changed = current.size !== lastSize || current.mtimeMs !== lastMtimeMs;
+      if (changed) {
+        this.log(
+          `session file growth detected: ${checkpoint.sessionInfo.sessionFilePath} (${lastSize} -> ${current.size})`,
+        );
+        return;
+      }
+      await this.sleep(DEFAULT_SESSION_POLL_INTERVAL_MS);
+    }
+
+    throw new Error("Stream start timeout: session file did not grow");
+  }
+
+  private async waitForSessionFileIdle(checkpoint: SessionFileCheckpoint): Promise<void> {
+    const timeoutMs = this.resolveTimeout(this.profile.timeouts?.streamEnd, 120000);
+    const startedAt = Date.now();
+    let previousSize = checkpoint.size;
+    let previousMtimeMs = checkpoint.mtimeMs;
+    let observedProgress = false;
+    let unchangedChecks = 0;
+    const requireCompletionMarker = this.requiresSessionCompletionMarker(checkpoint.sessionInfo.backend);
+    let completionMarkerSeen = false;
+
+    while (Date.now() - startedAt < timeoutMs) {
+      this.assertAliveOrThrow();
+      const current = await this.readSessionFileStat(checkpoint.sessionInfo.sessionFilePath);
+      const changed = current.size !== previousSize || current.mtimeMs !== previousMtimeMs;
+      if (changed) {
+        this.log(
+          `session file changed: backend=${checkpoint.sessionInfo.backend} size=${previousSize}->${current.size} mtime=${previousMtimeMs}->${current.mtimeMs}`,
+        );
+        observedProgress = true;
+        unchangedChecks = 0;
+        previousSize = current.size;
+        previousMtimeMs = current.mtimeMs;
+        if (requireCompletionMarker && !completionMarkerSeen) {
+          completionMarkerSeen = await this.hasSessionCompletionMarker(checkpoint, current.size);
+          if (completionMarkerSeen) {
+            this.log(
+              `session completion marker observed: backend=${checkpoint.sessionInfo.backend} file=${checkpoint.sessionInfo.sessionFilePath}`,
+            );
+          }
+        }
+      } else {
+        unchangedChecks += 1;
+        this.log(
+          `session file unchanged: backend=${checkpoint.sessionInfo.backend} checks=${unchangedChecks} completionMarkerSeen=${completionMarkerSeen}`,
+        );
+        if (observedProgress && unchangedChecks >= 2) {
+          if (!requireCompletionMarker || completionMarkerSeen) {
+            this.log(
+              `session file idle reached: backend=${checkpoint.sessionInfo.backend} checks=${unchangedChecks} completionMarkerSeen=${completionMarkerSeen}`,
+            );
+            return;
+          }
+        }
+      }
+      await this.sleep(DEFAULT_SESSION_POLL_INTERVAL_MS);
+    }
+
+    if (!observedProgress) {
+      throw new Error("Stream end timeout: session file did not grow");
+    }
+    if (requireCompletionMarker && !completionMarkerSeen) {
+      throw new Error("Stream end timeout: session completion marker not observed");
+    }
+    throw new Error("Stream end timeout: session file did not become stable");
+  }
+
+  private async extractAnswerFromSessionFile(checkpoint: SessionFileCheckpoint): Promise<string> {
+    const lines = await this.readSessionFileJsonLines(
+      checkpoint.sessionInfo.sessionFilePath,
+      checkpoint.size,
+    );
+    const codexTaskCompleteMessage = this.extractCodexTaskCompleteMessageFromJsonLines(lines);
+    if (codexTaskCompleteMessage) {
+      this.log(
+        `session answer source=codex.task_complete preview="${this.summarizeForLog(codexTaskCompleteMessage, 160)}"`,
+      );
+      return codexTaskCompleteMessage;
+    }
+    const answer = this.extractAssistantReplyFromJsonLines(lines, checkpoint.sessionInfo.backend);
+    if (answer) {
+      this.log(
+        `session answer source=${checkpoint.sessionInfo.backend}.assistant preview="${this.summarizeForLog(answer, 160)}"`,
+      );
+      return answer;
+    }
+    throw new Error("No assistant reply found in session file");
+  }
+
+  private extractSessionUsageSummaryFromJsonLines(
+    lines: string[],
+    sessionInfo: TuiSessionInfo,
+  ): TuiSessionUsageSummary {
+    const backend = sessionInfo.backend;
+    const baseSummary: TuiSessionUsageSummary = {
+      backend,
+      sessionId: sessionInfo.sessionId,
+      sessionFilePath: sessionInfo.sessionFilePath,
+    };
+
+    const usage =
+      backend === "codex"
+        ? this.extractCodexUsageFromJsonLines(lines)
+        : backend === "claude-code"
+          ? this.extractClaudeUsageFromJsonLines(lines)
+          : backend === "copilot"
+            ? this.extractCopilotUsageFromJsonLines(lines)
+            : {};
+
+    return {
+      ...baseSummary,
+      ...usage,
+    };
+  }
+
+  private extractCodexUsageFromJsonLines(
+    lines: string[],
+  ): Pick<TuiSessionUsageSummary, "tokenUsagePercent" | "contextUsagePercent"> {
+    let tokenUsagePercent: number | undefined;
+    let contextUsagePercent: number | undefined;
+
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (!entry || entry.type !== "event_msg") {
+        continue;
+      }
+      const payload = entry.payload as Record<string, unknown> | undefined;
+      if (!payload || typeof payload !== "object") {
+        continue;
+      }
+
+      const secondaryUsedPercent = this.readNumberPath(payload, ["rate_limits", "secondary", "used_percent"]);
+      if (secondaryUsedPercent !== undefined) {
+        tokenUsagePercent = this.normalizePercent(secondaryUsedPercent);
+      }
+
+      const inputTokens = this.readNumberPath(payload, ["info", "last_token_usage", "input_tokens"]);
+      const contextWindow = this.readNumberPath(payload, ["info", "model_context_window"]);
+      if (inputTokens !== undefined && contextWindow !== undefined && contextWindow > 0) {
+        contextUsagePercent = this.normalizePercent((inputTokens / contextWindow) * 100);
+      }
+    }
+
+    return {
+      tokenUsagePercent,
+      contextUsagePercent,
+    };
+  }
+
+  private extractClaudeUsageFromJsonLines(
+    lines: string[],
+  ): Pick<TuiSessionUsageSummary, "tokenUsagePercent" | "contextUsagePercent"> {
+    let tokenUsagePercent: number | undefined;
+    let contextUsagePercent: number | undefined;
+    let latestInputTokens: number | undefined;
+    let latestContextWindow: number | undefined;
+
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+
+      const secondaryUsedPercent =
+        this.readNumberPath(entry, ["rate_limits", "secondary", "used_percent"]) ??
+        this.readNumberPath(entry, ["rateLimits", "secondary", "usedPercent"]);
+      if (secondaryUsedPercent !== undefined) {
+        tokenUsagePercent = this.normalizePercent(secondaryUsedPercent);
+      }
+
+      const inputTokens =
+        this.readNumberPath(entry, ["message", "usage", "input_tokens"]) ??
+        this.readNumberPath(entry, ["message", "usage", "inputTokens"]) ??
+        this.readNumberPath(entry, ["usage", "input_tokens"]) ??
+        this.readNumberPath(entry, ["usage", "inputTokens"]);
+      if (inputTokens !== undefined) {
+        latestInputTokens = inputTokens;
+      }
+
+      const contextWindow =
+        this.readNumberPath(entry, ["message", "model_context_window"]) ??
+        this.readNumberPath(entry, ["message", "modelContextWindow"]) ??
+        this.readNumberPath(entry, ["message", "context_window"]) ??
+        this.readNumberPath(entry, ["message", "contextWindow"]) ??
+        this.readNumberPath(entry, ["model_context_window"]) ??
+        this.readNumberPath(entry, ["modelContextWindow"]) ??
+        this.readNumberPath(entry, ["context_window"]) ??
+        this.readNumberPath(entry, ["contextWindow"]);
+      if (contextWindow !== undefined && contextWindow > 0) {
+        latestContextWindow = contextWindow;
+      }
+    }
+
+    if (
+      latestInputTokens !== undefined &&
+      latestContextWindow !== undefined &&
+      latestContextWindow > 0
+    ) {
+      contextUsagePercent = this.normalizePercent((latestInputTokens / latestContextWindow) * 100);
+    }
+
+    return {
+      tokenUsagePercent,
+      contextUsagePercent,
+    };
+  }
+
+  private extractCopilotUsageFromJsonLines(
+    lines: string[],
+  ): Pick<TuiSessionUsageSummary, "tokenUsagePercent" | "contextUsagePercent"> {
+    let tokenUsagePercent: number | undefined;
+    let contextUsagePercent: number | undefined;
+    let latestContextTokens: number | undefined;
+    let latestContextLimit: number | undefined;
+
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+
+      const secondaryUsedPercent =
+        this.readNumberPath(entry, ["data", "rate_limits", "secondary", "used_percent"]) ??
+        this.readNumberPath(entry, ["data", "rateLimits", "secondary", "usedPercent"]) ??
+        this.readNumberPath(entry, ["rate_limits", "secondary", "used_percent"]) ??
+        this.readNumberPath(entry, ["rateLimits", "secondary", "usedPercent"]);
+      if (secondaryUsedPercent !== undefined) {
+        tokenUsagePercent = this.normalizePercent(secondaryUsedPercent);
+      }
+
+      const responseTokenLimit =
+        this.readNumberPath(entry, ["data", "toolTelemetry", "metrics", "responseTokenLimit"]) ??
+        this.readNumberPath(entry, ["data", "responseTokenLimit"]) ??
+        this.readNumberPath(entry, ["data", "modelContextWindow"]) ??
+        this.readNumberPath(entry, ["data", "model_context_window"]) ??
+        this.readNumberPath(entry, ["data", "contextWindow"]) ??
+        this.readNumberPath(entry, ["data", "context_window"]) ??
+        this.readNumberPath(entry, ["responseTokenLimit"]);
+      if (responseTokenLimit !== undefined && responseTokenLimit > 0) {
+        latestContextLimit = responseTokenLimit;
+      }
+
+      const contextTokens =
+        this.readNumberPath(entry, ["data", "preCompactionTokens"]) ??
+        this.readNumberPath(entry, ["data", "compactionTokensUsed", "input"]) ??
+        this.readNumberPath(entry, ["data", "postCompactionTokens"]) ??
+        this.readNumberPath(entry, ["data", "tokenUsage", "input_tokens"]) ??
+        this.readNumberPath(entry, ["data", "usage", "input_tokens"]) ??
+        this.readNumberPath(entry, ["data", "inputTokens"]);
+      if (contextTokens !== undefined && contextTokens >= 0) {
+        latestContextTokens = contextTokens;
+      }
+    }
+
+    if (
+      latestContextTokens !== undefined &&
+      latestContextLimit !== undefined &&
+      latestContextLimit > 0
+    ) {
+      contextUsagePercent = this.normalizePercent((latestContextTokens / latestContextLimit) * 100);
+    }
+
+    return {
+      tokenUsagePercent,
+      contextUsagePercent,
+    };
+  }
+
+  private readNumberPath(source: unknown, path: string[]): number | undefined {
+    let cursor: unknown = source;
+    for (const key of path) {
+      if (!cursor || typeof cursor !== "object") {
+        return undefined;
+      }
+      cursor = (cursor as Record<string, unknown>)[key];
+    }
+    if (typeof cursor === "number" && Number.isFinite(cursor)) {
+      return cursor;
+    }
+    if (typeof cursor === "string") {
+      const parsed = Number(cursor);
+      if (Number.isFinite(parsed)) {
+        return parsed;
+      }
+    }
+    return undefined;
+  }
+
+  private normalizePercent(value: number): number {
+    if (!Number.isFinite(value)) {
+      return 0;
+    }
+    if (value < 0) {
+      return 0;
+    }
+    if (value > 100) {
+      return 100;
+    }
+    return value;
+  }
+
+  private requiresSessionCompletionMarker(backend: string): boolean {
+    return backend === "codex" || backend === "copilot";
+  }
+
+  private async hasSessionCompletionMarker(
+    checkpoint: SessionFileCheckpoint,
+    endOffset?: number,
+  ): Promise<boolean> {
+    const lines = await this.readSessionFileJsonLines(
+      checkpoint.sessionInfo.sessionFilePath,
+      checkpoint.size,
+      endOffset,
+    );
+    if (checkpoint.sessionInfo.backend === "codex") {
+      return this.hasCodexTaskCompleteFromJsonLines(lines);
+    }
+    if (checkpoint.sessionInfo.backend === "copilot") {
+      return this.hasCopilotTurnEndFromJsonLines(lines);
+    }
+    return false;
+  }
+
+  private async readSessionFileJsonLines(
+    sessionFilePath: string,
+    startOffset = 0,
+    endOffset?: number,
+  ): Promise<string[]> {
+    let fullBuffer: Buffer;
+    try {
+      fullBuffer = await fs.readFile(sessionFilePath);
+    } catch {
+      return [];
+    }
+    const boundedStartOffset = Math.max(0, Math.min(startOffset, fullBuffer.length));
+    const boundedEndOffset = Number.isFinite(endOffset)
+      ? Math.max(boundedStartOffset, Math.min(Number(endOffset), fullBuffer.length))
+      : fullBuffer.length;
+    return fullBuffer
+      .subarray(boundedStartOffset, boundedEndOffset)
+      .toString("utf8")
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  private extractAssistantReplyFromJsonLines(lines: string[], backend: string): string {
+    const replies: string[] = [];
+
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+
+      const text =
+        backend === "codex"
+          ? this.extractCodexAssistantText(entry)
+          : backend === "claude-code"
+            ? this.extractClaudeAssistantText(entry)
+            : backend === "copilot"
+              ? this.extractCopilotAssistantText(entry)
+              : "";
+      if (text) {
+        replies.push(text);
+      }
+    }
+
+    return replies.length > 0 ? replies[replies.length - 1] : "";
+  }
+
+  private hasCodexTaskCompleteFromJsonLines(lines: string[]): boolean {
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (entry && this.isCodexTaskCompleteEntry(entry)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private hasCopilotTurnEndFromJsonLines(lines: string[]): boolean {
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (entry && this.isCopilotTurnEndEntry(entry)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private extractCodexTaskCompleteMessageFromJsonLines(lines: string[]): string {
+    let latestMessage = "";
+    for (const line of lines) {
+      let entry: Record<string, unknown> | null = null;
+      try {
+        entry = JSON.parse(line) as Record<string, unknown>;
+      } catch {
+        continue;
+      }
+      if (!entry || !this.isCodexTaskCompleteEntry(entry)) {
+        continue;
+      }
+      const payload = entry.payload as Record<string, unknown> | undefined;
+      const message = typeof payload?.last_agent_message === "string" ? payload.last_agent_message.trim() : "";
+      if (message) {
+        latestMessage = message;
+      }
+    }
+    return latestMessage;
+  }
+
+  private isCodexTaskCompleteEntry(entry: Record<string, unknown>): boolean {
+    if (entry.type !== "event_msg") {
+      return false;
+    }
+    const payload = entry.payload as Record<string, unknown> | undefined;
+    return payload?.type === "task_complete";
+  }
+
+  private isCopilotTurnEndEntry(entry: Record<string, unknown>): boolean {
+    return entry.type === "assistant.turn_end";
+  }
+
+  private summarizeForLog(value: string, maxLen = 160): string {
+    const normalized = String(value || "").replace(/\s+/g, " ").trim();
+    if (!normalized) {
+      return "";
+    }
+    if (normalized.length <= maxLen) {
+      return normalized;
+    }
+    return `${normalized.slice(0, maxLen)}...`;
+  }
+
+  private extractCodexAssistantText(entry: Record<string, unknown>): string {
+    if (entry.type !== "response_item") {
+      return "";
+    }
+    const payload = entry.payload as Record<string, unknown> | undefined;
+    if (!payload || payload.type !== "message" || payload.role !== "assistant") {
+      return "";
+    }
+    const content = payload.content as Array<Record<string, unknown>> | undefined;
+    if (!Array.isArray(content)) {
+      return "";
+    }
+    const text = content
+      .map((part) => (typeof part?.text === "string" ? part.text : ""))
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    return text;
+  }
+
+  private extractClaudeAssistantText(entry: Record<string, unknown>): string {
+    if (entry.type !== "assistant") {
+      return "";
+    }
+    const message = entry.message as Record<string, unknown> | undefined;
+    if (!message || message.role !== "assistant") {
+      return "";
+    }
+    const content = message.content;
+    if (typeof content === "string") {
+      return content.trim();
+    }
+    if (!Array.isArray(content)) {
+      return "";
+    }
+    const text = content
+      .map((block) => {
+        const typed = block as Record<string, unknown>;
+        return typed?.type === "text" && typeof typed?.text === "string" ? typed.text : "";
+      })
+      .filter(Boolean)
+      .join("\n")
+      .trim();
+    return text;
+  }
+
+  private extractCopilotAssistantText(entry: Record<string, unknown>): string {
+    if (entry.type !== "assistant.message") {
+      return "";
+    }
+    const data = entry.data as Record<string, unknown> | undefined;
+    if (!data || typeof data.content !== "string") {
+      return "";
+    }
+    return data.content.trim();
+  }
+
   private async waitStreamStart(previousSnapshot: ScreenSnapshot): Promise<void> {
     const timeout = this.resolveTimeout(this.profile.timeouts?.streamStart, 10000);
-    const replyStartMatcher = this.profile.signals?.replyStart?.length
-      ? Matchers.anyOf(this.profile.signals.replyStart, "scrollback")
-      : null;
 
     if (this.profile.anchors.busy && this.profile.anchors.busy.length > 0) {
       const busyPatterns = this.profile.anchors.busy;
       const previousScrollback = previousSnapshot.scrollbackText;
       const startMatcher = (snapshot: ScreenSnapshot): boolean => {
-        const { added } = computeLineDiff(previousScrollback, snapshot.scrollbackText);
-        if (added.some(line => busyPatterns.some(pattern => pattern.test(line)))) {
+        this.assertAliveOrThrow();
+        const added = this.getChangedTailLines(previousScrollback, snapshot.scrollbackText);
+        if (this.anyAddedLineMatches(added, busyPatterns)) {
           return true;
         }
-        if (replyStartMatcher && replyStartMatcher(snapshot)) {
+        const hasNewReplyStart = this.hasNewScrollbackPatternSince(
+          previousScrollback,
+          snapshot.scrollbackText,
+          this.profile.signals?.replyStart
+        );
+        if (hasNewReplyStart) {
           this.log("waitStreamStart: replyStart detected before busy status");
           return true;
         }
+        if (this.behavior.matchStreamStartFallback?.({
+          previousSnapshot,
+          snapshot,
+          previousScrollback,
+          addedLines: added,
+          hasNewReplyStart,
+        })) {
+          this.log("waitStreamStart: matched backend fallback condition");
+          return true;
+        }
         return false;
       };
       const result = await this.expect.until({
@@ -415,38 +1429,84 @@ export class TuiDriver extends EventEmitter {
     }
   }
 
-  private async waitStreamEnd(): Promise<void> {
+  private async waitStreamEnd(turnStartSnapshot?: ScreenSnapshot): Promise<void> {
     const idleMs = this.profile.timeouts?.idle ?? 800;
     const timeout = this.resolveTimeout(this.profile.timeouts?.streamEnd, 120000);
+    const turnStartScrollback = turnStartSnapshot?.scrollbackText ?? "";
+    const turnStartHash = turnStartSnapshot?.hash ?? "";
+    const replyWaitStartAt = Date.now();
 
     const readyMatcher = Matchers.anyOf(this.profile.anchors.ready);
     const busyMatcher = this.profile.anchors.busy?.length
       ? Matchers.anyOf(this.profile.anchors.busy)
       : null;
-    const replyStartMatcher = this.profile.signals?.replyStart?.length
-      ? Matchers.anyOf(this.profile.signals.replyStart, "scrollback")
-      : null;
-    const promptHintMatcher = this.profile.signals?.promptHint?.length
-      ? Matchers.anyOf(this.profile.signals.promptHint)
+    const promptMatcher = this.profile.signals?.prompt?.length
+      ? Matchers.anyOf(this.profile.signals.prompt)
       : null;
+    const hasNewReplyStart = (snapshot: ScreenSnapshot): boolean =>
+      this.hasNewScrollbackPatternSince(turnStartScrollback, snapshot.scrollbackText, this.profile.signals?.replyStart);
+    const hasNewPromptHint = (snapshot: ScreenSnapshot): boolean =>
+      this.hasNewScrollbackPatternSince(turnStartScrollback, snapshot.scrollbackText, this.profile.signals?.promptHint);
+    const hasPromptHintSignal = Boolean(this.profile.signals?.promptHint?.length);
     const statusMatcher = this.profile.signals?.status?.length
       ? Matchers.anyOf(this.profile.signals.status)
       : null;
     const statusDoneMatcher = this.profile.signals?.statusDone?.length
       ? Matchers.anyOf(this.profile.signals.statusDone)
       : null;
+    let sawBusyDuringWait = false;
+    const hasAnyNewScrollbackLine = (snapshot: ScreenSnapshot): boolean => {
+      const added = this.getChangedTailLines(turnStartScrollback, snapshot.scrollbackText);
+      return added.some((line) => line.trim().length > 0);
+    };
 
     // 组合条件：屏幕 idle + ready anchor 出现 + busy anchor 消失
-    const completeMatcher = busyMatcher
+    const defaultCompleteMatcher = busyMatcher
       ? Matchers.and(readyMatcher, Matchers.not(busyMatcher))
       : readyMatcher;
-
-    if (this.profile.requireReplyStart && replyStartMatcher) {
+    const completeMatcher = this.behavior.buildStreamEndCompleteMatcher
+      ? this.behavior.buildStreamEndCompleteMatcher({
+          readyMatcher,
+          busyMatcher,
+          defaultMatcher: defaultCompleteMatcher,
+        })
+      : defaultCompleteMatcher;
+
+    if (this.profile.requireReplyStart && this.profile.signals?.replyStart?.length) {
       const replyOrHintResult = await this.expect.until({
         name: "STREAM_END_REPLY_OR_HINT",
-        match: promptHintMatcher
-          ? Matchers.or(replyStartMatcher, promptHintMatcher)
-          : replyStartMatcher,
+        match: Matchers.custom((snapshot) => {
+          this.assertAliveOrThrow();
+          const busyNow = busyMatcher ? busyMatcher(snapshot) : false;
+          if (busyNow) {
+            sawBusyDuringWait = true;
+          }
+          const fallbackMatched = this.behavior.matchStreamEndReplyFallback
+            ? this.behavior.matchStreamEndReplyFallback({
+                snapshot,
+                turnStartSnapshot,
+                turnStartScrollback,
+                turnStartHash,
+                readyMatcher,
+                busyMatcher,
+                promptMatcher,
+                sawBusyDuringWait,
+                waitStartedAt: replyWaitStartAt,
+                hasAnyNewScrollbackLine,
+              })
+            : false;
+          if (fallbackMatched) {
+            this.log("waitStreamEnd: matched backend reply fallback condition");
+            return true;
+          }
+          if (hasNewReplyStart(snapshot)) {
+            return true;
+          }
+          if (hasPromptHintSignal && hasNewPromptHint(snapshot)) {
+            return true;
+          }
+          return false;
+        }),
         stableMs: 200,
         timeoutMs: timeout,
       });
@@ -456,15 +1516,15 @@ export class TuiDriver extends EventEmitter {
 
       // Check if we matched promptHint but not replyStart - this indicates potential empty response
       const snapshot = this.screen.snapshot();
-      const hasReplyStart = replyStartMatcher(snapshot);
-      if (!hasReplyStart && promptHintMatcher) {
-        const hasPromptHint = promptHintMatcher(snapshot);
+      const hasReplyStart = hasNewReplyStart(snapshot);
+      if (!hasReplyStart && hasPromptHintSignal) {
+        const hasPromptHint = hasNewPromptHint(snapshot);
         if (hasPromptHint) {
           this.log(`waitStreamEnd: WARNING - promptHint matched but replyStart did not. Waiting for actual reply...`);
           // Wait a bit longer for the actual reply to appear
           const retryResult = await this.expect.until({
             name: "STREAM_END_REPLY_RETRY",
-            match: replyStartMatcher,
+            match: Matchers.custom((nextSnapshot) => hasNewReplyStart(nextSnapshot)),
             stableMs: 200,
             timeoutMs: 10000, // Give it 10 more seconds
           });
@@ -474,14 +1534,32 @@ export class TuiDriver extends EventEmitter {
         }
       }
 
-      await this.waitForScrollbackIdle(idleMs, timeout);
+      await this.waitForScrollbackIdle(idleMs, timeout, (snapshot) => {
+        const hasPrompt = promptMatcher ? promptMatcher(snapshot) : readyMatcher(snapshot);
+        const busyNow = busyMatcher ? busyMatcher(snapshot) : false;
+        if (!hasPrompt || busyNow) {
+          return false;
+        }
+        const currentSignals = this.getSignals(snapshot);
+        return !currentSignals.replyInProgress;
+      });
 
       if (statusMatcher) {
+        const defaultStatusClearMatcher = statusDoneMatcher
+          ? Matchers.or(Matchers.not(statusMatcher), statusDoneMatcher)
+          : Matchers.not(statusMatcher);
+        const statusClearMatcher = this.behavior.buildStreamEndStatusClearMatcher
+          ? this.behavior.buildStreamEndStatusClearMatcher({
+              defaultMatcher: defaultStatusClearMatcher,
+              getSignals: (snapshot) => this.getSignals(snapshot),
+            })
+          : defaultStatusClearMatcher;
         const statusClearResult = await this.expect.until({
           name: "STREAM_END_STATUS_CLEAR",
-          match: statusDoneMatcher
-            ? Matchers.or(Matchers.not(statusMatcher), statusDoneMatcher)
-            : Matchers.not(statusMatcher),
+          match: Matchers.custom((snapshot) => {
+            this.assertAliveOrThrow();
+            return statusClearMatcher(snapshot);
+          }),
           stableMs: 300,
           timeoutMs: timeout,
         });
@@ -505,7 +1583,10 @@ export class TuiDriver extends EventEmitter {
     if (this.profile.requireReplyStart) {
       const readyResult = await this.expect.until({
         name: "STREAM_END_READY",
-        match: completeMatcher,
+        match: Matchers.custom((snapshot) => {
+          this.assertAliveOrThrow();
+          return completeMatcher(snapshot);
+        }),
         stableMs: 500,
         timeoutMs: 3000,
       });
@@ -515,7 +1596,10 @@ export class TuiDriver extends EventEmitter {
     } else {
       const readyResult = await this.expect.until({
         name: "STREAM_END_READY",
-        match: completeMatcher,
+        match: Matchers.custom((snapshot) => {
+          this.assertAliveOrThrow();
+          return completeMatcher(snapshot);
+        }),
         stableMs: 500,
         timeoutMs: 10000,
       });
@@ -593,13 +1677,98 @@ export class TuiDriver extends EventEmitter {
 
   private async restart(): Promise<void> {
     this.log("Restarting PTY...");
+    const restartSession = await this.resolveRestartSessionInfo();
+    const restartArgs = this.resolveRestartArgs(restartSession?.sessionId);
+    if (restartSession?.sessionId) {
+      this.log(
+        `restart resume target: backend=${this.profile.name} session=${restartSession.sessionId} args=${JSON.stringify(restartArgs)}`,
+      );
+    } else {
+      this.log(`restart without resume: backend=${this.profile.name} args=${JSON.stringify(restartArgs)}`);
+    }
     this.pty.kill();
+    this.pty.setCommandArgs(this.initialCommand, restartArgs);
     this.screen.reset();
     this.isBooted = false;
     await this.sleep(500);
     await this.boot();
   }
 
+  private async resolveRestartSessionInfo(): Promise<TuiSessionInfo | null> {
+    const cached = this.sessionInfo ?? this.lastSessionInfo;
+    if (cached?.sessionId) {
+      return { ...cached };
+    }
+    if (!this.supportsSessionFileTracking()) {
+      return null;
+    }
+    const detected = await this.detectSessionInfoByBackend();
+    if (!detected?.sessionId) {
+      return null;
+    }
+    this.lastSessionInfo = detected;
+    return { ...detected };
+  }
+
+  private resolveRestartArgs(sessionId?: string): string[] {
+    const normalizedSessionId = String(sessionId || "").trim();
+    if (!normalizedSessionId) {
+      return [...this.initialArgs];
+    }
+    const baseArgs = this.stripResumeArgs(this.initialArgs, this.profile.name);
+    const resumeArgs = this.buildResumeArgsForBackend(this.profile.name, normalizedSessionId);
+    if (resumeArgs.length === 0) {
+      return [...this.initialArgs];
+    }
+    return [...baseArgs, ...resumeArgs];
+  }
+
+  private stripResumeArgs(args: string[], backendName: string): string[] {
+    const result: string[] = [];
+    const backend = String(backendName || "").toLowerCase();
+
+    for (let index = 0; index < args.length; index += 1) {
+      const current = String(args[index] || "");
+      const next = args[index + 1];
+
+      if (current === "--resume") {
+        index += 1;
+        continue;
+      }
+      if (current.startsWith("--resume=")) {
+        continue;
+      }
+      if ((backend === "codex" || backend === "code") && current === "resume") {
+        if (typeof next === "string" && next.length > 0) {
+          index += 1;
+        }
+        continue;
+      }
+
+      result.push(current);
+    }
+
+    return result;
+  }
+
+  private buildResumeArgsForBackend(backendName: string, sessionId: string): string[] {
+    const normalizedBackend = String(backendName || "").toLowerCase();
+    const normalizedSessionId = String(sessionId || "").trim();
+    if (!normalizedSessionId) {
+      return [];
+    }
+    if (normalizedBackend === "codex" || normalizedBackend === "code") {
+      return ["resume", normalizedSessionId];
+    }
+    if (normalizedBackend === "claude-code" || normalizedBackend === "claude") {
+      return ["--resume", normalizedSessionId];
+    }
+    if (normalizedBackend === "copilot") {
+      return [`--resume=${normalizedSessionId}`];
+    }
+    return [];
+  }
+
   private captureSnapshot(label: string): ScreenSnapshot {
     const snapshot = this.screen.snapshot();
     if (this.onSnapshot) {
@@ -750,9 +1919,24 @@ export class TuiDriver extends EventEmitter {
       this.log(`getSignals: DEBUG scrollback tail (last 30 lines):\n${lastLines.map((l, i) => `  [${lines.length - 30 + i}] "${l}"`).join('\n')}`);
     }
     const promptLine = this.findLastMatch(lines, signals.prompt);
-    const statusLine = this.findLastMatch(lines, signals.status);
-    const statusDoneLine = this.findLastMatch(lines, signals.statusDone);
-    const reply = this.extractReplyBlocks(lines, signals);
+    const signalScopeLines = this.behavior.getSignalScopeLines
+      ? this.behavior.getSignalScopeLines({
+          lines,
+          signals,
+          helpers: { findLastMatch: this.findLastMatch.bind(this) },
+        })
+      : lines;
+    const defaultStatusLine = this.findLastMatch(signalScopeLines, signals.status);
+    const statusLine = this.behavior.resolveStatusLine
+      ? this.behavior.resolveStatusLine({
+          lines: signalScopeLines,
+          signals,
+          defaultStatusLine,
+          helpers: { findLastMatch: this.findLastMatch.bind(this) },
+        })
+      : defaultStatusLine;
+    const statusDoneLine = this.findLastMatch(signalScopeLines, signals.statusDone);
+    const reply = this.extractReplyBlocks(signalScopeLines, signals);
     this.log(`getSignals: promptLine="${promptLine || '(none)'}" statusLine="${statusLine || '(none)'}" reply.text="${reply.text?.slice(0, 100) || '(none)'}" reply.blocks=${reply.blocks.length}`);
 
     return {
@@ -774,10 +1958,29 @@ export class TuiDriver extends EventEmitter {
     this.pty.write(data);
   }
 
+  async forceRestart(): Promise<void> {
+    await this.restart();
+  }
+
   kill(): void {
+    this.isKilled = true;
     this.pty.kill();
     this.screen.dispose();
     this.isBooted = false;
+    this.sessionInfo = null;
+    this.lastSessionInfo = null;
+  }
+
+  private createSessionClosedError(): Error {
+    const error = new Error("TUI session closed");
+    (error as any).reason = "session_closed";
+    return error;
+  }
+
+  private assertAliveOrThrow(): void {
+    if (this.isKilled || !this.running) {
+      throw this.createSessionClosedError();
+    }
   }
 
   private sleep(ms: number): Promise<void> {
@@ -787,28 +1990,70 @@ export class TuiDriver extends EventEmitter {
   private terminateSessionForLoginRequired(): void {
     this.pty.kill();
     this.isBooted = false;
+    this.sessionInfo = null;
+    this.lastSessionInfo = null;
   }
 
   private resolveTimeout(timeoutMs: number | undefined, defaultTimeoutMs: number): number {
-    const value = timeoutMs ?? defaultTimeoutMs;
-    if (!Number.isFinite(value) || value <= 0) {
-      return Number.POSITIVE_INFINITY;
+    const fallback = this.normalizeTimeoutValue(defaultTimeoutMs, Math.max(MIN_STAGE_TIMEOUT_MS, defaultTimeoutMs));
+    return this.normalizeTimeoutValue(timeoutMs, fallback);
+  }
+
+  private normalizeTimeoutValue(timeoutMs: number | undefined, fallback: number): number {
+    const parsed = Number(timeoutMs);
+    if (!Number.isFinite(parsed)) {
+      return fallback;
     }
-    return value;
+    // `0` means "disable hard timeout" for long-running turns.
+    if (parsed === 0) {
+      return this.resolveMaxStageTimeoutMs();
+    }
+    if (parsed < 0) {
+      return fallback;
+    }
+    const bounded = Math.max(MIN_STAGE_TIMEOUT_MS, Math.round(parsed));
+    return Math.min(bounded, this.resolveMaxStageTimeoutMs());
+  }
+
+  private resolveMaxStageTimeoutMs(): number {
+    const raw = process.env.CONDUCTOR_TUI_MAX_TIMEOUT_MS;
+    const parsed = Number.parseInt(String(raw || ""), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+      return DEFAULT_STAGE_TIMEOUT_MAX_MS;
+    }
+    return Math.min(Math.max(parsed, MIN_STAGE_TIMEOUT_MS), ABSOLUTE_STAGE_TIMEOUT_MAX_MS);
   }
 
-  private async waitForScrollbackIdle(idleMs: number, timeoutMs: number): Promise<void> {
+  private async waitForScrollbackIdle(
+    idleMs: number,
+    timeoutMs: number,
+    completionHint?: (snapshot: ScreenSnapshot) => boolean
+  ): Promise<void> {
     const startTime = Date.now();
     let lastHash = ScreenSnapshot.computeHash(this.screen.snapshot().scrollbackText);
     let lastChangeTime = Date.now();
+    let hintStableSince: number | null = null;
+    const boundedTimeoutMs = Number.isFinite(timeoutMs) ? timeoutMs : 60000;
 
     while (true) {
+      this.assertAliveOrThrow();
       const elapsed = Date.now() - startTime;
-      if (elapsed >= timeoutMs) {
+      if (elapsed >= boundedTimeoutMs) {
         throw new Error("Stream end timeout: scrollback did not become idle");
       }
 
-      const currentHash = ScreenSnapshot.computeHash(this.screen.snapshot().scrollbackText);
+      const snapshot = this.screen.snapshot();
+      if (completionHint && completionHint(snapshot)) {
+        if (hintStableSince === null) {
+          hintStableSince = Date.now();
+        } else if (Date.now() - hintStableSince >= idleMs) {
+          return;
+        }
+      } else {
+        hintStableSince = null;
+      }
+
+      const currentHash = ScreenSnapshot.computeHash(snapshot.scrollbackText);
       if (currentHash !== lastHash) {
         lastHash = currentHash;
         lastChangeTime = Date.now();
@@ -835,6 +2080,48 @@ export class TuiDriver extends EventEmitter {
     return null;
   }
 
+  private anyAddedLineMatches(lines: string[], patterns?: RegExp[]): boolean {
+    if (!patterns || patterns.length === 0 || lines.length === 0) {
+      return false;
+    }
+    return lines.some((line) => this.lineMatchesAny(line, patterns));
+  }
+
+  private lineMatchesAny(line: string, patterns: RegExp[]): boolean {
+    for (const pattern of patterns) {
+      pattern.lastIndex = 0;
+      if (pattern.test(line)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private hasNewScrollbackPatternSince(previousScrollback: string, currentScrollback: string, patterns?: RegExp[]): boolean {
+    if (!patterns || patterns.length === 0) {
+      return false;
+    }
+    const added = this.getChangedTailLines(previousScrollback, currentScrollback);
+    return this.anyAddedLineMatches(added, patterns);
+  }
+
+  private getChangedTailLines(previousScrollback: string, currentScrollback: string): string[] {
+    const previousLines = previousScrollback.split("\n");
+    const currentLines = currentScrollback.split("\n");
+    const minLength = Math.min(previousLines.length, currentLines.length);
+    let prefixLength = 0;
+
+    while (prefixLength < minLength && previousLines[prefixLength] === currentLines[prefixLength]) {
+      prefixLength += 1;
+    }
+
+    if (prefixLength >= currentLines.length) {
+      return [];
+    }
+
+    return currentLines.slice(prefixLength);
+  }
+
   private extractReplyBlocks(
     lines: string[],
     signals: TuiSignals