@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/runs/background/async-resume.js

@@ -1,39 +1,18 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { ASYNC_DIR, RESULTS_DIR } from "../../shared/types.js";
-import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.js";
-import { deliverInterruptRequest } from "./control-channel.js";
+import { DIRS } from "../../shared/types.js";
+import { normalizeExtensionBindings } from "../shared/extension-bindings.js";
+import { normalizeWorkflowLaneMetadata } from "../shared/lane-metadata.js";
+import { validateAcceptanceInput } from "../shared/acceptance.js";
+import { validateToolBudgetConfig } from "../shared/tool-budget.js";
+import { intersectSubagentCapabilityCeilings, parseSubagentCapabilityCeiling } from "../shared/capability-ceiling.js";
+import { validateRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.js";
 import { reconcileAsyncRun } from "./stale-run-reconciler.js";
-export const ASYNC_RESUME_INTERRUPT_SIGNAL = process.platform === "win32" ? "SIGBREAK" : "SIGUSR2";
-export function interruptLiveAsyncResumeTarget(input) {
-  const asyncId = input.target.runId;
-  if (!input.target.asyncDir) {
-    return { ok: false, message: `Async run ${asyncId} is live but does not have an async directory to interrupt.` };
-  }
-  const status = reconcileAsyncRun(input.target.asyncDir, { resultsDir: input.resultsDir, kill: input.kill, now: input.now }).status;
-  if (!status || status.state !== "running" || typeof status.pid !== "number") {
-    return { ok: false, message: `Async run ${asyncId} is live but no interrupt-capable runner pid was found.` };
-  }
-  try {
-    deliverInterruptRequest({
-      asyncDir: input.target.asyncDir,
-      pid: status.pid,
-      kill: input.kill,
-      signal: ASYNC_RESUME_INTERRUPT_SIGNAL,
-      now: input.now,
-      source: "async-resume"
-    });
-    const tracked = input.state?.asyncJobs.get(asyncId);
-    if (tracked) {
-      tracked.activityState = undefined;
-      tracked.updatedAt = input.now?.() ?? Date.now();
-    }
-    return { ok: true, asyncId };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return { ok: false, message: `Failed to interrupt async run ${asyncId}: ${message}` };
-  }
-}
+import { resultFilePath, resultPayloadPathForIndexedRun } from "./result-files.js";
+import { canScanAsyncRunPrefix, MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH } from "./run-id-query.js";
+import { parallelHandoffPath, resolveRetainedWorktreeCwd } from "../shared/parallel-handoff.js";
+import { intersectThinkingCeilings, parseThinkingLevel } from "../../shared/thinking-ceiling.js";
+import { assertWorkflowGraphHostSteps } from "../shared/host-step-status.js";
 function getErrorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -62,11 +41,16 @@ function validateResultFile(value, resultPath) {
       const child = ensureObject(entry, `${resultPath} results[${index}]`);
       const agent = validateOptionalString(child, "agent", resultPath, `results[${index}].agent`);
       const sessionFile = validateOptionalString(child, "sessionFile", resultPath, `results[${index}].sessionFile`);
+      const sessionName = validateOptionalString(child, "sessionName", resultPath, `results[${index}].sessionName`);
       const intercomTarget = validateOptionalString(child, "intercomTarget", resultPath, `results[${index}].intercomTarget`);
+      const model = validateOptionalString(child, "model", resultPath, `results[${index}].model`);
+      const thinking = validateOptionalString(child, "thinking", resultPath, `results[${index}].thinking`);
+      const launchContractDigest = validateOptionalString(child, "launchContractDigest", resultPath, `results[${index}].launchContractDigest`);
+      const capabilityCeiling = child.capabilityCeiling === undefined ? undefined : parseSubagentCapabilityCeiling(child.capabilityCeiling, `async result file '${resultPath}' results[${index}].capabilityCeiling`);
       const success = child.success;
       if (success !== undefined && typeof success !== "boolean")
         throw new Error(`Invalid async result file '${resultPath}': results[${index}].success must be a boolean.`);
-      return { agent, sessionFile, intercomTarget, ...typeof success === "boolean" ? { success } : {} };
+      return { agent, sessionName, sessionFile, intercomTarget, model, thinking, launchContractDigest, ...capabilityCeiling ? { capabilityCeiling } : {}, ...typeof success === "boolean" ? { success } : {} };
     });
   }
   const success = data.success;
