@relayflows/sdk 2.0.9 → 2.0.10

package/src/worker-cli.ts

@@ -1,14 +1,25 @@
+import { decodeProviderResult, decodeWrapperResult, requirePricedUsage } from './worker-usage.js';
+import { openSidechannel, type SidechannelContext } from './pty-sidechannel.js';
 import { spawn } from 'node:child_process';
+import { childStop, ownsProcessGroup } from './child-stop.js';
 import {
   agentExecution,
+  llmExecution,
   cliAdapterKind,
   type CliInvocation,
+  type CliAdapterKind,
 } from './cli-adapter.js';
 import {
   runWrapperSession,
   type WrapperSessionLimits,
 } from './wrapper-session.js';
 import { wrapperEnvironment } from './wrapper-runtime.js';
+import {
+  agentRelaySpawn,
+  deriveAgentName,
+  AgentRelayTransportError,
+  type AgentTransport,
+} from './agent-relay-transport.js';
 
 /** Present only when a dispatched agent step carries a journaled wake context. */
 export const WAKE_CONTEXT_ENV = 'RELAYFLOW_WAKE_CONTEXT';
@@ -21,35 +32,61 @@ export const WAKE_CONTEXT_ENV = 'RELAYFLOW_WAKE_CONTEXT';
 export const MODEL_ENV = 'RELAYFLOW_MODEL';
 
 export interface WorkerCliResult {
+  tokens_input?: number;
+  tokens_output?: number;
   exit_code: number | null;
   stdout_tail: string;
   stderr_tail: string;
 }
 
