fix: replace extension capping with timeout.extended/windingDown events (#522) (#524)

Instead of capping extensions to an external hard timeout (wrong model),
emit events that let the parent dynamically extend its own deadline:

- `timeout.extended`: emitted when observer grants extension, includes
  grantedMs so parent can adjust its Promise.race/deadline
- `timeout.windingDown`: emitted when observer declines, so parent
  knows agent is producing final answer

Remove externalHardTimeout option — the parent should wait for the child,
not cap it. The parent listens to events and stays in sync.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: buger

npm/src/agent/ProbeAgent.d.ts

@@ -116,8 +116,38 @@ export interface ProbeAgentOptions {
   negotiatedTimeoutMaxRequests?: number;
   /** Max ms per extension request for negotiated timeout (default: 600000 = 10 min). Env var: NEGOTIATED_TIMEOUT_MAX_PER_REQUEST */
   negotiatedTimeoutMaxPerRequest?: number;
-  /** External hard timeout ceiling in ms (e.g., visor's Promise.race timeout). When set, the observer caps extensions so granted time never exceeds this ceiling. Env var: EXTERNAL_HARD_TIMEOUT */
-  externalHardTimeout?: number | null;
+}
+
+/**
+ * Emitted when the negotiated timeout observer grants a time extension.
+ * Parent processes should listen to this event and extend their own deadlines accordingly.
+ */
+export interface TimeoutExtendedEvent {
+  /** Duration of the granted extension in milliseconds */
+  grantedMs: number;
+  /** Reason the observer granted the extension */
+  reason: string;
+  /** Number of extensions used so far */
+  extensionsUsed: number;
+  /** Number of extensions remaining */
+  extensionsRemaining: number;
+  /** Total extra time granted across all extensions in ms */
+  totalExtraTimeMs: number;
+  /** Remaining budget for future extensions in ms */
+  budgetRemainingMs: number;
+}
+
+/**
+ * Emitted when the negotiated timeout observer declines an extension and begins wind-down.
+ * After this event, the agent will produce its final answer and no more extensions will be granted.
+ */
+export interface TimeoutWindingDownEvent {
+  /** Reason the observer declined the extension */
+  reason: string;
+  /** Number of extensions used before declining */
+  extensionsUsed: number;
+  /** Total extra time granted across all extensions in ms */
+  totalExtraTimeMs: number;
 }
 
 /**

npm/src/agent/ProbeAgent.js

@@ -425,14 +425,6 @@ export class ProbeAgent {
       return (isNaN(parsed) || parsed < 60000 || parsed > 3600000) ? 600000 : parsed;
     })();
 
-    // External hard timeout: the caller's hard ceiling (e.g., visor's Promise.race timeout).
-    // When set, the observer caps extensions so granted time never exceeds this ceiling,
-    // preventing the agent from being killed mid-work with no partial results. (#522)
-    this.externalHardTimeout = options.externalHardTimeout ?? (() => {
-      const parsed = parseInt(process.env.EXTERNAL_HARD_TIMEOUT, 10);
-      return (isNaN(parsed) || parsed < 0) ? null : parsed;
-    })();
-
     // Graceful stop deadline: how long to wait for subagents/MCP after observer declines (default 45s)
     this.gracefulStopDeadline = options.gracefulStopDeadline ?? (() => {
       const parsed = parseInt(process.env.GRACEFUL_STOP_DEADLINE, 10);
@@ -3712,31 +3704,6 @@ Follow these instructions carefully:
           return;
         }
 
-        // Check external hard timeout headroom — if the caller has a hard ceiling
-        // (e.g., visor's Promise.race), decline extensions when headroom is insufficient (#522)
-        const MINIMUM_USEFUL_HEADROOM_MS = 60000; // 60s — less than this isn't useful for an extension
-        if (this.externalHardTimeout) {
-          const elapsed = Date.now() - negotiatedTimeoutState.startTime;
-          const externalHeadroom = Math.max(0, this.externalHardTimeout - elapsed);
-          if (externalHeadroom < MINIMUM_USEFUL_HEADROOM_MS) {
-            if (this.debug) {
-              console.log(`[DEBUG] Timeout observer: external hard timeout headroom exhausted (${Math.round(externalHeadroom / 1000)}s < ${MINIMUM_USEFUL_HEADROOM_MS / 1000}s minimum) — triggering graceful wind-down`);
-            }
-            if (this.tracer) {
-              this.tracer.addEvent('negotiated_timeout.external_headroom_exhausted', {
-                external_hard_timeout_ms: this.externalHardTimeout,
-                elapsed_ms: elapsed,
-                headroom_ms: externalHeadroom,
-                minimum_useful_ms: MINIMUM_USEFUL_HEADROOM_MS,
-                extensions_used: negotiatedTimeoutState.extensionsUsed,
-              });
-            }
-            await this._initiateGracefulStop(gracefulTimeoutState, 'external hard timeout headroom exhausted');
-            negotiatedTimeoutState.observerRunning = false;
-            return;
-          }
-        }
-
         // Build context for the observer
         const activeToolsList = Array.from(activeTools.values());
         const now = Date.now();
@@ -3843,22 +3810,7 @@ or
 
           if (decision.extend && decision.minutes > 0) {
             const requestedMs = Math.min(decision.minutes, maxPerReqMin) * 60000;
-            // Cap to external hard timeout headroom if set (#522)
-            const externalCap = this.externalHardTimeout
-              ? Math.max(0, this.externalHardTimeout - (Date.now() - negotiatedTimeoutState.startTime))
-              : Infinity;
-            const grantedMs = Math.min(requestedMs, remainingBudgetMs, negotiatedTimeoutState.maxPerRequestMs, externalCap);
-
-            // If capped below minimum useful time, decline instead of granting a useless extension
-            if (grantedMs < MINIMUM_USEFUL_HEADROOM_MS) {
-              if (this.debug) {
-                console.log(`[DEBUG] Timeout observer: extension capped to ${Math.round(grantedMs / 1000)}s (below ${MINIMUM_USEFUL_HEADROOM_MS / 1000}s minimum) — declining and triggering graceful wind-down`);
-              }
-              await this._initiateGracefulStop(gracefulTimeoutState, `extension capped below minimum useful time (${Math.round(grantedMs / 1000)}s)`);
-              negotiatedTimeoutState.observerRunning = false;
-              return;
-            }
-
+            const grantedMs = Math.min(requestedMs, remainingBudgetMs, negotiatedTimeoutState.maxPerRequestMs);
             const grantedMin = Math.round(grantedMs / 60000 * 10) / 10;
 
             // Update state
@@ -3895,6 +3847,18 @@ or
                 active_tools_count: activeToolsList.length,
               });
             }
+
+            // Notify the parent that the agent extended its timeout (#522).
+            // The parent can listen to this event and extend its own deadline
+            // (e.g., adjust Promise.race timeout) instead of killing the agent.
+            this.events.emit('timeout.extended', {
+              grantedMs,
+              reason: decision.reason || 'work in progress',
+              extensionsUsed: negotiatedTimeoutState.extensionsUsed,
+              extensionsRemaining: negotiatedTimeoutState.maxRequests - negotiatedTimeoutState.extensionsUsed,
+              totalExtraTimeMs: negotiatedTimeoutState.totalExtraTimeMs,
+              budgetRemainingMs: remainingBudgetMs - grantedMs,
+            });
           } else {
             // Observer decided not to extend — two-phase graceful stop
             if (this.debug) {
@@ -3911,6 +3875,13 @@ or
               });
             }
 
+            // Notify the parent that the agent is winding down — no more extensions (#522)
+            this.events.emit('timeout.windingDown', {
+              reason: decision.reason || 'observer declined',
+              extensionsUsed: negotiatedTimeoutState.extensionsUsed,
+              totalExtraTimeMs: negotiatedTimeoutState.totalExtraTimeMs,
+            });
+
             await this._initiateGracefulStop(gracefulTimeoutState, `observer declined: ${decision.reason}`);
           }
         };