pty-manager 1.6.2 → 1.6.4

package/README.md

@@ -216,6 +216,8 @@ interface SpawnConfig {
   rows?: number;         // Terminal rows (default: 40)
   timeout?: number;      // Session timeout in ms
   readySettleMs?: number; // Override adapter's ready settle delay
+  stallTimeoutMs?: number; // Override manager stall timeout for this session
+  traceTaskCompletion?: boolean; // Verbose completion trace logs (auto-enabled for Claude)
 }
 ```
 
@@ -479,12 +481,60 @@ Content-based stall detection monitors sessions for output that stops changing.
 
 ### Task Completion Fast-Path (Settle Pattern)
 
-When a busy session's output matches the adapter's `detectReady()` pattern, a `task_complete` debounce timer starts. TUI agents like Claude Code continue rendering decorative output after the prompt — update notices, shortcut hints, status bar updates. Instead of cancelling the timer on each new data chunk (which would prevent the event from ever firing), the session uses a **settle pattern**: the debounce timer resets on each new chunk but is never cancelled. The timer callback re-verifies `detectReady()` before transitioning, so stale triggers are safe.
+When a busy session's output matches the adapter's task-complete signal (`detectTaskComplete()` when implemented, otherwise `detectReady()`), a `task_complete` debounce timer starts. TUI agents like Claude Code continue rendering decorative output after the prompt — update notices, shortcut hints, status bar updates. Instead of cancelling the timer on each new data chunk (which would prevent the event from ever firing), the session uses a **settle pattern**: the debounce timer resets on each new chunk but is never cancelled. The timer callback re-verifies the same task-complete signal before transitioning, so stale triggers are safe.
 
 This mirrors the `readySettlePending` pattern used for startup ready detection, and ensures the `task_complete` event fires reliably even when TUI chrome continues rendering after the agent has finished its task.
 
 If the fast-path timer doesn't fire (e.g. the prompt indicator disappears from the buffer), the session falls back to stall detection which emits `stall_detected` for external classification.
 
+### Task Completion Trace Logs (Claude-focused)
+
+`PTYSession` now emits structured debug logs with message `"Task completion trace"` at each completion transition point:
+
+- `busy_signal`
+- `debounce_schedule`
+- `debounce_fire`
+- `debounce_reject_status`
+- `debounce_reject_signal`
+- `transition_ready`
+
+By default, tracing is enabled for adapter type `claude`. You can override per session:
+
+```typescript
+const handle = await manager.spawn({
+  name: 'agent',
+  type: 'claude',
+  traceTaskCompletion: true, // force on
+  // traceTaskCompletion: false, // force off
+});
+```
+
+Each trace includes detection booleans (`detectTaskComplete`, `detectReady`, `detectLoading`) and a normalized tail hash/snippet to correlate against PTY output captures.
+
+### Completion Confidence Timeline Utility
+
+Use the exported helpers to turn raw trace logs into a per-turn confidence timeline:
+
+```typescript
+import {
+  extractTaskCompletionTraceRecords,
+  buildTaskCompletionTimeline,
+} from 'pty-manager';
+
+const records = extractTaskCompletionTraceRecords(mixedLogEntries);
+const timeline = buildTaskCompletionTimeline(records, { adapterType: 'claude' });
+
+console.log(timeline.turns);
+```
+
+The timeline classifies each trace step as:
+
+- `active`
+- `active_loading`
+- `likely_complete`
+- `rejected`
+- `completed`
+
 ```typescript
 // Enable stall detection with a pluggable classifier
 const session = await manager.spawn({

package/dist/index.d.mts

@@ -40,6 +40,9 @@ interface SpawnConfig {
     /** Override adapter's readySettleMs for this session.
      *  Ms of output silence after detectReady match before emitting session_ready. */
     readySettleMs?: number;
+    /** Enable verbose task-completion trace logs.
+     *  If unset, PTYSession enables this automatically for adapter type "claude". */
+    traceTaskCompletion?: boolean;
     /** Override or disable specific adapter auto-response rules for this session.
      *  Keys are regex source strings (from rule.pattern.source).
      *  - null value disables that rule entirely
@@ -460,6 +463,8 @@ declare class PTYSession extends EventEmitter {
     private _lastContentHash;
     private _stallBackoffMs;
     private static readonly MAX_STALL_BACKOFF_MS;
+    private _stallEmissionCount;
+    private static readonly MAX_STALL_EMISSIONS;
     private _taskCompleteTimer;
     private _taskCompletePending;
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
@@ -541,10 +546,21 @@ declare class PTYSession extends EventEmitter {
      * being a no-op when already scheduled. This allows TUI agents that
      * continue rendering decorative output (status bar, update notices) after
      * the prompt to eventually settle, rather than having the timer cancelled
-     * by every new data chunk. The callback re-verifies detectReady() before
-     * transitioning, so stale triggers are safe.
+     * by every new data chunk. The callback re-verifies the task-complete
+     * signal before transitioning, so stale triggers are safe.
      */
     private scheduleTaskComplete;
+    /**
+     * Adapter-level task completion check with compatibility fallback.
+     * Prefer detectTaskComplete() because detectReady() may be broad for TUIs.
+     */
+    private isTaskCompleteSignal;
+    /**
+     * Claude-oriented task completion traces for PTY debugging.
+     * Enabled by config.traceTaskCompletion, otherwise defaults to enabled for Claude.
+     */
+    private traceTaskCompletion;
+    private shouldTraceTaskCompletion;
     /**
      * Cancel a pending task_complete timer (new output arrived that
      * doesn't match the idle prompt, so the agent is still working).
@@ -784,6 +800,65 @@ declare class PTYManager extends EventEmitter {
     clearAutoResponseRules(sessionId: string): void;
 }
 
+/**
+ * Task completion trace analysis helpers.
+ *
+ * Parses structured "Task completion trace" logs and builds a compact
+ * per-turn confidence timeline useful for debugging idle/completion detection.
+ */
+interface TaskCompletionTraceRecord {
+    sessionId?: string;
+    adapterType?: string;
+    event: string;
+    status?: string;
+    taskCompletePending?: boolean;
+    signal?: boolean;
+    wasPending?: boolean;
+    debounceMs?: number;
+    detectTaskComplete?: boolean;
+    detectReady?: boolean;
+    detectLoading?: boolean;
+    tailHash?: string;
+    tailSnippet?: string;
+    timestamp?: string | number | Date;
+}
+interface TaskCompletionTimelineStep {
+    event: string;
+    atIndex: number;
+    status: 'active' | 'active_loading' | 'likely_complete' | 'completed' | 'rejected';
+    confidence: number;
+    signal?: boolean;
+    detectTaskComplete?: boolean;
+    detectReady?: boolean;
+    detectLoading?: boolean;
+}
+interface TaskCompletionTurnTimeline {
+    turn: number;
+    startIndex: number;
+    endIndex: number;
+    completed: boolean;
+    maxConfidence: number;
+    finalConfidence: number;
+    events: TaskCompletionTimelineStep[];
+}
+interface TaskCompletionTimelineResult {
+    turns: TaskCompletionTurnTimeline[];
+    totalRecords: number;
+    ignoredRecords: number;
+}
+interface BuildTimelineOptions {
+    adapterType?: string;
+}
+/**
+ * Extract trace records from mixed log inputs.
+ * Accepts structured objects and JSON lines.
+ */
+declare function extractTaskCompletionTraceRecords(entries: Array<string | Record<string, unknown>>): TaskCompletionTraceRecord[];
+/**
+ * Build a per-turn confidence timeline from task-completion traces.
+ */
+declare function buildTaskCompletionTimeline(records: TaskCompletionTraceRecord[], options?: BuildTimelineOptions): TaskCompletionTimelineResult;
+
 /**
  * Base CLI Adapter
  *
@@ -1075,4 +1150,4 @@ declare function isBun(): boolean;
  */
 declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };

package/dist/index.d.ts

@@ -40,6 +40,9 @@ interface SpawnConfig {
     /** Override adapter's readySettleMs for this session.
      *  Ms of output silence after detectReady match before emitting session_ready. */
     readySettleMs?: number;
+    /** Enable verbose task-completion trace logs.
+     *  If unset, PTYSession enables this automatically for adapter type "claude". */
+    traceTaskCompletion?: boolean;
     /** Override or disable specific adapter auto-response rules for this session.
      *  Keys are regex source strings (from rule.pattern.source).
      *  - null value disables that rule entirely
@@ -460,6 +463,8 @@ declare class PTYSession extends EventEmitter {
     private _lastContentHash;
     private _stallBackoffMs;
     private static readonly MAX_STALL_BACKOFF_MS;
+    private _stallEmissionCount;
+    private static readonly MAX_STALL_EMISSIONS;
     private _taskCompleteTimer;
     private _taskCompletePending;
     private static readonly TASK_COMPLETE_DEBOUNCE_MS;
@@ -541,10 +546,21 @@ declare class PTYSession extends EventEmitter {
      * being a no-op when already scheduled. This allows TUI agents that
      * continue rendering decorative output (status bar, update notices) after
      * the prompt to eventually settle, rather than having the timer cancelled
-     * by every new data chunk. The callback re-verifies detectReady() before
-     * transitioning, so stale triggers are safe.
+     * by every new data chunk. The callback re-verifies the task-complete
+     * signal before transitioning, so stale triggers are safe.
      */
     private scheduleTaskComplete;
+    /**
+     * Adapter-level task completion check with compatibility fallback.
+     * Prefer detectTaskComplete() because detectReady() may be broad for TUIs.
+     */
+    private isTaskCompleteSignal;
+    /**
+     * Claude-oriented task completion traces for PTY debugging.
+     * Enabled by config.traceTaskCompletion, otherwise defaults to enabled for Claude.
+     */
+    private traceTaskCompletion;
+    private shouldTraceTaskCompletion;
     /**
      * Cancel a pending task_complete timer (new output arrived that
      * doesn't match the idle prompt, so the agent is still working).
@@ -784,6 +800,65 @@ declare class PTYManager extends EventEmitter {
     clearAutoResponseRules(sessionId: string): void;
 }
 
+/**
+ * Task completion trace analysis helpers.
+ *
+ * Parses structured "Task completion trace" logs and builds a compact
+ * per-turn confidence timeline useful for debugging idle/completion detection.
+ */
+interface TaskCompletionTraceRecord {
+    sessionId?: string;
+    adapterType?: string;
+    event: string;
+    status?: string;
+    taskCompletePending?: boolean;
+    signal?: boolean;
+    wasPending?: boolean;
+    debounceMs?: number;
+    detectTaskComplete?: boolean;
+    detectReady?: boolean;
+    detectLoading?: boolean;
+    tailHash?: string;
+    tailSnippet?: string;
+    timestamp?: string | number | Date;
+}
+interface TaskCompletionTimelineStep {
+    event: string;
+    atIndex: number;
+    status: 'active' | 'active_loading' | 'likely_complete' | 'completed' | 'rejected';
+    confidence: number;
+    signal?: boolean;
+    detectTaskComplete?: boolean;
+    detectReady?: boolean;
+    detectLoading?: boolean;
+}
+interface TaskCompletionTurnTimeline {
+    turn: number;
+    startIndex: number;
+    endIndex: number;
+    completed: boolean;
+    maxConfidence: number;
+    finalConfidence: number;
+    events: TaskCompletionTimelineStep[];
+}
+interface TaskCompletionTimelineResult {
+    turns: TaskCompletionTurnTimeline[];
+    totalRecords: number;
+    ignoredRecords: number;
+}
+interface BuildTimelineOptions {
+    adapterType?: string;
+}
+/**
+ * Extract trace records from mixed log inputs.
+ * Accepts structured objects and JSON lines.
+ */
+declare function extractTaskCompletionTraceRecords(entries: Array<string | Record<string, unknown>>): TaskCompletionTraceRecord[];
+/**
+ * Build a per-turn confidence timeline from task-completion traces.
+ */
+declare function buildTaskCompletionTimeline(records: TaskCompletionTraceRecord[], options?: BuildTimelineOptions): TaskCompletionTimelineResult;
+
 /**
  * Base CLI Adapter
  *
@@ -1075,4 +1150,4 @@ declare function isBun(): boolean;
  */
 declare function createPTYManager(options?: BunPTYManagerOptions): BunCompatiblePTYManager;
 
-export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TerminalAttachment, type WorkerSessionHandle, createAdapter, createPTYManager, isBun };
+export { type AdapterFactoryConfig, AdapterRegistry, type AutoResponseRule, BaseCLIAdapter, type BlockingPromptDetection, type BlockingPromptInfo, type BlockingPromptType, type BuildTimelineOptions, BunCompatiblePTYManager, type BunPTYManagerOptions, type CLIAdapter, type LogOptions, type Logger, type LoginDetection, type MessageType, PTYManager, type PTYManagerConfig, type PTYManagerEvents, PTYSession, type PTYSessionEvents, type ParsedOutput, SPECIAL_KEYS, type SessionFilter, type SessionHandle, type SessionMessage, type SessionStatus, ShellAdapter, type ShellAdapterOptions, type SpawnConfig, type StallClassification, type StopOptions, type TaskCompletionTimelineResult, type TaskCompletionTimelineStep, type TaskCompletionTraceRecord, type TaskCompletionTurnTimeline, type TerminalAttachment, type WorkerSessionHandle, buildTaskCompletionTimeline, createAdapter, createPTYManager, extractTaskCompletionTraceRecords, isBun };

package/dist/index.js

@@ -37,8 +37,10 @@ __export(index_exports, {
   PTYSession: () => PTYSession,
   SPECIAL_KEYS: () => SPECIAL_KEYS,
   ShellAdapter: () => ShellAdapter,
+  buildTaskCompletionTimeline: () => buildTaskCompletionTimeline,
   createAdapter: () => createAdapter,
   createPTYManager: () => createPTYManager,
+  extractTaskCompletionTraceRecords: () => extractTaskCompletionTraceRecords,
   isBun: () => isBun
 });
 module.exports = __toCommonJS(index_exports);
@@ -348,6 +350,8 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
   _stallBackoffMs = 0;
   // Initialized in constructor from _stallTimeoutMs
   static MAX_STALL_BACKOFF_MS = 3e4;
+  _stallEmissionCount = 0;
+  static MAX_STALL_EMISSIONS = 5;
   // Task completion detection (idle detection when busy)
   _taskCompleteTimer = null;
   _taskCompletePending = false;
@@ -465,6 +469,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       return;
     }
     this._lastContentHash = hash;
+    this._stallEmissionCount = 0;
     if (this._stallTimer) {
       clearTimeout(this._stallTimer);
       this._stallTimer = null;
@@ -487,6 +492,7 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     this._stallStartedAt = null;
     this._lastContentHash = null;
     this._stallBackoffMs = this._stallTimeoutMs;
+    this._stallEmissionCount = 0;
   }
   /**
    * Called when the stall timer fires (no output for stallTimeoutMs).
@@ -523,6 +529,15 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       );
       return;
     }
+    this._stallEmissionCount++;
+    if (this._stallEmissionCount > _PTYSession.MAX_STALL_EMISSIONS) {
+      this.logger.warn(
+        { sessionId: this.id, count: this._stallEmissionCount },
+        "Max stall emissions reached \u2014 suspending stall detection for this task"
+      );
+      this.clearStallTimer();
+      return;
+    }
     const recentRaw = this.outputBuffer.slice(-2e3);
     const recentOutput = this.stripAnsiForStall(recentRaw);
     const stallDurationMs = this._stallStartedAt ? Date.now() - this._stallStartedAt : this._stallTimeoutMs;
@@ -562,6 +577,8 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     let result = str.replace(/\x1b\[\d*[CDABGdEF]/g, " ");
     result = result.replace(/\x1b\[\d*(?:;\d+)?[Hf]/g, " ");
     result = result.replace(/\x1b\[\d*[JK]/g, " ");
+    result = result.replace(/\x1b\](?:[^\x07\x1b]|\x1b[^\\])*(?:\x07|\x1b\\)/g, "");
+    result = result.replace(/\x1bP(?:[^\x1b]|\x1b[^\\])*\x1b\\/g, "");
     result = result.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
     result = result.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "");
     result = result.replace(/\xa0/g, " ");
@@ -645,10 +662,15 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
    * being a no-op when already scheduled. This allows TUI agents that
    * continue rendering decorative output (status bar, update notices) after
    * the prompt to eventually settle, rather than having the timer cancelled
-   * by every new data chunk. The callback re-verifies detectReady() before
-   * transitioning, so stale triggers are safe.
+   * by every new data chunk. The callback re-verifies the task-complete
+   * signal before transitioning, so stale triggers are safe.
    */
   scheduleTaskComplete() {
+    const wasPending = this._taskCompletePending;
+    this.traceTaskCompletion("debounce_schedule", {
+      wasPending,
+      debounceMs: _PTYSession.TASK_COMPLETE_DEBOUNCE_MS
+    });
     if (this._taskCompleteTimer) {
       clearTimeout(this._taskCompleteTimer);
     }
@@ -656,17 +678,72 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
     this._taskCompleteTimer = setTimeout(() => {
       this._taskCompleteTimer = null;
       this._taskCompletePending = false;
-      if (this._status !== "busy") return;
-      if (!this.adapter.detectReady(this.outputBuffer)) return;
+      const signal = this.isTaskCompleteSignal(this.outputBuffer);
+      this.traceTaskCompletion("debounce_fire", { signal });
+      if (this._status !== "busy") {
+        this.traceTaskCompletion("debounce_reject_status", { signal });
+        return;
+      }
+      if (!signal) {
+        this.traceTaskCompletion("debounce_reject_signal", { signal });
+        return;
+      }
       this._status = "ready";
       this._lastBlockingPromptHash = null;
       this.outputBuffer = "";
       this.clearStallTimer();
       this.emit("status_changed", "ready");
       this.emit("task_complete");
+      this.traceTaskCompletion("transition_ready", { signal: true });
       this.logger.info({ sessionId: this.id }, "Task complete \u2014 agent returned to idle prompt");
     }, _PTYSession.TASK_COMPLETE_DEBOUNCE_MS);
   }
+  /**
+   * Adapter-level task completion check with compatibility fallback.
+   * Prefer detectTaskComplete() because detectReady() may be broad for TUIs.
+   */
+  isTaskCompleteSignal(output) {
+    if (this.adapter.detectTaskComplete) {
+      return this.adapter.detectTaskComplete(output);
+    }
+    return this.adapter.detectReady(output);
+  }
+  /**
+   * Claude-oriented task completion traces for PTY debugging.
+   * Enabled by config.traceTaskCompletion, otherwise defaults to enabled for Claude.
+   */
+  traceTaskCompletion(event, ctx = {}) {
+    if (!this.shouldTraceTaskCompletion()) return;
+    const output = this.outputBuffer;
+    const detectTaskComplete = this.adapter.detectTaskComplete ? this.adapter.detectTaskComplete(output) : void 0;
+    const detectReady = this.adapter.detectReady(output);
+    const detectLoading = this.adapter.detectLoading ? this.adapter.detectLoading(output) : void 0;
+    const normalizedTail = this.stripAnsiForStall(output.slice(-280));
+    this.logger.debug(
+      {
+        sessionId: this.id,
+        adapterType: this.adapter.adapterType,
+        event,
+        status: this._status,
+        taskCompletePending: this._taskCompletePending,
+        signal: ctx.signal,
+        wasPending: ctx.wasPending,
+        debounceMs: ctx.debounceMs,
+        detectTaskComplete,
+        detectReady,
+        detectLoading,
+        tailHash: this.simpleHash(normalizedTail),
+        tailSnippet: normalizedTail.slice(-140)
+      },
+      "Task completion trace"
+    );
+  }
+  shouldTraceTaskCompletion() {
+    if (typeof this.config.traceTaskCompletion === "boolean") {
+      return this.config.traceTaskCompletion;
+    }
+    return this.adapter.adapterType === "claude";
+  }
   /**
    * Cancel a pending task_complete timer (new output arrived that
    * doesn't match the idle prompt, so the agent is still working).
@@ -819,7 +896,9 @@ var PTYSession = class _PTYSession extends import_events.EventEmitter {
       return;
     }
     if (this._status === "busy") {
-      if (this._taskCompletePending || this.adapter.detectReady(this.outputBuffer)) {
+      const signal = this.isTaskCompleteSignal(this.outputBuffer);
+      if (this._taskCompletePending || signal) {
+        this.traceTaskCompletion("busy_signal", { signal });
         this.scheduleTaskComplete();
       }
     }
@@ -1570,6 +1649,171 @@ var PTYManager = class extends import_events2.EventEmitter {
   }
 };
 
+// src/task-completion-trace.ts
+function extractTaskCompletionTraceRecords(entries) {
+  const out = [];
+  for (const entry of entries) {
+    let obj = null;
+    if (typeof entry === "string") {
+      const line = entry.trim();
+      if (!line.startsWith("{") || !line.endsWith("}")) continue;
+      try {
+        obj = JSON.parse(line);
+      } catch {
+        continue;
+      }
+    } else if (entry && typeof entry === "object") {
+      obj = entry;
+    }
+    if (!obj) continue;
+    if (obj.msg !== "Task completion trace") continue;
+    if (typeof obj.event !== "string") continue;
+    out.push({
+      sessionId: asString(obj.sessionId),
+      adapterType: asString(obj.adapterType),
+      event: obj.event,
+      status: asString(obj.status),
+      taskCompletePending: asBool(obj.taskCompletePending),
+      signal: asBool(obj.signal),
+      wasPending: asBool(obj.wasPending),
+      debounceMs: asNumber(obj.debounceMs),
+      detectTaskComplete: asBool(obj.detectTaskComplete),
+      detectReady: asBool(obj.detectReady),
+      detectLoading: asBool(obj.detectLoading),
+      tailHash: asString(obj.tailHash),
+      tailSnippet: asString(obj.tailSnippet),
+      timestamp: asTimestamp(obj.time) ?? asTimestamp(obj.timestamp)
+    });
+  }
+  return out;
+}
+function buildTaskCompletionTimeline(records, options = {}) {
+  const filtered = records.filter((r) => {
+    if (!options.adapterType) return true;
+    return r.adapterType === options.adapterType;
+  });
+  const turns = [];
+  let current = null;
+  let ignored = 0;
+  filtered.forEach((record, index) => {
+    if (record.event === "busy_signal" && current && current.completed) {
+      current = null;
+    }
+    if (!current) {
+      current = {
+        turn: turns.length + 1,
+        startIndex: index,
+        endIndex: index,
+        completed: false,
+        maxConfidence: 0,
+        finalConfidence: 0,
+        events: []
+      };
+      turns.push(current);
+    }
+    const step = toStep(record, index);
+    if (!step) {
+      ignored++;
+      return;
+    }
+    current.events.push(step);
+    current.endIndex = index;
+    current.maxConfidence = Math.max(current.maxConfidence, step.confidence);
+    current.finalConfidence = step.confidence;
+    if (step.status === "completed") {
+      current.completed = true;
+    }
+  });
+  return {
+    turns,
+    totalRecords: filtered.length,
+    ignoredRecords: ignored
+  };
+}
+function toStep(record, atIndex) {
+  const event = record.event;
+  const confidence = scoreConfidence(record);
+  if (event === "transition_ready") {
+    return withCommon(record, {
+      event,
+      atIndex,
+      status: "completed",
+      confidence: 100
+    });
+  }
+  if (event === "debounce_reject_signal" || event === "debounce_reject_status") {
+    return withCommon(record, {
+      event,
+      atIndex,
+      status: "rejected",
+      confidence
+    });
+  }
+  if (record.detectLoading) {
+    return withCommon(record, {
+      event,
+      atIndex,
+      status: "active_loading",
+      confidence
+    });
+  }
+  if (event === "debounce_fire" && record.signal) {
+    return withCommon(record, {
+      event,
+      atIndex,
+      status: "likely_complete",
+      confidence
+    });
+  }
+  if (event === "busy_signal" || event === "debounce_schedule" || event === "debounce_fire") {
+    return withCommon(record, {
+      event,
+      atIndex,
+      status: "active",
+      confidence
+    });
+  }
+  return null;
+}
+function scoreConfidence(record) {
+  let score = 10;
+  if (record.detectLoading) score -= 40;
+  if (record.detectReady) score += 20;
+  if (record.detectTaskComplete) score += 45;
+  if (record.signal) score += 20;
+  if (record.event === "debounce_reject_signal" || record.event === "debounce_reject_status") {
+    score -= 30;
+  }
+  if (record.event === "transition_ready") score = 100;
+  if (score < 0) return 0;
+  if (score > 100) return 100;
+  return score;
+}
+function withCommon(record, step) {
+  return {
+    ...step,
+    signal: record.signal,
+    detectTaskComplete: record.detectTaskComplete,
+    detectReady: record.detectReady,
+    detectLoading: record.detectLoading
+  };
+}
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function asBool(value) {
+  return typeof value === "boolean" ? value : void 0;
+}
+function asNumber(value) {
+  return typeof value === "number" ? value : void 0;
+}
+function asTimestamp(value) {
+  if (typeof value === "string" || typeof value === "number" || value instanceof Date) {
+    return value;
+  }
+  return void 0;
+}
+
 // src/adapters/base-adapter.ts
 var import_child_process = require("child_process");
 var BaseCLIAdapter = class {
@@ -1799,7 +2043,9 @@ var BaseCLIAdapter = class {
    */
   stripAnsi(str) {
     const withSpaces = str.replace(/\x1b\[\d*C/g, " ");
-    return withSpaces.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
+    const withoutOsc = withSpaces.replace(/\x1b\](?:[^\x07\x1b]|\x1b[^\\])*(?:\x07|\x1b\\)/g, "");
+    const withoutDcs = withoutOsc.replace(/\x1bP(?:[^\x1b]|\x1b[^\\])*\x1b\\/g, "");
+    return withoutDcs.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
   }
 };
 
@@ -2494,8 +2740,10 @@ function createPTYManager(options) {
   PTYSession,
   SPECIAL_KEYS,
   ShellAdapter,
+  buildTaskCompletionTimeline,
   createAdapter,
   createPTYManager,
+  extractTaskCompletionTraceRecords,
   isBun
 });
 //# sourceMappingURL=index.js.map