@aiwg/cli 2026.10.10 → 2026.10.12

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

@@ -29,7 +29,7 @@ import { loadCliCommandsContribution, registerCliCommands, registerHooks, } from
 import { translateSkillsToCommands, providerNeedsCommands } from '../../plugin/skill-command-translator.js';
 import * as ui from '../ui.js';
 import { readAiwgConfig, writeAiwgConfig, updateInstalled, hashManifest, emptyConfig, getProjectDir, getConfigPath } from '../../config/aiwg-config.js';
-import { appendGitignore } from '../../config/gitignore.js';
+import { AIWG_RUNTIME_PATTERNS, appendGitignore } from '../../config/gitignore.js';
 import { getLogger } from '../log.js';
 import { installCockpit } from './cockpit.js';
 import { initHandler } from './init.js';
@@ -64,6 +64,7 @@ const PREPARABLE_BUILTIN_PROVIDERS = new Set(['claude', 'codex', 'cursor', 'herm
 // Distinct from agentsmith (which creates subagent personas).
 import { generate as generateContextFiles, discoverDeployedArtifacts, } from '../../smiths/context-pipeline/index.js';
 import { verifyModelWrapperDeployment } from '../../models/wrapper-deployment.js';
+import { countDeployedBundleFiles, countDeployedBundleRules } from './use-bundle-counts.js';
 import { aggregateUseDeploymentResult, buildDryRunUseResult, renderUseDeploymentResult, verifyProviderDeployment, } from '../services/deployment-verification.js';
 import { finalizeProviderTransformationReceipt, providerReceiptHasLocalSources, sourceVerificationsFromSignedWebRelease, } from '../../providers/transformation-receipt-integration.js';
 import { loadResourceTrustRootFile, resolveWebRelease, } from '../../resources/web-release.js';
@@ -501,11 +502,19 @@ function getProviderKernelSkillsPath(provider) {
 const PROVIDER_GENERATED_GITIGNORE_PATTERNS = {
     codex: ['.codex/', '.agents/'],
 };
-async function ensureProviderGeneratedDirsIgnored(projectRoot, provider, opts) {
+/**
+ * Patterns `aiwg use` ensures in the project's .gitignore on every deploy:
+ * the AIWG runtime subdirs doctor expects, plus any provider-generated dirs.
+ * Append-only via appendGitignore — operator content is never rewritten (#3635).
+ */
+export function gitignorePatternsForDeploy(provider) {
+    return [...AIWG_RUNTIME_PATTERNS, ...(PROVIDER_GENERATED_GITIGNORE_PATTERNS[provider] ?? [])];
+}
+export async function ensureProviderGeneratedDirsIgnored(projectRoot, provider, opts) {
     if (opts.dryRun)
         return;
-    const patterns = PROVIDER_GENERATED_GITIGNORE_PATTERNS[provider];
-    if (!patterns || patterns.length === 0)
+    const patterns = gitignorePatternsForDeploy(provider);
+    if (patterns.length === 0)
         return;
     try {
         const result = await appendGitignore(projectRoot, patterns);
@@ -1020,24 +1029,6 @@ async function listBundleMdStems(bundlePath, subdir) {
         return [];
     }
 }
-async function countDeployedBundleFiles(bundlePath, subdir, target, deployPath, extensions) {
-    if (!deployPath)
-        return 0;
-    const stems = await listBundleMdStems(bundlePath, subdir);
-    if (stems.length === 0)
-        return 0;
-    const destDir = resolveDeployPath(target, deployPath);
-    let count = 0;
-    for (const stem of stems) {
-        for (const ext of extensions) {
-            if (await fileExists(path.join(destDir, `${stem}${ext}`))) {
-                count++;
-                break;
-            }
-        }
-    }
-    return count;
-}
 async function listBundleSkillNameCandidates(bundlePath) {
     const skillsRoot = path.join(bundlePath, 'skills');
     try {
@@ -1099,7 +1090,7 @@ async function countBundleDeployedArtifacts(bundlePath, target, provider) {
         agents: await countDeployedBundleFiles(bundlePath, 'agents', target, paths.agents, ['.md', '.toml']),
         commands: await countDeployedBundleFiles(bundlePath, 'commands', target, paths.commands, ['.md']),
         skills: await countDeployedBundleSkills(bundlePath, target, provider),
-        rules: await countDeployedBundleFiles(bundlePath, 'rules', target, paths.rules, ['.md', '.mdc']),
+        rules: await countDeployedBundleRules(bundlePath, target, paths.rules),
     };
 }
 const SKILL_SUPPORT_REFERENCE = /(?:^|[\s`('"\[])((?:templates|references|scripts|assets)\/[A-Za-z0-9._@/+\-]+)(?=$|[\s`)'"\],:;])/gm;
@@ -3513,11 +3504,10 @@ export class UseHandler {
                     try {
                         const manifestPath = path.join(addonSource, 'manifest.json');
                         const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
-                        // Provider rule aggregation may rename many source rules into one
-                        // managed index. Record this addon's contributed artifact counts,
-                        // matching framework registry semantics, rather than trying to
-                        // attribute shared aggregate filenames after deployment.
-                        const counts = await countBundleSourceArtifacts(addonSource);
+                        // Record only artifacts actually written for this provider. Bridge-only
+                        // providers (e.g. project-scope grokbot) write zero native files,
+                        // so source-manifest counts would leave phantom registry entries.
+                        const counts = await countBundleDeployedArtifacts(addonSource, target, provider);
                         const updated = updateInstalled(config, framework, provider, counts, {
                             version: manifest.version ?? (await getVersionInfo()).version,
                             source: 'bundled',

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

@@ -13,6 +13,7 @@ import fs from 'fs';
 import fsp from 'fs/promises';
 import path from 'path';
 import { createScriptRunner } from './script-runner.js';
+import { DOCTOR_HELP } from './doctor-help.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { updateInstallation } from '../../update/service.mjs';
 import { useHandler as useFrameworkHandler } from './use.js';
@@ -494,30 +495,6 @@ async function runUserScopeDoctor(verbose) {
         message: lines.join('\n') + '\n',
     };
 }
-const DOCTOR_HELP = `aiwg doctor — check AIWG installation health
-
-Usage:
-  aiwg doctor [options]
-  aiwg -doctor [options]
-  aiwg --doctor [options]
-
-Options:
-  --deployment          Verify configured provider deployments
-  --provider <name>     Limit deployment verification to one provider
-  --bundle <name>       Limit deployment verification to one bundle
-  --scope <scope>       Verification scope: project or user
-  --user                Alias for --scope user
-  --qualify             With --probe-workers, record installation and configured model/role approval
-  --yes                 Confirm worker qualification without a terminal
-  --dry-run             With --probe-workers, preview qualification without writes
-  --cli NAME            Limit worker probes/qualification to one configured CLI
-  --decision-offload    Show offline advisory decision readiness and adoption report
-  --probe-workers       Run bounded worker CLI version probes (default: config-only, no subprocess)
-  --project-local       Include project-local artifact diagnostics
-  --json                Emit machine-readable output (with --probe-workers: one worker-probe record per CLI; with --deployment: deployment verification; with --decision-offload: offline snapshot)
-  --verbose, -v         Include verbose diagnostics
-  --help, -h            Show this help
-`;
 /**
  * Handler for doctor command
  *

package/dist/src/config/aiwg-config.js

@@ -1,3 +1,4 @@
+import { validateHitlPolicy } from '../policy/hitl-validation.js';
 import { normalizeAiwgConfigCandidate } from './config-normalization.js';
 import { atomicConfigWrite, withWorkerWriteLock } from './worker-write.js';
 import { workerConfigDigest } from './worker-config-digest.js';
@@ -979,6 +980,9 @@ export async function readAiwgConfigCandidate(projectDir) {
     if (workspaceErrors.length > 0) {
         throw new Error(`Invalid .aiwg/aiwg.config:\n${workspaceErrors.join('\n')}`);
     }
+    const hitlErrors = validateHitlPolicy(parsed.authorization?.hitl);
+    if (hitlErrors.length)
+        throw new Error(hitlErrors.join("\n"));
     const authorizationErrors = parsed.authorization
         ? validateAuthorization(parsed.authorization).filter(item => item.severity === 'error')
         : [];
@@ -1050,6 +1054,9 @@ async function writeAiwgConfigUnlocked(projectDir, config) {
                 throw error;
         }
     }
+    const hitlErrors = validateHitlPolicy(config.authorization?.hitl);
+    if (hitlErrors.length)
+        throw new Error(hitlErrors.join("\n"));
     const pinConfigs = loadRulePinConfigs(projectDir, config);
     const currentCapabilities = new Set(installedRuleCapabilities(pinConfigs));
     const removed = previous ? installedRuleCapabilities({ ...pinConfigs, project: previous }).filter(id => !currentCapabilities.has(id)) : [];

package/dist/src/config/authorization-cli.js

@@ -0,0 +1,89 @@
+// Exposes HITL inspection, validation, preview, enable/revoke and signed receipts under config/steward.
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { AiwgError, EXIT_CODES } from '../cli/errors.js';
+import { getProjectDir, readAiwgConfig, writeAiwgConfig } from './aiwg-config.js';
+import { ensureAuthorization, loadHitlLayers } from '../policy/hitl-config.js';
+import { resolveHitlAuthorization } from '../policy/hitl.js';
+import { validateHitlPolicy } from '../policy/hitl-validation.js';
+export const authorizationUsage = `aiwg config authorization (also aiwg steward authorization)
+  inspect | validate [--target DIRECTORY]
+  preview --action-file FILE [--target DIRECTORY]
+  enable --policy-file FILE [--target DIRECTORY]
+  revoke [--profile NAME] [--target DIRECTORY]
+  receipt --action-file FILE [--target DIRECTORY]
+Preview is read-only. Receipt writes the decision to the existing signed effect ledger;
+it does not perform the proposed action. Action files cannot supply session authorization.`;
+const usageError = (message) => new AiwgError({ code: 'ERR_AUTHORIZATION_USAGE', message, exitCode: EXIT_CODES.USAGE });
+async function jsonFile(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        throw usageError('Authorization JSON input could not be read or parsed');
+    }
+}
+export async function authorizationCli(args, cwd = process.cwd()) {
+    if (!args.length || args.includes('--help') || args[0] === 'help') {
+        console.log(authorizationUsage);
+        return;
+    }
+    const [operation, ...rest] = args;
+    const flags = {};
+    const allowed = ['--target', ...(operation === 'enable' ? ['--policy-file'] : []),
+        ...(['preview', 'receipt'].includes(operation) ? ['--action-file'] : []), ...(operation === 'revoke' ? ['--profile'] : [])];
+    for (let i = 0; i < rest.length; i += 2) {
+        if (!allowed.includes(rest[i]) || !rest[i + 1] || rest[i + 1].startsWith('--') || flags[rest[i]])
+            throw usageError('Invalid authorization option');
+        flags[rest[i]] = rest[i + 1];
+    }
+    const target = resolve(getProjectDir({ cwd }, rest));
+    if (operation === 'inspect' || operation === 'validate') {
+        const loaded = await loadHitlLayers(target);
+        console.log(JSON.stringify(operation === 'inspect' ? loaded : { valid: true, layers: loaded.layers.length }, null, 2));
+        return;
+    }
+    if (operation === 'preview' || operation === 'receipt') {
+        if (!flags['--action-file'])
+            throw usageError('--action-file is required');
+        const action = await jsonFile(resolve(cwd, flags['--action-file']));
+        const loaded = await loadHitlLayers(target);
+        const context = { now: new Date().toISOString(), layers: loaded.layers };
+        if (operation === 'preview')
+            console.log(JSON.stringify(resolveHitlAuthorization(action, context), null, 2));
+        else {
+            const { effectSession, openLedger } = await import('../effects/host.js');
+            const { recordHitlAuthorization } = await import('../policy/hitl-receipt.js');
+            const session = await effectSession(loaded.projectDir, 'custom');
+            console.log(JSON.stringify(await recordHitlAuthorization(openLedger(session), action, context), null, 2));
+        }
+        return;
+    }
+    if (operation !== 'enable' && operation !== 'revoke')
+        throw usageError('Unknown authorization operation');
+    const config = await readAiwgConfig(target);
+    if (!config)
+        throw usageError('No project config found; initialize project config first');
+    const authorization = ensureAuthorization(config);
+    if (operation === 'enable') {
+        if (!flags['--policy-file'])
+            throw usageError('--policy-file is required');
+        const policy = await jsonFile(resolve(cwd, flags['--policy-file']));
+        const errors = validateHitlPolicy(policy);
+        if (policy === undefined || errors.length)
+            throw usageError('Invalid authorization.hitl policy');
+        authorization.hitl = { ...policy, enabled: true };
+    }
+    else if (authorization.hitl) {
+        if (flags['--profile']) {
+            if (!Object.hasOwn(authorization.hitl.profiles, flags['--profile']))
+                throw usageError('Unknown authorization profile');
+            delete authorization.hitl.profiles[flags['--profile']];
+        }
+        else
+            authorization.hitl.enabled = false;
+    }
+    await writeAiwgConfig(target, config);
+    console.log(JSON.stringify({ operation, enabled: authorization.hitl?.enabled ?? false }));
+}
+//# sourceMappingURL=authorization-cli.js.map

package/dist/src/config/cli-help.js

@@ -17,6 +17,7 @@ Subcommands:
   path                Print config directory path
   edit                Open config in $EDITOR/$VISUAL (requires a terminal)
   edit --print-path   Print the config file path instead of opening an editor
+  authorization       Inspect/validate/preview/enable/revoke bounded HITL policy
   gitignore           Show/check/fix .gitignore AIWG entries
 
 Reviewed worker policy pair (project scope, no prompts):

package/dist/src/config/cli.js

@@ -33,6 +33,11 @@ const _scriptDir = path.dirname(fileURLToPath(import.meta.url));
  * Main CLI entry point for `aiwg config <subcommand> [args]`
  */
 export async function main(args) {
+    if (args[0] === 'authorization') {
+        const { authorizationCli } = await import('./authorization-cli.js');
+        await authorizationCli(args.slice(1));
+        return;
+    }
     if (await handleWorkerAdoptionArgs(args, process.cwd(), 'config'))
         return;
     // Extract --config-dir flag before routing
@@ -291,7 +296,7 @@ async function projectConfigSet(key, raw, args, quiet = false) {
     }
     // Coerce booleans for known boolean fields
     let value = raw;
-    if (key === 'rules' || key.startsWith('rules.') || key === 'parallelism' || /^parallelism\.(worker_dispatch|worker_mode|groups|clis|admission|budgets|health|retry|activation)(\.|$)/.test(key)) {
+    if (key === 'authorization' || key.startsWith('authorization.') || key === 'rules' || key.startsWith('rules.') || key === 'parallelism' || /^parallelism\.(worker_dispatch|worker_mode|groups|clis|admission|budgets|health|retry|activation)(\.|$)/.test(key)) {
         try {
             value = JSON.parse(raw);
         }
@@ -397,6 +402,10 @@ async function projectConfigSet(key, raw, args, quiet = false) {
         ? (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : emptyConfig())
         : (await readAiwgConfig(projectDir)) ?? emptyConfig();
     const before = structuredClone(getDottedPath(cfg, key));
+    if (key.startsWith('authorization.hitl')) {
+        const { ensureAuthorization } = await import('../policy/hitl-config.js');
+        ensureAuthorization(cfg);
+    }
     setDottedPath(cfg, key, value);
     const externalLinkErrors = validateExternalLinks(cfg.externalLinks);
     if (externalLinkErrors.length > 0) {

package/dist/src/config/worker-context.js

@@ -0,0 +1,337 @@
+/**
+ * Worker AIWG context providers and launch-time bootstrap ensure (#3685).
+ *
+ * Orchestration must automatically `aiwg use` the providers configured for
+ * it, so any new worker process starts with the AIWG bootstrap in place.
+ * This module owns the config-side half: resolving WHICH providers
+ * (config `providers` plus every CLI configured under
+ * `parallelism.clis` / `parallelism.groups.*.members`, mapped through the
+ * provider registry) and checking/ensuring that bootstrap inside exactly
+ * one worker workdir (never outside it).
+ *
+ * The tools/ half (`tools/ralph-external/lib/worker-context.mjs`) loads the
+ * config through `readAiwgConfig` and injects it here; direct callers may
+ * pass an already-loaded config object instead.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { getProviderArtifactPathStrings, getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
+import { emptyConfig, readAiwgConfig, writeAiwgConfig, } from './aiwg-config.js';
+/**
+ * Typed refusal when a worker's AIWG bootstrap cannot be ensured.
+ * `remedy` names the operator action that unblocks the launch.
+ */
+export class WorkerContextBootstrapError extends Error {
+    code = 'OG_WORKER_CONTEXT_UNAVAILABLE';
+    remedy;
+    provider;
+    workdir;
+    constructor(message, remedy, opts) {
+        super(message);
+        this.name = 'WorkerContextBootstrapError';
+        this.remedy = remedy;
+        if (opts?.provider !== undefined)
+            this.provider = opts.provider;
+        if (opts?.workdir !== undefined)
+            this.workdir = opts.workdir;
+    }
+}
+/** Explicit provider lists must be non-empty arrays of deployable ids. */
+export function validateExplicitWorkerContextProviders(providers) {
+    if (!Array.isArray(providers) || providers.length === 0
+        || providers.some(p => typeof p !== 'string' || p.length === 0 || p.includes('\0') || p.includes(','))) {
+        throw new WorkerContextBootstrapError('worker context providers must be a non-empty array of provider ids', 'pass an explicit non-empty provider list, or configure providers plus orchestration CLIs in .aiwg/aiwg.config');
+    }
+    return [...new Set(providers)];
+}
+const ADAPTER_REFERENCE = /^(providers|workerAdapters):([a-z][a-z0-9-]{0,62})$/;
+/**
+ * Map one orchestration CLI id to its AIWG provider id.
+ * A CLI without an explicit `parallelism.clis` entry defaults to
+ * `providers:<cli>` (the same default `resolveWorkerGroupInstallation`
+ * applies). Non-provider adapters (e.g. `workerAdapters:local-http`) and
+ * ids the registry does not know are reported as skipped, never guessed.
+ */
+export function mapCliToProviderId(cli, parallelism) {
+    if (typeof cli !== 'string' || cli.length === 0) {
+        return { skipped: `empty CLI reference` };
+    }
+    const raw = typeof parallelism?.clis?.[cli]?.adapter === 'string'
+        && parallelism.clis[cli].adapter.length > 0
+        ? parallelism.clis[cli].adapter
+        : `providers:${cli}`;
+    const match = ADAPTER_REFERENCE.exec(raw);
+    if (!match || match[1] !== 'providers') {
+        return { skipped: `clis/${cli}: ${raw}` };
+    }
+    const provider = normalizeProviderDefinitionId(match[2]);
+    if (!provider)
+        return { skipped: `clis/${cli}: ${raw} (unknown provider)` };
+    return { provider };
+}
+/**
+ * Resolve the full worker-context provider set: the union of the config's
+ * own `providers` and every CLI configured for orchestration
+ * (`parallelism.clis` keys/adapters and the `cli` of every
+ * `parallelism.groups.*.members[]`), mapped to AIWG provider ids through
+ * the provider registry. Non-provider adapters are skipped and reported.
+ * Fails closed when the union is empty.
+ */
+export function resolveWorkerContextProvidersFromConfig(config) {
+    const providers = [];
+    const skipped = [];
+    const add = (id) => {
+        if (!providers.includes(id))
+            providers.push(id);
+    };
+    const skip = (entry) => {
+        if (!skipped.includes(entry))
+            skipped.push(entry);
+    };
+    const configured = config?.providers;
+    if (Array.isArray(configured)) {
+        for (const entry of configured) {
+            if (typeof entry !== 'string' || entry.length === 0)
+                continue;
+            // Configured providers deploy verbatim when the registry does not
+            // know them: project-local provider adapters resolve at deploy time
+            // (see the `use` handler's project-local resolution), so an unknown
+            // id here is the deployer's decision, not this resolver's.
+            add(normalizeProviderDefinitionId(entry) ?? entry);
+        }
+    }
+    const parallelism = config?.parallelism;
+    for (const cli of Object.keys(parallelism?.clis ?? {})) {
+        const mapped = mapCliToProviderId(cli, parallelism);
+        if ('provider' in mapped)
+            add(mapped.provider);
+        else
+            skip(mapped.skipped);
+    }
+    for (const [groupId, group] of Object.entries(parallelism?.groups ?? {})) {
+        for (const member of group?.members ?? []) {
+            const cli = member?.cli;
+            const mapped = mapCliToProviderId(cli, parallelism);
+            if ('provider' in mapped)
+                add(mapped.provider);
+            else
+                skip(typeof cli === 'string' && cli ? `groups/${groupId}/members cli '${cli}': ${mapped.skipped}` : `groups/${groupId}/members: ${mapped.skipped}`);
+        }
+    }
+    if (providers.length === 0) {
+        throw new WorkerContextBootstrapError('worker context deployment needs configured providers: the union of config providers and orchestration CLIs is empty'
+            + (skipped.length > 0 ? ` (skipped: ${skipped.join('; ')})` : ''), 'configure providers and/or parallelism clis/groups in .aiwg/aiwg.config, or pass an explicit provider list');
+    }
+    return { providers, skipped };
+}
+/** AIWG-managed rule-section markers written into a deployed AGENTS.md. */
+const WORKER_CONTEXT_RULE_MARKER = /<!--\s*AIWG:[A-Za-z0-9_-]+:(start|end)\s*-->/;
+/**
+ * Check that a worker workdir already carries one provider's bootstrap:
+ * the kernel artifact dirs (`use all` writes kernel skills, rules,
+ * behaviors — never the full agent/command surface) and, for providers
+ * whose contract targets AGENTS.md, the AIWG rule sections.
+ */
+export function workerContextBootstrapStatus({ workdir, provider }) {
+    const missing = [];
+    const definition = getProviderDefinition(provider);
+    if (!definition) {
+        return { present: false, missing: [`unknown provider '${provider}'`] };
+    }
+    const paths = getProviderArtifactPathStrings(provider);
+    const kernelDirs = [
+        definition.paths.kernelSkills,
+        paths?.rules ?? null,
+        paths?.behaviors ?? null,
+    ].filter((dir) => typeof dir === 'string' && dir.length > 0);
+    const requiredDirs = kernelDirs.length > 0
+        ? kernelDirs
+        : Object.values(paths ?? {}).filter((dir) => typeof dir === 'string' && dir.length > 0);
+    for (const dir of [...new Set(requiredDirs)]) {
+        const absolute = path.isAbsolute(dir) ? dir : path.join(workdir, dir);
+        let entries = null;
+        try {
+            entries = readdirSync(absolute);
+        }
+        catch {
+            entries = null;
+        }
+        if (!entries || entries.length === 0)
+            missing.push(`provider dir '${dir}'`);
+    }
+    if ((definition.context?.bootstrapTargets ?? []).includes('AGENTS.md')) {
+        let content = null;
+        try {
+            content = readFileSync(path.join(workdir, 'AGENTS.md'), 'utf8');
+        }
+        catch {
+            content = null;
+        }
+        if (!content || !WORKER_CONTEXT_RULE_MARKER.test(content)) {
+            missing.push('AGENTS.md rule sections');
+        }
+    }
+    return { present: missing.length === 0, missing };
+}
+/**
+ * Materialize the union provider set into the worker workdir's own config
+ * through the existing loader/writer (never ad-hoc JSON). Existing entries
+ * keep their order; union members absent from the worktree base are
+ * appended. A missing config is created minimal. An already-current config
+ * is left untouched so the deploy below stays the only writer.
+ */
+export async function syncWorkerContextProviders(options) {
+    const { workdir } = options;
+    if (typeof workdir !== 'string' || !path.isAbsolute(workdir)) {
+        throw new WorkerContextBootstrapError(`worker context sync needs an absolute workdir, got ${JSON.stringify(workdir)}`, 'sync worker context providers only into the worker workdir', { workdir: typeof workdir === 'string' ? workdir : undefined });
+    }
+    const providers = validateExplicitWorkerContextProviders(options.providers);
+    const read = options.readConfig ?? ((dir) => readAiwgConfig(dir));
+    const existing = await read(workdir);
+    const current = Array.isArray(existing?.providers)
+        ? existing.providers.filter((entry) => typeof entry === 'string')
+        : [];
+    const merged = [...current];
+    for (const provider of providers) {
+        if (!merged.includes(provider))
+            merged.push(provider);
+    }
+    const unchanged = merged.length === current.length && merged.every((entry, index) => entry === current[index]);
+    if (unchanged)
+        return { providers: merged, updated: false };
+    const base = existing !== null && typeof existing === 'object' && 'version' in existing
+        ? existing
+        : {};
+    const next = { ...emptyConfig(merged), ...base, providers: merged };
+    const write = options.writeConfig ?? ((dir, config) => writeAiwgConfig(dir, config));
+    await write(workdir, next);
+    return { providers: merged, updated: true };
+}
+/**
+ * Canonical one-pass deploy argv: a single `aiwg use all` invocation
+ * covering every listed provider. Never one deploy per provider:
+ * per-provider invocations rewrite AGENTS.md piecemeal and clobber each
+ * other's rule sections, while one pass keeps them all. No `--providers`
+ * flag: it feeds only the global bootstrap and the orchestrated
+ * verification report — `executeCore` resolves project-scope providers
+ * from config (`src/cli/handlers/use.ts`), ignoring both the flag and any
+ * explicitly resolved list. The supported project-scope mechanism is the
+ * configured-provider path: `syncWorkerContextProviders` first, then this
+ * single pass reads the union back from the worktree config.
+ */
+export function buildWorkerContextDeployArgs({ providers, target }) {
+    // Fail fast on a hostile list; the synced worktree config carries the set.
+    validateExplicitWorkerContextProviders(providers);
+    return ['use', 'all', '--target', target, '--yes'];
+}
+/**
+ * Ensure a worker workdir carries its CLI's AIWG bootstrap before launch.
+ * Present: no-op. Missing: sync the union set into the workdir config,
+ * then exactly one `aiwg use all` pass into the workdir (never anywhere
+ * else), then re-verify. Impossible (no binary, failed deploy, still
+ * missing afterwards): throw `WorkerContextBootstrapError` naming the
+ * remedy — the caller refuses the launch rather than starting a
+ * context-free worker.
+ */
+export async function ensureWorkerContextBootstrap(options) {
+    const { workdir, provider, aiwgBin = process.env.AIWG_BIN ?? 'aiwg', spawn = spawnSync, timeoutMs = 300000, statusFn = workerContextBootstrapStatus, } = options;
+    if (typeof workdir !== 'string' || !path.isAbsolute(workdir) || !existsSync(workdir)) {
+        throw new WorkerContextBootstrapError(`worker context bootstrap needs an existing absolute workdir, got ${JSON.stringify(workdir)}`, 'launch the worker with its resolved absolute workdir', { provider, workdir: typeof workdir === 'string' ? workdir : undefined });
+    }
+    const status = statusFn({ workdir, provider });
+    if (status.present)
+        return { ensured: false, providers: [provider], skippedBridges: [] };
+    const providers = options.providers && options.providers.length > 0
+        ? validateExplicitWorkerContextProviders(options.providers)
+        : [provider];
+    // The configured-provider path: the single pass below resolves its set
+    // from the workdir config, so the union must be materialized there
+    // first — `--providers` never reaches project-scope deploys.
+    const sync = options.syncFn ?? syncWorkerContextProviders;
+    let synced;
+    try {
+        synced = await sync({ workdir, providers });
+    }
+    catch (error) {
+        if (error instanceof WorkerContextBootstrapError)
+            throw error;
+        throw new WorkerContextBootstrapError(`worker context sync failed: ${error instanceof Error ? error.message : String(error)}`, `write the union providers into ${path.join(workdir, '.aiwg', 'aiwg.config')} (or run 'aiwg use all --target ${workdir} --yes' manually) before launch`, { provider, workdir });
+    }
+    const argv = buildWorkerContextDeployArgs({ providers: synced.providers, target: workdir });
+    const deploy = options.deployFn ?? (({ worktreePath, providers: deployProviders, aiwgBin: bin }) => {
+        // worktreePath IS the worker workdir by construction: the only
+        // `--target` ever passed is `workdir` above, and the spawn cwd is the
+        // same directory, so no deploy write can land outside it.
+        if (path.resolve(worktreePath) !== path.resolve(workdir)) {
+            throw new WorkerContextBootstrapError(`refusing worker context deploy outside the worker workdir (${worktreePath} !== ${workdir})`, 'deploy worker context only into the worker workdir', { provider, workdir });
+        }
+        const result = spawn(bin, argv, { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
+        if (result.error) {
+            throw new WorkerContextBootstrapError(`worker context deploy failed to run (${result.error?.message});`
+                + ` missing in ${workdir}: ${status.missing.join('; ')}`, `install the aiwg CLI on PATH or set AIWG_BIN to its location (tried '${bin}'),`
+                + ` or run 'aiwg ${argv.join(' ')}' manually before launch`, { provider, workdir });
+        }
+        if (result.status !== 0) {
+            throw new WorkerContextBootstrapError(`worker context deploy exited ${result.status}: ${String(result.stderr ?? '').trim().slice(0, 2000)};`
+                + ` missing in ${workdir}: ${status.missing.join('; ')}`, `run 'aiwg ${argv.join(' ')}' manually and resolve the reported failure before launch`, { provider, workdir });
+        }
+        return { providers: [...deployProviders] };
+    });
+    let deployed;
+    try {
+        deployed = await deploy({ worktreePath: workdir, providers: synced.providers, aiwgBin });
+    }
+    catch (error) {
+        if (error instanceof WorkerContextBootstrapError)
+            throw error;
+        throw new WorkerContextBootstrapError(`worker context deploy failed: ${error instanceof Error ? error.message : String(error)};`
+            + ` missing in ${workdir}: ${status.missing.join('; ')}`, `run 'aiwg ${argv.join(' ')}' manually and resolve the reported failure before launch`, { provider, workdir });
+    }
+    const after = statusFn({ workdir, provider });
+    if (!after.present) {
+        throw new WorkerContextBootstrapError(`worker context deploy did not produce the bootstrap: still missing in ${workdir}: ${after.missing.join('; ')}`, `run 'aiwg ${argv.join(' ')}' manually and verify the provider bootstrap before launch`, { provider, workdir });
+    }
+    // Keep deploy-touched tracked bridges out of the worker diff. A workdir
+    // outside any git repository has no tracked files; skip silently there.
+    let skippedBridges = [];
+    if (options.skipWorktreeFn) {
+        skippedBridges = options.skipWorktreeFn({ workdir });
+    }
+    else {
+        try {
+            skippedBridges = flagDeployDirtiedSkipWorktree({ workdir, spawn, timeoutMs });
+        }
+        catch {
+            skippedBridges = [];
+        }
+    }
+    return { ensured: true, providers: [...deployed.providers], skippedBridges };
+}
+/** Tracked files the deploy modified, hidden from the worker diff. */
+export function flagDeployDirtiedSkipWorktree({ workdir, spawn = spawnSync, timeoutMs = 30000 }) {
+    const status = spawn('git', ['status', '--porcelain=v1', '--untracked-files=no'], { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
+    if (status.error)
+        throw new Error(`git status failed: ${status.error?.message}`);
+    if (status.status !== 0)
+        throw new Error(`git status exited ${status.status}`);
+    const files = [];
+    for (const line of String(status.stdout ?? '').split('\n')) {
+        if (!line.trim())
+            continue;
+        const raw = line.slice(3);
+        const arrow = raw.indexOf(' -> ');
+        const rel = arrow >= 0 ? raw.slice(arrow + 4) : raw;
+        if (!rel || rel.startsWith('"'))
+            throw new Error(`worker context deploy dirtied an unflaggeable path: ${line}`);
+        files.push(rel);
+    }
+    if (files.length > 0) {
+        const flag = spawn('git', ['update-index', '--skip-worktree', '--', ...files], { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
+        if (flag.error || flag.status !== 0) {
+            throw new Error(`git update-index --skip-worktree failed: ${flag.error?.message ?? String(flag.stderr ?? '').trim()}`);
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=worker-context.js.map

package/dist/src/decision/context-pruning.js

@@ -1,3 +1,4 @@
+import { ceilingDecision } from '../gates/lattice.js';
 import { ContextBudgetManager } from '../metrics/context-budget.js';
 import { sha256 } from './compile-cache/identity.js';
 import { admitEntry } from './entry.js';
@@ -436,9 +437,9 @@ export function buildContextPruningEvaluationReport(input) {
         findings.add(`missing-input:${name}`);
     // Automatic rollback triggers from the D26 rollout plan: protected miss, demonstrated quality harm, negative
     // economics. An inconclusive non-inferiority result (no evidence of harm) holds instead.
-    const rollback = upstreamDecision === 'ROLLBACK' || findings.has('protected-retention-breach')
+    const rollback = findings.has('protected-retention-breach')
         || findings.has('quality-harm') || findings.has('negative-net-economics');
-    const decision = rollback ? 'ROLLBACK' : upstreamDecision === 'HOLD' || findings.size > 0 ? 'HOLD' : 'PROMOTE';
+    const decision = ceilingDecision(upstreamDecision, rollback ? 'ROLLBACK' : findings.size > 0 ? 'HOLD' : 'PROMOTE');
     const advisory = [...findings].some(item => item.startsWith('insufficient-') || item.startsWith('quality-metric-missing:')
         || item.startsWith('missing-input:') || item.startsWith('quality-outcomes-incomplete:')
         || item.startsWith('quality-non-inferiority-inconclusive:')