@aiwg/cli 2026.10.1 → 2026.10.4

package/dist/src/mcp/helpers.mjs

@@ -5,11 +5,113 @@
  * @issues #1311 (scope split), #1312 (command-run), #1313 (discover + pairs)
  */
 
+import { signalChild } from '../process/signal-child.mjs';
 import { spawn } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+/** Existing MCP owners have not qualified worker contracts; fail before handoff. */
+const MISSION_WORKER_SCHEMA_ID = 'https://aiwg.io/schemas/mission.aiwg.io/v1';
+const MISSION_WORKER_DEFINITIONS = new Set([
+  'workerArtifact',
+  'workerEffort',
+  'workerTuple',
+  'workerLimits',
+  'workerSelectionIntent',
+  'workerBrief',
+  'workerClaims',
+  'workerUsage',
+  'workerExecution',
+  'workerVerification',
+  'workerResult',
+  'workerDispatch',
+  'workerDirectIntent',
+  'workerDirectBrief',
+  'workerResolvedInvocation',
+  'workerDirectVerification',
+  'workerDirectResult',
+  'workerHealthSummary',
+  'workerEffectiveHealth',
+]);
+
+// Resolve against the owning schema, never infer ownership from a $defs name.
+function workerContractReference(reference, base = 'https://aiwg.invalid/local-schema') {
+  if (typeof reference !== 'string') return false;
+  try {
+    const resolved = new URL(reference, base);
+    const fragment = decodeURIComponent(resolved.hash).split('/');
+    resolved.hash = '';
+    return resolved.href === MISSION_WORKER_SCHEMA_ID
+      && fragment[0] === '#' && fragment[1] === '$defs'
+      && MISSION_WORKER_DEFINITIONS.has(fragment[2]);
+  } catch {
+    return false;
+  }
+}
+
+export function assertNoWorkerBinding(value, consumer) {
+  const seenExtensions = new Set();
+  const seenRecords = new Set();
+  const seenSchemas = new Map();
+  function unsupported() {
+    const error = new Error(`OG_CONTRACT_UNSUPPORTED: ${consumer} does not advertise worker contract support.`);
+    error.code = 'OG_CONTRACT_UNSUPPORTED';
+    throw error;
+  }
+  function extensions(item) {
+    if (!item || typeof item !== 'object' || Array.isArray(item) || seenExtensions.has(item)) return;
+    seenExtensions.add(item);
+    if (Object.hasOwn(item, 'aiwg.worker-dispatch')) unsupported();
+    for (const [key, child] of Object.entries(item)) if (key.startsWith('aiwg.source.')) {
+      extensions(child);
+      record(child);
+    }
+  }
+  function schema(item, inheritedBase = 'https://aiwg.invalid/local-schema') {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return;
+    let base = inheritedBase;
+    if (typeof item.$id === 'string') {
+      try { base = new URL(item.$id, inheritedBase).href; } catch { /* invalid schemas belong to validation */ }
+    }
+    const bases = seenSchemas.get(item) ?? new Set();
+    if (bases.has(base)) return;
+    bases.add(base);
+    seenSchemas.set(item, bases);
+    if (workerContractReference(item.$ref, base) || workerContractReference(item.schemaRef, base)) unsupported();
+    // Only JSON Schema subschemas inherit an owner. const/default/examples
+    // and properties' names are data, not active references or extensions.
+    for (const key of ['$defs', 'definitions', 'properties', 'patternProperties', 'dependentSchemas', 'dependencies']) {
+      for (const child of Object.values(item[key] ?? {})) schema(child, base);
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+      if (Array.isArray(item[key])) for (const child of item[key]) schema(child, base);
+    }
+    for (const key of ['items', 'additionalItems', 'additionalProperties', 'unevaluatedItems', 'unevaluatedProperties', 'contains', 'propertyNames', 'not', 'if', 'then', 'else']) {
+      if (Array.isArray(item[key])) for (const child of item[key]) schema(child, base);
+      else schema(item[key], base);
+    }
+  }
+  function record(item) {
+    if (!item || typeof item !== 'object' || Array.isArray(item) || seenRecords.has(item)) return;
+    seenRecords.add(item);
+    // All mission-v1 carriers: /extensions and /status/artifacts/*/extensions.
+    extensions(item.extensions);
+    if (Array.isArray(item.status?.artifacts)) item.status.artifacts.forEach(record);
+    // Native protocols also use metadata and top-level artifacts.
+    extensions(item.metadata);
+    if (Array.isArray(item.artifacts)) item.artifacts.forEach(record);
+    if (typeof item.$ref === 'string' || typeof item.schemaRef === 'string'
+      || typeof item.$id === 'string' || typeof item.$schema === 'string') schema(item);
+    schema(item.schema);
+    if (workerContractReference(item.output?.schemaRef)) unsupported();
+    // Existing sandbox response envelopes own these records explicitly.
+    record(item.workload);
+    if (item.document_type === 'inventory' && Array.isArray(item.records)) item.records.forEach(record);
+  }
+  record(value);
+}
+
 /**
  * Resolve AIWG_ROOT, with safe fallback to known install locations.
  */
