@aiwg/cli 2026.10.5 → 2026.10.7

package/dist/src/cli/handlers/models.js

@@ -8,7 +8,7 @@ import { isDeepStrictEqual } from 'node:util';
 import path from 'node:path';
 import { glob } from 'glob';
 import { load as loadYaml } from 'js-yaml';
-import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, loadProviderModelCapabilities, WorkerPolicyError, } from '../../models/provider-policy.js';
+import { compileModelPolicy, validateCanonicalModelPolicy, validateUserProjectModelConfig, loadProviderModelCapabilities, WorkerPolicyError, assertWorkerRoleEffort, } from '../../models/provider-policy.js';
 import { resolveGrokBuildRoleModel } from '../../models/grok-build-models.js';
 import { readAiwgConfig, emptyConfig } from '../../config/aiwg-config.js';
 import { ConfigLoader } from '../../models/config-loader.js';
@@ -39,8 +39,38 @@ export async function loadWorkerInputs(ctx) {
         return { snapshot: { config, models, modelDigests: loader.getInputDigests(), catalog,
                 registry, installations: {} }, drivers: {} };
     }
+    // Explain missing policy before a recorded approval's digest check can
+    // mask it. The host owner first preserves its missing-installation errors.
+    const parallelism = config.parallelism;
+    const precheckPolicy = () => {
+        if (!ctx.args.some(arg => arg === '--role' || arg.startsWith('--role=')))
+            return;
+        const request = parseWorkerCommandArgs(ctx.args.slice(1));
+        const members = Object.entries(parallelism.groups ?? {})
+            .filter(([id]) => !request.group || request.group === id)
+            .flatMap(([, group]) => group.members).filter(member => member.enabled !== false
+            && parallelism.clis?.[member.cli]?.enabled !== false && member.roles.includes(request.role));
+        const requiresExplicit = members.length > 0 && members.every(member => {
+            // Health metadata can identify the provider before an operator has
+            // qualified its dispatch adapter. It grants no dispatch authority.
+            const [namespace, id] = (parallelism.clis?.[member.cli]?.adapter ?? `providers:${member.cli}`).split(':');
+            const provider = namespace === 'providers' ? registry.providers[id] : undefined;
+            const adapter = namespace === 'workerAdapters' ? registry.workerAdapters?.[id]
+                : provider?.workerAdapter ?? provider?.workerHealthAdapter;
+            const observation = (catalog.discovery?.instances?.[member.cli]
+                ?? catalog.discovery?.providers?.[adapter?.provider ?? id])?.models.find(row => row.id === member.model)?.worker;
+            if (observation?.effortSupport === 'explicit')
+                return true;
+            if (observation?.effortSupport === 'not-applicable')
+                return false;
+            return adapter?.capabilities.effort === 'explicit';
+        });
+        // With no matching worker, do not invent policy needs.
+        if (members.length)
+            assertWorkerRoleEffort(models.defaults.workerSelection, request.role, requiresExplicit);
+    };
     const { registry: qualifiedRegistry, installations, drivers, observations } = await loadRecordedWorkerInstallations({
-        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection, parallelism: config.parallelism,
+        registry, cwd: ctx.cwd, policy: models.defaults.workerSelection, parallelism: config.parallelism, precheckPolicy,
     });
     catalog.discovery ??= { source: 'static', fetchedAt: new Date().toISOString(), providers: {} };
     catalog.discovery.instances = { ...catalog.discovery.instances };

package/dist/src/cli/handlers/ralph-launcher.js