+/**
+ * Optional identity threaded through so the relay transport can derive a
+ * stable, DM-addressable agent name (flows#385).
+ */
+export interface AgentRelayContext {
+  runId: string;
+  stepId: string;
+}
+
 export async function runAgentCli(
   cli: string,
   instruction: string,
   wakeContext: unknown,
   model?: string,
   wrapperLimits?: Partial<WrapperSessionLimits>,
+  signal?: AbortSignal,
+  mode: 'agent' | 'llm' = 'agent',
+  sidechannel?: SidechannelContext,
+  cwd?: string,
+  transport: AgentTransport = 'direct',
+  relayContext?: AgentRelayContext,
 ): Promise<WorkerCliResult> {
+  signal?.throwIfAborted();
+  if (signal !== undefined && process.platform === 'win32') {
+    throw new Error('Lease-bound agent execution requires macOS or Linux process-group cancellation; Windows is unsupported.');
+  }
   const kind = cliAdapterKind(cli);
 
   if (kind === 'relayflows-wrapper-v1') {
-    return runWrapperSession(
+    return requirePricedUsage(decodeWrapperResult(await runWrapperSession(
       cli,
       instruction,
       wakeContext,
       model,
       wrapperEnvironment(process.env),
       wrapperLimits,
-    );
+      signal,
+    )), model);
+  }
+
+  if (mode === 'agent' && transport === 'relay') {
+    return runViaAgentRelay(kind, instruction, model, relayContext, cwd);
   }
 
   const env: NodeJS.ProcessEnv = { ...process.env };
   delete env[WAKE_CONTEXT_ENV];
   delete env[MODEL_ENV];
-  const invocation = agentExecution(kind, instruction, model);
+  const invocation = mode === 'llm' ? llmExecution(kind, instruction, model) : agentExecution(kind, instruction, model);
 
   if (wakeContext !== undefined) {
     try {
@@ -64,16 +101,100 @@ export async function runAgentCli(
   }
 
   if (invocation.modelEnv !== undefined) env[MODEL_ENV] = invocation.modelEnv;
-  return spawnInvocation(cli, invocation, env);
+  // Structured provider output carries the authoritative token counts.
+  const args = [...invocation.args];
+  args.splice(args.length - 1, 0, ...(kind === 'claude' ? ['--output-format', 'json'] : ['--json']));
+  return requirePricedUsage(decodeProviderResult(await spawnInvocation(cli, { ...invocation, args }, env, signal, sidechannel, cwd), kind), model);
 }
 
-function spawnInvocation(
+/**
+ * Relay-transport path (flows#385). Fires an agent-relay spawn HTTP request
+ * that registers the CLI as a first-class workspace participant DMs can
+ * steer, then reports the spawn outcome as a WorkerCliResult. Streaming
+ * completion tracking is a follow-up — this initial slice proves the
+ * transport wire and returns quickly with the registered name in stdout.
+ */
+async function runViaAgentRelay(
+  kind: CliAdapterKind,
+  instruction: string,
+  model: string | undefined,
+  relayContext: AgentRelayContext | undefined,
+  worker_cwd: string | undefined,
+): Promise<WorkerCliResult> {
+  if (kind === 'relayflows-wrapper-v1') {
+    return {
+      exit_code: null,
+      stdout_tail: '',
+      stderr_tail: 'agent-relay transport does not support the relayflows-wrapper-v1 same-process session.',
+    };
+  }
+  if (relayContext === undefined) {
+    return {
+      exit_code: null,
+      stdout_tail: '',
+      stderr_tail: 'agent-relay transport requires a relayContext (runId, stepId); the caller did not thread it through.',
+    };
+  }
+  const name = deriveAgentName(relayContext.runId, relayContext.stepId);
+  try {
+    const handle = await agentRelaySpawn({
+      name,
+      cli: kind,
+      task: instruction,
+      ...(model === undefined ? {} : { model }),
+      ...(worker_cwd === undefined ? {} : { worker_cwd }),
+    });
+    return {
+      exit_code: 0,
+      stdout_tail: JSON.stringify({ registeredName: handle.registeredName, invocationId: handle.invocationId }),
+      stderr_tail: '',
+    };
+  } catch (error) {
+    const detail = error instanceof AgentRelayTransportError
+      ? error.message
+      : `agent-relay spawn failed: ${(error as Error).message ?? String(error)}`;
+    return { exit_code: null, stdout_tail: '', stderr_tail: detail };
+  }
+}
+
+async function spawnInvocation(
   cli: string,
   invocation: CliInvocation,
   env: NodeJS.ProcessEnv,
+  signal?: AbortSignal,
+  sidechannel?: SidechannelContext,
+  cwd?: string,
 ): Promise<WorkerCliResult> {
+  let writeInput: (bytes: Buffer) => Promise<boolean> = async () => false;
+  let canDrive = () => false;
+  let driven = false;
+  const channel = sidechannel === undefined ? undefined : await openSidechannel({
+    ...sidechannel,
+    onDrive() { driven = true; sidechannel.onDrive(); },
+  }, bytes => writeInput(bytes), () => canDrive());
+  if (signal?.aborted) { channel?.close(); signal.throwIfAborted(); }
   return new Promise((resolve) => {
-    const child = spawn(cli, invocation.args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+    const ownsGroup = ownsProcessGroup(signal);
+    const child = spawn(cli, invocation.args, {
+      stdio: ['pipe', 'pipe', 'pipe'], env,
+      detached: ownsGroup,
+      ...(cwd === undefined ? {} : { cwd }),
+    });
+    child.stdin.on('error', () => {});
+    if (channel === undefined) child.stdin.end();
+    canDrive = () => !child.stdin.destroyed && !child.stdin.writableEnded;
+    // A pipe cannot be reopened after EOF. Give startup subscribers a bounded
+    // chance to opt into drive, then let unattended/view-only CLIs read EOF.
+    const inputTimer = channel === undefined ? undefined : setTimeout(() => {
+      if (!driven) child.stdin.end();
+    }, 100);
+    writeInput = bytes => new Promise(resolve => {
+      if (!canDrive()) { resolve(false); return; }
+      // write(false) still accepts the bytes. The completion callback waits
+      // until they flush; the sidechannel pauses its reader in the meantime.
+      child.stdin.write(bytes, error => resolve(!error));
+    });
+    const stop = childStop(child, ownsGroup);
     const stdout: Buffer[] = [];
     const stderr: Buffer[] = [];
     let settled = false;
@@ -81,24 +202,48 @@ function spawnInvocation(
     const finish = (result: WorkerCliResult): void => {
       if (settled) return;
       settled = true;
+      if (inputTimer !== undefined) clearTimeout(inputTimer);
+      channel?.close();
       if (timer !== undefined) clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
       resolve(result);
     };
-    child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
-    child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
-    child.once('error', (error) => finish({
+    const onAbort = (): void => {
+      stop.kill();
+      finish({ exit_code: null, stdout_tail: '', stderr_tail: 'Agent execution aborted: lease ownership lost.' });
+    };
+    /**
+     * Same invariant as `wrapper-session.ts`: `'close'` and `'error'` are
+     * evidence about the DIRECT CHILD, so they may not settle over a pending
+     * escalation, and only `maySettleOnChildExit` may drop one. This settle
+     * carries no deadline of its own because it needs none — the timeout below
+     * settles on the spot and lets its escalation outlive that, so refusing
+     * here can only defer to a `'close'` we are still going to get.
+     */
+    const finishOnChildExit = (result: WorkerCliResult): void => {
+      if (!stop.maySettleOnChildExit()) return;
+      finish(result);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    child.stdout.on('data', (chunk: Buffer) => { stdout.push(chunk); channel?.publish(chunk); });
+    child.stderr.on('data', (chunk: Buffer) => { stderr.push(chunk); channel?.publish(chunk); });
+    child.once('error', (error) => finishOnChildExit({
       exit_code: null,
       stdout_tail: Buffer.concat(stdout).toString('utf8'),
       stderr_tail: error.message,
     }));
-    child.once('close', (code) => finish({
+    child.once('close', (code) => finishOnChildExit({
       exit_code: code,
       stdout_tail: Buffer.concat(stdout).toString('utf8'),
       stderr_tail: Buffer.concat(stderr).toString('utf8'),
     }));
     if (invocation.timeoutMs > 0) {
       timer = setTimeout(() => {
-        child.kill('SIGTERM');
+        // The stop outlives this settle on purpose: `finish` resolves the step,
+        // but only the forced group kill releases the pipes a leaked descendant
+        // is holding, and until they are released `flows run` cannot exit.
+        stop.terminate();
         finish({
           exit_code: null,
           stdout_tail: Buffer.concat(stdout).toString('utf8'),

package/src/worker-input.ts

@@ -0,0 +1,15 @@
+import type { StepDispatchEvent } from './protocol.js';
+
+/** Memory precedes the final, visibly delimited JSON input segment. */
+export function workerInstruction(instruction: string, dispatch: StepDispatchEvent): string {
+  const withMemory = dispatch.memory === undefined ? instruction
+    : `${instruction}\n\nMemory context (journaled):\n${JSON.stringify(dispatch.memory.pack)}`;
+  if (dispatch.input === undefined) {
+    if (typeof dispatch.spec === 'object' && dispatch.spec !== null
+      && 'input' in dispatch.spec) {
+      throw new Error('Step declares input bindings but the kernel did not resolve them; upgrade relayflowd.');
+    }
+    return withMemory;
+  }
+  return `${withMemory}\n\ninput:\n${JSON.stringify(dispatch.input)}`;
+}

package/src/worker-lease.ts

@@ -0,0 +1,85 @@
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+
+/** Hold the dispatched lease only while its subprocess is still ours to run. */
+export async function withWorkerLease<T>(
+  client: JournalClient,
+  dispatch: StepDispatchEvent,
+  execute: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  const controller = new AbortController();
+  let stopped = false;
+  let latestDeadline = dispatch.lease_deadline_ms;
+  let renewalTimer: NodeJS.Timeout | undefined;
+  let expiryTimer: NodeJS.Timeout | undefined;
+  let pending: Promise<void> = Promise.resolve();
+  const fail = (error: unknown): void => { controller.abort(error); };
+  const armExpiry = (deadline: number): number => {
+    const remaining = deadline - Date.now();
+    if (!Number.isFinite(remaining) || remaining <= 0) {
+      throw new Error(`Agent lease is already expired for ${dispatch.run_id}/${dispatch.step_id}.`);
+    }
+    latestDeadline = deadline;
+    if (expiryTimer !== undefined) clearTimeout(expiryTimer);
+    expiryTimer = setTimeout(() => fail(new Error(
+      `Agent lease expired before renewal for ${dispatch.run_id}/${dispatch.step_id}.`,
+    )), remaining);
+    return remaining;
+  };
+  const renew = async (): Promise<void> => {
+    const result = await untilAborted(client.stepHeartbeat(
+      dispatch.run_id, dispatch.step_id, dispatch.attempt, dispatch.lease_id,
+    ), controller.signal);
+    controller.signal.throwIfAborted();
+    // A response handled after local expiry cannot revive ownership, even
+    // if its future deadline was issued before this event loop stalled.
+    if (Date.now() >= latestDeadline) {
+      throw new Error(`Agent lease expired before renewal for ${dispatch.run_id}/${dispatch.step_id}.`);
+    }
+    const remaining = armExpiry(result.lease_deadline_ms);
+    if (!stopped) {
+      renewalTimer = setTimeout(() => {
+        pending = renew().catch(fail);
+      }, Math.max(1, Math.floor(remaining / 3)));
+    }
+  };
+  try {
+    armExpiry(dispatch.lease_deadline_ms);
+    // Establish ownership before starting an effectful process.
+    await renew();
+    const result = await execute(controller.signal);
+    stopped = true;
+    if (renewalTimer !== undefined) clearTimeout(renewalTimer);
+    // Drain any renewal before the caller sends step.complete. A renewal
+    // racing after completion would otherwise report a spurious lease error.
+    await pending;
+    controller.signal.throwIfAborted();
+    // Timer callbacks can be delayed behind a resolved subprocess promise.
+    // Check the clock itself before permitting step.complete.
+    if (Date.now() >= latestDeadline) {
+      throw new Error(`Agent lease expired before completion for ${dispatch.run_id}/${dispatch.step_id}.`);
+    }
+    return result;
+  } finally {
+    stopped = true;
+    controller.abort(new Error('Worker lease scope ended.'));
+    if (renewalTimer !== undefined) clearTimeout(renewalTimer);
+    if (expiryTimer !== undefined) clearTimeout(expiryTimer);
+    await pending;
+  }
+}
+
+function untilAborted<T>(request: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = (): void => { reject(signal.reason); };
+    signal.addEventListener('abort', abort, { once: true });
+    request.then(value => {
+      signal.removeEventListener('abort', abort);
+      resolve(value);
+    }, error => {
+      signal.removeEventListener('abort', abort);
+      reject(error);
+    });
+    if (signal.aborted) abort();
+  });
+}

package/src/worker-spend.ts

@@ -0,0 +1,23 @@
+import { pricedUsage } from './model-pricing.js';
+import type { WorkerCliResult } from './worker-cli.js';
+
+/**
+ * Attach token/dollar usage to a worker's CLI result. Invalid token counts
+ * (non-integer or negative) are the one remaining failure mode — those are
+ * journaled as `worker_error` with the usage projected from clamped counts.
+ *
+ * Unpriced models are NOT a failure here: `pricedUsage` returns
+ * `dollars: null` and preflight (see `budgetDiagnostics`) has already refused
+ * declared dollar budgets against unpriced models before the CLI dispatched.
+ */
+export function workerSpend(result: WorkerCliResult, model?: string) {
+  try { return { result, usage: pricedUsage(model, result.tokens_input, result.tokens_output) }; }
+  catch (error) {
+    return {
+      result: { ...result, exit_code: null, stderr_tail: error instanceof Error ? error.message : 'Invalid model usage' },
+      usage: pricedUsage(undefined,
+        Number.isSafeInteger(result.tokens_input) && result.tokens_input! >= 0 ? result.tokens_input : 0,
+        Number.isSafeInteger(result.tokens_output) && result.tokens_output! >= 0 ? result.tokens_output : 0),
+    };
+  }
+}

package/src/worker-usage.ts

@@ -0,0 +1,48 @@
+import type { WorkerCliResult } from './worker-cli.js';
+import { MODEL_PRICING } from './model-pricing.js';
+
+type RecordValue = Record<string, unknown>;
+const record = (value: unknown): value is RecordValue => typeof value === 'object' && value !== null && !Array.isArray(value);
+const count = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+function invalid(result: WorkerCliResult, detail: string): WorkerCliResult {
+  return { ...result, exit_code: null, stderr_tail: `${result.stderr_tail}\n${detail}`.trim() };
+}
+
+function usageResult(result: WorkerCliResult, usage: unknown, output: unknown): WorkerCliResult {
+  if (output === undefined) return invalid(result, 'Provider completion is missing its output.');
+  if (!record(usage) || !count(usage.input_tokens) || !count(usage.output_tokens)) {
+    return invalid(result, 'Provider completion has invalid token usage.');
+  }
+  return { ...result, stdout_tail: typeof output === 'string' ? output : JSON.stringify(output),
+    tokens_input: usage.input_tokens, tokens_output: usage.output_tokens };
+}
+
+/** Provider envelopes are execution metadata, never the authored output. */
+export function decodeProviderResult(result: WorkerCliResult, kind: 'claude' | 'codex'): WorkerCliResult {
+  const frames: RecordValue[] = [];
+  for (const line of result.stdout_tail.split('\n')) {
+    try { const frame: unknown = JSON.parse(line); if (record(frame)) frames.push(frame); } catch { /* Plain text remains output. */ }
+  }
+  const terminal = [...frames].reverse().find(f => kind === 'claude' ? f.type === 'result' : f.type === 'turn.completed');
+  if (terminal === undefined) return result;
+  const text = kind === 'claude' ? terminal.result : frames
+    .flatMap(f => f.type === 'item.completed' && record(f.item) && f.item.type === 'agent_message' && typeof f.item.text === 'string' ? [f.item.text] : []).join('\n');
+  return usageResult(result, terminal.usage, text);
+}
+
+/** Optional wrapper result envelope; existing opaque text output stays valid. */
+export function decodeWrapperResult(result: WorkerCliResult): WorkerCliResult {
+  let value: unknown;
+  try { value = JSON.parse(result.stdout_tail); } catch { return result; }
+  if (!record(value) || value.protocol !== 'relayflows-agent-cli-v1-result') return result;
+  return usageResult(result, value.usage, value.output);
+}
+
+export function requirePricedUsage(result: WorkerCliResult, model?: string): WorkerCliResult {
+  if (model !== undefined && Object.hasOwn(MODEL_PRICING, model)
+      && (result.tokens_input === undefined || result.tokens_output === undefined)) {
+    return invalid(result, 'Priced model completion is missing token usage.');
+  }
+  return result;
+}

package/src/worker.ts

@@ -1,8 +1,14 @@
+import { workerSpend } from './worker-spend.js';
+import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
 import type { JournalClient } from './journal-client.js';
 import type { Pins, StepDispatchEvent } from './protocol.js';
 import type { KernelAgentStep } from './spec.js';
 import { runAgentCli } from './worker-cli.js';
+import { withWorkerLease } from './worker-lease.js';
+import { workerInstruction } from './worker-input.js';
+import { helperCall } from './yaml-helpers.js';
+import { completeHelperDispatch } from './yaml-helper-effect.js';
 
 export { MODEL_ENV, WAKE_CONTEXT_ENV } from './worker-cli.js';
 
@@ -10,6 +16,8 @@ export interface AgentWorkerOptions {
   workerId: string;
   pins: Pins;
   capacity?: number;
+  dataDir?: string;
+  onPtyReady?: (path: string) => void;
 }
 
 /**
@@ -90,9 +98,23 @@ export class AgentWorker extends EventEmitter {
 
   private async execute(dispatch: StepDispatchEvent): Promise<void> {
     const spec = dispatch.spec as Partial<KernelAgentStep>;
-    const result = typeof spec.cli === 'string' && typeof spec.instruction === 'string'
-      ? await runAgentCli(spec.cli, memoryInstruction(spec.instruction, dispatch.memory), dispatch.wake_context, spec.model)
-      : { exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' };
+    const helper = helperCall(spec);
+    if (helper !== undefined) {
+      if (this.options.dataDir === undefined) throw new Error('Helper worker requires a data directory for durable receipts');
+      await completeHelperDispatch(this.client, dispatch, helper, this.options.dataDir);
+      return;
+    }
+    let humanIntervention = false;
+    const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
+      typeof spec.cli === 'string' && typeof spec.instruction === 'string'
+        ? runAgentCli(spec.cli, workerInstruction(spec.instruction, dispatch), dispatch.wake_context, spec.model, undefined, signal, 'agent', this.options.dataDir === undefined ? undefined : {
+          dataDir: this.options.dataDir, runId: dispatch.run_id, stepId: dispatch.step_id,
+          onReady: this.options.onPtyReady, onDrive: () => { humanIntervention = true; },
+        }, typeof spec.cwd === 'string' ? spec.cwd : undefined,
+          spec.transport === 'relay' ? 'relay' : 'direct',
+          { runId: dispatch.run_id, stepId: dispatch.step_id })
+        : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'agent step has no declared CLI' }));
+    const { result, usage } = workerSpend(completed, spec.model);
     const completionReason = result.exit_code === 0 ? 'success' : 'worker_error';
 
     // Output shape: if the CLI's stdout parses as JSON, promote THAT
@@ -118,6 +140,8 @@ export class AgentWorker extends EventEmitter {
       completionReason,
       {
         output,
+        ...(humanIntervention ? { human_intervention: true } : {}),
+        ...(usage !== undefined ? { usage } : {}),
         started_pins: dispatch.pins,
         end_pins: dispatch.pins,
       },
@@ -148,9 +172,3 @@ export function parseJsonOutput(stdout: string): Record<string, unknown> | null
   }
   return parsed as Record<string, unknown>;
 }
-
-/** Pass the journaled pack to both raw CLI and wrapper execution paths. */
-function memoryInstruction(instruction: string, memory: StepDispatchEvent['memory']): string {
-  return memory === undefined ? instruction
-    : `${instruction}\n\nMemory context (journaled):\n${JSON.stringify(memory.pack)}`;
-}

package/src/wrapper-session.ts

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { FORCE_KILL_DELAY_MS, childStop, ownsProcessGroup } from './child-stop.js';
 import {
   WRAPPER_EXECUTE_TOKEN,
   WRAPPER_IDENTIFY_ARG,
@@ -28,7 +29,6 @@ const DEFAULT_LIMITS: WrapperSessionLimits = {
   maxOutputBytes: 1_048_576,
 };
 const HANDSHAKE_OUTPUT_LIMIT = 8_192;
-const FORCE_KILL_DELAY_MS = 1_000;
 /**
  * Grace after `SIGKILL` before the reader settles on its own. Node emits
  * `'close'` only once every inherited stdio pipe is closed, which any
@@ -48,7 +48,12 @@ export function runWrapperSession(
   model: string | undefined,
   env: NodeJS.ProcessEnv,
   overrides: Partial<WrapperSessionLimits> = {},
+  signal?: AbortSignal,
 ): Promise<WrapperSessionResult> {
+  if (signal?.aborted) return Promise.reject(signal.reason);
+  if (signal !== undefined && process.platform === 'win32') {
+    return Promise.reject(new Error('Lease-bound wrapper execution requires macOS or Linux process-group cancellation; Windows is unsupported.'));
+  }
   const limits = sessionLimits(overrides);
   let request: string;
   try {
@@ -72,7 +77,7 @@ export function runWrapperSession(
     ));
   }
 
-  return executePinnedWrapper(cli, identity, request, env, limits);
+  return executePinnedWrapper(cli, identity, request, env, limits, signal);
 }
 
 function executePinnedWrapper(
@@ -81,12 +86,16 @@ function executePinnedWrapper(
   request: string,
   env: NodeJS.ProcessEnv,
   limits: WrapperSessionLimits,
+  signal?: AbortSignal,
 ): Promise<WrapperSessionResult> {
   return new Promise((resolve) => {
+    const ownsGroup = ownsProcessGroup(signal);
     const child = spawn(identity.executable, [WRAPPER_IDENTIFY_ARG], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env,
+      detached: ownsGroup,
     });
+    const stop = childStop(child, ownsGroup);
     const stdout: string[] = [];
     const stderr: Buffer[] = [];
     let handshakePending = '';
@@ -96,27 +105,53 @@ function executePinnedWrapper(
     let protocolError: string | undefined;
     let settled = false;
     let lifecycleTimer: NodeJS.Timeout | undefined;
-    let killTimer: NodeJS.Timeout | undefined;
     let settleTimer: NodeJS.Timeout | undefined;
 
-    const clearTimers = (): void => {
-      if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
-      if (killTimer !== undefined) clearTimeout(killTimer);
-      if (settleTimer !== undefined) clearTimeout(settleTimer);
-    };
     const finish = (result: WrapperSessionResult): void => {
       if (settled) return;
       settled = true;
-      clearTimers();
+      if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
+      if (settleTimer !== undefined) clearTimeout(settleTimer);
+      signal?.removeEventListener('abort', onAbort);
       resolve(result);
     };
+    /**
+     * INVARIANT: a session may not settle until either the process group is
+     * confirmed dead or the escalation has actually run.
+     *
+     * `'close'` and `'error'` are evidence about the DIRECT CHILD and nothing
+     * more. A descendant that ignores `SIGTERM` and inherited none of the
+     * wrapper's stdio emits exactly those events while it is still running, so
+     * neither may drop a pending escalation and neither may settle ahead of
+     * one. Every child-level settle therefore goes through
+     * `maySettleOnChildExit`, which is the one place that asks the GROUP.
+     *
+     * When it says no, `terminate`'s own deadline settles instead, with a
+     * byte-identical `failure(protocolError)` result. That deadline is armed
+     * whenever an escalation is — both come from the single `terminate` below —
+     * so refusing here can defer a settle but can never strand one.
+     */
+    const finishOnChildExit = (result: WrapperSessionResult): void => {
+      // Asked before `finish`, and asked even once we have already settled:
+      // this is also the only place a pointless escalation is refunded, and a
+      // session that settled on `terminate`'s deadline still owes that refund.
+      if (!stop.maySettleOnChildExit()) return;
+      finish(result);
+    };
+    const onAbort = (): void => {
+      stop.kill();
+      finish(failure('Agent execution aborted: lease ownership lost.'));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) { onAbort(); return; }
     const terminate = (message: string): void => {
       if (protocolError !== undefined) return;
       protocolError = message;
       if (lifecycleTimer !== undefined) clearTimeout(lifecycleTimer);
-      child.kill('SIGTERM');
-      killTimer = setTimeout(() => child.kill('SIGKILL'), FORCE_KILL_DELAY_MS);
-      killTimer.unref();
+      // Same reach as an abort, only gentler first: this stop must find the
+      // whole group, or a descendant outlives the session still holding the
+      // stdio it inherited.
+      stop.terminate();
       // The reader owns the bound. `'close'` is emitted only after every
       // inherited stdio pipe closes, so a wrapper that leaves a descendant
       // holding one withholds it forever and strands the step with no
@@ -241,7 +276,7 @@ function executePinnedWrapper(
     child.stdin.on('error', () => {
       // A child that closes stdin before acknowledgement is classified on close.
     });
-    child.once('error', (error) => finish(failure(error.message)));
+    child.once('error', (error) => finishOnChildExit(failure(error.message)));
     child.once('close', (code) => {
       if (protocolError === undefined && phase === 'execute' && executionPending.length > 0) {
         if (normalizeLine(executionPending) === WRAPPER_EXECUTE_TOKEN) {
@@ -251,13 +286,13 @@ function executePinnedWrapper(
         }
       }
       if (protocolError !== undefined || phase !== 'execute') {
-        finish(failure(
+        finishOnChildExit(failure(
           protocolError
             ?? `CLI ${JSON.stringify(cli)} exited before completing the ${WRAPPER_IDENTIFY_TOKEN} same-process handshake.`,
         ));
         return;
       }
-      finish({
+      finishOnChildExit({
         exit_code: code,
         stdout_tail: stdout.join(''),
         stderr_tail: Buffer.concat(stderr).toString('utf8'),