@aiwg/cli 2026.10.3 → 2026.10.4

package/dist/src/models/worker-installation.mjs

@@ -1,5 +1,6 @@
 /** Shared installed-worker qualification owner, also used by the Ralph compatibility facade. */
 import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
 import { open, realpath, lstat, mkdir, rename, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { homedir } from 'node:os';
@@ -8,6 +9,21 @@ import { createHash } from 'node:crypto';
 import { parse } from 'acorn';
 import { satisfies, valid, validRange } from 'semver';
 
+// Recovery metadata belongs to the installed driver identity, never its shape.
+const workerRecoveryCapabilities = new WeakMap();
+
+/** Register capabilities for an installed or caller-supplied driver. Keep the
+ * original driver when passing it to readers; copies must be registered anew. */
+export function registerWorkerRecoveryCapabilities(driver, capabilities) {
+  workerRecoveryCapabilities.set(driver, Object.freeze({ ...capabilities }));
+  return driver;
+}
+
+/** Gated readers use this single lookup; ordinary driver properties are ignored. */
+export function getWorkerRecoveryCapabilities(driver) {
+  return workerRecoveryCapabilities.get(driver) ?? null;
+}
+
 // Shipped negative-suite definition. Evidence producers hash this definition,
 // including case semantics and permission rows; arbitrary fixture labels cannot
 // qualify an installation. Passed observations still come from the trusted host.
@@ -84,7 +100,7 @@ function assertWorkerControlArgv(profile, argv) {
 
 
 async function assertWorkerInstallationEvidence(request, scopeDigest) {
-  const { DEFAULT_WORKER_SELECTION } = await import('./provider-policy.js');
+  const { DEFAULT_WORKER_SELECTION, WORKER_OPERATOR_APPROVAL, isOperatorQualifiedWorkerAdapter } = await import('./provider-policy.js');
   const { evidence, now } = request;
   if (!Number.isFinite(now) || !evidence || !/^sha256:[a-f0-9]{64}$/.test(scopeDigest) || evidence.scopeDigest !== scopeDigest
     || evidence.fixtureDigest !== await workerNegativeFixtureDigest()
@@ -95,17 +111,21 @@ async function assertWorkerInstallationEvidence(request, scopeDigest) {
   if (now - Date.parse(evidence.verifiedAt) >= (request.policy?.freshness?.policyDays ?? DEFAULT_WORKER_SELECTION.freshness.policyDays) * 86400000) {
     throw new Error('Installation evidence expired');
   }
+  // Decision 17's direct CLI baseline records operator approval, never claims
+  // that a version probe ran the negative suite. Stronger host evidence keeps
+  // its existing checks below.
+  if (evidence.evidenceRef === WORKER_OPERATOR_APPROVAL && isOperatorQualifiedWorkerAdapter(request.adapter)) return;
   const { cases: requiredCases } = await workerPermissionRequirements(request.adapter.provider, request.requiredControls);
   if (requiredCases.some(id => evidence.cases?.[id] !== 'passed')) {
     throw new Error('Installation negative evidence is incomplete');
   }
 }
 
-/** Read-only recheck: the version probe is bound to the unchanged binary digest. */
+/** Read-only recheck of the approved installation bytes and bindings. */
 async function recheckWorkerInstallation(instance, options) {
   const request = structuredClone(options);
-  const { requiredWorkerControls } = await import('./provider-policy.js');
-  request.requiredControls = requiredWorkerControls(request);
+  const { requiredWorkerControls, isOperatorQualifiedWorkerAdapter } = await import('./provider-policy.js');
+  if (!isOperatorQualifiedWorkerAdapter(request.adapter)) request.requiredControls = requiredWorkerControls(request);
   const scope = await inspectWorkerInstallation(instance, request);
   await assertWorkerInstallationEvidence(request, scope.scopeDigest);
   return { scope, request };
@@ -143,9 +163,9 @@ export async function qualifyWorkerInstallation(instance, options) {
 }
 
 export async function prepareInstalledWorkerInvocation(instance, invocation, qualification) {
-  const { prepareWorkerInvocation } = await import('../serve/worker-invocation.js');
-  const { requiredWorkerControls, WorkerPolicyError } = await import('./provider-policy.js');
-  qualification = { ...qualification, requiredControls: requiredWorkerControls({
+  const { prepareWorkerInvocation, WorkerPathScopeError } = await import('../serve/worker-invocation.js');
+  const { requiredWorkerControls, WorkerPolicyError, isOperatorQualifiedWorkerAdapter } = await import('./provider-policy.js');
+  if (!isOperatorQualifiedWorkerAdapter(qualification.adapter)) qualification = { ...qualification, requiredControls: requiredWorkerControls({
     ...qualification, effort: invocation.selected.effort.value }) };
   const result = await prepareWorkerInvocation(invocation, { ...qualification, adapterId: instance.getName() });
   const profile = qualification.adapter.invocationProfiles[result.selected.profileRef];
@@ -172,14 +192,16 @@ export async function prepareInstalledWorkerInvocation(instance, invocation, qua
     for (const key of ['briefPath', 'stdoutPath', 'stderrPath', 'finalPath']) {
       const target = await canonicalFuturePath(result[key]);
       const roots = key === 'briefPath' ? scope.inputRoots : scope.outputRoots;
-      if (!roots.some(root => inside(root, target))) throw new WorkerPolicyError('OG_CONFIG_REFERENCE', 'Worker input/output path is outside the qualified scope');
+      if (!roots.some(root => inside(root, target))) throw new WorkerPathScopeError(key, result[key], roots);
     }
     if (result.transport === 'shell') {
+      const driverInput = isOperatorQualifiedWorkerAdapter(qualification.adapter)
+        ? { ...result, brief: (await readInstalledFile(result.briefPath)).toString('utf8') } : result;
       const expectedArtifacts = typeof instance.buildWorkerArtifacts === 'function'
-        ? instance.buildWorkerArtifacts({ ...result, permissions: qualification.permissions }) : undefined;
+        ? instance.buildWorkerArtifacts({ ...driverInput, permissions: qualification.permissions }) : undefined;
       if (JSON.stringify(expectedArtifacts) !== JSON.stringify(result.artifacts)) throw new WorkerPolicyError('OG_PIN_MISMATCH', 'Worker artifacts differ from authorized driver mapping');
-      const workerArgs = instance.buildWorkerArgs(result, profile, qualification.permissions);
-      assertWorkerControlArgv(profile, workerArgs);
+      const workerArgs = instance.buildWorkerArgs(driverInput, profile, qualification.permissions);
+      if (!isOperatorQualifiedWorkerAdapter(qualification.adapter)) assertWorkerControlArgv(profile, workerArgs);
       const expected = [scope.binary.realpath, ...workerArgs];
       if (JSON.stringify(expected) !== JSON.stringify(result.argv)
         || result.stdin !== qualification.adapter.invocation.stdin) {
@@ -215,6 +237,7 @@ async function binaryIdentity(filename, workerWritableRoots) {
     const stat = await handle.stat();
     if (!stat.isFile() || !(stat.mode & 0o111) || (stat.mode & 0o022)
       || (stat.nlink > 1 && (stat.mode & 0o222))) throw new Error('Untrusted binary permissions');
+    if (stat.size > 1024 * 1024 * 1024) throw new Error('Binary exceeds qualification byte bound (1 GiB)');
     const hash = createHash('sha256');
     // Incremental, bounded reads: never allocate the size reported by the binary.
     const buffer = Buffer.alloc(64 * 1024);
@@ -223,7 +246,7 @@ async function binaryIdentity(filename, workerWritableRoots) {
       const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
       if (!bytesRead) break;
       total += bytesRead;
-      if (total > 256 * 1024 * 1024) throw new Error('Binary exceeds qualification byte bound');
+      if (total > 1024 * 1024 * 1024) throw new Error('Binary exceeds qualification byte bound');
       hash.update(buffer.subarray(0, bytesRead));
     }
     return { realpath: canonical, sha256: `sha256:${hash.digest('hex')}` };
@@ -245,11 +268,12 @@ async function canonicalFuturePath(filename) {
 }
 
 export async function inspectWorkerInstallation(instance, request) {
-  const { inspectWorkerInvocationProfile, requiredWorkerControls } = await import('./provider-policy.js');
+  const { inspectWorkerInvocationProfile, requiredWorkerControls, isOperatorQualifiedWorkerAdapter } = await import('./provider-policy.js');
   const { qualificationDigest } = await import('./qualification-digest.mjs');
   const { adapter, profile: profileId, cliVersion, workerWritableRoots,
     effectiveConfigDigest, accountScope, boundary, cwd } = request;
-  const requiredControls = requiredWorkerControls(request);
+  const operatorApproved = isOperatorQualifiedWorkerAdapter(adapter);
+  const requiredControls = operatorApproved ? request.requiredControls ?? [] : requiredWorkerControls(request);
   const platform = request.platform ?? process.platform;
   if (platform !== 'linux' || adapter.id !== instance.getName()) throw new Error('Unsupported installation identity/platform');
   if (!Array.isArray(requiredControls) || !Array.isArray(workerWritableRoots)
@@ -269,11 +293,11 @@ export async function inspectWorkerInstallation(instance, request) {
     throw new Error('External control lacks an enforcing boundary');
   }
   const permissionRequirements = await workerPermissionRequirements(adapter.provider, requiredControls);
-  if (permissionRequirements.externalBoundary && boundary.kind === 'native') {
+  if (!operatorApproved && permissionRequirements.externalBoundary && boundary.kind === 'native') {
     throw new Error('Profile requires an external enforcing boundary');
   }
   let controlArgv = null;
-  if (Object.values(profile.controls).some(hasControlArgvMapping)) {
+  if (!operatorApproved && Object.values(profile.controls).some(hasControlArgvMapping)) {
     if (!request.invocation) throw new Error('Worker control qualification requires representative argv invocation');
     controlArgv = instance.buildWorkerArgs(structuredClone(request.invocation), profile, request.permissions);
     assertWorkerControlArgv(profile, controlArgv);
@@ -425,7 +449,7 @@ export function boundedVersionProbe(executable, argv, environment, cwd, timeoutM
     let size = 0;
     let failed = false;
     const stop = () => {
-      if (child.pid) { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* already stopped */ } }
+      if (Number.isSafeInteger(child.pid) && child.pid > 0) { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* already stopped */ } }
     };
     // Never rely on close: an escaped descendant may retain the pipe descriptors.
     const abort = () => {
@@ -564,7 +588,8 @@ async function inspectInstalledModule(entry, workerWritableRoots, platform) {
   }
   for (const target of [root, path.join(root, 'package.json'), ...entry.modulePath.split('/').map((_, i, parts) => path.join(root, ...parts.slice(0, i + 1)))]) {
     const stat = await lstat(target);
-    if (stat.isSymbolicLink() || (stat.mode & 0o022) !== 0) throw new Error('Symlink or untrusted writable installed module path');
+    if (stat.isSymbolicLink()) throw new Error(`Symlink in installed module path: ${target}`);
+    if ((stat.mode & 0o022) !== 0) throw new Error(`Installed module path is group/other-writable: ${target}. Run: chmod -R go-w ${JSON.stringify(root)}`);
     // Directory link counts reflect children, not file aliases. Hardlinked store
     // files qualify only when no permission class can write the shared inode.
     if (stat.isFile() && stat.nlink > 1 && (stat.mode & 0o222) !== 0) {
@@ -722,7 +747,29 @@ function installationStorePath() {
   return path.join(root, 'worker-installations.json');
 }
 
-async function assertTrustedStore(filename, writableRoots) {
+// HOME is the operator's trust boundary; custom stores outside it are checked
+// back to /. O_NOFOLLOW on the store itself does not protect its ancestors.
+async function assertTrustedStoreAncestors(directory) {
+  const home = path.resolve(homedir());
+  const boundary = inside(home, directory) ? home : path.parse(directory).root;
+  // The store directory itself is checked by the caller.
+  if (directory === boundary) return;
+  const ancestors = [];
+  for (let target = path.dirname(directory); ; target = path.dirname(target)) {
+    ancestors.push(target);
+    if (target === boundary) break;
+  }
+  for (const target of ancestors.reverse()) {
+    const stat = await lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o022
+      || process.getuid && stat.uid !== 0 && stat.uid !== process.getuid()) {
+      throw new Error(`Untrusted installation store ancestor: ${target}`);
+    }
+  }
+}
+
+async function assertTrustedStore(filename, writableRoots, repairDirectory = false, apply = false) {
+  const changes = [];
   const canonical = await canonicalFuturePath(filename);
   if (canonical !== filename) throw new Error('Symlinked installation store');
   for (const root of writableRoots) {
@@ -731,10 +778,35 @@ async function assertTrustedStore(filename, writableRoots) {
   for (const target of [path.dirname(filename), filename]) {
     try {
       const stat = await lstat(target);
-      if (stat.isSymbolicLink() || (stat.mode & 0o022) || stat.isFile() && stat.nlink !== 1
-        || process.getuid && stat.uid !== process.getuid()) throw new Error('Untrusted installation store permissions');
+      if (process.getuid && stat.uid !== process.getuid()) throw new Error(`Installation store path is owned by another user: ${target}`);
+      if (stat.isSymbolicLink() || stat.isFile() && stat.nlink !== 1
+        || target === path.dirname(filename) && !stat.isDirectory()
+        || target === filename && !stat.isFile()) throw new Error(`Untrusted installation store permissions: ${target}`);
+      if (stat.mode & 0o022) {
+        if (!repairDirectory || target !== path.dirname(filename) || !process.getuid) {
+          throw new Error(`Untrusted installation store permissions: ${target}`);
+        }
+        await assertTrustedStoreAncestors(target);
+        changes.push({ path: target, action: 'chmod go-w' });
+        if (apply) {
+          const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_DIRECTORY);
+          try {
+            const current = await handle.stat();
+            if (current.uid !== process.getuid() || current.ino !== stat.ino || current.dev !== stat.dev) {
+              throw new Error(`Installation store directory changed: ${target}`);
+            }
+            await handle.chmod(current.mode & ~0o022);
+          } finally { await handle.close(); }
+        }
+      }
     } catch (error) { if (error.code !== 'ENOENT') throw error; }
   }
+  return changes;
+}
+
+/** Qualification's confirmed write may secure its own directory; ordinary readers never repair. */
+export async function prepareWorkerInstallationStore({ workerWritableRoots, apply = false }) {
+  return assertTrustedStore(installationStorePath(), workerWritableRoots, true, apply);
 }
 
 async function readInstallationStore(filename, expectedDigest) {
@@ -775,7 +847,7 @@ export async function recordWorkerInstallation(instance, options) {
   delete installation.environment;
   delete installation.adapter;
   delete installation.now;
-  const record = { cli, binding: { ...structuredClone(binding), boundary: installation.boundary }, adapter,
+  const record = { cli, ...(options.modelObservations ? { modelObservations: structuredClone(options.modelObservations) } : {}), binding: { ...structuredClone(binding), boundary: installation.boundary }, adapter,
     installation: { ...installation, environmentNames, versionProbe: { rawBanner: result.rawVersionBanner, version: result.cliVersion } },
     ...(options.mcpSchemas ? { mcpSchemas: structuredClone(options.mcpSchemas) } : {}),
     ...(options.mcpProfile ? { mcpProfile: structuredClone(options.mcpProfile) } : {}) };
@@ -789,9 +861,9 @@ export async function recordWorkerInstallation(instance, options) {
   return result;
 }
 
-/** Read recorded host authority, validate installation bytes, then load the same
- * approved factory used by Ralph. Resolution never launches a version probe. */
-export async function loadRecordedWorkerInstallations({ registry, cwd, policy, storePath, storeDigest }) {
+/** Read recorded host authority, validate installation bytes and the current CLI
+ * version, then load the same approved factory used by Ralph. */
+export async function loadRecordedWorkerInstallations({ registry, cwd, policy, parallelism, storePath, storeDigest }) {
   const { WorkerPolicyError, parseProviderModelCapabilities } = await import('./provider-policy.js');
   const { qualificationDigest } = await import('./qualification-digest.mjs');
   const fail = () => new WorkerPolicyError('OG_ADAPTER_UNQUALIFIED', 'Trusted installation qualification is required');
@@ -805,6 +877,7 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, s
   catch { throw fail(); }
   const installations = {};
   const drivers = {};
+  const observations = {};
   const resolvedRegistry = structuredClone(registry);
   const counts = new Map();
   for (const record of stored.registrations) counts.set(record?.cli, (counts.get(record?.cli) ?? 0) + 1);
@@ -825,8 +898,8 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, s
       const proof = adapter.invocationProfiles?.[binding.profile]?.installationQualification;
       if (!proof || ['scopeDigest', 'fixtureDigest', 'verifiedAt', 'evidenceRef'].some(key => proof[key] !== installation.evidence?.[key])) throw fail();
       // Reject expired/unbound negative observations before any factory import.
-      const { requiredWorkerControls } = await import('./provider-policy.js');
-      installation.requiredControls = requiredWorkerControls(installation);
+      const { requiredWorkerControls, isOperatorQualifiedWorkerAdapter } = await import('./provider-policy.js');
+      if (!isOperatorQualifiedWorkerAdapter(adapter)) installation.requiredControls = requiredWorkerControls(installation);
       await assertWorkerInstallationEvidence(installation, proof.scopeDigest);
       await assertTrustedStore(filename, installation.workerWritableRoots);
       const candidateRegistry = structuredClone(resolvedRegistry);
@@ -842,7 +915,31 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, s
         workerWritableRoots: installation.workerWritableRoots, platform: process.platform });
       const instance = createProvider(adapter.id);
       const { scope } = await recheckWorkerInstallation(instance, installation);
+      if (parallelism && isOperatorQualifiedWorkerAdapter(adapter)) {
+        const { resolveWorkerGroupInstallation } = await import('../config/aiwg-config.js');
+        const configured = resolveWorkerGroupInstallation(parallelism, cli, candidateRegistry);
+        let executable = configured.executable;
+        if (!path.isAbsolute(executable)) {
+          if (executable.includes(path.sep)) executable = path.resolve(cwd, executable);
+          else {
+            const candidates = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean).map(directory => path.resolve(directory, executable));
+            executable = null;
+            for (const candidate of candidates) {
+              try { await binaryIdentity(candidate, installation.workerWritableRoots); executable = candidate; break; } catch { /* Next PATH entry. */ }
+            }
+          }
+        }
+        if (!executable || await realpath(executable) !== scope.binary.realpath) throw fail();
+      }
       if (scope.scopeDigest !== proof.scopeDigest) throw fail();
+      // A launcher can keep the same bytes while its CLI payload is updated.
+      // Reuse the bounded, credential-free doctor probe before granting authority.
+      const { version } = await boundedVersionProbe(scope.binary.realpath,
+        adapter.invocation.versionArgv, workerVersionProbeEnvironment(), cwd,
+        workerVersionProbeDefaults.timeoutMs, workerVersionProbeDefaults.maxBytes,
+        adapter.invocation.versionPattern);
+      if (version !== binding.cliVersion
+        || (await inspectWorkerInstallation(instance, installation)).scopeDigest !== scope.scopeDigest) throw fail();
       const profile = adapter.invocationProfiles[binding.profile];
       let mcpRegistry;
       if (profile.transport === 'mcp') {
@@ -870,10 +967,20 @@ export async function loadRecordedWorkerInstallations({ registry, cwd, policy, s
         prepareWorkerInvocation: (invocation, qualification) => prepareInstalledWorkerInvocation(instance, invocation, qualification),
         ...(mcpRegistry ? { mcpRegistry, mcpProfile: record.mcpProfile } : {}),
       };
+      registerWorkerRecoveryCapabilities(drivers[cli], {
+        ...(typeof instance.parseWorkerAttemptFinal === 'function'
+          ? { parseWorkerAttemptFinal: (output, options) => instance.parseWorkerAttemptFinal(output, options) } : {}),
+        // Adapters with neither an explicit signal nor an attempt parser cannot
+        // verify success (e.g. OpenHuman); never admit an unreachable canary.
+        canVerifyAttempt: typeof instance.supportsAttemptVerification === 'function'
+          ? !!instance.supportsAttemptVerification()
+          : typeof instance.parseWorkerAttemptFinal === 'function',
+      });
       installations[cli] = structuredClone(binding);
+      if (record.modelObservations) observations[cli] = structuredClone(record.modelObservations);
       Object.assign(resolvedRegistry, candidateRegistry);
     } catch { /* One missing/changed installation cannot grant authority or hide qualified peers. */ }
   }
   if (!Object.keys(installations).length) throw fail();
-  return { registry: resolvedRegistry, installations, drivers };
+  return { registry: resolvedRegistry, installations, drivers, observations };
 }

package/dist/src/process/bounded-child-process.d.mts

@@ -0,0 +1,84 @@
+import type {
+  ExecFileSyncOptions,
+  ExecFileSyncOptionsWithBufferEncoding,
+  ExecFileSyncOptionsWithStringEncoding,
+  ExecSyncOptions,
+  ExecSyncOptionsWithBufferEncoding,
+  ExecSyncOptionsWithStringEncoding,
+  SpawnSyncOptions,
+  SpawnSyncOptionsWithBufferEncoding,
+  SpawnSyncOptionsWithStringEncoding,
+  SpawnSyncReturns,
+} from 'node:child_process';
+
+export type SyncProcessTier = 'quick' | 'network' | 'long';
+
+export const AIWG_SYNC_LONG_TIMEOUT_MS_ENV: 'AIWG_SYNC_LONG_TIMEOUT_MS';
+
+export const SYNC_PROCESS_TIER_BOUNDS_MS: Readonly<{
+  quick: number;
+  network: number;
+  long: number;
+}>;
+
+export function resolveSyncProcessTimeoutMs(tier: SyncProcessTier): number;
+
+export function positiveTimeoutMs(value: unknown, fallbackMs: number): number;
+
+// Overloads mirror Node's own execSync/execFileSync/spawnSync overload set
+// (string vs Buffer return type keyed on `options.encoding`), with the
+// required `tier` inserted right before `options` — same narrowing behavior
+// callers get from the native APIs, e.g. `.trim()` on the result when
+// `encoding: 'utf8'` is set.
+
+export function boundedExecSync(command: string, tier: SyncProcessTier): Buffer;
+export function boundedExecSync(command: string, tier: SyncProcessTier, options: ExecSyncOptionsWithStringEncoding): string;
+export function boundedExecSync(command: string, tier: SyncProcessTier, options: ExecSyncOptionsWithBufferEncoding): Buffer;
+export function boundedExecSync(command: string, tier: SyncProcessTier, options?: ExecSyncOptions): string | Buffer;
+
+export function boundedExecFileSync(file: string, args: readonly string[], tier: SyncProcessTier): Buffer;
+export function boundedExecFileSync(
+  file: string,
+  args: readonly string[],
+  tier: SyncProcessTier,
+  options: ExecFileSyncOptionsWithStringEncoding,
+): string;
+export function boundedExecFileSync(
+  file: string,
+  args: readonly string[],
+  tier: SyncProcessTier,
+  options: ExecFileSyncOptionsWithBufferEncoding,
+): Buffer;
+export function boundedExecFileSync(
+  file: string,
+  args: readonly string[],
+  tier: SyncProcessTier,
+  options?: ExecFileSyncOptions,
+): string | Buffer;
+
+export function boundedSpawnSync(command: string, args: readonly string[], tier: SyncProcessTier): SpawnSyncReturns<Buffer>;
+export function boundedSpawnSync(
+  command: string,
+  args: readonly string[],
+  tier: SyncProcessTier,
+  options: SpawnSyncOptionsWithStringEncoding,
+): SpawnSyncReturns<string>;
+export function boundedSpawnSync(
+  command: string,
+  args: readonly string[],
+  tier: SyncProcessTier,
+  options: SpawnSyncOptionsWithBufferEncoding,
+): SpawnSyncReturns<Buffer>;
+export function boundedSpawnSync(
+  command: string,
+  args: readonly string[],
+  tier: SyncProcessTier,
+  options?: SpawnSyncOptions,
+): SpawnSyncReturns<string | Buffer>;
+
+/** Async launch with direct-child timeout and cleanup before termination. */
+export function boundedSpawn(
+  command: string, args: readonly string[], tier: SyncProcessTier,
+  options: import('node:child_process').SpawnOptions,
+  onTermination?: () => void,
+): Promise<{ status: number | null; signal: NodeJS.Signals | null; error?: Error; pid?: number }>;

package/dist/src/process/bounded-child-process.mjs

@@ -70,10 +70,12 @@
  */
 
 import {
+  spawn,
   execSync as nodeExecSync,
   execFileSync as nodeExecFileSync,
   spawnSync as nodeSpawnSync,
 } from 'node:child_process';
+import { signalChild } from './signal-child.mjs';
 
 /** Env var that raises or disables the `long` tier bound. `0` disables it (no timeout). */
 export const AIWG_SYNC_LONG_TIMEOUT_MS_ENV = 'AIWG_SYNC_LONG_TIMEOUT_MS';
@@ -385,3 +387,44 @@ export function boundedSpawnSync(command, args, tier, options) {
   enrichTimeoutError(result.error, { description: describeCommand(command, args), tier, boundMs, signal: result.signal });
   return result;
 }
+
+/** Async counterpart for launches that must clean owned files on termination.
+ * Like the sync wrappers, this supervises the direct child only. */
+export async function boundedSpawn(command, args, tier, options, onTermination = () => {}) {
+  assertValidTier(tier);
+  const boundMs = effectiveTimeoutMs(tier, options);
+  const { timeout: _timeout, killSignal: _killSignal, ...nodeOptions } = toNodeOptions(options, boundMs);
+  let child;
+  let timer;
+  let timedOut = false;
+  const handlers = new Map();
+  try {
+    child = spawn(command, args, nodeOptions);
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+      const handler = () => {
+        try { onTermination(); }
+        finally {
+          signalChild(child, 'SIGKILL');
+          // Restore the signal's normal exit semantics after cleanup.
+          process.removeListener(signal, handler);
+          process.kill(process.pid, signal);
+        }
+      };
+      handlers.set(signal, handler);
+      process.once(signal, handler);
+    }
+    if (boundMs > 0) timer = setTimeout(() => { timedOut = true; signalChild(child, 'SIGKILL'); }, boundMs);
+    return await new Promise(resolve => {
+      let spawnError;
+      child.once('error', error => { spawnError = error; });
+      child.once('close', (status, signal) => {
+        const error = timedOut ? Object.assign(new Error(`Command timed out after ${boundMs}ms`), { code: 'ETIMEDOUT' }) : spawnError;
+        enrichTimeoutError(error, { description: describeCommand(command, args), tier, boundMs, signal });
+        resolve({ status, signal, error, pid: child.pid, stdout: null, stderr: null, output: [] });
+      });
+    });
+  } finally {
+    clearTimeout(timer);
+    for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+  }
+}

package/dist/src/process/cli-command.d.mts

@@ -0,0 +1,16 @@
+export function resolveExecutable(
+  command: string,
+  platform?: NodeJS.Platform,
+  searchPath?: string,
+  pathExt?: string,
+  cwd?: string,
+): string;
+
+export function cliCommand(
+  command: string,
+  args: string[],
+  platform?: NodeJS.Platform,
+  searchPath?: string,
+  pathExt?: string,
+  cwd?: string,
+): [string, string[]];

package/dist/src/process/signal-child.d.mts

@@ -0,0 +1,6 @@
+import type { ChildProcess } from 'node:child_process';
+
+export function signalChild(
+  child: Pick<ChildProcess, 'pid' | 'kill'> | null | undefined,
+  signal?: NodeJS.Signals | number,
+): boolean;

package/dist/src/process/signal-child.mjs

@@ -0,0 +1,7 @@
+/** Signal only a child that acquired a real PID. Failed spawns can retain a
+ * native handle with PID zero until their asynchronous error event arrives.
+ * Keep native return/throw behavior so callers retain their stop semantics. */
+export function signalChild(child, signal) {
+  if (!Number.isSafeInteger(child?.pid) || child.pid <= 0) return false;
+  return !!child.kill(signal);
+}

package/dist/src/providers/deployed-skill-roots.js

@@ -0,0 +1,20 @@
+import path from 'node:path';
+import { getProviderArtifactPathStrings, getProviderKernelSkillPath } from './provider-definitions.js';
+import { resolveGrokbotSkillsDir } from './grokbot-paths.js';
+/** All shared-copier tiers, including adapter mirrors. */
+export function deployedSkillRoots(target, provider) {
+    const roots = [(getProviderArtifactPathStrings(provider) ?? getProviderArtifactPathStrings('claude'))?.skills,
+        getProviderKernelSkillPath(provider) || getProviderKernelSkillPath('claude')];
+    if (provider === 'muse')
+        roots.push('.agents/.aiwg/skills');
+    if (provider === 'grok-build')
+        roots.push('.grok/.aiwg/skills');
+    if (provider === 'grokbot') {
+        const root = resolveGrokbotSkillsDir();
+        if (root)
+            roots.push(root, path.join(root, '.aiwg', 'skills'));
+    }
+    return [...new Set(roots.filter((root) => Boolean(root))
+            .map(root => path.isAbsolute(root) ? root : path.join(target, root)))];
+}
+//# sourceMappingURL=deployed-skill-roots.js.map

package/dist/src/providers/grok-build-acp.js

@@ -1,4 +1,5 @@
 /** Grok Build ACP stdio client. Separate from one-shot headless execution. */
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 import { redactGrokOutput } from './grok-build-headless.js';
 export class GrokAcpClient {
@@ -182,9 +183,9 @@ export class GrokAcpClient {
         this.terminated = true;
         this.failAll(new Error('Grok ACP connection closed'));
         this.child.stdin.end();
-        if (!this.child.kill('SIGTERM'))
+        if (!signalChild(this.child, 'SIGTERM'))
             return;
-        const forceTimer = setTimeout(() => this.child.kill('SIGKILL'), 2_000);
+        const forceTimer = setTimeout(() => signalChild(this.child, 'SIGKILL'), 2_000);
         forceTimer.unref();
         this.child.once('close', () => clearTimeout(forceTimer));
     }

package/dist/src/providers/grok-build-headless.js

@@ -1,8 +1,13 @@
 /** Bounded Grok Build headless transport. The caller owns task authorization. */
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 const MAX_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_TIMEOUT_MS = 2 * 60_000;
 const DEFAULT_MAX_OUTPUT = 8 * 1024 * 1024;
+// grok 1.0.50 --output-format streaming-json: ACP session updates.
+// See docs/providers/grok-build-cli-evidence.md; json is a separate result object.
+const STREAM_EVENT_TYPES = new Set(['text', 'thought', 'tool_call', 'tool_call_update',
+    'usage', 'plan', 'available_commands', 'end', 'error']);
 export function redactGrokOutput(value, env = process.env) {
     let redacted = value
         .replace(/\b(Bearer\s+)[A-Za-z0-9._~+/-]+/gi, '$1[REDACTED]')
@@ -28,14 +33,14 @@ function isError(event) {
         || (['tool_call', 'tool_call_update'].includes(String(event.type)) && event.status === 'failed');
 }
 function stopProcess(child) {
-    if (child.pid && process.platform !== 'win32') {
+    if (Number.isSafeInteger(child.pid) && child.pid > 0 && process.platform !== 'win32') {
         try {
             process.kill(-child.pid, 'SIGTERM');
             return;
         }
         catch { /* process already exited */ }
     }
-    child.kill('SIGTERM');
+    signalChild(child, 'SIGTERM');
 }
 export async function runGrokHeadless(options) {
     if (!options.prompt.trim())
@@ -90,7 +95,9 @@ export async function runGrokHeadless(options) {
             if (format === 'json') {
                 try {
                     const parsed = JSON.parse(cleanStdout);
-                    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || isError(parsed) || parsed.stopReason !== 'end_turn')
+                    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)
+                        || typeof parsed.text !== 'string' || isError(parsed)
+                        || parsed.stopReason !== 'end_turn')
                         throw new Error('Grok Build returned a JSON error result');
                     events.push(parsed);
                 }
@@ -110,7 +117,8 @@ export async function runGrokHeadless(options) {
         const acceptEvent = (event) => {
             if (settled)
                 return;
-            if (!event || typeof event !== 'object' || Array.isArray(event)) {
+            if (!event || typeof event !== 'object' || Array.isArray(event)
+                || typeof event.type !== 'string' || !STREAM_EVENT_TYPES.has(event.type)) {
                 finish(new Error('Invalid Grok Build streaming-json event'));
                 return;
             }

package/dist/src/providers/grok-build-inspect.js

@@ -177,6 +177,7 @@ export function runGrokInspect(envOrOptions = process.env) {
             // npm exposes Grok through a .cmd shim on Windows; Node requires a shell
             // for .cmd/.bat launchers. Native .exe installs stay shell-free.
             shell: process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(binary),
+            killSignal: 'SIGKILL',
         });
         if (result.error && result.error.code === 'ENOENT') {
             return { status: 'absent', remediation: ABSENT_REMEDIATION };

package/dist/src/providers/omp-agent.d.mts

@@ -0,0 +1,8 @@
+export interface OmpAgentOptions {
+  diagnostics?: string[];
+  quiet?: boolean;
+  modelsConfig?: Record<string, any>;
+  modelConfig?: Record<string, any>;
+}
+export function transformAgent(src: string, content: string, opts?: OmpAgentOptions): string;
+export function mapModel(model: string | undefined, config?: Record<string, any>): string | undefined;

package/dist/src/providers/omp-diagnostics.d.mts

@@ -0,0 +1 @@
+export function diagnoseOmpRuntime(options?: {cwd?: string; env?: NodeJS.ProcessEnv; binary?: string; runner?: (...args: any[]) => Promise<{stdout: string}>}): Promise<{executable: string; available: boolean; version: string | null; paths: ReturnType<typeof import('./omp-paths.mjs').resolveOmpPaths>; reason: string | null}>;

package/dist/src/providers/omp-paths.d.mts

@@ -0,0 +1,13 @@
+export interface OmpPathOptions {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  cwd?: string;
+  platform?: string;
+  exists?: (path: string) => boolean;
+}
+export function normalizeOmpProfile(value?: string): string | undefined;
+export function resolveOmpPaths(options?: OmpPathOptions): {
+  profile?: string; configRoot: string; agentDir: string; projectDir: string;
+  resourceDirs: { agents: string; skills: string; commands: string; rules: string; behaviors: string };
+  dataDir: string; stateDir: string; cacheDir: string; sessionsDir: string;
+};

package/dist/src/providers/skill-ownership.d.mts

@@ -0,0 +1,9 @@
+export interface SkillReceipt {
+  skillSource?: string;
+  managed?: Record<string, { hash: string; frameworkSlug?: string; source?: string; version?: string }>;
+}
+export function extractFrameworkSlug(source: string): string | null;
+export function sameSkillOwner(receipt: SkillReceipt | null, skillSource: string, frameworkSlug?: string | null): boolean;
+export function canDeploySkill(receipt: SkillReceipt | null, skillSource: string, opts?: { force?: boolean }): boolean;
+export function pruneRecordedSkillFiles(skillDir: string, managed: SkillReceipt['managed'], desired: Set<string>, opts?: { dryRun?: boolean }): void;
+export function releaseSkillOwnership(skillDir: string, owner: { frameworkSlug?: string; skillSource?: string; sourceRoot?: string }, opts?: { dryRun?: boolean }): boolean | null;