@the-open-engine/zeroshot 6.7.0 → 6.7.1

package/src/agent-cli-provider/adapters/claude.ts

@@ -4,7 +4,6 @@ import {
   type ClaudeCliFeatures,
   type CommandSpec,
   type ErrorClassification,
-  InvalidProviderModelError,
   type LevelModelSpec,
   type LevelOverrides,
   type ModelCatalogEntry,
@@ -28,8 +27,23 @@ import { parseClaudeEvent } from './claude-parser';
 
 const MODEL_CATALOG: Readonly<Record<string, ModelCatalogEntry>> = {
   haiku: { rank: 1 },
+  'claude-haiku-4-5': { rank: 1 },
+  'claude-haiku-4-5-20251001': { rank: 1 },
   sonnet: { rank: 2 },
+  'claude-sonnet-4-5': { rank: 2 },
+  'claude-sonnet-4-5-20250929': { rank: 2 },
+  'claude-sonnet-4-6': { rank: 2 },
+  'claude-sonnet-5': { rank: 2 },
   opus: { rank: 3 },
+  'claude-opus-4-5': { rank: 3 },
+  'claude-opus-4-5-20251101': { rank: 3 },
+  'claude-opus-4-6': { rank: 3 },
+  'claude-opus-4-7': { rank: 3 },
+  'claude-opus-4-8': { rank: 3 },
+  fable: { rank: 3 },
+  'claude-fable-5': { rank: 3 },
+  'claude-mythos-5': { rank: 3 },
+  'claude-mythos-preview': { rank: 3 },
 };
 
 const LEVEL_MAPPING: Readonly<Record<ModelLevel, LevelModelSpec>> = {
@@ -50,6 +64,7 @@ function detectCliFeatures(helpText?: string | null): ClaudeCliFeatures {
     supportsIncludePartials: unknown ? true : /--include-partial-messages/.test(help),
     supportsVerbose: unknown ? true : /--verbose/.test(help),
     supportsModel: unknown ? true : /--model/.test(help),
+    supportsEffort: unknown ? true : /--effort/.test(help),
     unknown,
   };
 }
@@ -86,6 +101,9 @@ function addModelArgs(args: string[], options: BuildProviderCommandOptions): voi
   if (options.modelSpec?.model && features.supportsModel !== false) {
     args.push('--model', options.modelSpec.model);
   }
+  if (options.modelSpec?.reasoningEffort && features.supportsEffort !== false) {
+    args.push('--effort', options.modelSpec.reasoningEffort);
+  }
 }
 
 function addAutoApproveArgs(args: string[], options: BuildProviderCommandOptions): void {
@@ -139,6 +157,15 @@ function collectWarnings(options: BuildProviderCommandOptions): WarningMetadata[
       )
     );
   }
+  if (options.modelSpec?.reasoningEffort && features.supportsEffort === false) {
+    warnings.push(
+      warning(
+        'claude',
+        'claude-reasoning',
+        'Claude CLI does not support --effort; skipping reasoningEffort.'
+      )
+    );
+  }
   return warnings;
 }
 
