@aiwg/cli 2026.10.9 → 2026.10.11

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/config/worker-group-templates.js

@@ -0,0 +1,150 @@
+import { mergeWorkerSelection } from '../models/worker-selection-policy.js';
+import { workerConfigDigest } from './worker-config-digest.js';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const escape = (value) => value.replace(/~/g, '~0').replace(/\//g, '~1');
+export function expandWorkerGroupTemplates(input, source = 'parallelism') {
+    const origins = {};
+    const errors = [];
+    if (!object(input))
+        return { parallelism: input, origins, errors };
+    const parallelism = structuredClone(input);
+    const templates = input.groupTemplates ?? {};
+    if (parallelism.groups)
+        parallelism.groups = Object.assign(Object.create(null), parallelism.groups);
+    const fail = (pointer, message) => { errors.push(`OG_POLICY_RELAXATION ${pointer}: ${message}`); };
+    const merge = (base, own, pointer) => {
+        const result = { ...base, ...own, execution: { ...base.execution, ...own.execution } };
+        delete result.template;
+        if (base.maxParallel !== undefined && own.maxParallel !== undefined) {
+            if (own.maxParallel > base.maxParallel)
+                fail(pointer, 'Template concurrency ceiling cannot be widened');
+            result.maxParallel = Math.min(base.maxParallel, own.maxParallel);
+        }
+        if (base.efforts && own.efforts) {
+            if (own.efforts.some(effort => !base.efforts.includes(effort)))
+                fail(pointer, 'Template effort ceiling cannot be widened');
+            result.efforts = own.efforts.filter(effort => base.efforts.includes(effort));
+        }
+        if (base.members && own.members) {
+            for (const member of own.members) {
+                const prior = base.members.find(candidate => candidate.id === member.id);
+                if (!prior || prior.cli !== member.cli || prior.model !== member.model
+                    || member.roles.some(role => !prior.roles.includes(role)) || prior.enabled === false && member.enabled !== false) {
+                    fail(pointer, 'Template member ceiling cannot be widened or rebound');
+                }
+            }
+        }
+        result.requiredRoles = [...new Set([...(base.requiredRoles ?? []), ...(own.requiredRoles ?? [])])];
+        if (base.dataPolicy || own.dataPolicy) {
+            const merged = mergeWorkerSelection([
+                { source, authority: 'project', digest: workerConfigDigest(base), policy: base.dataPolicy ? { dataPolicy: base.dataPolicy } : undefined },
+                { source, authority: 'project', digest: workerConfigDigest(own), policy: own.dataPolicy ? { dataPolicy: own.dataPolicy } : undefined },
+            ]);
+            for (const diagnostic of merged.diagnostics)
+                fail(`${pointer}/dataPolicy`, diagnostic.message);
+            result.dataPolicy = merged.policy.dataPolicy;
+        }
+        for (const key of Object.keys(base.execution ?? {})) {
+            const before = base.execution[key];
+            const after = own.execution?.[key];
+            // Execution constraints have no universally safe cross-profile ordering.
+            if (after !== undefined && after !== before)
+                fail(`${pointer}/execution/${key}`, 'Inherited execution control cannot change');
+        }
+        return result;
+    };
+    const shape = (value, pointer) => {
+        if (!object(value) || value.template !== undefined && typeof value.template !== 'string'
+            || value.members !== undefined && (!Array.isArray(value.members) || value.members.some((member) => !object(member) || !Array.isArray(member.roles)))
+            || value.efforts !== undefined && !Array.isArray(value.efforts)
+            || value.execution !== undefined && !object(value.execution)) {
+            errors.push(`OG_CONFIG_REFERENCE ${pointer}: Invalid group template shape`);
+            return false;
+        }
+        return true;
+    };
+    const expanded = new Map();
+    const depths = new Map();
+    const failed = new Set();
+    const expand = (name) => {
+        const pending = [];
+        const active = new Set();
+        let next = name;
+        // Collect uncached ancestors iteratively, then expand from the root down.
+        while (!expanded.has(next) && !failed.has(next)) {
+            const pointer = `/parallelism/groupTemplates/${escape(next)}`;
+            if (active.has(next)) {
+                errors.push(`OG_CONFIG_REFERENCE ${pointer}: Cyclic or excessive template nesting`);
+                failed.add(next);
+                break;
+            }
+            if (!object(templates) || !Object.hasOwn(templates, next)) {
+                errors.push(`OG_CONFIG_REFERENCE ${pointer}: Unknown template`);
+                failed.add(next);
+                break;
+            }
+            const own = templates[next];
+            if (!shape(own, pointer)) {
+                failed.add(next);
+                break;
+            }
+            active.add(next);
+            pending.push(next);
+            if (!own.template)
+                break;
+            next = own.template;
+        }
+        for (const current of pending.reverse()) {
+            const own = templates[current];
+            if (failed.has(current) || own.template && failed.has(own.template)) {
+                failed.add(current);
+                continue;
+            }
+            const depth = (own.template ? depths.get(own.template) : 0) + 1;
+            if (depth > 64) {
+                errors.push(`OG_CONFIG_REFERENCE /parallelism/groupTemplates/${escape(current)}: Cyclic or excessive template nesting`);
+                failed.add(current);
+                continue;
+            }
+            const parent = own.template ? expanded.get(own.template) : {};
+            expanded.set(current, merge(parent, own, `/parallelism/groupTemplates/${escape(current)}`));
+            depths.set(current, depth);
+        }
+        return expanded.get(name) ?? {};
+    };
+    if (object(templates))
+        for (const name of Object.keys(templates))
+            expand(name);
+    if (object(input.groups)) {
+        for (const [id, own] of Object.entries(input.groups)) {
+            const pointer = `/parallelism/groups/${escape(id)}`;
+            if (!shape(own, pointer))
+                continue;
+            const base = own.template ? expand(own.template) : {};
+            const result = merge(base, own, pointer);
+            // Existing shape validation requires members on every fully expanded group.
+            parallelism.groups[id] = result;
+            if (own.template) {
+                const names = [];
+                for (let name = own.template; name && expanded.has(name); name = templates[name].template)
+                    names.push(name);
+                names.reverse();
+                origins[`${pointer}/template`] = names.map(name => ({ source, authority: 'project',
+                    digest: workerConfigDigest(templates[name]), pointer: `/parallelism/groupTemplates/${escape(name)}`,
+                    contribution: structuredClone(templates[name]),
+                }));
+                origins[`${pointer}/template`].push({ source, authority: 'project', digest: workerConfigDigest(own), pointer, contribution: structuredClone(own) });
+            }
+        }
+    }
+    // Keep raw declarations for stable provenance; the validator checks them separately.
+    return { parallelism, origins, errors };
+}
+/** Group data declarations are further restrictions on the already merged model policy. */
+export function mergeGroupWorkerPolicy(policy, group) {
+    return mergeWorkerSelection([
+        { source: 'models:effective', authority: 'project', digest: workerConfigDigest(policy), policy },
+        { source: 'parallelism:group', authority: 'project', digest: workerConfigDigest(group), policy: group.dataPolicy ? { dataPolicy: group.dataPolicy } : undefined },
+    ]);
+}
+//# sourceMappingURL=worker-group-templates.js.map

package/dist/src/config/worker-guidance-warning.js

@@ -0,0 +1,28 @@
+// Reports guidance refresh steps after direct parallelism edits.
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { normalizeProviderDefinitionId } from '../providers/provider-definitions.js';
+export function warnStaleParallelism(cfg, projectDir, key, before) {
+    if (key !== 'parallelism' && !key.startsWith('parallelism.'))
+        return;
+    if (isDeepStrictEqual(before, getDottedPath(cfg, key)))
+        return;
+    const configured = (cfg.providers ?? []).map(normalizeProviderDefinitionId).filter((id) => !!id);
+    const recorded = Object.values(cfg.installed ?? {}).flatMap(entry => Object.keys(entry.deployedTo ?? {}))
+        .map(normalizeProviderDefinitionId).filter((id) => !!id).sort();
+    const providers = [...new Set([...configured, ...recorded])];
+    const targets = providers.length ? providers : ['<provider>'];
+    const lines = [
+        `WARNING: ${key} changed project configuration; generated workspace/provider guidance may now be stale.`,
+        `From project root ${path.resolve(projectDir)}, preview and refresh every configured or recorded provider context:`,
+        ...targets.flatMap(provider => [
+            `  aiwg regenerate --workspace --provider ${provider} --dry-run`,
+            `  aiwg regenerate --workspace --provider ${provider}`,
+        ]),
+        '  aiwg workspace-context doctor',
+        `Shared parallelism defaults and labels use primary provider '${cfg.providers?.[0] ?? 'unknown'}' (providers[0]); --provider selects the adapter/context target.`,
+    ];
+    console.error(lines.join('\n'));
+}
+function getDottedPath(value, key) { return key.split('.').reduce((node, part) => node?.[part], value); }
+//# sourceMappingURL=worker-guidance-warning.js.map

package/dist/src/config/worker-owner-lock.js

@@ -0,0 +1,152 @@
+// Publishes complete owner identities atomically and fences dead-owner takeover by generation.
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { mkdir, writeFile, symlink, readlink, unlink, rm, readdir } from 'node:fs/promises';
+import { readFileSync, readlinkSync } from 'node:fs';
+import { projectControlPath } from './project-artifacts.js';
+export const workerWriteLock = (project) => projectControlPath(project, 'aiwg.config.apply-lock');
+const missing = (error) => error.code === 'ENOENT';
+function processStart(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return `${readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim()}:${stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19]}`;
+    }
+    catch {
+        return null;
+    }
+}
+function identity() {
+    return { generation: randomUUID(), host: hostname(), pid: process.pid, start: processStart(process.pid) };
+}
+function provablyDead(owner) {
+    if (owner.released)
+        return true; // The operation ended and explicitly relinquished exclusion.
+    if (owner.host !== hostname() || !Number.isSafeInteger(owner.pid) || owner.pid <= 0)
+        return false;
+    try {
+        process.kill(owner.pid, 0);
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+    const start = processStart(owner.pid);
+    return typeof owner.start === 'string' && owner.start.length > 0 && start !== null && owner.start !== start;
+}
+function latest(directory) {
+    let owner = JSON.parse(readFileSync(join(directory, 'owner.json'), 'utf8'));
+    // Immutable successor links are a compare-and-swap: only one contender can claim a generation.
+    for (;;) {
+        if (!/^[a-f0-9-]{36}$/.test(owner.generation))
+            throw new Error('Invalid worker lock generation');
+        try {
+            owner = JSON.parse(readlinkSync(join(directory, `next-${owner.generation}`)));
+        }
+        catch (error) {
+            if (missing(error))
+                return owner;
+            throw error;
+        }
+    }
+}
+async function sweepOrphanedOwners(path) {
+    const parent = dirname(path);
+    const prefix = `${basename(path)}.`;
+    for (const entry of await readdir(parent, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !entry.name.startsWith(prefix) || !/^[a-f0-9-]{36}$/.test(entry.name.slice(prefix.length)))
+            continue;
+        const directory = join(parent, entry.name);
+        let owner;
+        try {
+            owner = latest(directory);
+        }
+        catch {
+            continue;
+        } // Incomplete or unreadable identities cannot prove death.
+        if (!provablyDead(owner))
+            continue;
+        try {
+            if (resolve(parent, await readlink(path)) === directory)
+                continue;
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+function lease(path, directory, owner) {
+    const assertOwned = () => {
+        try {
+            if (readlinkSync(path) === basename(directory) && latest(directory).generation === owner.generation)
+                return;
+        }
+        catch { /* Missing or replaced ownership must never authorize another write. */ }
+        throw new Error(`Worker configuration lock ownership lost (${owner.generation}); dispatch remains closed at ${path}`);
+    };
+    return { path, generation: owner.generation, assertOwned, release: async (keepBlocked = false) => {
+            assertOwned();
+            if (keepBlocked) {
+                // A caught failure can be retried even while this embedding process stays alive.
+                await symlink(JSON.stringify({ ...identity(), released: true }), join(directory, `next-${owner.generation}`));
+            }
+            else {
+                // A live owner cannot be reclaimed; unlink only while we still own this exact generation.
+                await unlink(path);
+                await rm(directory, { recursive: true });
+            }
+        } };
+}
+export async function acquireWorkerWriteLock(project, block = false, proposalDigest) {
+    const path = workerWriteLock(project);
+    const owner = { ...identity(), ...(proposalDigest ? { proposalDigest } : {}) };
+    const directory = `${path}.${owner.generation}`;
+    await mkdir(dirname(path), { recursive: true });
+    await sweepOrphanedOwners(path);
+    await mkdir(directory);
+    try {
+        await writeFile(join(directory, 'owner.json'), JSON.stringify(owner), { mode: 0o600 });
+        if (block)
+            await writeFile(join(directory, 'blocked'), 'Worker policy apply/recovery in progress.\n', { mode: 0o600 });
+        // No visible lock can exist without an owner, even if initialization is interrupted.
+        await symlink(basename(directory), path);
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        if (error.code === 'EEXIST')
+            throw new Error(`Worker configuration is locked: ${path}; use authorized recovery after its owner exits`);
+        throw error;
+    }
+    return lease(path, directory, owner);
+}
+export async function reclaimWorkerWriteLock(project) {
+    const path = workerWriteLock(project);
+    let directory;
+    let previous;
+    try {
+        directory = resolve(dirname(path), await readlink(path));
+        previous = latest(directory);
+    }
+    catch (error) {
+        if (missing(error))
+            throw new Error(`No interrupted apply; nothing to recover at ${path}`);
+        throw error;
+    }
+    if (!provablyDead(previous))
+        throw new Error(`Worker configuration is locked by a live or unverifiable owner (${previous.host}:${previous.pid}); ${path}`);
+    const owner = identity();
+    try {
+        await symlink(JSON.stringify(owner), join(directory, `next-${previous.generation}`));
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`Worker configuration is locked: another recovery claimed generation ${previous.generation}`);
+        throw error;
+    }
+    const result = lease(path, directory, owner);
+    result.assertOwned();
+    await writeFile(join(directory, 'blocked'), 'Worker policy recovery in progress.\n', { mode: 0o600 });
+    return result;
+}
+//# sourceMappingURL=worker-owner-lock.js.map