@@ -62,6 +62,13 @@ export function generateLoopId(objective) {
  * Build command-line arguments for the external Ralph process
  */
 export function buildArgs(options) {
+    if (options.managedWorker) {
+        if (!options.managedAdmission)
+            throw new Error('Managed worker execution requires admission');
+        return ['--launch-worker', '--invocation', options.managedWorker.invocationPath,
+            '--run-dir', options.managedWorker.runDir, '--managed-request', options.managedAdmission.requestId,
+            '--managed-generation', String(options.managedAdmission.generation)];
+    }
     const args = [options.objective];
     args.push('--completion', options.completionCriteria);
     if (options.maxIterations) {
@@ -175,7 +182,9 @@ export async function assertRalphParallelismCap(projectRoot) {
  * Launch the external Ralph process as a detached daemon
  */
 export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
-    const orchestratorPath = getOrchestratorPath(frameworkRoot);
+    const orchestratorPath = options.managedWorker
+        ? join(frameworkRoot, 'tools', 'ralph-external', 'session-launcher.mjs')
+        : getOrchestratorPath(frameworkRoot);
     if (!existsSync(orchestratorPath)) {
         throw new AiwgError({
             code: 'ERR_RALPH_ORCHESTRATOR_MISSING',
@@ -191,6 +200,9 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
     // surprising. Tell the operator what's running and how to lift the cap.
     await assertRalphParallelismCap(projectRoot);
     const loopId = options.loopId || generateLoopId(options.objective);
+    if (loadLauncherRegistry(projectRoot).loops[loopId]?.managedAdmission) {
+        throw new Error('Managed loop identity cannot be relaunched before admission reconciliation');
+    }
     const loopDir = join(registryDir, 'loops', loopId);
     mkdirSync(loopDir, { recursive: true });
     // Create output file for the detached process
@@ -200,6 +212,17 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
     const promptFile = join(loopDir, 'prompts', '001-prompt.md');
     // Build arguments
     const args = buildArgs(options);
+    if (options.managedAdmission) {
+        const registry = loadLauncherRegistry(projectRoot);
+        registry.loops[loopId] = { loopId, pid: 0, objective: options.objective,
+            completionCriteria: options.completionCriteria, status: 'running',
+            startedAt: new Date().toISOString(), lastUpdate: new Date().toISOString(),
+            iteration: 0, maxIterations: options.managedWorker ? 1 : options.maxIterations || 5, outputFile,
+            sessionStdoutFile, sessionStderrFile, promptFile, provider: options.provider,
+            managedAdmission: { ...options.managedAdmission },
+            ...(options.managedWorker ? { managedWorker: { ...options.managedWorker } } : {}) };
+        saveLauncherRegistry(projectRoot, registry);
+    }
     // Create output file descriptors
     const { openSync, closeSync } = await import('fs');
     const outFd = openSync(outputFile, 'w');
@@ -232,6 +255,25 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
             exitCode: EXIT_CODES.GENERAL,
         });
     }
+    let managedAdmission;
+    if (options.managedAdmission) {
+        const { sampleWorkerIdentity, createWorkerIdentityCapture } = await import(join(frameworkRoot, 'tools', 'ralph-external', 'process-monitor.mjs'));
+        const capture = createWorkerIdentityCapture({ timeoutMs: 250 });
+        const identityDeadline = process.hrtime.bigint() + 250000000n;
+        let identity;
+        while (!identity && process.hrtime.bigint() < identityDeadline) {
+            if ((child.exitCode !== null && child.exitCode !== undefined) || child.signalCode)
+                break;
+            identity = capture.observe(sampleWorkerIdentity(pid));
+            if (!identity)
+                await new Promise(resolve => setTimeout(resolve, 10));
+        }
+        if (!identity?.bootId || !identity.startTicks || !Number.isSafeInteger(identity.uid)) {
+            throw new Error('managed Ralph execution identity unavailable; reconcile uncertain launch');
+        }
+        managedAdmission = { ...options.managedAdmission,
+            execution: { pid, startedAt: `${identity.bootId}:${identity.startTicks}:${identity.uid}` }, processIdentity: identity };
+    }
     // Record the loop in our launcher registry (backup to the external-multi-loop-state-manager)
     const launcherRegistry = loadLauncherRegistry(projectRoot);
     launcherRegistry.loops[loopId] = {
@@ -243,12 +285,14 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
         startedAt: new Date().toISOString(),
         lastUpdate: new Date().toISOString(),
         iteration: 0,
-        maxIterations: options.maxIterations || 5,
+        maxIterations: options.managedWorker ? 1 : options.maxIterations || 5,
         outputFile,
         sessionStdoutFile,
         sessionStderrFile,
         promptFile,
         provider: options.provider,
+        ...(managedAdmission ? { managedAdmission } : {}),
+        ...(options.managedWorker ? { managedWorker: { ...options.managedWorker } } : {}),
     };
     saveLauncherRegistry(projectRoot, launcherRegistry);
     return {
@@ -257,6 +301,7 @@ export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
         pid,
         message: `agent loop started (${loopId}). Check status: aiwg ralph-status`,
         registryPath: getRegistryPath(projectRoot),
+        ...(managedAdmission ? { execution: managedAdmission.execution } : {}),
     };
 }
 /**
@@ -341,7 +386,7 @@ export function getLoopStatuses(projectRoot, options = {}) {
             entry.stale = true;
         }
         // Auto-clean completed entries if requested
-        if (options.autoCleanCompleted && (entry.status === 'completed')) {
+        if (options.autoCleanCompleted && !entry.managedAdmission && (entry.status === 'completed')) {
             cleanupCompletedLoop(projectRoot, loopId);
             registryDirty = true;
             continue; // Don't include in statuses
@@ -372,6 +417,8 @@ export function abortLoop(projectRoot, loopId) {
     if (!entry) {
         return { success: false, message: `Loop not found: ${loopId}` };
     }
+    if (entry.managedAdmission)
+        return { success: false, message: 'Managed loop cancellation requires its current admission generation' };
     if (!isProcessAlive(entry.pid)) {
         entry.status = 'aborted';
         saveLauncherRegistry(projectRoot, registry);
@@ -391,6 +438,26 @@ export function abortLoop(projectRoot, loopId) {
         };
     }
 }
+/** Signal only the birth identity bound to this current managed reservation.
+ * Native Ralph exit/status cannot prove descendant termination, so cancellation
+ * always leaves its admission reservation uncertain for explicit reconciliation.
+ */
+export async function cancelManagedRalph(frameworkRoot, projectRoot, loopId, binding) {
+    const entry = loadLauncherRegistry(projectRoot).loops[loopId];
+    const owned = entry?.managedAdmission;
+    if (!owned?.execution || !owned.processIdentity || owned.requestId !== binding.requestId || owned.generation !== binding.generation
+        || owned.execution.pid !== binding.execution.pid || owned.execution.startedAt !== binding.execution.startedAt) {
+        return { state: 'uncertain', signalled: false };
+    }
+    const { sampleWorkerIdentity } = await import(join(frameworkRoot, 'tools', 'ralph-external', 'process-monitor.mjs'));
+    const identity = sampleWorkerIdentity(owned.execution.pid);
+    const expected = owned.processIdentity;
+    if (!identity || ['pid', 'uid', 'bootId', 'startTicks', 'executable', 'pgid', 'sessionId']
+        .some(key => identity[key] !== expected[key]))
+        return { state: 'uncertain', signalled: false };
+    const { signalOwnedWorker } = await import(join(frameworkRoot, 'tools', 'ralph-external', 'session-launcher.mjs'));
+    return { state: 'uncertain', signalled: signalOwnedWorker(identity, 'SIGTERM') };
+}
 /**
  * Resume an interrupted agent loop
  */
@@ -438,6 +505,8 @@ export async function resumeLoop(frameworkRoot, projectRoot, loopId, overrides)
             exitCode: EXIT_CODES.USAGE,
         });
     }
