@relayflows/sdk 2.0.37 → 2.0.39

package/src/flow-extension-loader.ts

@@ -13,7 +13,18 @@ import { pluginStoreDirectory, readStoredPluginFiles } from './plugin-store.js';
 const JSON_PARSE = JSON.parse;
 const ARRAY_IS_ARRAY = Array.isArray;
 const JSON_STRINGIFY = JSON.stringify;
+const NUMBER = Number;
+const NUMBER_IS_FINITE = Number.isFinite.bind(Number);
+const NUMBER_IS_SAFE_INTEGER = Number.isSafeInteger.bind(Number);
+const NUMBER_TO_STRING = Function.prototype.call.bind(Number.prototype.toString) as (
+  value: number,
+) => string;
+const OBJECT_GET_OWN_PROPERTY_DESCRIPTOR = Object.getOwnPropertyDescriptor;
 const OBJECT_FREEZE = Object.freeze;
+const POSITIVE_INFINITY = Number.POSITIVE_INFINITY;
+const REGEXP_EXEC = Function.prototype.call.bind(RegExp.prototype.exec) as (
+  regexp: RegExp, value: string,
+) => RegExpExecArray | null;
 const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
   regexp: RegExp, value: string,
 ) => boolean;
@@ -74,12 +85,111 @@ export interface LoadFlowExtensionsOptions<Authority> {
 
 const EXTENSION_HEADER_FIELDS = new Set(['budget', 'tools']);
 const WALLCLOCK_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+type StructuredFlowBudget = Exclude<NonNullable<AuthoredFlowDefinition['header']['budget']>, string>;
+
+function ownBudgetField<K extends keyof StructuredFlowBudget>(
+  budget: StructuredFlowBudget,
+  field: K,
+): StructuredFlowBudget[K] | undefined {
+  const descriptor = OBJECT_GET_OWN_PROPERTY_DESCRIPTOR(budget, field);
+  return descriptor !== undefined && 'value' in descriptor
+    ? descriptor.value as StructuredFlowBudget[K]
+    : undefined;
+}
 
 function wallclockMs(value: string): number | undefined {
-  const match = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+  const match = REGEXP_EXEC(/^(\d+)(ms|s|m|h|d)$/, value);
   if (!match) return undefined;
   const unit = match[2] as keyof typeof WALLCLOCK_MS;
-  return Number(match[1]) * WALLCLOCK_MS[unit];
+  const milliseconds = NUMBER(match[1]) * WALLCLOCK_MS[unit];
+  return NUMBER_IS_FINITE(milliseconds) ? milliseconds : undefined;
+}
+
+function hasBudgetCeiling(budget: StructuredFlowBudget): boolean {
+  return ownBudgetField(budget, 'tokens') !== undefined
+    || ownBudgetField(budget, 'dollars') !== undefined
+    || ownBudgetField(budget, 'wallclock') !== undefined;
+}
+
+function validateStructuredBudget(budget: StructuredFlowBudget): void {
+  const tokens = ownBudgetField(budget, 'tokens');
+  if (tokens !== undefined && (!NUMBER_IS_SAFE_INTEGER(tokens) || tokens < 0)) {
+    throw new PluginError('plugin_incompatible', `Malformed token budget ceiling ${JSON_STRINGIFY(tokens)}.`);
+  }
+  const dollars = ownBudgetField(budget, 'dollars');
+  if (dollars !== undefined && (!NUMBER_IS_FINITE(dollars) || dollars < 0
+    || REGEXP_EXEC(/^\d+(?:\.\d{1,6})?$/, NUMBER_TO_STRING(dollars)) === null)) {
+    throw new PluginError('plugin_incompatible', `Malformed dollar budget ceiling ${JSON_STRINGIFY(dollars)}.`);
+  }
+}
+
+function composeBudget(
+  base: AuthoredFlowDefinition['header']['budget'],
+  extensions: readonly LoadedFlowExtension[],
+): AuthoredFlowDefinition['header']['budget'] {
+  type Budget = NonNullable<AuthoredFlowDefinition['header']['budget']>;
+  type StructuredBudget = Exclude<Budget, string>;
+  const effectiveBase = typeof base === 'object' && !hasBudgetCeiling(base)
+    ? undefined
+    : base;
+  const ceilings: Budget[] = [];
+  for (let index = 0; index < extensions.length; index += 1) {
+    const extension = extensions[index]!;
+    const manifestBudget = extension.manifest.permissions.budget;
+    const entryBudget = extension.getDefinition(extension.handle).header.budget;
+    if (manifestBudget !== undefined
+      && (typeof manifestBudget === 'string' || hasBudgetCeiling(manifestBudget))) {
+      appendIntrinsicArray(ceilings, manifestBudget);
+    }
+    if (entryBudget !== undefined
+      && (typeof entryBudget === 'string' || hasBudgetCeiling(entryBudget))) {
+      appendIntrinsicArray(ceilings, entryBudget);
+    }
+  }
+  if (ceilings.length === 0) return base;
+  if (effectiveBase === undefined && ceilings.length === 1 && typeof ceilings[0] === 'string') {
+    return ceilings[0];
+  }
+  let shorthand = typeof effectiveBase === 'string';
+  for (let index = 0; index < ceilings.length; index += 1) {
+    if (typeof ceilings[index] === 'string') shorthand = true;
+  }
+  if (shorthand) {
+    throw new PluginError('plugin_incompatible', 'A shorthand budget cannot compose with structured base-flow or extension budget ceilings.');
+  }
+  const budgets: StructuredBudget[] = [];
+  if (effectiveBase !== undefined) appendIntrinsicArray(budgets, effectiveBase as StructuredBudget);
+  for (let index = 0; index < ceilings.length; index += 1) {
+    appendIntrinsicArray(budgets, ceilings[index] as StructuredBudget);
+  }
+  let tokens: number | undefined;
+  let dollars: number | undefined;
+  let wallclock: string | undefined;
+  let wallclockLimit = POSITIVE_INFINITY;
+  for (let index = 0; index < budgets.length; index += 1) {
+    const budget = budgets[index]!;
+    const budgetTokens = ownBudgetField(budget, 'tokens');
+    const budgetDollars = ownBudgetField(budget, 'dollars');
+    const budgetWallclock = ownBudgetField(budget, 'wallclock');
+    validateStructuredBudget(budget);
+    if (budgetTokens !== undefined && (tokens === undefined || budgetTokens < tokens)) tokens = budgetTokens;
+    if (budgetDollars !== undefined && (dollars === undefined || budgetDollars < dollars)) dollars = budgetDollars;
+    if (budgetWallclock !== undefined) {
+      const candidate = wallclockMs(budgetWallclock);
+      if (candidate === undefined) {
+        throw new PluginError('plugin_incompatible', `Malformed wallclock budget ceiling ${JSON_STRINGIFY(budgetWallclock)}.`);
+      }
+      if (wallclock === undefined || candidate < wallclockLimit) {
+        wallclock = budgetWallclock;
+        wallclockLimit = candidate;
+      }
+    }
+  }
+  return OBJECT_FREEZE({
+    ...(tokens === undefined ? {} : { tokens }),
+    ...(dollars === undefined ? {} : { dollars }),
+    ...(wallclock === undefined ? {} : { wallclock }),
+  });
 }
 
 /** Credentials and servers declared on a flow-extension, probed before the base body starts. */
@@ -253,14 +363,26 @@ async function loadOne<Authority>(
   assertBaseCompatible(manifest, { name: base.definition.name, version: base.definition.header.version });
   const baseBudget = base.definition.header.budget;
   const ceiling = manifest.permissions.budget;
-  if (ceiling?.dollars !== undefined && typeof baseBudget === 'object' && baseBudget.dollars !== undefined && ceiling.dollars > baseBudget.dollars) {
-    throw new PluginError('plugin_incompatible', `${manifest.name} declares a $${ceiling.dollars} budget ceiling above the base flow's $${baseBudget.dollars}.`);
+  if (ceiling !== undefined && hasBudgetCeiling(ceiling) && typeof baseBudget === 'string') {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a structured budget ceiling that cannot compose with the base flow's shorthand budget.`);
   }
-  if (ceiling?.wallclock !== undefined && typeof baseBudget === 'object' && baseBudget.wallclock !== undefined) {
-    const pluginMs = wallclockMs(ceiling.wallclock);
-    const baseMs = wallclockMs(baseBudget.wallclock);
+  const ceilingTokens = ceiling === undefined ? undefined : ownBudgetField(ceiling, 'tokens');
+  const ceilingDollars = ceiling === undefined ? undefined : ownBudgetField(ceiling, 'dollars');
+  const ceilingWallclock = ceiling === undefined ? undefined : ownBudgetField(ceiling, 'wallclock');
+  const baseTokens = typeof baseBudget === 'object' ? ownBudgetField(baseBudget, 'tokens') : undefined;
+  const baseDollars = typeof baseBudget === 'object' ? ownBudgetField(baseBudget, 'dollars') : undefined;
+  const baseWallclock = typeof baseBudget === 'object' ? ownBudgetField(baseBudget, 'wallclock') : undefined;
+  if (ceilingTokens !== undefined && baseTokens !== undefined && ceilingTokens > baseTokens) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceilingTokens}-token budget ceiling above the base flow's ${baseTokens}-token ceiling.`);
+  }
+  if (ceilingDollars !== undefined && baseDollars !== undefined && ceilingDollars > baseDollars) {
+    throw new PluginError('plugin_incompatible', `${manifest.name} declares a $${ceilingDollars} budget ceiling above the base flow's $${baseDollars}.`);
+  }
+  if (ceilingWallclock !== undefined && baseWallclock !== undefined) {
+    const pluginMs = wallclockMs(ceilingWallclock);
+    const baseMs = wallclockMs(baseWallclock);
     if (pluginMs !== undefined && baseMs !== undefined && pluginMs > baseMs) {
-      throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceiling.wallclock} wallclock ceiling above the base flow's ${baseBudget.wallclock}.`);
+      throw new PluginError('plugin_incompatible', `${manifest.name} declares a ${ceilingWallclock} wallclock ceiling above the base flow's ${baseWallclock}.`);
     }
   }
   const entryPath = join(directory, manifest.entry);
@@ -279,7 +401,9 @@ async function loadOne<Authority>(
   if (!manifest.extends.handlers && definition.handlers.length > 0) {
     throw new PluginError('plugin_manifest_invalid', `${manifest.name}: ${manifest.entry} declares handlers but extends.handlers is false.`);
   }
-  definition.handlers.forEach((handler, index) => assertDeclaredSubscription(manifest.name, manifest, handler, index));
+  for (let index = 0; index < definition.handlers.length; index += 1) {
+    assertDeclaredSubscription(manifest.name, manifest, definition.handlers[index]!, index);
+  }
   const hooks = imported.hooks;
   const exported = Object.keys(hooks).sort();
   const declared = [...manifest.extends.hooks].sort();
@@ -292,9 +416,13 @@ async function loadOne<Authority>(
       throw new PluginError('plugin_incompatible', `${manifest.name}: hook ${hook} is not declared by the base flow.`);
     }
   }
-  return Object.freeze({
+  const handlers: TriggerHandler[] = [];
+  for (let index = 0; index < definition.handlers.length; index += 1) {
+    appendIntrinsicArray(handlers, definition.handlers[index]!);
+  }
+  return OBJECT_FREEZE({
     name: manifest.name, version: manifest.version, ref, digest: lock.digest, directory, entryPath, manifest,
-    handle: imported.handle, getDefinition: imported.getDefinition, handlers: Object.freeze([...definition.handlers]),
+    handle: imported.handle, getDefinition: imported.getDefinition, handlers: OBJECT_FREEZE(handlers),
     hooks,
   });
 }
@@ -329,11 +457,23 @@ export async function loadFlowExtensions<Authority>(
   return Object.freeze(loaded);
 }
 
-/** The base definition with extension handlers appended in lock order; the base's own fields are untouched. */
+/** The base definition with extension handlers appended and every declared budget ceiling retained. */
 export function composeDefinition<Input>(base: AuthoredFlowDefinition<Input>, extensions: readonly LoadedFlowExtension[]): AuthoredFlowDefinition<Input> {
   if (extensions.length === 0) return base;
-  return Object.freeze({
+  const budget = composeBudget(base.header.budget, extensions);
+  const handlers: TriggerHandler[] = [];
+  for (let index = 0; index < base.handlers.length; index += 1) appendIntrinsicArray(handlers, base.handlers[index]!);
+  for (let extensionIndex = 0; extensionIndex < extensions.length; extensionIndex += 1) {
+    const extensionHandlers = extensions[extensionIndex]!.handlers;
+    for (let handlerIndex = 0; handlerIndex < extensionHandlers.length; handlerIndex += 1) {
+      appendIntrinsicArray(handlers, extensionHandlers[handlerIndex]!);
+    }
+  }
+  return OBJECT_FREEZE({
     ...base,
-    handlers: Object.freeze([...base.handlers, ...extensions.flatMap(extension => extension.handlers)]),
+    header: budget === base.header.budget
+      ? base.header
+      : OBJECT_FREEZE({ ...base.header, budget }),
+    handlers: OBJECT_FREEZE(handlers),
   });
 }

package/src/flow-extension-manifest.ts

@@ -6,6 +6,7 @@ import { PluginError, pluginKindOf } from './plugin-manifest.js';
 import { safePath } from './bundle.js';
 import { SHA, parsePluginSource, type PluginSourceInput } from './plugin-source.js';
 import { isVersionRange, parseVersion } from './semver-range.js';
+import { parseBudget } from './budget.js';
 
 /**
  * Schema 2, `kind: "flow-extension"`: a plugin whose `entry` default-exports
@@ -29,7 +30,7 @@ export interface FlowExtensionPermissions {
   readonly mcp: readonly string[];
   /** Declared effect classes, shown for review; not enforced by this runtime (gate 8 / #442). */
   readonly writes: readonly string[];
-  readonly budget?: { readonly dollars?: number; readonly wallclock?: string };
+  readonly budget?: { readonly tokens?: number; readonly dollars?: number; readonly wallclock?: string };
 }
 export interface FlowExtensionManifest {
   readonly schema: 2;
@@ -117,10 +118,12 @@ function permissions(value: unknown): FlowExtensionPermissions {
   for (const harness of harnesses) if (!(FLOW_HARNESSES as readonly string[]).includes(harness)) return invalid(`permissions.harnesses: unknown harness ${harness}.`);
   let budget: FlowExtensionPermissions['budget'];
   if (value.budget !== undefined) {
-    if (!object(value.budget) || Object.keys(value.budget).some(k => !['dollars', 'wallclock'].includes(k))) return invalid('permissions.budget expects dollars and/or wallclock.');
+    if (!object(value.budget) || Object.keys(value.budget).some(k => !['tokens', 'dollars', 'wallclock'].includes(k))) return invalid('permissions.budget expects tokens, dollars, and/or wallclock.');
+    if (value.budget.tokens !== undefined && (typeof value.budget.tokens !== 'number' || !Number.isSafeInteger(value.budget.tokens) || value.budget.tokens < 0)) return invalid('permissions.budget.tokens must be a non-negative safe integer.');
     if (value.budget.dollars !== undefined && (typeof value.budget.dollars !== 'number' || !(value.budget.dollars > 0) || !Number.isFinite(value.budget.dollars))) return invalid('permissions.budget.dollars must be a positive number.');
     if (value.budget.wallclock !== undefined && (typeof value.budget.wallclock !== 'string' || !WALLCLOCK.test(value.budget.wallclock))) return invalid('permissions.budget.wallclock must be a duration such as 45m.');
-    budget = Object.freeze({ ...(value.budget.dollars === undefined ? {} : { dollars: value.budget.dollars }), ...(value.budget.wallclock === undefined ? {} : { wallclock: value.budget.wallclock }) });
+    try { parseBudget(value.budget); } catch { return invalid('permissions.budget must use runtime budget syntax.'); }
+    budget = Object.freeze({ ...(value.budget.tokens === undefined ? {} : { tokens: value.budget.tokens }), ...(value.budget.dollars === undefined ? {} : { dollars: value.budget.dollars }), ...(value.budget.wallclock === undefined ? {} : { wallclock: value.budget.wallclock }) });
   }
   return Object.freeze({
     integrations: stringList(value.integrations, 'permissions.integrations', PROVIDER),

package/src/hosted-extension-manifest.ts

@@ -12,6 +12,7 @@ import { PluginError } from './plugin-manifest.js';
 
 const ARRAY_IS_ARRAY = Array.isArray;
 const NUMBER_IS_FINITE = Number.isFinite;
+const NUMBER_IS_SAFE_INTEGER = Number.isSafeInteger;
 const OBJECT_CREATE = Object.create;
 const OBJECT_FREEZE = Object.freeze;
 const OBJECT_HAS_OWN = Object.hasOwn;
@@ -20,6 +21,10 @@ const REGEXP_TEST = Function.prototype.call.bind(RegExp.prototype.test) as (
   regexp: RegExp,
   value: string,
 ) => boolean;
+const REGEXP_EXEC = Function.prototype.call.bind(RegExp.prototype.exec) as (
+  regexp: RegExp,
+  value: string,
+) => RegExpExecArray | null;
 const STRING_ENDS_WITH = Function.prototype.call.bind(String.prototype.endsWith) as (
   value: string,
   search: string,
@@ -38,7 +43,8 @@ const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const PROVIDER = /^[a-z0-9][a-z0-9-]{0,63}$/;
 const WRITE_CLASS = /^[a-z0-9-]+(?::[a-z0-9_-]+)+$/;
-const WALLCLOCK = /^\d+(?:ms|s|m|h|d)$/;
+const DOLLARS = /^\d+(?:\.\d{1,6})?$/;
+const WALLCLOCK = /^(\d+)(ms|s|m|h|d)$/;
 const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
 const VERSION_RANGE = /^(?:\*|(?:[\^~]|>=)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?: <\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)?)$/;
 const MAX_DESCRIPTION = 500;
@@ -168,19 +174,36 @@ function permissionsShape(value: unknown): FlowExtensionPermissions {
   }
   let budget: FlowExtensionPermissions['budget'];
   if (value.budget !== undefined) {
-    if (!record(value.budget) || !hasOnlyKeys(value.budget, ['dollars', 'wallclock'])) {
-      return invalid('permissions.budget expects dollars and/or wallclock.');
+    if (!record(value.budget) || !hasOnlyKeys(value.budget, ['tokens', 'dollars', 'wallclock'])) {
+      return invalid('permissions.budget expects tokens, dollars, and/or wallclock.');
+    }
+    if (value.budget.tokens !== undefined
+      && (typeof value.budget.tokens !== 'number'
+        || !NUMBER_IS_SAFE_INTEGER(value.budget.tokens) || value.budget.tokens < 0)) {
+      return invalid('permissions.budget.tokens must be a non-negative safe integer.');
     }
     if (value.budget.dollars !== undefined
       && (typeof value.budget.dollars !== 'number' || value.budget.dollars <= 0
-        || !NUMBER_IS_FINITE(value.budget.dollars))) {
+        || !NUMBER_IS_FINITE(value.budget.dollars)
+        || !matches(DOLLARS, `${value.budget.dollars}`))) {
       return invalid('permissions.budget.dollars must be a positive number.');
     }
     if (value.budget.wallclock !== undefined
       && (typeof value.budget.wallclock !== 'string' || !matches(WALLCLOCK, value.budget.wallclock))) {
       return invalid('permissions.budget.wallclock must be a duration such as 45m.');
     }
-    const projected = OBJECT_CREATE(null) as { dollars?: number; wallclock?: string };
+    if (value.budget.wallclock !== undefined) {
+      const match = REGEXP_EXEC(WALLCLOCK, value.budget.wallclock)!;
+      const multiplier = match[2] === 'ms' ? 1
+        : match[2] === 's' ? 1_000
+        : match[2] === 'm' ? 60_000
+        : match[2] === 'h' ? 3_600_000 : 86_400_000;
+      if (!NUMBER_IS_SAFE_INTEGER(+match[1]! * multiplier)) {
+        return invalid('permissions.budget.wallclock must fit the runtime duration range.');
+      }
+    }
+    const projected = OBJECT_CREATE(null) as { tokens?: number; dollars?: number; wallclock?: string };
+    if (value.budget.tokens !== undefined) projected.tokens = value.budget.tokens;
     if (value.budget.dollars !== undefined) projected.dollars = value.budget.dollars;
     if (value.budget.wallclock !== undefined) projected.wallclock = value.budget.wallclock;
     budget = OBJECT_FREEZE(projected);

package/src/hosted-extension-runtime.ts

@@ -26,7 +26,7 @@ const REALPATH = realpath;
 const PATH_DIRNAME = dirname;
 const PATH_JOIN = join;
 const PATH_RESOLVE = resolve;
-const SOFTWARE_FACTORY_SHA256 = '8bbcf0e42f47d6bc6491a129935f96b791be03c8a5ed5b73d651c4e77913e2d7';
+const SOFTWARE_FACTORY_SHA256 = '4339c0c45a4fc928092a3e32275c061000887ed95acdc2f898966c35aca91a2d';
 const ARRAY_IS_ARRAY = Array.isArray;
 const OBJECT_FREEZE = Object.freeze;
 const WEAK_MAP_GET = Function.prototype.call.bind(WeakMap.prototype.get) as <K extends object, V>(

package/src/hosted-extension-sandbox.ts

@@ -124,11 +124,11 @@ const NODE_EXECUTABLE = captureNodeExecutable();
 const ADDRESS_SPACE_BYTES = 16 * 1024 * 1024 * 1024;
 const DATA_BYTES = 3 * 1024 * 1024 * 1024;
 const SURFACE_RUNTIME_SHA256 = OBJECT_FREEZE({
-  'flow.js': '4aaeacc55de3074f4d121ce7253c3be50a93757e6540ba8159889a9450d1c05c',
+  'flow.js': '2ba972849bf435bba36b918c348efeab71ec34d180cec7a722e535f482687a6a',
   'helpers/providers.js': '4eb06d0d85ca0a3434bb2dbba7407e3d95eef2dfbedaeb0e2de0c0c0ea812457',
   'provider-trigger.js': 'e2664c65397f93fb486eb6f1e756c7cec3f88b3851d79c23567cad986f80f1ff',
   'schedule.js': '8fe72f176a75ec0b5f26e12db7a597575c259a2e2cbb59690f9dc20a5e63940b',
-  'triggers.js': '4a3515b571a318f6c7a5661f9310bc9af43e3faf20ea39903a9b363c51258e4c',
+  'triggers.js': '421609a6ea6d2ea77051dd4826a32e773b7db81dedd1dde91f4187b382cd46e3',
   'triggers/github.js': 'e312994320f82aad0af00d09c504175d929cc6c601dfe1bc522632462ad9a48b',
 });
 const SURFACE_PACKAGE_JSON = '{"name":"@relayflows/surface","type":"module","exports":{".":"./index.js","./runtime":"./runtime.js"}}';

package/src/llm-worker.ts

@@ -5,7 +5,7 @@ import type { WorkerCliResult } from './worker-cli.js';
 import { EventEmitter } from 'node:events';
 import type { JournalClient } from './journal-client.js';
 import type { CompletionReason, StepDispatchEvent } from './protocol.js';
-import type { KernelLlmStep } from './spec.js';
+import type { ResolvedKernelLlmStep } from './resolved-cli-identity.js';
 import { runAgentCli } from './worker-cli.js';
 import { resolveCliModel } from './cli-adapter.js';
 import { withWorkerLease } from './worker-lease.js';
@@ -54,15 +54,17 @@ export class LlmWorker extends EventEmitter {
   };
 
   private async execute(dispatch: StepDispatchEvent): Promise<void> {
-    const spec = dispatch.spec as KernelLlmStep;
+    const spec = dispatch.spec as ResolvedKernelLlmStep;
     const schema = spec.verification?.json_schema;
     const prompt = schema === undefined ? spec.prompt
       : `${spec.prompt}\n\nReturn only a JSON value matching this JSON Schema (no Markdown fences):\n${JSON.stringify(schema)}`;
-    const effectiveModel = typeof spec.cli === 'string' ? resolveCliModel(spec.cli, spec.model) : spec.model;
+    const effectiveModel = typeof spec.cli === 'string'
+      ? resolveCliModel(spec.cli_identity ?? spec.cli, spec.model)
+      : spec.model;
     const completed: WorkerCliResult = await withWorkerLease(this.client, dispatch, signal =>
       typeof spec.cli === 'string' && typeof spec.prompt === 'string'
         ? runAgentCli(spec.cli, workerInstruction(prompt, dispatch), dispatch.wake_context, effectiveModel, undefined, signal, 'llm',
-          undefined, undefined, 'direct', undefined, this.environment)
+          undefined, undefined, 'direct', undefined, this.environment, spec.cli_identity)
         : Promise.resolve({ exit_code: null, stdout_tail: '', stderr_tail: 'llm step has no declared CLI' }));
     const { result, usage } = workerSpend(completed, effectiveModel);
     const cost = reportedCost(completed, effectiveModel);

package/src/mcp-stdio.ts

@@ -13,8 +13,9 @@ export class McpStdioTransport implements Transport {
   onmessage?: Transport['onmessage'];
   private child?: ChildProcessWithoutNullStreams;
   private stopTree?: ChildStop;
+  private childClosed = false;
   private readonly buffer = new ReadBuffer({ maxBufferSize: 1_048_576 });
-  private closed?: Promise<void>;
+  private stopped?: Promise<void>;
   private closing?: Promise<void>;
   constructor(private readonly config: Extract<McpServerConfig, { command: string }>) {}
 
@@ -23,11 +24,24 @@ export class McpStdioTransport implements Transport {
     for (const name of this.config.env ?? []) {
       if (process.env[name] !== undefined) env[name] = process.env[name];
     }
+    const ownsGroup = process.platform !== 'win32';
     const child = this.child = spawn(this.config.command, this.config.args ?? [], {
-      env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+      env, stdio: ['pipe', 'pipe', 'pipe'], detached: ownsGroup,
+    });
+    let resolveStopped!: () => void;
+    let rejectStopped!: (error: Error) => void;
+    this.stopped = new Promise<void>((resolve, reject) => {
+      resolveStopped = resolve;
+      rejectStopped = reject;
+    });
+    this.stopTree = childStop(child, ownsGroup, undefined, error => {
+      if (error === undefined) resolveStopped();
+      else rejectStopped(error);
+    });
+    child.once('close', () => {
+      this.childClosed = true;
+      this.stopTree?.maySettleOnChildExit();
     });
-    this.stopTree = childStop(child, process.platform !== 'win32');
-    this.closed = new Promise(resolve => child.once('close', () => resolve()));
     child.stderr.resume();
     child.stdout.on('data', (chunk: Buffer) => {
       if (this.closing) return;
@@ -63,22 +77,22 @@ export class McpStdioTransport implements Transport {
     if (!child) return;
     child.stdin.end();
     this.stopTree!.terminate();
-    // A direct-child close is insufficient: wrappers can leave descendants
-    // alive with either inherited pipes or completely detached stdio.
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const deadline = new Promise<void>(resolve => { timer = setTimeout(resolve, 1000); });
-    await Promise.race([this.closed, deadline]);
-    if (!this.stopTree!.maySettleOnChildExit()) await deadline;
-    clearTimeout(timer);
-    if (child.exitCode === null && child.signalCode === null && child.pid !== undefined) {
-      const exited = new Promise<void>(resolve => child.once('exit', () => resolve()));
-      this.stopTree!.kill();
-      await exited;
+    // `close()` may be called after the direct child already emitted close and
+    // resolved `stopped`. Refund the just-armed escalation in that case before
+    // awaiting the already-settled promise; otherwise its referenced timer can
+    // fire later against a captured, potentially reused process-group id.
+    if (this.childClosed) this.stopTree!.maySettleOnChildExit();
+    try {
+      // A direct-child close is insufficient: wrappers can leave descendants
+      // alive with either inherited pipes or completely detached stdio. The
+      // shared stop owns the bound and rejects when group death is unprovable.
+      await this.stopped;
+    } finally {
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      this.buffer.clear();
+      this.onclose?.();
     }
-    child.stdin.destroy();
-    child.stdout.destroy();
-    child.stderr.destroy();
-    this.buffer.clear();
-    this.onclose?.();
   }
 }

package/src/preflight.ts

@@ -35,6 +35,8 @@ export interface CliResolution {
 export interface CliProbeResult {
   exists: boolean;
   authenticated: boolean | 'unverified';
+  /** Absolute executable selected once for both this probe and later dispatch. */
+  executable?: string;
   /** False when a custom executable did not identify as a wrapper adapter. */
   supported?: boolean;
   /** Exact declared model passed the CLI's model-scoped readiness probe. */

package/src/protocol.ts

@@ -253,6 +253,8 @@ export interface StepDispatchEvent {
   lease_id: string;
   idempotency_key: string;
   pins: Pins;
+  /** Remaining lease duration at dispatch; `lease_deadline_ms` stays absolute. */
+  lease_ttl_ms?: number;
   /**
    * The `wake_context` payload from the run's `subscription.matched`
    * journal entry — carries the triggering event and any epoch summary
@@ -291,6 +293,13 @@ export interface StepHeartbeatParams {
 }
 export interface StepHeartbeatResult {
   lease_deadline_ms: number;
+  /**
+   * The renewed lease as a duration on the daemon's clock. Absent from older
+   * daemons; a worker that has it times the lease on its own monotonic clock
+   * instead of comparing the absolute deadline with a wall clock that may
+   * disagree with the daemon's.
+   */
+  lease_ttl_ms?: number;
 }
 
 /** completionReason mirrors kernel DESIGN.md §1.3. */

package/src/resolved-cli-identity.ts

@@ -0,0 +1,42 @@
+import type {
+  FlowSpec,
+  KernelAgentStep,
+  KernelLlmStep,
+  KernelStepCommon,
+  KernelStepSpec,
+} from './spec.js';
+
+interface ResolvedCliIdentityField {
+  /** Host-proved authored identity used to select the adapter for canonical CLI bytes. */
+  cli_identity?: string;
+}
+
+export type ResolvedKernelStepCommon = KernelStepCommon & ResolvedCliIdentityField;
+export type ResolvedKernelAgentStep = KernelAgentStep & ResolvedCliIdentityField;
+export type ResolvedKernelLlmStep = KernelLlmStep & ResolvedCliIdentityField;
+export type ResolvedKernelStepSpec = KernelStepSpec & ResolvedCliIdentityField;
+
+/**
+ * Host-proved CLI identities are deliberately out-of-band from the authoring
+ * schema. A flow cannot claim that a canonical `cli.js` target is Claude; only
+ * the successful preflight that resolved the authored `claude` declaration
+ * can attach that identity before kernel lowering.
+ */
+const IDENTITIES = new WeakMap<object, ReadonlyMap<string, string>>();
+
+export function resolvedCliIdentities(value: unknown): ReadonlyMap<string, string> | undefined {
+  return typeof value === 'object' && value !== null ? IDENTITIES.get(value) : undefined;
+}
+
+export function rememberResolvedCliIdentities<T extends FlowSpec>(
+  flow: T,
+  identities: ReadonlyMap<string, string>,
+): T {
+  IDENTITIES.set(flow, new Map(identities));
+  return flow;
+}
+
+export function inheritResolvedCliIdentities<T extends FlowSpec>(source: unknown, flow: T): T {
+  const identities = resolvedCliIdentities(source);
+  return identities === undefined ? flow : rememberResolvedCliIdentities(flow, identities);
+}