@@ -49,11 +151,14 @@ function parseProjectArtifactLocation(contents) {
   return null;
 }
 
-export async function resolveProjectAiwgDir(projectDir) {
+// MCP artifact I/O resolves pointers and environment configuration when each
+// project is first trusted, then pins the resulting store.
+export async function resolveProjectAiwgDir(projectDir, { allowLocationPointer = true, env = process.env } = {}) {
   for (const key of ARTIFACT_PATH_ENV_ALIASES) {
-    const value = process.env[key];
+    const value = env[key];
     if (typeof value === 'string' && value.trim()) return expandProjectArtifactPath(value, projectDir);
   }
+  if (!allowLocationPointer) return path.resolve(projectDir, '.aiwg');
   try {
     const pointer = await fs.readFile(path.join(projectDir, PROJECT_AIWG_LOCATION_FILE), 'utf-8');
     const configured = parseProjectArtifactLocation(pointer);
@@ -183,11 +288,11 @@ export function runAiwgCli(args, { cwd, env, timeoutMs = 120_000, input } = {})
       // owned child one second to exit gracefully, then escalate cleanup.
       reject(err);
       killTimer = setTimeout(() => {
-        try { proc.kill('SIGKILL'); } catch { /* child may already have exited */ }
+        try { signalChild(proc, 'SIGKILL'); } catch { /* child may already have exited */ }
       }, 1000);
       killTimer.unref?.();
       // Install cleanup first: kill() can synchronously trigger close in an adapter.
-      try { proc.kill('SIGTERM'); } catch { /* retain the original failure */ }
+      try { signalChild(proc, 'SIGTERM'); } catch { /* retain the original failure */ }
     };
     const timer = setTimeout(() => {
       rejectAndTerminate(new Error(`aiwg ${args[0] || ''} timed out after ${timeoutMs}ms`));

package/dist/src/mcp/muse-native-config.d.mts

@@ -0,0 +1,13 @@
+export type MuseNativeInspection = {
+  cli: string;
+  hooks: 'absent' | 'managed' | 'operator-only';
+  mcp: 'absent' | 'configured' | 'unreadable';
+};
+
+export function inspectMuseNative(options?: {
+  projectDir?: string;
+  env?: Record<string, string | undefined>;
+  userHome?: string;
+}): Promise<MuseNativeInspection>;
+
+export function isMuseDeployedProject(projectDir?: string): Promise<boolean>;

package/dist/src/mcp/muse-native-config.mjs

@@ -50,6 +50,7 @@ function inspectMuseCli(env) {
     env,
     encoding: 'utf8',
     timeout: MUSE_VERSION_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
   });
   if (result.error?.code === 'ENOENT') return 'absent';
   if (result.error?.code === 'ETIMEDOUT') return 'present (version timeout)';

package/dist/src/mcp/omp-config.d.mts

@@ -0,0 +1,4 @@
+export function ompServerConfig(server: Record<string, any>): Record<string, any>;
+export function manageOmpMcp(configPath: string, servers: Array<{name: string; [key: string]: any}>, options?: {dryRun?: boolean; remove?: string[]; userScope?: boolean; projectRoot?: string}): Promise<{
+  configPath: string; serversInjected: string[]; alreadyPresent: string[]; removed: string[];
+}>;

package/dist/src/mcp/omp-config.mjs

@@ -1,22 +1,37 @@
-import { readFile, writeFile, mkdir, rename, lstat, unlink, open } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
+import { assertConfigDestination, assertNoSymlinkParents, writeConfigAtomic } from './config-file.mjs';
+import { readFile, mkdir, lstat, unlink, open } from 'node:fs/promises';
+import { dirname, parse, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
 
 const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-async function rejectSymlinkPath(file) {
-  let current = resolve(file);
-  for (;;) {
-    try {
-      if ((await lstat(current)).isSymbolicLink()) throw new Error('OMP MCP configuration path cannot traverse a symbolic link');
-    } catch (error) { if (error.code !== 'ENOENT') throw error; }
-    const parent = dirname(current);
-    if (parent === current) return;
-    current = parent;
+/**
+ * Reject a symlinked ancestor, regardless of whether the caller passed a
+ * projectRoot: a symlinked parent can redirect the write outside the intended
+ * directory either way.
+ *
+ *   - With a projectRoot, the walk stops there (matching
+ *     assertConfigDestination) so a deliberately symlinked project root
+ *     itself - a dotfile-manager alias - is not rejected as its own ancestor.
+ *   - Without a projectRoot, an explicit `userScope: true` means the caller
+ *     knows this is a private home-scope destination (symlinked dotfile-
+ *     manager parents there are tolerated, same as every other provider's
+ *     home-scope target); the walk is skipped.
+ *   - Without a projectRoot and without an explicit userScope, there is no
+ *     known safe boundary, so every ancestor up to the filesystem root is
+ *     checked - the conservative default for a caller that supplied neither.
+ */
+async function rejectSymlinkAncestors(file, projectRoot, userScope) {
+  if (projectRoot) {
+    await assertNoSymlinkParents(file, resolve(projectRoot));
+    return;
   }
+  if (userScope === true) return;
+  await assertNoSymlinkParents(file, parse(resolve(file)).root);
 }
-async function readObject(file) {
-  await rejectSymlinkPath(file);
+async function readObject(file, projectRoot, userScope) {
+  await rejectSymlinkAncestors(file, projectRoot, userScope);
+  await assertConfigDestination(file, projectRoot);
   try {
     if ((await lstat(file)).isSymbolicLink()) throw new Error('OMP MCP configuration cannot be a symbolic link');
     const data = JSON.parse(await readFile(file, 'utf8'));
@@ -28,13 +43,10 @@ async function readObject(file) {
     throw error;
   }
 }
-async function atomic(file, data) {
-  await mkdir(dirname(file), { recursive: true });
-  const temporary = `${file}.${randomUUID()}.tmp`;
-  try {
-    await writeFile(temporary, JSON.stringify(data, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
-    await rename(temporary, file);
-  } finally { await unlink(temporary).catch(() => {}); }
+async function atomic(file, data, options) {
+  // OMP files can carry auth/oauth secrets, so they are always owner-only even
+  // for project-scope destinations. Containment still follows projectRoot.
+  await writeConfigAtomic(file, JSON.stringify(data, null, 2) + '\n', { ...options, userScope: true });
 }
 
 export function ompServerConfig(server) {
@@ -74,14 +86,21 @@ export function ompServerConfig(server) {
       config.headers[header] = '${' + variable + '}';
     }
   }
+  if (server.envFrom) {
+    config.env = { ...config.env };
+    for (const [key, variable] of Object.entries(server.envFrom)) {
+      if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(variable)) throw new Error('Invalid MCP env-from environment reference');
+      config.env[key] = '${' + variable + '}';
+    }
+  }
   return config;
 }
 
 /** Hash-only receipt: never saves an extra copy of operator configuration. */
-async function manageLockedOmpMcp(configPath, servers, { dryRun = false, remove = [] } = {}) {
+async function manageLockedOmpMcp(configPath, servers, { dryRun = false, remove = [], userScope, projectRoot } = {}) {
   const receiptPath = `${configPath}.aiwg-ownership.json`;
-  const existing = await readObject(configPath);
-  const receipt = await readObject(receiptPath);
+  const existing = await readObject(configPath, projectRoot, userScope);
+  const receipt = await readObject(receiptPath, projectRoot, userScope);
   if (receipt.servers !== undefined && (!record(receipt.servers) || receipt.schema !== 'aiwg.omp-mcp-ownership.v1')) throw new Error('Invalid OMP MCP ownership receipt');
   if (existing.mcpServers !== undefined && !record(existing.mcpServers)) throw new Error('Invalid OMP mcpServers object');
   const next = { ...(existing.mcpServers || {}) };
@@ -105,10 +124,10 @@ async function manageLockedOmpMcp(configPath, servers, { dryRun = false, remove
     if (owned[name]) { delete next[name]; delete owned[name]; result.removed.push(name); }
   }
   if (!dryRun) {
-    if (hash(await readObject(configPath)) !== hash(existing) || hash(await readObject(receiptPath)) !== hash(receipt)) throw new Error('OMP MCP configuration changed during injection; retry after reviewing the operator edit');
+    if (hash(await readObject(configPath, projectRoot, userScope)) !== hash(existing) || hash(await readObject(receiptPath, projectRoot, userScope)) !== hash(receipt)) throw new Error('OMP MCP configuration changed during injection; retry after reviewing the operator edit');
     // If interrupted between writes, a retry fails closed on the hash mismatch.
-    await atomic(configPath, { ...existing, mcpServers: next });
-    await atomic(receiptPath, { schema: 'aiwg.omp-mcp-ownership.v1', servers: owned });
+    await atomic(configPath, { ...existing, mcpServers: next }, { userScope, projectRoot });
+    await atomic(receiptPath, { schema: 'aiwg.omp-mcp-ownership.v1', servers: owned }, { userScope: true, projectRoot });
   }
   return result;
 }
@@ -116,9 +135,11 @@ async function manageLockedOmpMcp(configPath, servers, { dryRun = false, remove
 /** Serialize AIWG writers; operator edits detected before committing a replacement. */
 export async function manageOmpMcp(configPath, servers, options = {}) {
   if (options.dryRun) return manageLockedOmpMcp(configPath, servers, options);
-  await rejectSymlinkPath(configPath);
+  await rejectSymlinkAncestors(configPath, options.projectRoot, options.userScope);
+  await assertConfigDestination(configPath, options.projectRoot);
   const lockPath = `${configPath}.aiwg-lock`;
-  await rejectSymlinkPath(lockPath);
+  await rejectSymlinkAncestors(lockPath, options.projectRoot, options.userScope);
+  await assertConfigDestination(lockPath, options.projectRoot);
   await mkdir(dirname(configPath), { recursive: true });
   let lock;
   try { lock = await open(lockPath, 'wx', 0o600); }

package/dist/src/mcp/profiles.js

@@ -9,7 +9,9 @@
  *
  * @implements #889
  */
-import { readFile, writeFile, mkdir } from 'fs/promises';
+import { resolveCredentialPolicy } from './credentials.mjs';
+import { isLowerLayerEntry, loadLayered, resolveProfileExtends, resolveConfigLayers, saveLayerData } from './config-layers.mjs';
+import { readFile, writeFile } from 'fs/promises';
 import { resolve } from 'path';
 import { resolveConfigDir } from '../config/user-config.js';
 // ─────────────────────────────────────────────
@@ -66,8 +68,12 @@ export const PRESET_PROFILES = {
 export class McpProfileRegistry {
     configDir;
     cache = null;
+    /** Configuration layers, lowest precedence first; null for a single directory */
+    layers;
+    layering = null;
     constructor(configDirOverride) {
-        this.configDir = resolveConfigDir(configDirOverride);
+        this.layers = resolveConfigLayers(configDirOverride);
+        this.configDir = this.layers ? this.layers[this.layers.length - 1] : resolveConfigDir(configDirOverride);
     }
     getPath() {
         return resolve(this.configDir, PROFILES_FILENAME);
@@ -75,6 +81,12 @@ export class McpProfileRegistry {
     async load() {
         if (this.cache)
             return this.cache;
+        if (this.layers) {
+            const layered = await loadLayered(this.layers, PROFILES_FILENAME, 'profiles', DEFAULT_DATA);
+            this.cache = layered.data;
+            this.layering = layered.layering;
+            return this.cache;
+        }
         const filePath = this.getPath();
         try {
             const content = await readFile(filePath, 'utf-8');
@@ -88,13 +100,24 @@ export class McpProfileRegistry {
         catch {
             this.cache = { ...DEFAULT_DATA, profiles: {} };
         }
+        try {
+            resolveCredentialPolicy({ registryPolicy: this.cache.credentialPolicy, env: {} });
+        }
+        catch (error) {
+            this.cache = null;
+            throw new Error(`Invalid MCP credential policy in ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
         return this.cache;
     }
-    async save() {
-        if (!this.cache)
+    async save(data = this.cache) {
+        if (!data)
             return;
-        await mkdir(this.configDir, { recursive: true });
-        await writeFile(this.getPath(), JSON.stringify(this.cache, null, 2) + '\n', 'utf-8');
+        await saveLayerData(this.getPath(), data, 'profiles', this.layers, this.layering);
+        this.cache = data;
+        if (this.layers) {
+            this.clearCache();
+            await this.load();
+        }
     }
     validateName(name) {
         if (!NAME_RE.test(name)) {
@@ -122,11 +145,13 @@ export class McpProfileRegistry {
     }
     async add(profile, serverRegistry) {
         this.validateName(profile.name);
-        const data = await this.load();
+        const data = structuredClone(await this.load());
         if (data.profiles[profile.name]) {
             throw new Error(`Profile "${profile.name}" already exists. Use "aiwg mcp profile edit" to modify it.`);
         }
         await this.validateServers(profile.servers ?? [], serverRegistry);
+        if (profile.extends?.length)
+            resolveProfileExtends(profile.name, { ...data.profiles, [profile.name]: profile });
         data.profiles[profile.name] = {
             ...profile,
             servers: profile.servers ?? [],
@@ -134,18 +159,28 @@ export class McpProfileRegistry {
             createdAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
         };
-        await this.save();
+        await this.save(data);
     }
     async get(name) {
         const data = await this.load();
         return data.profiles[name];
     }
+    /**
+     * Return a profile with its `extends` chain applied across all configuration
+     * layers. Use get() for the profile exactly as stored.
+     */
+    async resolve(name) {
+        const data = await this.load();
+        if (!data.profiles[name])
+            return undefined;
+        return resolveProfileExtends(name, data.profiles);
+    }
     async list() {
         const data = await this.load();
         return Object.values(data.profiles);
     }
     async edit(name, changes, serverRegistry) {
-        const data = await this.load();
+        const data = structuredClone(await this.load());
         const existing = data.profiles[name];
         if (!existing)
             throw new Error(`Profile "${name}" not found.`);
@@ -162,20 +197,45 @@ export class McpProfileRegistry {
         if (changes.removeServers && changes.removeServers.length > 0) {
             current.servers = current.servers.filter((s) => !(changes.removeServers ?? []).includes(s));
         }
+        if (changes.clearToolFilters) {
+            const overrides = { ...(current.providerOverrides ?? {}) };
+            delete overrides[changes.clearToolFilters];
+            current.providerOverrides = overrides;
+        }
+        for (const [provider, override] of Object.entries(changes.providerOverrides ?? {})) {
+            const overrides = { ...(current.providerOverrides ?? {}) };
+            const previous = overrides[provider] ?? {};
+            const merge = (before, added) => (added ? [...new Set([...(before ?? []), ...added])] : before);
+            overrides[provider] = {
+                ...previous,
+                ...(override.toolDeny ? { toolDeny: merge(previous.toolDeny, override.toolDeny) } : {}),
+                ...(override.toolAllow ? { toolAllow: merge(previous.toolAllow, override.toolAllow) } : {}),
+            };
+            current.providerOverrides = overrides;
+        }
         current.updatedAt = new Date().toISOString();
         data.profiles[name] = current;
-        await this.save();
+        await this.save(data);
         return data.profiles[name];
     }
     async remove(name) {
-        const data = await this.load();
+        const data = structuredClone(await this.load());
         if (!data.profiles[name])
             throw new Error(`Profile "${name}" not found.`);
+        if (this.layering && isLowerLayerEntry(this.layering, name)) {
+            throw new Error(`Profile "${name}" is defined in a lower configuration layer; remove it there.`);
+        }
+        const dependents = Object.entries(data.profiles)
+            .filter(([other, profile]) => other !== name && profile.extends?.includes(name))
+            .map(([other]) => other);
+        if (dependents.length) {
+            throw new Error(`Cannot remove profile "${name}": extended by ${dependents.join(', ')}.`);
+        }
         delete data.profiles[name];
-        await this.save();
+        await this.save(data);
     }
     async resolveServers(name, serverRegistry) {
-        const profile = await this.get(name);
+        const profile = await this.resolve(name);
         if (!profile)
             throw new Error(`Profile "${name}" not found.`);
         if (profile.servers.includes('__all__') && serverRegistry) {
@@ -194,20 +254,27 @@ export class McpProfileRegistry {
     async importFrom(filePath) {
         const content = await readFile(filePath, 'utf-8');
         const imported = JSON.parse(content);
-        const data = await this.load();
+        const data = structuredClone(await this.load());
         let added = 0;
         let updated = 0;
-        const profiles = imported.profiles ?? {};
+        const invalidNames = [];
+        const profiles = imported.profiles ?? (typeof imported === 'object' && !Array.isArray(imported)
+            ? imported
+            : {});
+        const candidate = { ...data.profiles };
         for (const [name, profile] of Object.entries(profiles)) {
             try {
                 this.validateName(name);
             }
-            catch {
+            catch (error) {
+                // Collected and refused below with the complete graph-validation pass,
+                // instead of silently dropping named profiles from the import.
+                invalidNames.push(`${name}: ${error instanceof Error ? error.message : String(error)}`);
                 continue;
             }
-            if (data.profiles[name]) {
-                data.profiles[name] = {
-                    ...data.profiles[name],
+            if (candidate[name]) {
+                candidate[name] = {
+                    ...candidate[name],
                     ...profile,
                     name,
                     updatedAt: new Date().toISOString(),
@@ -215,9 +282,10 @@ export class McpProfileRegistry {
                 updated++;
             }
             else {
-                data.profiles[name] = {
+                candidate[name] = {
                     name,
                     description: profile.description,
+                    ...(profile.extends ? { extends: profile.extends } : {}),
                     servers: profile.servers ?? [],
                     providerOverrides: profile.providerOverrides ?? {},
                     createdAt: new Date().toISOString(),
@@ -226,7 +294,13 @@ export class McpProfileRegistry {
                 added++;
             }
         }
-        await this.save();
+        if (invalidNames.length) {
+            throw new Error(`Refusing to import profile(s) with invalid names: ${invalidNames.join('; ')}`);
+        }
+        for (const name of Object.keys(candidate))
+            resolveProfileExtends(name, candidate);
+        data.profiles = candidate;
+        await this.save(data);
         return { added, updated };
     }
     async exportTo(filePath, profileName) {
@@ -240,7 +314,7 @@ export class McpProfileRegistry {
         await writeFile(filePath, JSON.stringify({ profiles: toExport }, null, 2) + '\n', 'utf-8');
     }
     async initPresets() {
-        const data = await this.load();
+        const data = structuredClone(await this.load());
         let added = 0;
         for (const [name, preset] of Object.entries(PRESET_PROFILES)) {
             if (!data.profiles[name]) {
@@ -253,7 +327,7 @@ export class McpProfileRegistry {
                 added++;
             }
         }
-        await this.save();
+        await this.save(data);
         return { added, total: Object.keys(PRESET_PROFILES).length };
     }
     clearCache() {