+    if (entry.managedAdmission)
+        throw new Error('Managed loops require policy and admission reconciliation before resume');
     const loopDir = join(registryDir, 'loops', targetLoopId);
     const outputFile = join(loopDir, 'daemon-output.log');
     // Create output file descriptor
@@ -494,6 +563,9 @@ export function cleanupCompletedLoop(projectRoot, loopId, options = {}) {
     const registryDir = getRegistryDir(projectRoot);
     const loopDir = join(registryDir, 'loops', loopId);
     const preserved = [];
+    if (loadLauncherRegistry(projectRoot).loops[loopId]?.managedAdmission) {
+        return { success: false, message: 'Managed loop artifacts require admission reconciliation before cleanup', preserved };
+    }
     // Preserve completion reports before deleting the loop directory
     if (existsSync(loopDir)) {
         try {
@@ -616,7 +688,7 @@ export function cleanupRegistry(projectRoot, keepDays = 7) {
     const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
     let cleaned = 0;
     for (const [loopId, entry] of Object.entries(registry.loops)) {
-        if (entry.status !== 'running') {
+        if (entry.status !== 'running' && !entry.managedAdmission) {
             const lastUpdate = new Date(entry.lastUpdate).getTime();
             if (lastUpdate < cutoff) {
                 delete registry.loops[loopId];

package/dist/src/cli/handlers/rules.js

@@ -68,7 +68,7 @@ export const rulesHandler = {
                     throw new Error('Invalid inventory scope');
                 const activation = list('--activation');
                 const tier = list('--tier');
-                if (activation?.some(value => !['kernel', 'summary', 'bound', 'paths', 'on-demand'].includes(value)))
+                if (activation?.some(value => !['core', 'kernel', 'summary', 'bound', 'paths', 'on-demand'].includes(value)))
                     throw new Error('Invalid activation filter');
                 if (tier?.some(value => !['critical', 'high', 'medium', 'low'].includes(value)))
                     throw new Error('Invalid tier filter');

package/dist/src/cli/handlers/script-runner.js

@@ -11,10 +11,17 @@
 import { signalChild } from '../../process/signal-child.mjs';
 import { spawn } from 'child_process';
 import path from 'path';
+import { pathToFileURL } from 'node:url';
+import { Console } from 'node:console';
+import { Writable } from 'node:stream';
+import { writeSync } from 'node:fs';
+// Embedded deployers use process-wide console/environment APIs. Serialize the
+// complete invocation (including import), and restore them even after failure.
+let deploymentQueue = Promise.resolve();
 /**
  * Default script runner implementation
  *
- * Delegates command execution to existing Node.js scripts.
+ * Embeds repeatable agent deployment passes; runs other scripts in a child.
  */
 export class DefaultScriptRunner {
     frameworkRoot;
@@ -30,12 +37,26 @@ export class DefaultScriptRunner {
      */
     async run(scriptPath, args = [], options = {}) {
         const fullPath = path.join(this.frameworkRoot, scriptPath);
+        if (scriptPath === 'tools/agents/deploy-agents.mjs'
+            && process.env.AIWG_DEPLOY_SUBPROCESS !== '1'
+            && options.env?.AIWG_DEPLOY_SUBPROCESS !== '1'
+            && !options.timeout
+            && (!options.cwd || path.resolve(options.cwd) === process.cwd())
+            // Other environment overrides can affect module initialization. Keep
+            // those callers isolated; AIWG_ROOT is resolved afresh by each pass.
+            && Object.keys(options.env ?? {}).every(key => key === 'AIWG_ROOT')) {
+            const invocation = deploymentQueue.then(() => this.runDeployment(fullPath, args, options));
+            deploymentQueue = invocation.catch(() => { });
+            return invocation;
+        }
         return new Promise((resolve) => {
             // When capture mode is enabled, stdout/stderr are piped so that
             // quiet-mode callers can suppress output. When not
             // capturing, stdio: 'inherit' lets subprocess output flow directly to
             // the terminal (verbose mode).
-            const stdio = options.capture ? 'pipe' : 'inherit';
+            const stdio = options.capture
+                ? ['pipe', options.stdoutFd ?? 'pipe', 'pipe']
+                : 'inherit';
             const child = spawn('node', [fullPath, ...args], {
                 stdio,
                 cwd: options.cwd || process.cwd(),
@@ -122,6 +143,56 @@ export class DefaultScriptRunner {
             });
         });
     }
+    async runDeployment(fullPath, args, options) {
+        const previousConsole = globalThis.console;
+        const previousRoot = process.env.AIWG_ROOT;
+        const stderrLimit = 1024 * 1024;
+        const diagnostics = [];
+        let diagnosticBytes = 0;
+        try {
+            if (options.env?.AIWG_ROOT !== undefined)
+                process.env.AIWG_ROOT = options.env.AIWG_ROOT;
+            if (options.capture) {
+                const stdout = new Writable({ write(chunk, _encoding, done) {
+                        try {
+                            if (options.stdoutFd !== undefined)
+                                writeSync(options.stdoutFd, chunk);
+                            done();
+                        }
+                        catch (error) {
+                            done(error);
+                        }
+                    } });
+                const stderr = new Writable({ write(chunk, _encoding, done) {
+                        const retained = chunk.subarray(0, stderrLimit - diagnosticBytes);
+                        if (retained.length) {
+                            diagnostics.push(Buffer.from(retained));
+                            diagnosticBytes += retained.length;
+                        }
+                        done();
+                    } });
+                globalThis.console = new Console({ stdout, stderr });
+            }
+            // Runtime loading follows the provider preparation coordinator precedent;
+            // the runner still supports arbitrary scripts via its subprocess path.
+            const deployer = await import(pathToFileURL(fullPath).href);
+            const exitCode = (await deployer.main(args, { capture: options.capture === true })) ?? 0;
+            const message = Buffer.concat(diagnostics).toString().trim();
+            return exitCode && message ? { exitCode, message } : { exitCode };
+        }
+        catch (error) {
+            const message = Buffer.concat(diagnostics).toString().trim()
+                || (error instanceof Error ? error.message : String(error));
+            return { exitCode: 1, message };
+        }
+        finally {
+            globalThis.console = previousConsole;
+            if (previousRoot === undefined)
+                delete process.env.AIWG_ROOT;
+            else
+                process.env.AIWG_ROOT = previousRoot;
+        }
+    }
 }
 /**
  * Create a script runner for the given framework root

package/dist/src/cli/handlers/serve.js

@@ -735,9 +735,11 @@ export async function startServer(opts) {
         if (!valid) {
             return c.json({ error: `Invalid register payload: ${errors}` }, 400);
         }
-        const result = executorRegistry.register(body);
-        if ('status' in result && result.status === 400) {
-            return c.json({ error: result.error }, 400);
+        const authHeader = c.req.header('authorization') ?? '';
+        const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : '';
+        const result = executorRegistry.register(body, token);
+        if ('status' in result) {
+            return c.json({ error: result.error }, result.status);
         }
         // Emit telemetry (reuse agent.spawn as closest match for executor registration)
         const resp = result;

package/dist/src/cli/handlers/sessions.js

@@ -76,6 +76,7 @@ Options:
   --manifest <path>  Override the discovery manifest path
   --provider-home <path>  Override the provider home root (testing/portable homes)
   --codex-root <path>  Authorize a shared Codex sessions/export root (repeatable)
+                   Adds to defaults separately authorized by --provider-home
   --omp-root <path>  Explicitly authorize an OMP profile sessions root
   --muse-root <path>  Explicitly authorize a Muse Code sessions root
   --dsh-root <path>  Explicitly authorize a DeepSeek Harness sessions root