@aiwg/cli 2026.10.3 → 2026.10.5

package/tools/agents/providers/hermes.mjs

@@ -24,6 +24,7 @@ import path from 'path';
 import os from 'os';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   deploySkillDir,
@@ -192,8 +193,8 @@ export function mapModel(shorthand, modelCfg, modelsConfig) {
 /**
  * Generate a lean AGENTS.md for Hermes
  *
- * Hermes loads AGENTS.md on every turn — keep it under 1,000 characters
- * to preserve context budget on 12GB VRAM setups.
+ * Hermes reaches AGENTS.md through its startup pointer on every task. Reserve
+ * the 19,000-character budget for CRITICAL kernel bodies and the kernel index.
  * See: docs/integrations/hermes-quickstart.md (Part 3)
  */
 // Hermes context cap is 20K chars (head-tail truncated above). Hard limit
@@ -201,6 +202,23 @@ export function mapModel(shorthand, modelCfg, modelsConfig) {
 const HERMES_AGENTS_MD_HARD_CAP = 19_000;
 const HERMES_AGENTS_MD_SOFT_WARN = 15_000;
 
+/** Never truncate CRITICAL bodies. Report each contribution before promotion. */
+export function assertContextBudget(content, name = 'AGENTS.md', rules = []) {
+  if (content.length <= HERMES_AGENTS_MD_HARD_CAP) return;
+  const critical = rules.filter(rule => rule.tagged && rule.activation === 'kernel'
+    && String(rule.enforcement || '').trim().toLowerCase() === 'critical');
+  const sizes = critical.map(rule => ({ name: rule.name,
+    chars: `## Rule: ${rule.name}\n\n${rule.body.trim()}`.length }));
+  const total = sizes.reduce((sum, rule) => sum + rule.chars, 0) + Math.max(0, sizes.length - 1) * 2;
+  throw new Error(
+    `Hermes ${name} (${content.length} chars) exceeds hard cap of ${HERMES_AGENTS_MD_HARD_CAP}. ` +
+    `Hermes truncates above 20K. ` +
+    (total > HERMES_AGENTS_MD_HARD_CAP ? 'CRITICAL kernel set alone exceeds the cap. ' : 'Assembled context exceeds the cap; review wrappers and operator additions. ') +
+    `CRITICAL kernel total: ${total} chars (bodies and rule headings).\n` +
+    sizes.map(rule => `  ${rule.name}: ${rule.chars} chars`).join('\n')
+  );
+}
+
 /**
  * Top-7 CRITICAL rule directives, inlined into AGENTS.md for guaranteed
  * priming on every Hermes turn (#1318 / S7; skill-discovery added #1347).
@@ -297,41 +315,32 @@ surface as provider-agnostic tools when configured.
 **Artifacts** (project-required, .aiwg/ directory):
 - \`mcp_aiwg_artifact_read\` / \`mcp_aiwg_artifact_write\``;
 
+function mergeHermesContext(file, generated, kind) {
+  let existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  existing = existing.replace(/\n?<!-- AIWG:rule-startup:start -->[\s\S]*?<!-- AIWG:rule-startup:end -->\n?/g, '');
+  const start = `<!-- AIWG:hermes-${kind}:start -->`;
+  const end = `<!-- AIWG:hermes-${kind}:end -->`;
+  const managed = `${start}\n${generated}\n${end}`;
+  if (existing.includes(start)) return existing.slice(0, existing.indexOf(start)) + managed + existing.slice(existing.indexOf(end) + end.length);
+  if (kind === 'context' && existing.startsWith('# AIWG Integration') && existing.includes(HERMES_AGENTS_MD_FOOTER)) {
+    existing = existing.slice(existing.indexOf(HERMES_AGENTS_MD_FOOTER) + HERMES_AGENTS_MD_FOOTER.length);
+  } else if (kind === 'routing' && existing.includes(generated)) {
+    existing = existing.replace(generated, '');
+  }
+  return existing ? `${existing.trimEnd()}\n\n${managed}\n` : `<!-- aiwg-managed -->\n${managed}\n`;
+}
+
 export function generateAgentsMd(agentCount, skillCount, targetDir, opts) {
   const { dryRun } = opts;
 
+  // Startup is reserved for rule contracts. Workflow routing, artifact catalogs,
+  // and the optional MCP tool inventory duplicate discover/show and consume
+  // Hermes's finite per-turn context before the kernel is appended.
   const header = `# AIWG Integration
 
-AIWG connected through file-based deployment. Native Hermes skills are available
-at \`$HERMES_HOME/skills/\` (kernel) and \`$HERMES_HOME/skills/.aiwg/\` (standard).
-When unset, \`HERMES_HOME\` defaults to the platform-native Hermes home.
-Use \`aiwg discover\` and \`aiwg show <type> <name>\` for the on-demand catalog.
-The MCP sidecar (\`aiwg mcp serve\`) is optional.
-
-## Route to AIWG When
-
-- Structured artifacts needed (requirements, architecture, test plans, risk registers)
-- Multi-step workflows with phase gates or checkpoints
-- Template-driven output that persists across sessions
-
-Handle in Hermes directly: one-off questions, short tasks, conversation.
-
-## Memory Boundary
-
-When AIWG returns an artifact: store path + one-sentence summary in MEMORY.md.
-Do NOT copy artifact body text into memory. Reference, don't replicate.
-
-Use \`delegate_task(goal="...", context="...")\` for AIWG workflows.
-Child agents automatically exclude context files and memory.
-
-## Artifact Store (.aiwg/)
-
-Fetch on demand via \`mcp_aiwg_artifact_read\`:
-- \`requirements/\` — use cases, user stories
-- \`architecture/\` — SAD, ADRs
-- \`planning/\` — phase plans
-- \`testing/\` — test strategy
-- \`security/\` — threat models
+Skills: \`$HERMES_HOME/skills/\` (kernel), \`$HERMES_HOME/skills/.aiwg/\` (standard).
+Find: \`aiwg discover "rule <topic>" --type rule\`. Fetch: \`aiwg show rule <name>\`.
+MCP is optional; \`mcp_aiwg_rule_show\` exposes the same rule catalog.
 `;
 
   // On-demand tier (#1675): the MEDIUM/LOW rules not inlined above. Hermes has
@@ -339,18 +348,15 @@ Fetch on demand via \`mcp_aiwg_artifact_read\`:
   const onDemandSection = opts.srcRoot
     ? renderOnDemandRuleSection(listOnDemandRuleFiles(opts.srcRoot))
     : '';
-  const sections = [header, CRITICAL_RULE_DIRECTIVES];
+  const migrated = new Set((opts.ruleDelivery?.rules || []).filter(rule => rule.tagged).map(rule => rule.name));
+  const directives = CRITICAL_RULE_DIRECTIVES.split(/(?=^### Rule: )/m).filter(section => section.startsWith('### Rule: ') && !migrated.has(section.match(/^### Rule: ([^ \n]+)/)?.[1])).join('');
+  const sections = [header, directives];
   if (onDemandSection) sections.push(onDemandSection);
-  sections.push(HERMES_AGENTS_MD_FOOTER);
-  const output = sections.join('\n\n');
+  // The optional tool inventory is available on demand through the CLI.
   const destPath = path.join(targetDir, 'AGENTS.md');
+  const output = mergeHermesContext(destPath, sections.join('\n\n'), 'context');
 
-  if (output.length > HERMES_AGENTS_MD_HARD_CAP) {
-    throw new Error(
-      `Hermes AGENTS.md (${output.length} chars) exceeds hard cap of ${HERMES_AGENTS_MD_HARD_CAP}. ` +
-      `Hermes truncates above 20K. Trim the priming block or split rule bodies further.`
-    );
-  }
+  assertContextBudget(output, 'AGENTS.md', opts.ruleDelivery?.rules);
 
   if (dryRun) {
     console.log(`[dry-run] Would write AGENTS.md (${output.length} chars, ${Math.round(output.length / 4)} tokens estimated)`);
@@ -397,7 +403,7 @@ when the full AIWG project context is needed.
   if (dryRun) {
     console.log(`[dry-run] Would write .hermes.md (${body.length} chars)`);
   } else {
-    fs.writeFileSync(destPath, body, 'utf8');
+    fs.writeFileSync(destPath, mergeHermesContext(destPath, body, 'routing'), 'utf8');
     console.log(`  Created .hermes.md (${body.length} chars)`);
   }
   return 1;
@@ -417,7 +423,7 @@ when the full AIWG project context is needed.
  */
 export function deploySkills(skillDirs, opts) {
   const standardDestDir = paths.skills;
-  const kernelDestDir = kernelSkillsPath;
+  const kernelDestDir = opts.kernelSkillsPath || kernelSkillsPath;
 
   if (!opts.dryRun) {
     console.log(`  Deploying ${skillDirs.length} skills (kernel + standard split)...`);
@@ -431,6 +437,10 @@ export function deploySkills(skillDirs, opts) {
 // ============================================================================
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath, assertContextBudget }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     target,
@@ -509,7 +519,7 @@ export async function deploy(opts) {
     const kernelNames = computeAllKernelNames(srcRoot);
     if (kernelNames != null) {
       const desiredKernel = [...kernelNames, 'aiwg-orchestrate'];
-      pruneStaleAiwgSkills(kernelSkillsPath, desiredKernel, opts);
+      pruneStaleAiwgSkills(opts.kernelSkillsPath || kernelSkillsPath, desiredKernel, opts);
 
       // Register kernel skills in Hermes's bundled manifest so the Curator
       // (v0.12.0+, 7-day archival cycle) does not archive them. Standard
@@ -603,7 +613,7 @@ export async function deploy(opts) {
  */
 export function updateBundledManifest(kernelSkillNames, opts) {
   const { dryRun, quiet } = opts;
-  const manifestPath = path.join(kernelSkillsPath, '.bundled_manifest');
+  const manifestPath = path.join(opts.kernelSkillsPath || kernelSkillsPath, '.bundled_manifest');
   const aiwgTag = 'aiwg-managed';
 
   // Read existing manifest (if any) and split into "ours" vs "theirs"
@@ -668,7 +678,7 @@ export function migrateLegacySkillPath(opts) {
   // this provider (env var first, platform default otherwise): with
   // HERMES_HOME set, the legacy tree lives under that root — never under
   // the process home directory.
-  const legacyPath = path.join(getHermesHome(), '.aiwg', 'skills');
+  const legacyPath = opts.hermesLegacySkills || path.join(getHermesHome(), '.aiwg', 'skills');
   const newPath = paths.skills;
 
   let legacyExists = false;
@@ -754,7 +764,7 @@ function deployAiwgOrchestrateSkill(srcRoot, opts) {
     return;
   }
 
-  const destDir = path.join(kernelSkillsPath, 'aiwg-orchestrate');
+  const destDir = path.join(opts.kernelSkillsPath || kernelSkillsPath, 'aiwg-orchestrate');
   const destPath = path.join(destDir, 'SKILL.md');
 
   if (fs.existsSync(destPath)) {

package/tools/agents/providers/openclaw.mjs

@@ -26,6 +26,7 @@ try { const gfs = _require('graceful-fs'); gfs.gracefulify(realFs); fs = realFs;
 import path from 'path';
 import os from 'os';
 import {
+  withRuleDeployment,
   ensureDir,
   listMdFiles,
   listMdFilesRecursive,
@@ -191,7 +192,7 @@ function deploySkills(skillDirs, opts) {
   // Standard: ~/.openclaw/.aiwg/skills/ (no extra aiwg/ — the .aiwg/ segment IS the namespace)
   const standardDestDir = paths.skills;
   // Kernel: ~/.openclaw/skills/aiwg/ (preserves legacy 2-level namespacing)
-  const kernelDestDir = path.join(kernelSkillsPath, 'aiwg');
+  const kernelDestDir = path.join(opts.kernelSkillsPath || kernelSkillsPath, 'aiwg');
 
   deploySkillsWithKernelRouting(skillDirs, standardDestDir, kernelDestDir, opts);
 
@@ -396,6 +397,10 @@ export function getFileExtension(type) {
 // ============================================================================
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath, resolveOpenClawWorkspace }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const {
     srcRoot,
     mode,
@@ -485,9 +490,9 @@ export async function deploy(opts) {
     // (`aiwg use` invokes deploy-agents.mjs once per framework + addon
     // batch).
     {
-      const _kernelDestDir = path.isAbsolute(kernelSkillsPath)
+      const _kernelDestDir = opts.kernelSkillsPath || (path.isAbsolute(kernelSkillsPath)
         ? kernelSkillsPath
-        : path.join(target, kernelSkillsPath);
+        : path.join(target, kernelSkillsPath));
       pruneStaleAiwgSkills(_kernelDestDir, computeAllKernelNames(srcRoot), opts);
     }
   }
@@ -549,7 +554,7 @@ export async function deploy(opts) {
       srcRoot, 'agentic', 'code', 'frameworks', 'sdlc-complete', 'templates', 'openclaw', 'AGENTS.md.aiwg-template',
     );
     if (fs.existsSync(templatePath)) {
-      const workspace = resolveOpenClawWorkspace();
+      const workspace = opts.activeWorkspace || resolveOpenClawWorkspace();
       ensureDir(workspace, dryRun);
       if (verbose || !opts.quiet) {
         console.log(`\nBridging AIWG context into ${path.join(workspace, 'AGENTS.md')} + SOUL.md (#1562/#1572)...`);

package/tools/agents/providers/pi.mjs

@@ -11,6 +11,7 @@ import path from 'path';
 import fs from 'fs';
 import {
   collectFrameworkArtifacts,
+  withRuleDeployment,
   createAgentsMdFromTemplate,
   deployFiles,
   deploySkillsWithKernelRouting,
@@ -139,6 +140,10 @@ export function getFileExtension() {
 }
 
 export async function deploy(opts) {
+  return withRuleDeployment(opts, { name, paths, kernelSkillsPath }, deploySelected);
+}
+
+async function deploySelected(opts) {
   const normalizedMode = normalizeDeploymentMode(opts.mode);
   const agentFiles = [];
   const commandFiles = [];

package/tools/agents/providers/provider-prepare-channel.mjs

@@ -0,0 +1,5 @@
+// A once-only IPC listener is removed before its async work finishes. Keep the
+// channel referenced until the worker disconnects after publishing its response.
+export function retainPreparationChannel() {
+  process.channel?.ref();
+}

package/tools/agents/providers/provider-prepare-coordinator.mjs

@@ -0,0 +1,247 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fork } from 'node:child_process';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { importImpl } from '../../_resolve-impl.mjs';
+import {
+  createRuleDeploymentInputPool,
+  describeRuleDeploymentInputPool,
+  disposeRuleDeploymentInputPool,
+  adoptRuleDeploymentPlan,
+  commitRuleDeploymentPlan,
+  disposeRuleDeploymentPlan,
+} from './rule-delivery.mjs';
+
+const { trackTemporaryDirectory } = await importImpl(import.meta.url, 'utils/temporary-directory.js');
+const { signalChild } = await importImpl(import.meta.url, 'process/signal-child.mjs');
+const DEFAULT_WORKER = fileURLToPath(new URL('./provider-prepare-worker.mjs', import.meta.url));
+const CHECKOUT_NEEDS_TS_TRANSFORM = !fs.existsSync(fileURLToPath(new URL('../../../dist/src', import.meta.url)));
+const PLAN_LIMIT = 256 * 1024 * 1024;
+
+const defaultTransaction = {
+  createPool: createRuleDeploymentInputPool,
+  describePool: describeRuleDeploymentInputPool,
+  disposePool: disposeRuleDeploymentInputPool,
+  adopt: adoptRuleDeploymentPlan,
+  commit: commitRuleDeploymentPlan,
+  disposePlan: disposeRuleDeploymentPlan,
+  isStale: error => error?.code === 'AIWG_RULE_DEPLOYMENT_STALE',
+};
+
+function exactKeys(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value) &&
+    JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+}
+
+function validateJob(job, expectedOrder) {
+  if (!job || job.order !== expectedOrder || !Number.isSafeInteger(job.order) ||
+      typeof job.provider !== 'string' || !job.provider || typeof job.target !== 'string' || !path.isAbsolute(job.target) ||
+      !Array.isArray(job.args) || job.args.some(value => typeof value !== 'string')) {
+    throw new Error(`Invalid provider preparation job at order ${expectedOrder}`);
+  }
+}
+
+function readPlan(response, expectedPath) {
+  if (!exactKeys(response.plan, ['path', 'size', 'sha256']) || response.plan.path !== expectedPath ||
+      !Number.isSafeInteger(response.plan.size) || response.plan.size < 2 || response.plan.size > PLAN_LIMIT ||
+      !/^[a-f0-9]{64}$/.test(response.plan.sha256)) throw new Error('Invalid provider preparation plan descriptor');
+  const stat = fs.lstatSync(expectedPath);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size !== response.plan.size) throw new Error('Invalid provider preparation plan file');
+  const body = fs.readFileSync(expectedPath);
+  if (body.length !== response.plan.size || createHash('sha256').update(body).digest('hex') !== response.plan.sha256) {
+    throw new Error('Provider preparation plan digest mismatch');
+  }
+  return JSON.parse(body.toString('utf8'));
+}
+
+function prepareInChild({ job, attempt, sessionRoot, poolDescriptor, workerPath, workerEnv, activeChildren, timeoutMs }) {
+  const scratch = path.join(sessionRoot, `${job.order}-${attempt}-${randomUUID()}`);
+  fs.mkdirSync(scratch, { mode: 0o700 });
+  const capability = randomBytes(32).toString('hex');
+  const jobId = randomUUID();
+  const expectedPlan = path.join(scratch, 'plan.json');
+  return new Promise((resolve, reject) => {
+    const child = fork(workerPath, [], {
+      cwd: process.cwd(),
+      env: { ...process.env, ...workerEnv },
+      stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+      serialization: 'json',
+      execArgv: CHECKOUT_NEEDS_TS_TRANSFORM ? ['--import', 'tsx'] : [],
+    });
+    activeChildren.add(child);
+    const stderr = [];
+    let stderrBytes = 0;
+    child.stderr?.on('data', chunk => {
+      const retained = chunk.subarray(0, Math.max(0, 1024 * 1024 - stderrBytes));
+      if (retained.length) { stderr.push(Buffer.from(retained)); stderrBytes += retained.length; }
+    });
+    let settled = false;
+    let outcome;
+    let killTimer;
+    let timedOut = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(killTimer);
+      activeChildren.delete(child);
+      if (child.connected) { try { child.disconnect(); } catch {} }
+      if (outcome?.error) reject(outcome.error); else if (outcome) resolve(outcome.value);
+      else reject(new Error(`Provider preparation worker exited ${child.exitCode ?? 'without status'} for ${job.provider}${stderrBytes ? `: ${Buffer.concat(stderr).toString('utf8').trim()}` : ''}`));
+    };
+    const stop = error => {
+      if (settled) return;
+      outcome = { error };
+      try { signalChild(child, 'SIGTERM'); } catch {}
+      if (!killTimer) {
+        killTimer = setTimeout(() => { try { signalChild(child, 'SIGKILL'); } catch {} }, 2_000);
+        killTimer.unref?.();
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      stop(new Error(`Provider preparation timed out for ${job.provider}`));
+    }, timeoutMs);
+    timer.unref?.();
+    child.once('error', error => {
+      // A spawn failure has no operating-system child to reap. Every error
+      // after a pid is assigned still waits for the exit event below.
+      if (!child.pid) { outcome = { error }; finish(); }
+      else stop(error);
+    });
+    // Settle only after the operating system reports process exit. This keeps
+    // every worker in activeChildren until it is confirmed gone, including workers
+    // that send a response and retain an unexpected live handle.
+    child.once('exit', (code, signal) => {
+      if (outcome?.value && (code !== 0 || signal)) {
+        outcome = { error: new Error(`Provider preparation worker exited ${signal || code || 'without status'} after responding for ${job.provider}`) };
+      }
+      if (!outcome) outcome = { error: new Error(`${timedOut ? 'Provider preparation timed out' : `Provider preparation worker exited ${code ?? 'without status'}`} for ${job.provider}${stderrBytes ? `: ${Buffer.concat(stderr).toString('utf8').trim()}` : ''}`) };
+      finish();
+    });
+    child.once('message', response => {
+      try {
+        if (timedOut) throw new Error(`Provider preparation timed out for ${job.provider}`);
+        if (!exactKeys(response, response?.type === 'error'
+          ? ['version', 'type', 'capability', 'jobId', 'error']
+          : ['version', 'type', 'capability', 'jobId', 'plan']) ||
+          response.version !== 1 || response.capability !== capability || response.jobId !== jobId) {
+          throw new Error('Invalid provider preparation worker response');
+        }
+        if (response.type === 'error') {
+          if (!exactKeys(response.error, ['message']) || typeof response.error.message !== 'string') throw new Error('Invalid provider preparation worker error');
+          throw new Error(`${job.provider}: ${response.error.message}`);
+        }
+        if (response.type !== 'prepared') throw new Error('Invalid provider preparation worker response type');
+        outcome = { value: { detached: readPlan(response, expectedPlan), scratch, attempt } };
+        // Closing the IPC channel lets the single-request worker exit normally;
+        // the exit handler above confirms termination before exposing its plan.
+        if (child.connected) { try { child.disconnect(); } catch {} }
+      } catch (error) { stop(error); }
+    });
+    child.send({ version: 1, type: 'prepare', capability, jobId, order: job.order, attempt, provider: job.provider,
+      target: job.target, args: job.args, scratch, inputPool: poolDescriptor }, error => { if (error) stop(error); });
+  });
+}
+
+/** Prepare provider projections in at most two subprocesses. The returned
+ * session owns every stage and promotes them only through ordered commit(). */
+export async function prepareProviderDeployments({
+  srcRoot,
+  jobs,
+  maxConcurrency = 2,
+  workerPath = DEFAULT_WORKER,
+  workerEnv = {},
+  timeoutMs = 120_000,
+  transaction = defaultTransaction,
+  onSessionRoot,
+  signal = signalChild,
+}) {
+  if (typeof srcRoot !== 'string' || !path.isAbsolute(srcRoot) || !Array.isArray(jobs) || !jobs.length) throw new Error('Invalid provider preparation request');
+  jobs.forEach(validateJob);
+  const concurrency = Math.max(1, Math.min(2, Number.isSafeInteger(maxConcurrency) ? maxConcurrency : 2, jobs.length));
+  const sessionRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'aiwg-provider-prepare-'));
+  const removeSession = trackTemporaryDirectory(sessionRoot);
+  onSessionRoot?.(sessionRoot);
+  const activeChildren = new Set();
+  let pool;
+  let poolDescriptor;
+  try {
+    pool = transaction.createPool(srcRoot);
+    poolDescriptor = transaction.describePool(pool);
+  } catch (error) {
+    if (pool) transaction.disposePool(pool);
+    removeSession();
+    throw error;
+  }
+  const prepared = new Array(jobs.length);
+  let next = 0;
+  let closed = false;
+  let nextCommit = 0;
+  const stopChildren = async () => {
+    const children = [...activeChildren];
+    await Promise.all(children.map(child => new Promise(resolve => {
+      if (child.exitCode !== null || child.signalCode !== null) return resolve();
+      if (!Number.isSafeInteger(child.pid) || child.pid <= 0) return resolve();
+      const hardKill = setTimeout(() => { try { signal(child, 'SIGKILL'); } catch {} }, 2_000);
+      hardKill.unref?.();
+      child.once('exit', () => { clearTimeout(hardKill); resolve(); });
+      try { signal(child, 'SIGTERM'); } catch { /* escalation and exit confirmation remain required */ }
+    })));
+  };
+  const cleanup = async () => {
+    if (closed) return;
+    closed = true;
+    await stopChildren();
+    for (const item of prepared) if (item?.plan && !item.committed) transaction.disposePlan(item.plan);
+    transaction.disposePool(pool);
+    removeSession();
+  };
+  const prepareOne = async (index, attempt = 0) => {
+    const raw = await prepareInChild({ job: jobs[index], attempt, sessionRoot, poolDescriptor, workerPath, workerEnv, activeChildren, timeoutMs });
+    const plan = transaction.adopt(raw.detached, {
+      scratch: raw.scratch,
+      target: jobs[index].target,
+      inputPool: pool,
+      cleanup: () => fs.rmSync(raw.scratch, { recursive: true, force: true }),
+    });
+    return { ...raw, plan, committed: false };
+  };
+  try {
+    await Promise.all(Array.from({ length: concurrency }, async () => {
+      for (;;) {
+        const index = next++;
+        if (index >= jobs.length) return;
+        prepared[index] = await prepareOne(index);
+      }
+    }));
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+  return {
+    get providers() { return jobs.map(job => job.provider); },
+    async commit(index) {
+      if (closed) throw new Error('Provider preparation session is closed');
+      if (index !== nextCommit) throw new Error(`Provider plans must commit in order: expected ${nextCommit}, received ${index}`);
+      let item = prepared[index];
+      try {
+        let report;
+        try { report = transaction.commit(item.plan); }
+        catch (error) {
+          if (!transaction.isStale(error) || item.attempt >= 1) throw error;
+          item = prepared[index] = await prepareOne(index, item.attempt + 1);
+          report = transaction.commit(item.plan);
+        }
+        item.committed = true;
+        nextCommit++;
+        return report;
+      } catch (error) {
+        throw error;
+      }
+    },
+    async dispose() { await cleanup(); },
+  };
+}

package/tools/agents/providers/provider-prepare-worker.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { main as deployProvider, parseArgs } from '../deploy-agents.mjs';
+import { retainPreparationChannel } from './provider-prepare-channel.mjs';
+import {
+  importRuleDeploymentInputPool,
+  disposeRuleDeploymentInputPool,
+  installRuleDeploymentPreparationHook,
+} from './rule-delivery.mjs';
+
+function exactKeys(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value) &&
+    JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+}
+
+function validRequest(request) {
+  return exactKeys(request, ['version', 'type', 'capability', 'jobId', 'order', 'attempt', 'provider', 'target', 'args', 'scratch', 'inputPool']) &&
+    request.version === 1 && request.type === 'prepare' && /^[a-f0-9]{64}$/.test(request.capability) &&
+    typeof request.jobId === 'string' && Number.isSafeInteger(request.order) && request.order >= 0 &&
+    (request.attempt === 0 || request.attempt === 1) && typeof request.provider === 'string' && request.provider &&
+    typeof request.target === 'string' && path.isAbsolute(request.target) && typeof request.scratch === 'string' && path.isAbsolute(request.scratch) &&
+    Array.isArray(request.args) && request.args.every(value => typeof value === 'string');
+}
+
+function publish(message) {
+  return new Promise(resolve => {
+    if (!process.connected) return resolve();
+    process.send(message, () => resolve());
+  });
+}
+
+process.once('message', async request => {
+  retainPreparationChannel();
+  if (!validRequest(request)) {
+    await publish({ version: 1, type: 'error', capability: request?.capability || '', jobId: request?.jobId || '', error: { message: 'Invalid provider preparation request' } });
+    try { process.disconnect(); } catch {}
+    return;
+  }
+  let pool;
+  let clearHook = () => {};
+  let response;
+  try {
+    const stat = fs.lstatSync(request.scratch);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || fs.readdirSync(request.scratch).length) throw new Error('Invalid provider preparation scratch directory');
+    const parsed = parseArgs(request.args);
+    if (parsed.provider !== request.provider || path.resolve(parsed.target) !== path.resolve(request.target)) {
+      throw new Error('Provider preparation request does not match its deployment arguments');
+    }
+    pool = importRuleDeploymentInputPool(request.inputPool);
+    let detached;
+    clearHook = installRuleDeploymentPreparationHook({
+      scratch: request.scratch,
+      inputPool: pool,
+      accept: plan => {
+        if (detached) throw new Error('Provider attempted more than one transactional preparation');
+        detached = plan;
+      },
+    });
+    await deployProvider(request.args);
+    if (!detached) throw new Error('Provider did not produce a transactional preparation plan');
+    if (detached.target !== path.resolve(request.target)) throw new Error('Provider preparation target mismatch');
+    const body = Buffer.from(JSON.stringify(detached));
+    const planPath = path.join(request.scratch, 'plan.json');
+    const fd = fs.openSync(planPath, 'wx', 0o600);
+    try { fs.writeFileSync(fd, body); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    response = {
+      version: 1,
+      type: 'prepared',
+      capability: request.capability,
+      jobId: request.jobId,
+      plan: { path: planPath, size: body.length, sha256: createHash('sha256').update(body).digest('hex') },
+    };
+  } catch (error) {
+    response = { version: 1, type: 'error', capability: request.capability, jobId: request.jobId,
+      error: { message: error instanceof Error ? error.message : String(error) } };
+  } finally {
+    clearHook();
+    if (pool) disposeRuleDeploymentInputPool(pool);
+  }
+  await publish(response);
+  try { process.disconnect(); } catch {}
+});