@wrongstack/core 0.308.6 → 0.309.0

package/dist/execution/compaction-core.d.ts

@@ -1,6 +1,6 @@
 import { estimateMessageTokens } from '../utils/token-estimate.js';
 export { buildSmartDigest, type ContentScore, extractText, hasLargeToolResult, hasToolUse, scoreMessage, } from './compaction-scoring.js';
-export { type AcknowledgedToolReceiptCollapse, type AcknowledgedToolResultElision, analyzeFileToolLifecycle, collapseAcknowledgedToolReceipts, compactionDebugEnabled, type CompactionMetrics, didFileMutationRun, eliseAcknowledgedToolResults, eliseOldToolResults, type EliseResult, emitCompactionMetrics, extractPathHints, type FileToolLifecycle, findPreserveStart, firstErrorLine, isElidedResultContent, isElidedToolInput, isFileMutationToolName, isReadToolName, normalizePathKey, readPathOf, safeToolResultString, sameFilePath, setCompactionDebugLogger, summarizeToolResultElision, summarizeToolUseInputElision, } from './compaction-elision.js';
+export { collapseAcknowledgedToolReceipts, eliseAcknowledgedToolResults, eliseOldToolResults, type EliseResult, findPreserveStart, isElidedResultContent, isElidedToolInput, normalizePathKey, readPathOf, setCompactionDebugLogger, summarizeToolResultElision, summarizeToolUseInputElision, } from './compaction-elision.js';
 export { buildLosslessDigest, type DedupResult, dedupStaleReads, elideMessageToolIo, enforceHardBudget, findExchangeStart, findSafeBoundary, type HardBudgetResult, hasTextContent, headTailTruncate, truncateMessageText, } from './compaction-budget.js';
 export { CompactionSummaryCache, type CompactionSummaryCacheOptions, compactionSummaryKey, isPlaceholderSummary, PLACEHOLDER_SUMMARIES, } from './compaction-summary-cache.js';
 export declare const estimateMessages: typeof estimateMessageTokens;

package/dist/execution/compaction-elision.d.ts

@@ -11,9 +11,7 @@ export interface CompactionMetrics {
     tokensSaved: number;
     changed: boolean;
 }
-export declare function compactionDebugEnabled(): boolean;
 export declare function setCompactionDebugLogger(logger: Logger | undefined): void;