@@ -79,7 +63,12 @@ function validateResultFile(value, resultPath) {
     mode: validateOptionalString(data, "mode", resultPath),
     state: validateOptionalString(data, "state", resultPath),
     cwd: validateOptionalString(data, "cwd", resultPath),
+    sessionId: validateOptionalString(data, "sessionId", resultPath),
     sessionFile: validateOptionalString(data, "sessionFile", resultPath),
+    model: validateOptionalString(data, "model", resultPath),
+    thinking: validateOptionalString(data, "thinking", resultPath),
+    launchContractDigest: validateOptionalString(data, "launchContractDigest", resultPath),
+    ...data.capabilityCeiling === undefined ? {} : { capabilityCeiling: parseSubagentCapabilityCeiling(data.capabilityCeiling, `async result file '${resultPath}' capabilityCeiling`) },
     ...typeof success === "boolean" ? { success } : {},
     ...results ? { results } : {}
   };
@@ -128,7 +117,10 @@ function prefixedRunIds(dir, prefix, suffix = "") {
   return fs.readdirSync(dir).filter((entry) => entry.startsWith(prefix) && (!suffix || entry.endsWith(suffix))).map((entry) => suffix ? entry.slice(0, -suffix.length) : entry).sort();
 }
 function exactResultPath(resultsDir, runId) {
-  const resultPath = path.join(resultsDir, `${runId}.json`);
+  const indexed = resultPayloadPathForIndexedRun(resultsDir, runId);
+  if (indexed)
+    return indexed;
+  const resultPath = resultFilePath(resultsDir, runId);
   assertInsideRoot(resultsDir, resultPath, "Async result file");
   return fs.existsSync(resultPath) ? resultPath : null;
 }