@@ -176,16 +203,7 @@ function resolveModelSpec(level: ModelLevel, overrides?: LevelOverrides): Resolv
 }
 
 function validateModelId(modelId: string | null | undefined): string | null | undefined {
-  try {
-    return validateModelIdFromCatalog('claude', MODEL_CATALOG, modelId);
-  } catch (error) {
-    if (modelId && (modelId === 'opus-4.6' || modelId === 'claude-opus-4-6')) {
-      throw new InvalidProviderModelError(
-        `Invalid model "${modelId}" for provider "claude". Use canonical model ids: haiku, sonnet, opus.`
-      );
-    }
-    throw error;
-  }
+  return validateModelIdFromCatalog('claude', MODEL_CATALOG, modelId);
 }
 
 function classifyError(error: unknown): ErrorClassification {

package/src/agent-cli-provider/adapters/codex.ts

@@ -27,6 +27,10 @@ import { parseCodexEvent } from './codex-parser';
 const MODEL_CATALOG: Readonly<Record<string, ModelCatalogEntry>> = {
   'gpt-5.4': { rank: 2 },
   'gpt-5.5': { rank: 3 },
+  'gpt-5.6': { rank: 3 },
+  'gpt-5.6-sol': { rank: 3 },
+  'gpt-5.6-terra': { rank: 2 },
+  'gpt-5.6-luna': { rank: 1 },
 };
 
 const LEVEL_MAPPING: Readonly<Record<ModelLevel, LevelModelSpec>> = {

package/src/agent-cli-provider/adapters/common.ts

@@ -100,8 +100,9 @@ export function validateModelIdFromCatalog(
 ): string | null | undefined {
   if (!modelId) return modelId;
   if (catalog[modelId] !== undefined) return modelId;
+  const validModels = Object.keys(catalog).join(', ');
   throw new InvalidProviderModelError(
-    `Invalid model "${modelId}" for provider "${provider}". Use a model listed in provider settings/catalog.`
+    `Invalid model "${modelId}" for provider "${provider}". Valid models: ${validModels}.`
   );
 }
 

package/src/agent-cli-provider/contract-options.ts

@@ -13,7 +13,7 @@ import type {
 
 const OUTPUT_FORMATS: readonly OutputFormat[] = ['text', 'json', 'stream-json'];
 const MODEL_LEVELS: readonly ModelLevel[] = ['level1', 'level2', 'level3'];
-const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh'];
+const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh', 'max'];
 const CLI_FEATURE_FIELDS = [
   'supportsOutputFormat',
   'supportsStreamJson',
@@ -22,6 +22,7 @@ const CLI_FEATURE_FIELDS = [
   'supportsIncludePartials',
   'supportsVerbose',
   'supportsModel',
+  'supportsEffort',
   'supportsJson',
   'supportsOutputSchema',
   'supportsDir',

package/src/agent-cli-provider/index.ts

@@ -91,6 +91,7 @@ export type {
   ProviderId,
   ProviderRegistryEntry,
   RedactionMetadata,
+  ReasoningEffort,
   ResolvedGatewayBuildOptions,
   ResolvedModelSpec,
   ResultEvent,

package/src/agent-cli-provider/provider-registry.ts

@@ -160,7 +160,7 @@ export const providerRegistry = [
     capabilities: {
       ...STANDARD_CAPABILITIES,
       jsonSchema: true,
-      reasoningEffort: false,
+      reasoningEffort: true,
     },
     docs: {
       label: 'Claude',

package/src/agent-cli-provider/single-agent-runtime.ts

@@ -61,7 +61,7 @@ type MutableModelSpec = {
 };
 
 const MODEL_LEVELS: readonly ModelLevel[] = ['level1', 'level2', 'level3'];
-const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh'];
+const REASONING_EFFORTS: readonly ReasoningEffort[] = ['low', 'medium', 'high', 'xhigh', 'max'];
 const settingsModule: unknown = require('../../lib/settings');
 const providerDetectionModule: unknown = require('../../lib/provider-detection');
 const claudeAuthModule: unknown = require('../../lib/settings/claude-auth');
@@ -420,7 +420,13 @@ function optionalModelLevel(value: unknown, field: string): ModelLevel | undefin
 
 function optionalReasoningEffort(value: unknown, field: string): ReasoningEffort | undefined {
   if (value === undefined) return undefined;
-  if (value === 'low' || value === 'medium' || value === 'high' || value === 'xhigh') {
+  if (
+    value === 'low' ||
+    value === 'medium' ||
+    value === 'high' ||
+    value === 'xhigh' ||
+    value === 'max'
+  ) {
     return value;
   }
   throw new Error(`${field} must be one of: ${REASONING_EFFORTS.join(', ')}.`);

package/src/agent-cli-provider/types.ts

@@ -15,7 +15,7 @@ export type ProviderId = (typeof providerIds)[number];
 export type ProviderAlias = (typeof providerAliases)[number];
 export type KnownProviderName = ProviderId | ProviderAlias;
 export type ModelLevel = 'level1' | 'level2' | 'level3';
-export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh';
+export type ReasoningEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export type OutputFormat = 'text' | 'json' | 'stream-json';
 export type {
   ProviderCapabilities,
@@ -95,6 +95,7 @@ export interface ClaudeCliFeatures extends BaseCliFeatures {
   readonly supportsIncludePartials: boolean;
   readonly supportsVerbose: boolean;
   readonly supportsModel: boolean;
+  readonly supportsEffort: boolean;
 }
 
 export interface CodexCliFeatures extends BaseCliFeatures {
@@ -186,6 +187,7 @@ export interface CliFeatureOverrides {
   readonly supportsIncludePartials?: boolean;
   readonly supportsVerbose?: boolean;
   readonly supportsModel?: boolean;
+  readonly supportsEffort?: boolean;
   readonly supportsJson?: boolean;
   readonly supportsOutputSchema?: boolean;
   readonly supportsDir?: boolean;

package/src/agent-wrapper.js

@@ -81,8 +81,15 @@ class AgentWrapper {
     // LIVENESS DETECTION - Track output freshness to detect stuck agents
     /** @type {number | null} */
     this.lastOutputTime = null; // Timestamp of last output received
+    /** @type {number | null} */
+    this.taskStartedAt = null; // Timestamp used for absolute task timeout
     /** @type {NodeJS.Timeout | null} */
     this.livenessCheckInterval = null; // Interval for health checks
+    this.consecutiveStaleWarnings = 0;
+    this.livenessTerminationStarted = false;
+    this.livenessTerminationContext = null;
+    this.livenessTerminationAttempts = 0;
+    this.livenessTerminationRetryAt = 0;
     this.staleDuration = normalizedConfig.staleDuration;
     this.enableLivenessCheck = normalizedConfig.enableLivenessCheck;
 
@@ -499,8 +506,8 @@ class AgentWrapper {
    * Kill current task
    * @private
    */
-  _killTask() {
-    return killTask(this);
+  _killTask(reason) {
+    return killTask(this, reason);
   }
 
   /**

package/src/config-validator.js

@@ -21,6 +21,9 @@ const { getProvider } = require('./providers');
 const { CAPABILITIES } = require('./providers/capabilities');
 const { GUIDANCE_TOPICS } = require('./guidance-topics');
 
+const REASONING_EFFORTS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
+const REASONING_EFFORT_LABEL = REASONING_EFFORTS.join('|');
+
 const HOOK_ACTION_TOPIC_CONTRACTS = Object.freeze({
   verify_pull_request: Object.freeze([
     { topic: 'CLUSTER_COMPLETE', keys: null },
@@ -2054,14 +2057,13 @@ function validateProviderSettings(provider, providerSettings) {
       providerModule.validateModelId(override.model);
     }
     if (override?.reasoningEffort && !providerSupportsCapability(provider, 'reasoningEffort')) {
-      throw new Error(`reasoningEffort overrides are only supported for Codex and Opencode`);
+      throw new Error(
+        `reasoningEffort overrides are only supported for Claude, Codex, and Opencode`
+      );
     }
-    if (
-      override?.reasoningEffort &&
-      !['low', 'medium', 'high', 'xhigh'].includes(override.reasoningEffort)
-    ) {
+    if (override?.reasoningEffort && !REASONING_EFFORTS.includes(override.reasoningEffort)) {
       throw new Error(
-        `Invalid reasoningEffort "${override.reasoningEffort}" (low|medium|high|xhigh)`
+        `Invalid reasoningEffort "${override.reasoningEffort}" (${REASONING_EFFORT_LABEL})`
       );
     }
   }
@@ -2172,12 +2174,9 @@ function validateModelRulesSupport(agent, provider, providerModule, levels, warn
 function validateReasoningEffortSupport(agent, provider, warnings) {
   if (agent.reasoningEffort && !providerSupportsCapability(provider, 'reasoningEffort')) {
     warnings.push(`Agent "${agent.id}" sets reasoningEffort but ${provider} does not support it`);
-  } else if (
-    agent.reasoningEffort &&
-    !['low', 'medium', 'high', 'xhigh'].includes(agent.reasoningEffort)
-  ) {
+  } else if (agent.reasoningEffort && !REASONING_EFFORTS.includes(agent.reasoningEffort)) {
     warnings.push(
-      `Agent "${agent.id}" has invalid reasoningEffort "${agent.reasoningEffort}" (low|medium|high|xhigh)`
+      `Agent "${agent.id}" has invalid reasoningEffort "${agent.reasoningEffort}" (${REASONING_EFFORT_LABEL})`
     );
   }
 }

package/src/orchestrator.js

@@ -1535,6 +1535,7 @@ class Orchestrator {
       const agentRole = message.content?.data?.role;
       const attempts = message.content?.data?.attempts || 1;
       const hookFailure = message.content?.data?.hookFailure === true;
+      const restartExhausted = message.content?.data?.restartExhausted === true;
 
       await this._saveClusters();
 
@@ -1542,7 +1543,7 @@ class Orchestrator {
         agentRole === 'implementation' ||
         agentRole === 'coordinator' ||
         message.sender === 'consensus-coordinator';
-      const shouldStop = shouldStopForRole && (hookFailure || attempts >= 3);
+      const shouldStop = shouldStopForRole && (hookFailure || restartExhausted || attempts >= 3);
 
       if (shouldStop) {
         this._log(`\n${'='.repeat(80)}`);
@@ -1551,6 +1552,7 @@ class Orchestrator {
         this._log(
           `${message.sender} (${agentRole || 'unknown role'}) failed` +
             (hookFailure ? ` (hookFailure=true)` : ``) +
+            (restartExhausted ? ` (restartExhausted=true)` : ``) +
             ` after ${attempts} attempts`
         );
         this._log(`Error: ${message.content?.data?.error || 'unknown'}`);
@@ -1573,7 +1575,7 @@ class Orchestrator {
     });
   }
 
-  _registerAgentLifecycleHandlers(messageBus, clusterId) {
+  _registerAgentLifecycleHandlers(messageBus, _clusterId) {
     messageBus.on('topic:AGENT_LIFECYCLE', async (message) => {
       const event = message.content?.data?.event;
       if (
@@ -1596,13 +1598,14 @@ class Orchestrator {
       const timeSinceLastOutput = message.content?.data?.timeSinceLastOutput;
       const analysis = message.content?.data?.analysis || 'No analysis available';
 
+      const consecutiveWarnings = message.content?.data?.consecutiveWarnings;
+      const warningsBeforeKill = message.content?.data?.warningsBeforeKill;
       this._log(
-        `⚠️  Orchestrator: Agent ${agentId} appears stale (${Math.round(timeSinceLastOutput / 1000)}s no output) but will NOT be killed`
+        `⚠️  Orchestrator: Agent ${agentId} has produced no output for ${Math.round(timeSinceLastOutput / 1000)}s ` +
+          `(warning ${consecutiveWarnings}/${warningsBeforeKill})`
       );
       this._log(`    Analysis: ${analysis}`);
-      this._log(
-        `    Manual intervention may be needed - use 'zeroshot resume ${clusterId}' if stuck`
-      );
+      this._log(`    Zeroshot will terminate and restart the task if inactivity persists`);
     });
   }
 
@@ -2361,6 +2364,15 @@ class Orchestrator {
       return;
     }
     this.closed = true;
+
+    for (const cluster of this.clusters.values()) {
+      if (typeof cluster.snapshotter?.stop === 'function') {
+        cluster.snapshotter.stop();
+      }
+      if (typeof cluster.messageBus?.close === 'function') {
+        cluster.messageBus.close();
+      }
+    }
   }
 
   /**

package/task-lib/attachable-watcher.js

@@ -319,6 +319,8 @@ server.on('exit', async ({ exitCode, signal }) => {
   try {
     await updateTask(taskId, {
       status,
+      pid: null,
+      processGroupId: null,
       exitCode: resolvedCode,
       error: fatalError || (resolvedCode !== 0 && signal ? `Killed by ${signal}` : null),
       socketPath: null,
@@ -336,7 +338,12 @@ server.on('error', async (err) => {
   log(`\nError: ${err.message}\n`);
   await cleanupCommandSpec();
   try {
-    await updateTask(taskId, { status: 'failed', error: err.message });
+    await updateTask(taskId, {
+      status: 'failed',
+      pid: null,
+      processGroupId: null,
+      error: err.message,
+    });
   } catch (updateError) {
     log(`[${Date.now()}][ERROR] Failed to update task status: ${updateError.message}\n`);
   }
@@ -358,6 +365,8 @@ try {
     pid: server.pid,
     socketPath,
     attachable: true,
+    processGroupId: process.platform === 'win32' ? null : server.pid,
+    terminationStrategy: process.platform === 'win32' ? 'process-tree' : 'process-group',
   });
 
   log(`[${Date.now()}][SYSTEM] Started with PTY (attachable)\n`);

package/task-lib/commands/kill.js

@@ -1,8 +1,8 @@
 import chalk from 'chalk';
 import { getTask, updateTask } from '../store.js';
-import { killTask as killProcess, isProcessRunning } from '../runner.js';
+import { terminateProcess } from '../runner.js';
 
-export function killTaskCommand(taskId) {
+export async function killTaskCommand(taskId, options = {}) {
   const task = getTask(taskId);
 
   if (!task) {
@@ -15,18 +15,43 @@ export function killTaskCommand(taskId) {
     return;
   }
 
-  if (!isProcessRunning(task.pid)) {
+  const terminationOptions = {
+    ...options,
+    processGroupId: task.processGroupId,
+    terminationStrategy: task.terminationStrategy || 'process',
+  };
+
+  const result = await terminateProcess(task.pid, terminationOptions);
+
+  if (result.terminated && result.alreadyDead) {
     console.log(chalk.yellow('Process already dead, updating status...'));
-    updateTask(taskId, { status: 'stale', error: 'Process died unexpectedly' });
+    updateTask(taskId, {
+      status: 'stale',
+      pid: null,
+      processGroupId: null,
+      error: 'Process died unexpectedly',
+    });
     return;
   }
 
-  const killed = killProcess(task.pid);
-
-  if (killed) {
-    console.log(chalk.green(`✓ Sent SIGTERM to task ${taskId} (PID: ${task.pid})`));
-    updateTask(taskId, { status: 'killed', error: 'Killed by user' });
+  if (result.terminated) {
+    const suffix = result.escalated ? ' after SIGKILL escalation' : ' with SIGTERM';
+    console.log(chalk.green(`✓ Killed task ${taskId} (PID: ${task.pid})${suffix}`));
+    if (result.degraded) {
+      console.log(chalk.yellow(`Warning: ${result.degradedReason}`));
+    }
+    updateTask(taskId, {
+      status: 'killed',
+      pid: null,
+      processGroupId: null,
+      exitCode: result.escalated ? 137 : 143,
+      error: result.escalated ? 'Killed by user after SIGKILL escalation' : 'Killed by user',
+    });
   } else {
     console.log(chalk.red(`Failed to kill task ${taskId}`));
+    updateTask(taskId, {
+      error: result.error || 'Process termination failed',
+    });
+    process.exitCode = 1;
   }
 }

package/task-lib/commands/status.js

@@ -1,6 +1,6 @@
 import chalk from 'chalk';
 import { getTask } from '../store.js';
-import { isProcessRunning } from '../runner.js';
+import { isOwnedProcessTreeRunning } from '../runner.js';
 
 export function showStatus(taskId) {
   const task = getTask(taskId);
@@ -12,8 +12,18 @@ export function showStatus(taskId) {
 
   // Verify running status
   let status = task.status;
-  if (status === 'running' && !isProcessRunning(task.pid)) {
-    status = 'stale (process died)';
+  if (status === 'running') {
+    try {
+      const running = isOwnedProcessTreeRunning(task.pid, {
+        processGroupId: task.processGroupId,
+        terminationStrategy: task.terminationStrategy || 'process',
+      });
+      if (!running) {
+        status = 'stale (process died)';
+      }
+    } catch (error) {
+      status = `stale (invalid process ownership: ${error.message})`;
+    }
   }
 
   const statusColor =

package/task-lib/process-termination.js

@@ -0,0 +1,202 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+export function isProcessRunning(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function killTask(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 'SIGTERM');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeTerminationOwnership(pid, options) {
+  const terminationStrategy = options.terminationStrategy || 'process';
+  const processGroupId = Number(options.processGroupId) || null;
+
+  if (terminationStrategy === 'process-group') {
+    if (process.platform === 'win32') {
+      throw new Error(
+        'Process-group termination is unavailable on Windows; use terminationStrategy "process-tree"'
+      );
+    }
+    if (!processGroupId || processGroupId !== pid) {
+      throw new Error(
+        `Refusing process-group termination for PID ${pid}: owned processGroupId must equal the provider root PID`
+      );
+    }
+  }
+
+  if (terminationStrategy === 'process-tree' && process.platform !== 'win32') {
+    throw new Error(
+      `Process-tree termination is only supported on Windows; use terminationStrategy "process-group" on ${process.platform}`
+    );
+  }
+
+  if (!['process', 'process-group', 'process-tree'].includes(terminationStrategy)) {
+    throw new Error(`Unsupported termination strategy: ${terminationStrategy}`);
+  }
+
+  return { terminationStrategy, processGroupId };
+}
+
+function isProcessGroupRunning(processGroupId) {
+  try {
+    process.kill(-processGroupId, 0);
+    return true;
+  } catch (error) {
+    return error?.code === 'EPERM';
+  }
+}
+
+export function isOwnedProcessTreeRunning(pid, options = {}) {
+  if (!pid) return false;
+  const ownership = normalizeTerminationOwnership(pid, options);
+  if (ownership.terminationStrategy === 'process-group') {
+    return isProcessGroupRunning(ownership.processGroupId);
+  }
+  return isProcessRunning(pid);
+}
+
+async function signalWindowsProcessTree(pid, force) {
+  const args = ['/PID', String(pid), '/T'];
+  if (force) args.push('/F');
+  await execFileAsync('taskkill', args, { windowsHide: true });
+}
+
+async function signalOwnedProcessTree(pid, signal, ownership) {
+  if (ownership.terminationStrategy === 'process-group') {
+    process.kill(-ownership.processGroupId, signal);
+    return;
+  }
+  if (ownership.terminationStrategy === 'process-tree') {
+    await signalWindowsProcessTree(pid, signal === 'SIGKILL');
+    return;
+  }
+  process.kill(pid, signal);
+}
+
+async function waitForOwnedProcessTreeExit(pid, ownership, timeoutMs, pollMs) {
+  const deadline = Date.now() + timeoutMs;
+  const options = {
+    terminationStrategy: ownership.terminationStrategy,
+    processGroupId: ownership.processGroupId,
+  };
+  while (Date.now() < deadline) {
+    if (!isOwnedProcessTreeRunning(pid, options)) return true;
+    await sleep(pollMs);
+  }
+  return !isOwnedProcessTreeRunning(pid, options);
+}
+
+function terminationResult(ownership, overrides = {}) {
+  const degraded = ownership.terminationStrategy === 'process';
+  return {
+    terminated: false,
+    alreadyDead: false,
+    escalated: false,
+    signal: null,
+    scope: ownership.terminationStrategy,
+    degraded,
+    degradedReason: degraded
+      ? 'Task has no process-tree ownership metadata; only the provider root PID can be terminated'
+      : null,
+    ...overrides,
+  };
+}
+
+async function signalAndWait(pid, ownership, signal, timeoutMs, pollMs) {
+  const escalated = signal === 'SIGKILL';
+  try {
+    await signalOwnedProcessTree(pid, signal, ownership);
+  } catch (error) {
+    if (
+      !isOwnedProcessTreeRunning(pid, {
+        terminationStrategy: ownership.terminationStrategy,
+        processGroupId: ownership.processGroupId,
+      })
+    ) {
+      return terminationResult(ownership, {
+        terminated: true,
+        alreadyDead: signal === 'SIGTERM',
+        escalated,
+        signal: escalated ? signal : null,
+      });
+    }
+    return terminationResult(ownership, {
+      escalated,
+      signal,
+      error: error.message,
+    });
+  }
+
+  const terminated = await waitForOwnedProcessTreeExit(pid, ownership, timeoutMs, pollMs);
+  return terminationResult(ownership, {
+    terminated,
+    escalated,
+    signal,
+    error:
+      terminated || !escalated
+        ? null
+        : `Owned ${ownership.terminationStrategy} for PID ${pid} survived ${signal}`,
+  });
+}
+
+/**
+ * Terminate an owned provider process tree. Watchers create a dedicated process
+ * group on POSIX and persist that ownership boundary; Windows uses taskkill /T.
+ * Legacy tasks without ownership metadata fall back to root-only termination
+ * and report the degraded scope explicitly.
+ */
+export async function terminateProcess(pid, options = {}) {
+  let ownership;
+  try {
+    ownership = normalizeTerminationOwnership(pid, options);
+  } catch (error) {
+    return {
+      terminated: false,
+      alreadyDead: false,
+      escalated: false,
+      signal: null,
+      error: error.message,
+    };
+  }
+
+  if (!isOwnedProcessTreeRunning(pid, options)) {
+    return terminationResult(ownership, { terminated: true, alreadyDead: true });
+  }
+
+  const graceful = await signalAndWait(
+    pid,
+    ownership,
+    'SIGTERM',
+    options.graceMs ?? 5000,
+    options.pollMs ?? 50
+  );
+  if (graceful.terminated || graceful.error) return graceful;
+
+  return signalAndWait(
+    pid,
+    ownership,
+    'SIGKILL',
+    options.hardKillWaitMs ?? 1000,
+    options.pollMs ?? 50
+  );
+}