-export declare function emitCompactionMetrics(event: string, metrics: CompactionMetrics): void;
 export interface EliseResult {
     messages: Message[];
     saved: number;
@@ -30,13 +28,8 @@ export interface FileToolLifecycle {
     activeReadIds: Set<string>;
     staleReadPaths: Map<string, string>;
 }
-export declare function isReadToolName(name: string): boolean;
-export declare function isFileMutationToolName(name: string): boolean;
-export declare function didFileMutationRun(use: ToolUseBlock): boolean;
-export declare function sameFilePath(a: string, b: string): boolean;
 export declare function readPathOf(input: Record<string, unknown> | undefined): string | undefined;
 export declare function normalizePathKey(p: string): string;
-export declare function analyzeFileToolLifecycle(messages: readonly Message[], acknowledgedBefore: number): FileToolLifecycle;
 export declare function isElidedResultContent(content: string): boolean;
 export declare function isElidedToolInput(input: Record<string, unknown> | undefined): boolean;
 export declare function eliseAcknowledgedToolResults(messages: readonly Message[], opts: {
@@ -52,7 +45,4 @@ export declare function eliseOldToolResults(messages: readonly Message[], opts:
 }, findPreserveStartFn?: (messages: readonly Message[], preserveK: number) => number): EliseResult;
 export declare function summarizeToolUseInputElision(block: ToolUseBlock, tokens: number): Record<string, unknown>;
 export declare function summarizeToolResultElision(block: ToolResultBlock, tokens: number): string;
-export declare function safeToolResultString(content: unknown): string;
-export declare function extractPathHints(content: unknown): string[];
-export declare function firstErrorLine(content: unknown): string | undefined;
 //# sourceMappingURL=compaction-elision.d.ts.map

package/dist/execution/index.js

@@ -11592,7 +11592,7 @@ function resolveReasoningForRequest(settings, rc, warnings) {
   const cfg = settings.reasoning;
   if (!cfg) return void 0;
   const capKnown = rc !== void 0;
-  const supportsReasoning = rc ? rc.default !== "disabled" || rc.disableSupported || rc.effortSupported : false;
+  const supportsReasoning = rc ? rc.default !== "disabled" || rc.disableSupported || rc.effortSupported !== false : false;
   const out = {};
   if (cfg.mode === "off") {
     if (capKnown && rc?.disableSupported) {
@@ -11614,14 +11614,17 @@ function resolveReasoningForRequest(settings, rc, warnings) {
   }
   const effort = cfg.effort;
   if (effort !== void 0) {
-    if (capKnown && rc?.effortSupported && rc.effortLevels.includes(effort)) {
-      out.effort = effort;
-    } else if (capKnown && rc?.effortSupported) {
+    if (!capKnown) {
+    } else if (rc?.effortSupported === false) {
+      warnings.push(
+        `reasoning effort "${effort}" requested, but this model does not support effort control; the setting was omitted.`
+      );
+    } else if (rc?.effortSupported === true && rc.effortLevels.length > 0 && !rc.effortLevels.includes(effort)) {
       warnings.push(
         `reasoning effort "${effort}" not supported by this model (supported: ${rc.effortLevels.join(", ")}); the setting was omitted.`
       );
-    } else if (capKnown) {
-      warnings.push(`reasoning effort "${effort}" requested, but this model does not support effort; the setting was omitted.`);
+    } else {
+      out.effort = effort;
     }
   }
   if (cfg.preserve !== void 0) {
@@ -11973,6 +11976,46 @@ function asTextBlocks(system) {
 // src/execution/parallel-eternal-engine.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 
+// src/core/btw.ts
+var META_KEY2 = "_btwNotes";
+var MAX_PENDING = 20;
+function readQueue(ctx) {
+  const raw = ctx.meta[META_KEY2];
+  return Array.isArray(raw) ? raw : [];
+}
+function setBtwNote(ctx, text) {
+  const trimmed = text.trim();
+  if (!trimmed) return readQueue(ctx).length;
+  const next = [...readQueue(ctx), trimmed].slice(-MAX_PENDING);
+  ctx.meta[META_KEY2] = next;
+  return next.length;
+}
+
+// src/coordination/subagent-finish.ts
+var SUBAGENT_FINISH_REQUESTED_EVENT = "subagent.finish_requested";
+var DEFAULT_SUBAGENT_FINISH_GRACE_MS = 12e4;
+function resolveGracefulFinish(config) {
+  const raw = config.gracefulFinish;
+  if (raw === void 0 || raw === false) return void 0;
+  if (raw === true) return { graceMs: DEFAULT_SUBAGENT_FINISH_GRACE_MS };
+  const graceMs = typeof raw.graceMs === "number" && Number.isFinite(raw.graceMs) && raw.graceMs > 0 ? Math.floor(raw.graceMs) : DEFAULT_SUBAGENT_FINISH_GRACE_MS;
+  return { graceMs };
+}
+function buildSubagentFinishNotice(input) {
+  const localTime = new Date(input.deadlineMs).toISOString();
+  const seconds = Math.max(1, Math.round(input.graceMs / 1e3));
+  const timeLeft = input.graceMs > 0 ? `You have roughly ${seconds} seconds (until ${localTime}) of legitimate working time left.` : `Your working-time window is already spent (deadline was ${localTime}) \u2014 finish now.`;
+  return [
+    "[SUBAGENT FINISH] The leader agent has finished its work.",
+    `Reason: ${input.reason}`,
+    timeLeft,
+    "Finish your task now, in this turn: complete the thought you are working on, stop",
+    "starting new tool calls unless one is strictly required to finish, and write your",
+    "final answer or report as your final output, then end your turn.",
+    "Do not restart the task and do not begin new work."
+  ].join("\n");
+}
+
 // src/coordination/subagent-budget.ts
 var TIMEOUT_PREEMPT_FRACTION = 0.85;
 var DECISION_TIMEOUT_MS = 6e4;
@@ -12030,6 +12073,82 @@ var SubagentBudget = class _SubagentBudget {
       this.limits.idleTimeoutMs = ext.idleTimeoutMs;
     }
   }
+  /**
+   * Graceful-finish state (see coordination/subagent-finish.ts).
+   * `_finishNotified` guards the single in-band emission; `_grace` records a
+   * granted working-time extension past the original wall-clock deadline.
+   * They are separate because the two callers want different semantics:
+   * the watchdog grants grace at the deadline crossing (notify + extend),
+   * while an explicit leader-finished request only notifies — a subagent
+   * well inside its budget keeps its full legitimate working time and simply
+   * accelerates.
+   */
+  _finishNotified = false;
+  _grace = null;
+  /** True once the in-band finish notification has been emitted. */
+  get finishNotified() {
+    return this._finishNotified;
+  }
+  /** True once a grace window has been granted past the original deadline. */
+  get graceGranted() {
+    return this._grace !== null;
+  }
+  /**
+   * Notify the subagent in-band to finish its task in its own turn:
+   * `subagent.finish_requested` is emitted on the wired EventBus and the
+   * agent loop folds the notice into the conversation between tool batches.
+   * Nothing aborts — this is a notification, never an interrupt.
+   *
+   * `opts.graceMs` additionally extends the wall-clock ceiling by that window
+   * (used by the watchdog at a deadline crossing, so the model gets working
+   * time instead of a kill). Omit it to notify without touching the budget —
+   * the subagent keeps its existing time budget and just accelerates.
+   *
+   * Returns `true` when this call did something (emitted the notification
+   * and/or granted grace); `false` when there was nothing to do (already
+   * notified, grace already granted, no EventBus wired, budget not started).
+   */
+  notifyFinish(reason, opts, now = Date.now) {
+    if (!this._events) return false;
+    if (this.startTime === null) return false;
+    const shouldEmit = !this._finishNotified;
+    const rawGrace = opts?.graceMs;
+    const shouldGrant = rawGrace !== void 0 && this._grace === null;
+    if (!shouldEmit && !shouldGrant) return false;
+    let grantedGraceMs = 0;
+    let graceDeadlineMs;
+    if (shouldGrant && rawGrace !== void 0) {
+      grantedGraceMs = Number.isFinite(rawGrace) && rawGrace > 0 ? Math.floor(rawGrace) : DEFAULT_SUBAGENT_FINISH_GRACE_MS;
+      graceDeadlineMs = now() + grantedGraceMs;
+      this._grace = { deadlineMs: graceDeadlineMs, graceMs: grantedGraceMs };
+      this.patchLimits({ timeoutMs: graceDeadlineMs - this.startTime });
+    }
+    if (shouldEmit) {
+      this._finishNotified = true;
+      const effectiveDeadlineMs = graceDeadlineMs ?? (this.limits.timeoutMs !== void 0 ? this.startTime + this.limits.timeoutMs : now() + DEFAULT_SUBAGENT_FINISH_GRACE_MS);
+      const effectiveGraceMs = Math.max(0, effectiveDeadlineMs - now());
+      const subagentId = this._subagentId;
+      this._events.emit(SUBAGENT_FINISH_REQUESTED_EVENT, {
+        // Omitted entirely when the budget was built without an id — an
+        // empty string is an address that matches nothing.
+        ...subagentId !== void 0 ? { subagentId } : {},
+        reason,
+        deadlineMs: effectiveDeadlineMs,
+        graceMs: effectiveGraceMs,
+        notice: buildSubagentFinishNotice({
+          reason,
+          deadlineMs: effectiveDeadlineMs,
+          graceMs: effectiveGraceMs
+        })
+      });
+    }
+    return true;
+  }
+  /** Epoch ms by which the subagent should have produced its final output,
+   *  once a grace window was granted. Undefined before that. */
+  get finishDeadlineMs() {
+    return this._grace?.deadlineMs;
+  }
   iterations = 0;
   toolCalls = 0;
   tokenInput = 0;
@@ -12045,6 +12164,10 @@ var SubagentBudget = class _SubagentBudget {
   lastActivityTime = null;
   _onThreshold;
   _sessionId;
+  /** Owning subagent id — used to address the graceful-finish event. */
+  _subagentId;
+  /** True when only the coordinator watchdog may enforce wall-clock limits. */
+  _wallClockWatchdogOwned;
   /**
    * Hard cap on how long `_negotiateExtension` waits for the coordinator to
    * respond before defaulting to 'stop'. Without this fallback an absent
@@ -12116,6 +12239,8 @@ var SubagentBudget = class _SubagentBudget {
   constructor(limits = {}, mode = "auto", options = {}) {
     this._mode = mode;
     this._sessionId = options.sessionId;
+    this._subagentId = options.subagentId;
+    this._wallClockWatchdogOwned = options.wallClockWatchdogOwned === true;
     this.limits = { ...limits };
   }
   currentSessionId() {
@@ -12194,7 +12319,7 @@ var SubagentBudget = class _SubagentBudget {
       if (this.limits.idleTimeoutMs !== void 0 && idle > this.limits.idleTimeoutMs) {
         exceeded.push({ kind: "idle_timeout", used: idle, limit: this.limits.idleTimeoutMs });
       }
-      const wallOwnedByWatchdog = this._onThreshold !== void 0 && this._watchdogActive === this.limits.timeoutMs;
+      const wallOwnedByWatchdog = this._wallClockWatchdogOwned || this._onThreshold !== void 0 && this._watchdogActive === this.limits.timeoutMs;
       if (this.limits.timeoutMs !== void 0 && elapsedMs > this.limits.timeoutMs && !wallOwnedByWatchdog) {
         exceeded.push({ kind: "timeout", used: elapsedMs, limit: this.limits.timeoutMs });
       }
@@ -12393,7 +12518,7 @@ var SubagentBudget = class _SubagentBudget {
     if (timeoutMs === void 0 && idleTimeoutMs === void 0) return;
     const elapsed = Date.now() - this.startTime;
     const wallSkipped = this._onThreshold !== void 0 && this._watchdogActive !== void 0 && timeoutMs !== void 0 && this._watchdogActive === timeoutMs;
-    const wallTripped = wallSkipped ? false : timeoutMs !== void 0 && elapsed > timeoutMs;
+    const wallTripped = this._wallClockWatchdogOwned || wallSkipped ? false : timeoutMs !== void 0 && elapsed > timeoutMs;
     const idleTripped = idleTimeoutMs !== void 0 && this.idleMs() > idleTimeoutMs;
     if (!wallTripped && !idleTripped) return;
     void this.checkLimits(elapsed);
@@ -12769,6 +12894,14 @@ function makeAgentSubagentRunner(opts) {
     );
     const onParentAbort = () => aborter.abort();
     ctx.signal.addEventListener("abort", onParentAbort);
+    if (resolveGracefulFinish(ctx.config)) {
+      unsub.push(
+        events.on("subagent.finish_requested", (e) => {
+          if (e.subagentId && e.subagentId !== ctx.subagentId) return;
+          setBtwNote(agent.ctx, e.notice);
+        })
+      );
+    }
     let result;
     try {
       result = await agent.run(format(task, ctx.config), { signal: aborter.signal });
@@ -13481,6 +13614,7 @@ function inferRuntimeCapabilities(toolNames) {
 var skillSet = (...names) => names;
 var ROLE_SKILL_SETS = {
   explore: skillSet("research-web", "node-modern", "typescript-strict"),
+  "explore-companion": skillSet("node-modern", "typescript-strict"),
   search: skillSet("bug-hunter", "typescript-strict", "research-web"),
   research: skillSet("research-web", "tech-stack", "security-scanner", "api-design"),
   analyst: skillSet("sdd", "api-design", "testing", "security-scanner"),
@@ -16937,6 +17071,42 @@ var SHADOW_AGENT = {
   ...defineAgent("shadow-agent", "Shadow"),
   skillNames: [...SHADOW_AGENT_SKILLS]
 };
+var EXPLORE_COMPANION_AGENT = {
+  ...defineAgent("explore-companion", "Explore Companion"),
+  tools: [...TOOLS.read, ...TOOLS.index],
+  // Read-only, triple-enforced: allowlist has no write/bash, and the
+  // disabled list blocks the escape hatches explicitly.
+  disabledTools: [
+    "write",
+    "edit",
+    "replace",
+    "patch",
+    "bash",
+    "exec",
+    "delegate",
+    "spawn_subagent",
+    "assign_task"
+  ],
+  skillNames: [...ROLE_SKILL_SETS["explore-companion"]],
+  spawnBudgetExempt: true,
+  // Findings travel via mailbox + submit_result, not the leader's stream.
+  textStream: "silent",
+  toolStream: "silent"
+};
+var CHAOS_MONKEY_AGENT = {
+  ...defineAgent("chaos-monkey", "Chaos Monkey"),
+  tools: [...TOOLS.build],
+  skillNames: ["testing", "typescript-strict"],
+  spawnBudgetExempt: true,
+  // Follow fleet worktree policy (NOT 'required'): mutation targets are
+  // often freshly written and uncommitted — a worktree spawned from HEAD
+  // would not contain them and every mutant would drift. Callers pass
+  // `worktree: 'off'` in the mutation_test input for uncommitted targets.
+  worktree: "auto",
+  // Report travels via submit_result + final text, not the leader's stream.
+  textStream: "silent",
+  toolStream: "silent"
+};
 var CRITIC_AGENT = defineAgent("critic", "Critic");
 var GENERIC_AGENT = defineAgent("generic", "Generic Project Agent");
 function withDispatchMetadata(definition) {
@@ -16955,6 +17125,8 @@ var FLEET_ROSTER = {
   critic: CRITIC_AGENT,
   generic: GENERIC_AGENT,
   "shadow-agent": SHADOW_AGENT,
+  "explore-companion": EXPLORE_COMPANION_AGENT,
+  "chaos-monkey": CHAOS_MONKEY_AGENT,
   ...Object.fromEntries(
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, withDispatchMetadata(d)])
   )
@@ -16978,6 +17150,23 @@ var FLEET_ROSTER_BUDGETS = {
     maxTokens: 96e3,
     maxCostUsd: 0.5
   },
+  "explore-companion": {
+    idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
+    maxIterations: 3e3,
+    maxToolCalls: 8e3,
+    maxTokens: 96e3,
+    maxCostUsd: 0.5
+  },
+  "chaos-monkey": {
+    // A mutation pass is many short apply/run/restore cycles — per-mutant
+    // work is tiny, but a large plan (25 mutants/file × N files) needs
+    // headroom. Idle-based reaping covers a stalled pass.
+    idleTimeoutMs: DEFAULT_IDLE_TIMEOUT_MS,
+    maxIterations: 2e3,
+    maxToolCalls: 6e3,
+    maxTokens: 96e3,
+    maxCostUsd: 0.5
+  },
   ...Object.fromEntries(
     ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.budget])
   )
@@ -17147,7 +17336,8 @@ async function executeSubagentWithTimeout({
   budget,
   preemptFraction = TIMEOUT_PREEMPT_FRACTION,
   abortSubagent,
-  currentSessionId
+  currentSessionId,
+  gracefulFinish
 }) {
   const initialTimeoutMs = budget.limits.timeoutMs;
   const idleLimitMs = budget.limits.idleTimeoutMs;
@@ -17178,9 +17368,17 @@ async function executeSubagentWithTimeout({
     const scheduleNext = () => {
       const wallLimit = budget.limits.timeoutMs ?? initialTimeoutMs;
       const wallRemaining = initialTimeoutMs === void 0 ? Number.POSITIVE_INFINITY : wallLimit - (Date.now() - start);
-      const idleRemaining = idleLimitMs === void 0 ? Number.POSITIVE_INFINITY : (budget.limits.idleTimeoutMs ?? idleLimitMs) - budget.idleMs();
-      const preemptRemaining = initialTimeoutMs === void 0 || preemptedCeiling === wallLimit ? Number.POSITIVE_INFINITY : wallLimit * preemptFraction - (Date.now() - start);
-      armFor(Math.max(25, Math.min(wallRemaining, idleRemaining, preemptRemaining)));
+      const idleRemaining = idleLimitMs === void 0 || gracefulFinish !== void 0 && initialTimeoutMs !== void 0 ? Number.POSITIVE_INFINITY : (budget.limits.idleTimeoutMs ?? idleLimitMs) - budget.idleMs();
+      const preemptRemaining = initialTimeoutMs === void 0 || preemptedCeiling === wallLimit || gracefulFinish !== void 0 ? Number.POSITIVE_INFINITY : wallLimit * preemptFraction - (Date.now() - start);
+      const next = Math.min(wallRemaining, idleRemaining, preemptRemaining);
+      if (!Number.isFinite(next)) {
+        if (timer) {
+          clearTimeout(timer);
+          timer = null;
+        }
+        return;
+      }
+      armFor(Math.max(25, next));
     };
     const negotiateTimeout = async (used, limit) => {
       const handler = budget.onThreshold;
@@ -17229,6 +17427,10 @@ async function executeSubagentWithTimeout({
       const wallExceeded = wallLimit !== void 0 && elapsed >= wallLimit;
       const idleExceeded = idleLimit !== void 0 && budget.idleMs() >= idleLimit;
       if (idleExceeded && !wallExceeded) {
+        if (gracefulFinish !== void 0 && initialTimeoutMs !== void 0) {
+          scheduleNext();
+          return;
+        }
         const sessionId = currentSessionId();
         budget._events?.emit("budget.threshold_reached", {
           ...sessionId ? { sessionId } : {},
@@ -17245,7 +17447,7 @@ async function executeSubagentWithTimeout({
         reject(new BudgetExceededError("idle_timeout", idleLimit ?? 0, budget.idleMs()));
         return;
       }
-      if (wallLimit !== void 0 && !wallExceeded && budget.onThreshold && preemptState === "active" /* ACTIVE */ && elapsed >= wallLimit * preemptFraction) {
+      if (wallLimit !== void 0 && !wallExceeded && gracefulFinish === void 0 && budget.onThreshold && preemptState === "active" /* ACTIVE */ && elapsed >= wallLimit * preemptFraction) {
         const activityTs = Date.now() - budget.idleMs();
         if (activityTs <= lastGrantActivityTs) {
           preemptState = "locked" /* LOCKED */;
@@ -17279,6 +17481,22 @@ async function executeSubagentWithTimeout({
         return;
       }
       const limit = wallLimit ?? 0;
+      if (gracefulFinish !== void 0) {
+        if (!budget.graceGranted) {
+          const reason = `wall-clock budget of ${Math.round(limit / 1e3)}s reached`;
+          if (budget.notifyFinish(reason, { graceMs: gracefulFinish.graceMs })) {
+            scheduleNext();
+            return;
+          }
+          abortSubagent(ctx.subagentId);
+          reject(new BudgetExceededError("timeout", limit, elapsed));
+          return;
+        } else {
+          abortSubagent(ctx.subagentId);
+          reject(new BudgetExceededError("timeout", limit, elapsed));
+          return;
+        }
+      }
       if (!budget.onThreshold) {
         abortSubagent(ctx.subagentId);
         reject(new BudgetExceededError("timeout", limit, elapsed));
@@ -17663,6 +17881,32 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
   completeTask(result) {
     this.recordCompletion(result);
   }
+  /**
+   * Ask every RUNNING subagent that opted into `gracefulFinish` to finish its
+   * task in its own turn (see coordination/subagent-finish.ts). This is the
+   * leader-side entry point for "the leader agent has finished": it delivers
+   * an in-band notification between tool batches — never an interrupt, never
+   * an abort. Each notified subagent keeps its existing time budget and
+   * accelerates; the watchdog still bounds the maximum lifetime.
+   *
+   * Subagents without the policy opted in are deliberately untouched — their
+   * lifecycle remains the legacy watchdog contract.
+   *
+   * Returns the number of subagents actually notified.
+   */
+  requestFinish(reason) {
+    let notified = 0;
+    for (const subagent of this.subagents.values()) {
+      if (subagent.status !== "running") continue;
+      if (!resolveGracefulFinish(subagent.config)) continue;
+      const budget = subagent.activeBudget;
+      if (!budget) continue;
+      const usage = budget.usage();
+      if (usage.iterations === 0 && usage.toolCalls === 0) continue;
+      if (budget.notifyFinish(reason)) notified++;
+    }
+    return notified;
+  }
   // --- internal dispatching ---------------------------------------------
   tryDispatchNext() {
     while (this.canDispatch()) {
@@ -17836,7 +18080,14 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
         idleTimeoutMs: rawIdleTimeoutMs ?? this.config.defaultBudget?.idleTimeoutMs ?? configWithRosterDefaults.idleTimeoutMs
       },
       "auto",
-      { sessionId: () => this.currentSessionId() }
+      {
+        sessionId: () => this.currentSessionId(),
+        subagentId,
+        // Graceful-finish runs own wall-clock enforcement to the watchdog so
+        // the notify-then-bound lifecycle cannot be raced by tool.progress
+        // heartbeats calling checkTimeout() (see subagent-budget.ts).
+        ...resolveGracefulFinish(subagent.config) ? { wallClockWatchdogOwned: true } : {}
+      }
     );
     subagent.activeBudget = budget;
     if (!this.runner) {
@@ -17869,7 +18120,8 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
         task,
         runCtx,
         budget,
-        subagent.config.preemptFraction
+        subagent.config.preemptFraction,
+        resolveGracefulFinish(subagent.config)
       );
       result = {
         subagentId,
@@ -17899,13 +18151,14 @@ var DefaultMultiAgentCoordinator = class _DefaultMultiAgentCoordinator extends E
     }
     this.recordCompletion(result);
   }
-  async executeWithTimeout(runner, task, ctx, budget, preemptFraction) {
+  async executeWithTimeout(runner, task, ctx, budget, preemptFraction, gracefulFinish) {
     return executeSubagentWithTimeout({
       runner,
       task,
       ctx,
       budget,
       preemptFraction,
+      gracefulFinish,
       abortSubagent: (subagentId) => this.subagents.get(subagentId)?.abortController.abort(),
       currentSessionId: () => this.currentSessionId()
     });

package/dist/goal/index.js

@@ -1427,6 +1427,13 @@ var PhaseOrchestrator = class {
   events;
   stopped = false;
   paused = false;
+  /**
+   * Run-wide abort source. stop() aborts it; every in-flight
+   * ctx.executeTask call observes the abort through its per-task signal
+   * (composed from this controller and the task's own timeout controller).
+   * Recreated by start() so a stopped orchestrator can be reused.
+   */
+  stopController = new AbortController();
   runningPhases = /* @__PURE__ */ new Set();
   tickInterval = null;
   trackerCache = /* @__PURE__ */ new Map();
@@ -1469,6 +1476,7 @@ var PhaseOrchestrator = class {
   async start() {
     this.stopped = false;
     this.paused = false;
+    this.stopController = new AbortController();
     this.normalizeForResume();
     this.graph.startedAt = Date.now();
     this.graph.updatedAt = Date.now();
@@ -1528,6 +1536,7 @@ var PhaseOrchestrator = class {
   /** Stop completely, including active phases. */
   stop() {
     this.stopped = true;
+    this.stopController.abort();
     if (this.tickInterval) {
       clearInterval(this.tickInterval);
       this.tickInterval = null;
@@ -1604,6 +1613,7 @@ var PhaseOrchestrator = class {
         return;
       }
       await this.executePhaseTasks(phase);
+      if (this.stopped) return;
       const failedTasks = this.getFailedTaskCount(phase);
       const completedTasks = this.getCompletedTaskCount(phase);
       this.emit("phase.allTasksDone", {
@@ -1763,34 +1773,47 @@ var PhaseOrchestrator = class {
       agentName: task.assignee
     });
     const handle = this.phaseWorktrees.get(phase.id);
-    const taskPromise = this.ctx.executeTask(task, phase.id, {
-      cwd: handle?.dir,
-      branch: handle?.branch
+    const timeoutController = this.opts.taskTimeoutMs > 0 ? new AbortController() : void 0;
+    const signal = timeoutController ? AbortSignal.any([this.stopController.signal, timeoutController.signal]) : this.stopController.signal;
+    const taskPromise = this.ctx.executeTask(
+      task,
+      phase.id,
+      { cwd: handle?.dir, branch: handle?.branch },
+      signal
+    );
+    if (!timeoutController) return taskPromise;
+    const timeoutMs = this.opts.taskTimeoutMs;
+    const timedOut = /* @__PURE__ */ Symbol("timed_out");
+    const result = await Promise.race([
+      taskPromise,
+      new Promise((resolve4) => {
+        const timer = setTimeout(() => {
+          timeoutController.abort();
+          resolve4(timedOut);
+        }, timeoutMs);
+        taskPromise.then(() => clearTimeout(timer)).catch(() => clearTimeout(timer));
+      })
+    ]);
+    if (result !== timedOut) return result;
+    this.emit("phase.taskTimedOut", {
+      phaseId: phase.id,
+      taskId: task.id,
+      taskTitle: task.title,
+      timeoutMs
     });
-    if (this.opts.taskTimeoutMs > 0) {
-      const timeoutMs = this.opts.taskTimeoutMs;
-      const timedOut = /* @__PURE__ */ Symbol("timed_out");
-      const result = await Promise.race([
-        taskPromise,
-        new Promise((resolve4) => {
-          const timer = setTimeout(() => resolve4(timedOut), timeoutMs);
-          taskPromise.then(() => clearTimeout(timer)).catch(() => clearTimeout(timer));
-        })
-      ]);
-      if (result === timedOut) {
-        this.emit("phase.taskTimedOut", {
-          phaseId: phase.id,
-          taskId: task.id,
-          taskTitle: task.title,
-          timeoutMs
-        });
-        throw new Error(
-          `Task "${task.title}" (${task.id}) exceeded timeout of ${timeoutMs} ms`
-        );
-      }
-      return result;
-    }
-    return taskPromise;
+    const settled = taskPromise.then(
+      () => void 0,
+      () => void 0
+    );
+    const grace = new Promise((resolve4) => {
+      const timer = setTimeout(resolve4, 5e3);
+      timer.unref?.();
+      void settled.then(() => clearTimeout(timer));
+    });
+    await Promise.race([settled, grace]);
+    throw new Error(
+      `Task "${task.title}" (${task.id}) exceeded timeout of ${timeoutMs} ms`
+    );
   }
   markTaskCompleted(phase, task) {
     const tracker = this.getTrackerForPhase(phase);
@@ -1805,6 +1828,10 @@ var PhaseOrchestrator = class {
     const tracker = this.getTrackerForPhase(phase);
     const taskKey = `${phase.id}:${task.id}`;
     const currentRetries = this.taskRetryCounts.get(taskKey) ?? 0;
+    if (this.stopped) {
+      tracker.updateNodeStatus(task.id, "pending", "Stopped before completion");
+      return;
+    }
     if (currentRetries < this.opts.maxRetries) {
       this.taskRetryCounts.set(taskKey, currentRetries + 1);
       tracker.updateNodeStatus(

package/dist/goal/phase-orchestrator.d.ts

@@ -19,6 +19,13 @@ export declare class PhaseOrchestrator {
     private events;
     private stopped;
     private paused;
+    /**
+     * Run-wide abort source. stop() aborts it; every in-flight
+     * ctx.executeTask call observes the abort through its per-task signal
+     * (composed from this controller and the task's own timeout controller).
+     * Recreated by start() so a stopped orchestrator can be reused.
+     */
+    private stopController;
     private runningPhases;
     private tickInterval;
     private trackerCache;

package/dist/goal/types.d.ts

@@ -223,7 +223,7 @@ export interface PhaseExecutionContext {
     executeTask: (task: TaskNode, phaseId: string, env?: {
         cwd?: string | undefined;
         branch?: string | undefined;
-    }) => Promise<unknown>;
+    }, signal?: AbortSignal | undefined) => Promise<unknown>;
     /**
      * Optional verification gate. Called after all tasks in a phase finish,
      * but before the phase is marked "completed" and its worktree is merged

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { DEPENDENCY_FILE_PATTERNS, type DependencyWatcherConfig, type DepWatchEn
 export { attachDepWatcherBridge, type DepWatcherBridgeOptions, } from './coordination/dep-watcher-bridge.js';
 export { Director, FleetCostCapError, FleetSpawnBudgetError, FleetTokenCapError, type TaskResultNotification, } from './coordination/director.js';
 export { type DirectorSessionFactory, type DirectorSessionFactoryOptions, makeDirectorSessionFactory, } from './coordination/director-session.js';
-export { makeAskTool, makeAssignTool, makeAwaitTasksTool, makeCollabDebugTool, makeFleetEmitTool, makeFleetTool, makeKanbanQueueTool, makeQualityGateTool, makeRollUpTool, makeSpawnTool, makeTerminateTool, } from './coordination/director-tools.js';
+export { makeAskTool, makeAssignTool, makeAwaitTasksTool, makeCollabDebugTool, makeFleetEmitTool, makeFleetTool, makeKanbanQueueTool, makeMutationTestTool, makeQualityGateTool, makeRollUpTool, makeSpawnTool, makeTerminateTool, } from './coordination/director-tools.js';
 export { DEFAULT_DISPATCH_ROLE, type DispatchCandidate, type DispatchClassifier, type DispatchMethod, type DispatchOptions, type DispatchResult, dispatchAgent, makeLLMClassifier, scoreAgents, } from './coordination/dispatcher.js';
 export { compactLog, type FileAuthorEntry, type FileAuthorLog, type FileAuthorTrackerOptions, getFileHistory, getFilesByAgent, getFullLog, getLastAuthor, recordFileAction, } from './coordination/file-author-tracker.js';
 export { ACP_AGENTS, ALL_FLEET_AGENTS, applyRosterBudget, FLEET_ROSTER, FLEET_ROSTER_BUDGETS, FLEET_ROSTER_WITHACP, type FleetRosterBudget, } from './coordination/fleet.js';