@@ -136,12 +128,11 @@ export function findAsyncRunPrefixMatches(prefix, asyncDirRoot, resultsDir) {
   const requestedId = assertRunId(prefix, "id");
   if (!requestedId)
     return [];
+  if (!canScanAsyncRunPrefix(requestedId))
+    return [];
   const asyncRoot = path.resolve(asyncDirRoot);
   const resultRoot = path.resolve(resultsDir);
-  const matchingIds = [...new Set([
-    ...prefixedRunIds(asyncRoot, requestedId),
-    ...prefixedRunIds(resultRoot, requestedId, ".json")
-  ])].sort();
+  const matchingIds = prefixedRunIds(asyncRoot, requestedId).sort();
   return matchingIds.map((id) => {
     const asyncDir = path.join(asyncRoot, id);
     assertInsideRoot(asyncRoot, asyncDir, "Async run directory");
@@ -180,6 +171,11 @@ export function resolveAsyncRunLocation(params, asyncDirRoot, resultsDir) {
       resolvedId: requestedId
     };
   }
+  if (requestedId.length < MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH) {
+    throw new Error(`Async run id prefix '${requestedId}' is too short. Provide at least ${MIN_SAFE_ASYNC_RUN_PREFIX_LENGTH} characters.`);
+  }
+  if (!canScanAsyncRunPrefix(requestedId))
+    return { asyncDir: null, resultPath: null, resolvedId: requestedId };
   const matching = findAsyncRunPrefixMatches(requestedId, asyncRoot, resultRoot);
   if (matching.length === 0)
     return { asyncDir: null, resultPath: null, resolvedId: requestedId };
@@ -189,7 +185,7 @@ export function resolveAsyncRunLocation(params, asyncDirRoot, resultsDir) {
   return matching[0].location;
 }
 function resultState(result) {
-  if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "running" || result.state === "queued") {
+  if (result.state === "complete" || result.state === "failed" || result.state === "partial" || result.state === "paused" || result.state === "stopped" || result.state === "running" || result.state === "queued") {
     return result.state;
   }
   return result.success ? "complete" : "failed";
@@ -199,25 +195,269 @@ function validateStatusForResume(status, source) {
     return;
   if (typeof status.runId !== "string")
     throw new Error(`Invalid async status '${source}': runId must be a string.`);
+  assertWorkflowGraphHostSteps(status.workflowGraph, source, status.runId);
   if (status.sessionId !== undefined && typeof status.sessionId !== "string")
     throw new Error(`Invalid async status '${source}': sessionId must be a string.`);
   if (status.cwd !== undefined && typeof status.cwd !== "string")
     throw new Error(`Invalid async status '${source}': cwd must be a string.`);
   if (status.sessionFile !== undefined && typeof status.sessionFile !== "string")
     throw new Error(`Invalid async status '${source}': sessionFile must be a string.`);
+  if (status.capabilityCeiling !== undefined)
+    status.capabilityCeiling = parseSubagentCapabilityCeiling(status.capabilityCeiling, `async status '${source}' capabilityCeiling`);
   if (status.steps !== undefined) {
     if (!Array.isArray(status.steps))
       throw new Error(`Invalid async status '${source}': steps must be an array.`);
     status.steps.forEach((step, index) => {
       if (!step || typeof step !== "object" || Array.isArray(step))
         throw new Error(`Invalid async status '${source}': steps[${index}] must be an object.`);
-      if (typeof step.agent !== "string")
+      const stepRecord = step;
+      if (typeof stepRecord.agent !== "string")
         throw new Error(`Invalid async status '${source}': steps[${index}].agent must be a string.`);
-      if (step.sessionFile !== undefined && typeof step.sessionFile !== "string")
+      if (stepRecord.sessionFile !== undefined && typeof stepRecord.sessionFile !== "string")
         throw new Error(`Invalid async status '${source}': steps[${index}].sessionFile must be a string.`);
+      if (stepRecord.sessionName !== undefined && typeof stepRecord.sessionName !== "string")
+        throw new Error(`Invalid async status '${source}': steps[${index}].sessionName must be a string.`);
+      if (stepRecord.model !== undefined && typeof stepRecord.model !== "string")
+        throw new Error(`Invalid async status '${source}': steps[${index}].model must be a string.`);
+      if (stepRecord.thinking !== undefined && typeof stepRecord.thinking !== "string")
+        throw new Error(`Invalid async status '${source}': steps[${index}].thinking must be a string.`);
+      if (stepRecord.thinkingCeiling !== undefined)
+        stepRecord.thinkingCeiling = parseThinkingLevel(stepRecord.thinkingCeiling, `async status '${source}' steps[${index}].thinkingCeiling`);
+      if (stepRecord.launchContractDigest !== undefined && typeof stepRecord.launchContractDigest !== "string")
+        throw new Error(`Invalid async status '${source}': steps[${index}].launchContractDigest must be a string.`);
+      if (stepRecord.capabilityCeiling !== undefined)
+        stepRecord.capabilityCeiling = parseSubagentCapabilityCeiling(stepRecord.capabilityCeiling, `async status '${source}' steps[${index}].capabilityCeiling`);
     });
   }
 }
+function normalizeRecoveryAcceptance(value, descriptorPath) {
+  const errors = validateAcceptanceInput(value, "recoveryDescriptor.acceptance");
+  if (errors.length)
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${errors.join(" ")}`);
+  return value;
+}
+export function asyncReviveRequiresRecoveryDescriptor(target) {
+  if (target.recoveryDescriptor)
+    return false;
+  return !(target.mode === "workflow" && Boolean(target.sessionFile));
+}
+function resumeTargetMode(status, result) {
+  if (status?.mode)
+    return status.mode;
+  if (result?.mode === "single" || result?.mode === "parallel" || result?.mode === "chain" || result?.mode === "workflow")
+    return result.mode;
+  return;
+}
+export function readAsyncRecoveryDescriptor(asyncDir) {
+  if (!asyncDir)
+    return;
+  const descriptorPath = path.join(asyncDir, "recovery-descriptor.json");
+  if (!fs.existsSync(descriptorPath))
+    return;
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(descriptorPath, "utf-8"));
+  } catch (error) {
+    throw new Error(`Failed to parse async recovery descriptor '${descriptorPath}': ${getErrorMessage(error)}`, { cause: error instanceof Error ? error : undefined });
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': expected an object.`);
+  const parsed = value;
+  const allowedFields = new Set([
+    "version",
+    "launchContractDigest",
+    "sourceRunId",
+    "agentContract",
+    "agent",
+    "sessionFile",
+    "cwd",
+    "model",
+    "modelProvider",
+    "modelOverrideFromParent",
+    "fallbackModels",
+    "thinking",
+    "thinkingCeiling",
+    "tools",
+    "allowNestedSubagents",
+    "extensions",
+    "subagentOnlyExtensions",
+    "mcpDirectTools",
+    "mutationTools",
+    "systemPrompt",
+    "systemPromptMode",
+    "inheritProjectContext",
+    "inheritGlobalContext",
+    "inheritSkills",
+    "skills",
+    "skillPath",
+    "agentFilePath",
+    "completionGuard",
+    "memory",
+    "outputPath",
+    "outputMode",
+    "structuredOutputSchema",
+    "acceptance",
+    "sessionDir",
+    "artifactConfig",
+    "artifactsDir",
+    "maxOutput",
+    "controlConfig",
+    "context",
+    "intercomBridge",
+    "absoluteDeadlineAt",
+    "initialTurnBudget",
+    "initialToolBudget",
+    "maxSubagentDepth",
+    "share",
+    "capabilityCeiling",
+    "launchResolvedExtensions",
+    "runFanoutBudget",
+    "lane",
+    "extensionBindings"
+  ]);
+  for (const field of Object.keys(parsed)) {
+    if (!allowedFields.has(field))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': unknown field '${field}'.`);
+  }
+  const requiredStrings = ["sourceRunId", "agent", "cwd", "systemPromptMode", "outputMode"];
+  for (const field of requiredStrings) {
+    if (typeof parsed[field] !== "string" || !parsed[field].trim())
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
+  }
+  if (parsed.version !== 1)
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': version must be 1.`);
+  try {
+    parsed.runFanoutBudget = validateRunFanoutBudgetDescriptor(parsed.runFanoutBudget);
+  } catch (error) {
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (parsed.capabilityCeiling !== undefined)
+    parsed.capabilityCeiling = parseSubagentCapabilityCeiling(parsed.capabilityCeiling, `async recovery descriptor '${descriptorPath}' capabilityCeiling`);
+  if (parsed.thinkingCeiling !== undefined)
+    parsed.thinkingCeiling = parseThinkingLevel(parsed.thinkingCeiling, `async recovery descriptor '${descriptorPath}' thinkingCeiling`);
+  if (parsed.extensionBindings !== undefined)
+    parsed.extensionBindings = normalizeExtensionBindings(parsed.extensionBindings).value;
+  if (parsed.lane !== undefined)
+    parsed.lane = normalizeWorkflowLaneMetadata(parsed.lane, `Invalid async recovery descriptor '${descriptorPath}': lane`);
+  if (parsed.agentContract !== undefined) {
+    if (!parsed.agentContract || typeof parsed.agentContract !== "object" || Array.isArray(parsed.agentContract))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be an object.`);
+    const contract = parsed.agentContract;
+    if (contract.version !== 1 || Object.keys(contract).some((key) => key !== "version"))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': agentContract must be { version: 1 }.`);
+  }
+  if (parsed.systemPromptMode !== "append" && parsed.systemPromptMode !== "replace")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPromptMode is invalid.`);
+  if (parsed.outputMode !== "inline" && parsed.outputMode !== "file-only")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': outputMode is invalid.`);
+  if (parsed.context !== undefined && parsed.context !== "fresh" && parsed.context !== "fork")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': context is invalid.`);
+  if (parsed.modelOverrideFromParent !== undefined && typeof parsed.modelOverrideFromParent !== "boolean")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': modelOverrideFromParent must be a boolean.`);
+  for (const field of ["inheritProjectContext", "inheritSkills", "share"]) {
+    if (typeof parsed[field] !== "boolean")
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a boolean.`);
+  }
+  if (parsed.inheritGlobalContext === undefined)
+    parsed.inheritGlobalContext = parsed.inheritProjectContext;
+  else if (typeof parsed.inheritGlobalContext !== "boolean")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': inheritGlobalContext must be a boolean.`);
+  if (parsed.allowNestedSubagents !== undefined && typeof parsed.allowNestedSubagents !== "boolean")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': allowNestedSubagents must be a boolean.`);
+  if (!Number.isInteger(parsed.maxSubagentDepth) || parsed.maxSubagentDepth < 0)
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxSubagentDepth must be a non-negative integer.`);
+  for (const field of ["fallbackModels", "tools", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "skills", "skillPath"]) {
+    const item = parsed[field];
+    if (item !== undefined && (!Array.isArray(item) || item.some((entry) => typeof entry !== "string" || !entry.trim())))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must contain non-empty strings.`);
+  }
+  if (parsed.systemPrompt !== undefined && typeof parsed.systemPrompt !== "string")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': systemPrompt must be a string.`);
+  for (const field of ["launchContractDigest", "sessionFile", "model", "modelProvider", "thinking", "agentFilePath", "outputPath", "sessionDir", "artifactsDir"]) {
+    if (parsed[field] !== undefined && (typeof parsed[field] !== "string" || !parsed[field].trim()))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${field} must be a non-empty string.`);
+  }
+  if (parsed.completionGuard !== undefined && typeof parsed.completionGuard !== "boolean")
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': completionGuard must be a boolean.`);
+  if (parsed.structuredOutputSchema !== undefined && (!parsed.structuredOutputSchema || typeof parsed.structuredOutputSchema !== "object" || Array.isArray(parsed.structuredOutputSchema)))
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': structuredOutputSchema must be an object.`);
+  if (parsed.memory !== undefined) {
+    if (!parsed.memory || typeof parsed.memory !== "object" || Array.isArray(parsed.memory))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory must be an object.`);
+    const memory = parsed.memory;
+    if (memory.scope !== "project" && memory.scope !== "user" || typeof memory.path !== "string" || !memory.path.trim())
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': memory is invalid.`);
+  }
+  if (parsed.absoluteDeadlineAt !== undefined && (!Number.isFinite(parsed.absoluteDeadlineAt) || parsed.absoluteDeadlineAt <= 0))
+    throw new Error(`Invalid async recovery descriptor '${descriptorPath}': absoluteDeadlineAt must be a positive timestamp.`);
+  if (parsed.initialTurnBudget !== undefined) {
+    delete parsed.initialTurnBudget;
+  }
+  if (parsed.initialToolBudget !== undefined) {
+    const result = validateToolBudgetConfig(parsed.initialToolBudget, "recoveryDescriptor.initialToolBudget");
+    if (result.error)
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': ${result.error}`);
+  }
+  if (parsed.maxOutput !== undefined) {
+    if (!parsed.maxOutput || typeof parsed.maxOutput !== "object" || Array.isArray(parsed.maxOutput))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxOutput must be an object.`);
+    for (const field of ["bytes", "lines"]) {
+      const item = parsed.maxOutput[field];
+      if (item !== undefined && (!Number.isInteger(item) || item < 1))
+        throw new Error(`Invalid async recovery descriptor '${descriptorPath}': maxOutput.${field} must be a positive integer.`);
+    }
+  }
+  if (parsed.artifactConfig !== undefined) {
+    if (!parsed.artifactConfig || typeof parsed.artifactConfig !== "object" || Array.isArray(parsed.artifactConfig))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig must be an object.`);
+    const artifact = parsed.artifactConfig;
+    for (const field of ["enabled", "includeInput", "includeOutput", "includeJsonl", "includeMetadata"]) {
+      if (typeof artifact[field] !== "boolean")
+        throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.${field} must be a boolean.`);
+    }
+    if (artifact.includeTranscript !== undefined && typeof artifact.includeTranscript !== "boolean")
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.includeTranscript must be a boolean.`);
+    if (!Number.isInteger(artifact.cleanupDays) || artifact.cleanupDays < 0)
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': artifactConfig.cleanupDays must be a non-negative integer.`);
+  }
+  if (parsed.intercomBridge !== undefined) {
+    if (!parsed.intercomBridge || typeof parsed.intercomBridge !== "object" || Array.isArray(parsed.intercomBridge))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge must be an object.`);
+    const bridge = parsed.intercomBridge;
+    for (const field of Object.keys(bridge)) {
+      if (field !== "mode" && field !== "instructionFile" && field !== "resultDelivery")
+        throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.${field} is not supported.`);
+    }
+    if (bridge.mode !== undefined && bridge.mode !== "off" && bridge.mode !== "fork-only" && bridge.mode !== "always")
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.mode is invalid.`);
+    if (bridge.instructionFile !== undefined && typeof bridge.instructionFile !== "string")
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.instructionFile must be a string.`);
+    if (bridge.resultDelivery !== undefined && typeof bridge.resultDelivery !== "boolean")
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': intercomBridge.resultDelivery must be a boolean.`);
+  }
+  if (parsed.controlConfig !== undefined) {
+    if (!parsed.controlConfig || typeof parsed.controlConfig !== "object" || Array.isArray(parsed.controlConfig))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig must be an object.`);
+    const control = parsed.controlConfig;
+    if (typeof control.enabled !== "boolean")
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.enabled must be a boolean.`);
+    for (const field of ["needsAttentionAfterMs", "activeNoticeAfterMs", "failedToolAttemptsBeforeAttention"]) {
+      if (!Number.isInteger(control[field]) || control[field] < 1)
+        throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.${field} must be a positive integer.`);
+    }
+    for (const field of ["activeNoticeAfterTurns", "activeNoticeAfterTokens"]) {
+      if (control[field] !== undefined && (!Number.isInteger(control[field]) || control[field] < 1))
+        throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.${field} must be a positive integer.`);
+    }
+    if (!Array.isArray(control.notifyOn) || control.notifyOn.some((item) => item !== "active_long_running" && item !== "needs_attention"))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyOn is invalid.`);
+    if (!Array.isArray(control.notifyChannels) || control.notifyChannels.some((item) => item !== "event" && item !== "async" && item !== "intercom"))
+      throw new Error(`Invalid async recovery descriptor '${descriptorPath}': controlConfig.notifyChannels is invalid.`);
+  }
+  if (parsed.acceptance !== undefined)
+    parsed.acceptance = normalizeRecoveryAcceptance(parsed.acceptance, descriptorPath);
+  return parsed;
+}
 function validateResumeSessionFile(runId, sessionFile) {
   if (path.extname(sessionFile) !== ".jsonl")
     throw new Error(`Async run '${runId}' session file must be a .jsonl file: ${sessionFile}`);
@@ -226,9 +466,21 @@ function validateResumeSessionFile(runId, sessionFile) {
     throw new Error(`Async run '${runId}' session file does not exist: ${sessionFile}`);
   return resolved;
 }
+function validateResumeCwd(runId, cwd) {
+  if (!cwd)
+    return;
+  const resolved = path.resolve(cwd);
+  try {
+    if (!fs.statSync(resolved).isDirectory())
+      throw new Error("path is not a directory");
+  } catch (error) {
+    throw new Error(`Async run '${runId}' required cwd does not exist: ${cwd}`, { cause: error instanceof Error ? error : undefined });
+  }
+  return resolved;
+}
 export function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
-  const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
-  const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+  const asyncDirRoot = deps.asyncDirRoot ?? DIRS.async;
+  const resultsDir = deps.resultsDir ?? DIRS.results;
   const requireSessionFile = options.requireSessionFile ?? true;
   const location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
   if (!location.asyncDir && !location.resultPath) {
@@ -237,11 +489,20 @@ export function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
   const reconciliation = location.asyncDir ? reconcileAsyncRun(location.asyncDir, { resultsDir, kill: deps.kill, now: deps.now }) : undefined;
   const status = reconciliation?.status ?? null;
   validateStatusForResume(status, location.asyncDir ? path.join(location.asyncDir, "status.json") : "status.json");
+  const recoveryDescriptor = readAsyncRecoveryDescriptor(location.asyncDir ?? undefined);
   const result = location.resultPath ? readResultFile(location.resultPath) : undefined;
   const runId = status?.runId ?? result?.runId ?? result?.id ?? location.resolvedId ?? (location.asyncDir ? path.basename(location.asyncDir) : "unknown");
+  const mode = resumeTargetMode(status, result);
+  if (options.sessionId && (status && status.sessionId !== options.sessionId || result && result.sessionId !== options.sessionId)) {
+    throw new Error(`Async run '${runId}' was not found in the active session.`);
+  }
+  if (recoveryDescriptor && recoveryDescriptor.sourceRunId !== runId)
+    throw new Error(`Async run '${runId}' has a recovery descriptor for a different source run.`);
   const state = status?.state ?? (result ? resultState(result) : undefined);
   if (!state)
     throw new Error(`Status file not found for async run '${runId}'.`);
+  if (state === "stopped")
+    throw new Error(`Async run '${runId}' was stopped and cannot be resumed. Start a new run instead.`);
   const statusSteps = status?.steps ?? [];
   const resultSteps = result?.results ?? [];
   const stepCount = statusSteps.length || resultSteps.length || (result?.agent ? 1 : 0);
@@ -255,16 +516,26 @@ export function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
         throw new Error(`Async run '${runId}' has ${stepCount} children. Index ${requestedIndex} is out of range.`);
       const selectedStep = statusSteps[requestedIndex];
       if (selectedStep?.status === "running") {
+        const capabilityCeiling = intersectSubagentCapabilityCeilings(status?.capabilityCeiling, selectedStep.capabilityCeiling);
         return {
           kind: "live",
           runId,
           asyncDir: location.asyncDir ?? undefined,
           state,
+          ...mode ? { mode } : {},
           agent: selectedStep.agent,
+          ...selectedStep.sessionName ?? result?.results?.[requestedIndex]?.sessionName ? { sessionName: selectedStep.sessionName ?? result?.results?.[requestedIndex]?.sessionName } : {},
           index: requestedIndex,
-          intercomTarget: resolveSubagentIntercomTarget(runId, selectedStep.agent, requestedIndex),
           cwd: status?.cwd ?? result?.cwd,
-          sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile
+          sessionFile: selectedStep.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+          model: selectedStep.model,
+          thinking: selectedStep.thinking,
+          launchContractDigest: selectedStep.launchContractDigest ?? result?.results?.[requestedIndex]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
+          ...selectedStep.runner ? { runner: selectedStep.runner } : {},
+          ...selectedStep.externalJob ? { externalJob: selectedStep.externalJob } : {},
+          ...capabilityCeiling ? { capabilityCeiling } : {},
+          ...selectedStep.thinkingCeiling ? { thinkingCeiling: selectedStep.thinkingCeiling } : {},
+          ...recoveryDescriptor ? { recoveryDescriptor } : {}
         };
       }
       if (selectedStep?.status === "pending")
@@ -277,16 +548,26 @@ export function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
       if (!selected) {
         throw new Error(`Async run '${runId}' has ${running.length} running children. Provide index to choose one.`);
       }
+      const capabilityCeiling = intersectSubagentCapabilityCeilings(status?.capabilityCeiling, selected.step.capabilityCeiling);
       return {
         kind: "live",
         runId,
         asyncDir: location.asyncDir ?? undefined,
         state,
+        ...mode ? { mode } : {},
         agent: selected.step.agent,
+        ...selected.step.sessionName ?? result?.results?.[selected.index]?.sessionName ? { sessionName: selected.step.sessionName ?? result?.results?.[selected.index]?.sessionName } : {},
         index: selected.index,
-        intercomTarget: resolveSubagentIntercomTarget(runId, selected.step.agent, selected.index),
         cwd: status?.cwd ?? result?.cwd,
-        sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile
+        sessionFile: selected.step.sessionFile ?? status?.sessionFile ?? result?.sessionFile,
+        model: selected.step.model,
+        thinking: selected.step.thinking,
+        launchContractDigest: selected.step.launchContractDigest ?? result?.results?.[selected.index]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
+        ...selected.step.runner ? { runner: selected.step.runner } : {},
+        ...selected.step.externalJob ? { externalJob: selected.step.externalJob } : {},
+        ...capabilityCeiling ? { capabilityCeiling } : {},
+        ...selected.step.thinkingCeiling ? { thinkingCeiling: selected.step.thinkingCeiling } : {},
+        ...recoveryDescriptor ? { recoveryDescriptor } : {}
       };
     }
   }
@@ -301,20 +582,66 @@ export function resolveAsyncResumeTarget(params, deps = {}, options = {}) {
   const agent = statusSteps[index]?.agent ?? resultSteps[index]?.agent ?? result?.agent;
   if (!agent)
     throw new Error(`Could not determine child agent for async run '${runId}'.`);
+  if (recoveryDescriptor && recoveryDescriptor.agent !== agent)
+    throw new Error(`Async run '${runId}' has a recovery descriptor for '${recoveryDescriptor.agent}', not '${agent}'.`);
   const sessionFile = statusSteps[index]?.sessionFile ?? resultSteps[index]?.sessionFile ?? (stepCount === 1 ? status?.sessionFile ?? result?.sessionFile : undefined);
   if (!sessionFile && requireSessionFile)
     throw new Error(`Async run '${runId}' child ${index} does not have a persisted session file to resume from.`);
   const resolvedSessionFile = sessionFile ? validateResumeSessionFile(runId, sessionFile) : undefined;
+  const stepModel = statusSteps[index]?.model ?? resultSteps[index]?.model ?? (stepCount === 1 ? result?.model : undefined);
+  const stepThinking = statusSteps[index]?.thinking ?? resultSteps[index]?.thinking ?? (stepCount === 1 ? result?.thinking : undefined);
+  const thinkingCeiling = statusSteps[index]?.thinkingCeiling ?? (stepCount === 1 ? recoveryDescriptor?.thinkingCeiling : undefined);
+  const capabilityCeiling = intersectSubagentCapabilityCeilings(status?.capabilityCeiling, statusSteps[index]?.capabilityCeiling, result?.capabilityCeiling, resultSteps[index]?.capabilityCeiling);
+  const managedWorktreeCwd = location.asyncDir ? resolveRetainedWorktreeCwd(parallelHandoffPath(location.asyncDir), runId, index) : undefined;
+  const resumeCwd = validateResumeCwd(runId, managedWorktreeCwd ?? status?.cwd ?? result?.cwd ?? recoveryDescriptor?.cwd);
   return {
     kind: "revive",
     runId,
     asyncDir: location.asyncDir ?? undefined,
     state,
+    ...mode ? { mode } : {},
     agent,
+    ...statusSteps[index]?.sessionName ?? resultSteps[index]?.sessionName ? { sessionName: statusSteps[index]?.sessionName ?? resultSteps[index]?.sessionName } : {},
     index,
-    intercomTarget: resolveSubagentIntercomTarget(runId, agent, index),
-    cwd: status?.cwd ?? result?.cwd,
-    ...resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {}
+    ...resumeCwd ? { cwd: resumeCwd } : {},
+    ...resolvedSessionFile ? { sessionFile: resolvedSessionFile } : {},
+    ...stepModel ? { model: stepModel } : {},
+    ...stepThinking ? { thinking: stepThinking } : {},
+    launchContractDigest: statusSteps[index]?.launchContractDigest ?? resultSteps[index]?.launchContractDigest ?? result?.launchContractDigest ?? recoveryDescriptor?.launchContractDigest,
+    ...statusSteps[index]?.runner ? { runner: statusSteps[index].runner } : {},
+    ...statusSteps[index]?.externalJob ? { externalJob: statusSteps[index].externalJob } : {},
+    ...capabilityCeiling ? { capabilityCeiling } : {},
+    ...thinkingCeiling ? { thinkingCeiling } : {},
+    ...recoveryDescriptor ? { recoveryDescriptor } : {}
+  };
+}
+export function applySteeringRecoveryAgentConfig(agentConfig, descriptor) {
+  return {
+    ...agentConfig,
+    model: descriptor.model,
+    modelProvider: descriptor.modelProvider,
+    fallbackModels: descriptor.fallbackModels ? [...descriptor.fallbackModels] : undefined,
+    thinking: descriptor.thinking,
+    maxThinking: intersectThinkingCeilings(descriptor.thinkingCeiling, agentConfig.maxThinking),
+    tools: descriptor.tools ? [...descriptor.tools] : undefined,
+    allowNestedSubagents: descriptor.allowNestedSubagents,
+    extensions: descriptor.extensions ? [...descriptor.extensions] : undefined,
+    subagentOnlyExtensions: descriptor.subagentOnlyExtensions ? [...descriptor.subagentOnlyExtensions] : undefined,
+    mcpDirectTools: descriptor.mcpDirectTools ? [...descriptor.mcpDirectTools] : undefined,
+    mutationTools: descriptor.mutationTools ? [...descriptor.mutationTools] : undefined,
+    systemPrompt: descriptor.systemPrompt ?? agentConfig.systemPrompt,
+    systemPromptMode: descriptor.systemPromptMode,
+    inheritProjectContext: descriptor.inheritProjectContext,
+    inheritGlobalContext: descriptor.inheritGlobalContext,
+    inheritSkills: descriptor.inheritSkills,
+    skills: descriptor.skills ? [...descriptor.skills] : undefined,
+    skillPath: descriptor.skillPath ? [...descriptor.skillPath] : undefined,
+    filePath: descriptor.agentFilePath,
+    completionGuard: descriptor.completionGuard,
+    memory: descriptor.memory ? { ...descriptor.memory } : undefined,
+    output: descriptor.outputPath,
+    toolBudget: descriptor.initialToolBudget,
+    maxSubagentDepth: descriptor.maxSubagentDepth
   };
 }
 export function buildRevivedAsyncTask(target, message) {