@aiwg/cli 2026.9.20 → 2026.9.21

package/dist/src/cli/scope-resolver.js

@@ -15,6 +15,7 @@ import * as path from 'node:path';
 import { resolveHermesHome, resolveHermesHomePath } from '../providers/hermes-home.js';
 import { resolveGrokbotSkillsDir } from '../providers/grokbot-paths.js';
 import { resolveGrokHome } from '../providers/grok-build-paths.js';
+import { resolveMuseXdgSkillsDir } from '../providers/muse-paths.js';
 export const hermesHome = resolveHermesHome;
 function piAgentDir() {
     const configured = process.env.PI_CODING_AGENT_DIR;
@@ -231,17 +232,31 @@ export const USER_SCOPE_PATHS = {
         };
     },
     get 'grok-build'() {
-        // Skills mirror to $GROK_HOME/skills. Agents/rules writers deferred #2577 —
-        // leave those user paths empty so mirroring does not invent empty trees.
+        // Grok Build discovers user agents and skills under the resolved home.
         const home = resolveGrokHome();
         return {
-            agents: '',
+            agents: home ? path.join(home, 'agents') : '',
             skills: home ? path.join(home, 'skills') : '',
             commands: '',
             rules: '',
             behaviors: '',
         };
     },
+    get muse() {
+        // #226 — Muse XDG user skills root resolves at deploy time (fail-closed).
+        // Bad XDG metadata yields '' so the --scope user mirror skips the skills
+        // lane rather than inventing ~/.muse or writing ~/.agents/skills
+        // (the cross-provider canonical is a READ surface for Muse, never an
+        // AIWG write target — see adr-muse-provider-target.md).
+        const skills = resolveMuseXdgSkillsDir() || '';
+        return {
+            agents: '',
+            skills,
+            commands: '',
+            rules: '',
+            behaviors: '',
+        };
+    },
     factory: {
         // #1164 — Verified against Factory docs (docs.factory.ai/cli/configuration/skills).
         // Skills primary user-scope path is ~/.factory/skills/, NOT the
@@ -345,6 +360,8 @@ export async function mirrorToUserScope(provider, projectPaths) {
     if (!userPaths) {
         return { agents: empty, skills: empty, commands: empty, rules: empty, behaviors: empty };
     }
+    if (provider === 'grok-build')
+        await assertGrokUserMirrorPaths(projectPaths, userPaths);
     const [agents, skills, commands, rules, behaviors] = await Promise.all([
         userPaths.agents ? mirrorArtifactDir(projectPaths.agents, userPaths.agents) : Promise.resolve(empty),
         userPaths.skills
@@ -356,16 +373,68 @@ export async function mirrorToUserScope(provider, projectPaths) {
     ]);
     return { agents, skills, commands, rules, behaviors };
 }
+async function assertGrokUserMirrorPaths(projectPaths, userPaths) {
+    const fs = await import('node:fs/promises');
+    const statIfPresent = async (target) => {
+        try {
+            return await fs.lstat(target);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+    };
+    const checkTarget = async (target) => {
+        const stat = await statIfPresent(target);
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+            throw new Error(`Refusing unsafe Grok Build user mirror target: ${target}`);
+        }
+        if (stat.isDirectory()) {
+            for (const name of await fs.readdir(target))
+                await checkTarget(path.join(target, name));
+        }
+    };
+    for (const [destination, sources] of [
+        [userPaths.agents, [projectPaths.agents]],
+        [userPaths.skills, [projectPaths.skills, projectPaths.kernelSkills ?? '']],
+    ]) {
+        if (!destination)
+            continue;
+        const rootStat = await statIfPresent(destination);
+        if (rootStat && (rootStat.isSymbolicLink() || !rootStat.isDirectory())) {
+            throw new Error(`Refusing unsafe Grok Build user mirror root: ${destination}`);
+        }
+        for (const source of sources) {
+            if (!source)
+                continue;
+            let names;
+            try {
+                names = await fs.readdir(source);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            for (const name of names)
+                await checkTarget(path.join(destination, name));
+        }
+    }
+}
 /**
  * Merge standard and kernel skill directories into one user-discoverable
  * target. Provider deployments intentionally keep those source surfaces
  * separate, while user scope exposes one native skill root. Duplicate skill
- * names are overwritten by the later source and counted once.
+ * names created by the earlier source are overwritten by the later source
+ * and counted once; pre-existing operator-owned names are preserved.
  */
 export async function mirrorSkillDirsToUserScope(sourceDirs, targetDir) {
     const entries = new Set();
     for (const sourceDir of sourceDirs) {
-        const result = await mirrorArtifactDir(sourceDir, targetDir);
+        const result = await mirrorArtifactDir(sourceDir, targetDir, entries);
         for (const entry of result.entries)
             entries.add(entry);
     }
@@ -387,7 +456,7 @@ export async function mirrorSkillDirsToUserScope(sourceDirs, targetDir) {
  * providers). Failures on individual entries are swallowed so a single bad
  * entry doesn't fail the whole mirror.
  */
-async function mirrorArtifactDir(src, dst) {
+async function mirrorArtifactDir(src, dst, ownedThisCall = new Set()) {
     if (!src || !dst)
         return { count: 0, targetDir: dst, entries: [] };
     const fs = await import('node:fs/promises');
@@ -402,9 +471,12 @@ async function mirrorArtifactDir(src, dst) {
     // path. Inventory that source for registry accounting instead of trying to
     // recursively copy each entry onto itself.
     if (path.resolve(src) === path.resolve(dst)) {
-        const entries = dirents
-            .filter((entry) => entry.isDirectory() || entry.isFile())
-            .map((entry) => entry.name);
+        const entries = [];
+        for (const entry of dirents) {
+            if ((entry.isDirectory() || entry.isFile()) && await isAiwgManagedEntry(path.join(dst, entry.name), entry.isDirectory())) {
+                entries.push(entry.name);
+            }
+        }
         return { count: entries.length, targetDir: dst, entries };
     }
     await fs.mkdir(dst, { recursive: true });
@@ -414,6 +486,18 @@ async function mirrorArtifactDir(src, dst) {
         const s = path.join(src, entry.name);
         const d = path.join(dst, entry.name);
         try {
+            // User-scope directories are shared with operator-created artifacts.
+            // A same-named unmanaged entry belongs to the operator, even when a
+            // project has an AIWG-managed source with that name.
+            try {
+                const existing = await fs.lstat(d);
+                if (!ownedThisCall.has(entry.name) && !await isAiwgManagedEntry(d, existing.isDirectory()))
+                    continue;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    continue;
+            }
             if (entry.isDirectory()) {
                 await fs.cp(s, d, { recursive: true, force: true });
             }
@@ -432,6 +516,25 @@ async function mirrorArtifactDir(src, dst) {
     }
     return { count, targetDir: dst, entries };
 }
+async function isAiwgManagedEntry(target, directory) {
+    const fs = await import('node:fs/promises');
+    if (directory) {
+        try {
+            const marker = await fs.readFile(path.join(target, '.aiwg-managed'), 'utf8');
+            if (marker.trim() === 'aiwg')
+                return true;
+        }
+        catch { /* legacy deployed skill may use an inline marker */ }
+    }
+    const markerFile = directory ? path.join(target, 'SKILL.md') : target;
+    try {
+        const text = await fs.readFile(markerFile, 'utf8');
+        return /(?:#|<!--) aiwg:managed v[^\s]+ [^\r\n]+/.test(text.slice(0, 2048));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * #1156 Phase 1 — some app providers are exclusively user-scope. `--scope
  * project` against them is meaningless because their paths are home-rooted;

package/dist/src/cli/services/deployment-verification.js

@@ -44,6 +44,11 @@ const RESTART_NOTICES = {
         action: 'Restart the Grok Build session so it reloads .grok skills and AGENTS.md.',
         reason: 'Grok Build reload semantics are not yet verified for live refresh; treat deploys as restart-required.',
     },
+    muse: {
+        policy: 'restart-required',
+        action: 'Trust this workspace when prompted, then start a new Muse session (or re-read skills) so Muse loads the deployed AGENTS.md bridge and skills.',
+        reason: 'Muse Code loads project AGENTS.md only after the workspace is explicitly trusted, and reads its skill registry when a session starts. Reloading an IDE window does not apply here.',
+    },
     factory: {
         policy: 'restart-required',
         action: 'Restart the Factory droid runtime so it reloads deployed droids.',

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

@@ -174,6 +174,7 @@ export function resolveDelivery(delivery) {
  *     should tune. Conservative 10 default.
  *   - grokbot: desktop multi-agent; conservative 4 until native evidence.
 *   - grok-build: experimental; conservative 4 until Wave 2/3 evidence.
+ *   - muse: experimental; conservative 4 until Wave 2/3 evidence.
  *   - unknown: conservative 4 default.
  */
 export const PROVIDER_PARALLELISM_DEFAULTS = {
@@ -191,6 +192,8 @@ export const PROVIDER_PARALLELISM_DEFAULTS = {
     // Desktop multi-agent; conservative until native concurrency evidence exists.
     grokbot: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
     'grok-build': { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
+    // Muse Code is experimental; conservative until Wave 2/3 native concurrency evidence (#235).
+    muse: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
     // Conservative defaults for remaining stable/experimental harnesses (#249).
     openhuman: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },
     omp: { max_parallel_subagents: 4, max_parallel_ralph_loops: 2, max_parallel_mc_missions: 4 },

package/dist/src/decision/acceptance-rollout.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { applyPrimitiveAcceptance } from './acceptance.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function digest(value) {
+    return `sha256:${createHash('sha256').update(canonical(value)).digest('hex')}`;
+}
+function required(value, label) {
+    if (!value.trim())
+        throw new Error(`${label} must not be empty`);
+}
+function timestamp(value, label) {
+    if (!Number.isFinite(Date.parse(value)))
+        throw new Error(`${label} must be a valid date-time`);
+}
+export function acceptancePolicyIdentity(id, policy) {
+    required(id, 'policy id');
+    return { id, version: policy.version, digest: digest(policy) };
+}
+/**
+ * Replays two immutable policy versions over already-stored observations. This
+ * function has no adapter, credential, executor, or action callback by design.
+ */
+export function replayAcceptancePolicyShadow(input) {
+    required(input.rolloutId, 'rollout id');
+    required(input.useCaseId, 'use case id');
+    timestamp(input.recordedAt, 'recordedAt');
+    if (!input.evidence.length)
+        throw new Error('shadow rollout requires stored evidence');
+    const ids = new Set();
+    const evidence = input.evidence.map(item => {
+        required(item.id, 'stored evidence id');
+        if (ids.has(item.id))
+            throw new Error(`duplicate stored evidence id '${item.id}'`);
+        ids.add(item.id);
+        const before = structuredClone(item);
+        const incumbent = applyPrimitiveAcceptance(item.definition, input.incumbent.policy, item.observation);
+        const candidate = applyPrimitiveAcceptance(item.definition, input.candidate.policy, item.observation);
+        if (canonical(item) !== canonical(before))
+            throw new Error(`shadow replay mutated stored evidence '${item.id}'`);
+        if (!incumbent.acceptance || !candidate.acceptance)
+            throw new Error(`shadow replay produced no acceptance evidence for '${item.id}'`);
+        return {
+            id: item.id,
+            storedObservationDigest: digest({ definition: item.definition, observation: item.observation }),
+            incumbentAcceptance: incumbent.acceptance,
+            candidateAcceptance: candidate.acceptance,
+        };
+    });
+    const withoutDigest = {
+        schemaVersion: 'decision-acceptance-shadow/v1', rolloutId: input.rolloutId, useCaseId: input.useCaseId,
+        incumbent: acceptancePolicyIdentity(input.incumbent.id, input.incumbent.policy),
+        candidate: acceptancePolicyIdentity(input.candidate.id, input.candidate.policy),
+        evidence,
+        summary: {
+            total: evidence.length,
+            changed: evidence.filter(item => item.incumbentAcceptance.disposition !== item.candidateAcceptance.disposition).length,
+            candidateActionCount: evidence.filter(item => item.candidateAcceptance.disposition === 'act').length,
+        },
+        actionAuthorization: 'not-authorized', recordedAt: input.recordedAt,
+    };
+    return structuredClone({ ...withoutDigest, digest: digest(withoutDigest) });
+}
+/** Records an explicitly approved, use-case-scoped pin change with an exact rollback target. */
+export function createAcceptancePromotionRecord(input) {
+    required(input.promotionId, 'promotion id');
+    required(input.useCaseId, 'use case id');
+    required(input.approvalReference, 'approval reference');
+    required(input.qualificationManifest.path, 'qualification manifest path');
+    timestamp(input.promotedAt, 'promotedAt');
+    if (input.shadow.useCaseId !== input.useCaseId)
+        throw new Error('shadow evidence belongs to a different use case');
+    const { digest: claimedShadowDigest, ...shadowPayload } = input.shadow;
+    if (digest(shadowPayload) !== claimedShadowDigest)
+        throw new Error('shadow record digest mismatch');
+    const withoutDigest = {
+        schemaVersion: 'decision-acceptance-promotion/v1', promotionId: input.promotionId,
+        useCaseId: input.useCaseId, from: input.shadow.incumbent, to: input.shadow.candidate,
+        rollback: input.shadow.incumbent, shadowRecordDigest: input.shadow.digest,
+        qualificationManifest: structuredClone(input.qualificationManifest),
+        approvalReference: input.approvalReference, promotedAt: input.promotedAt,
+    };
+    return structuredClone({ ...withoutDigest, digest: digest(withoutDigest) });
+}
+//# sourceMappingURL=acceptance-rollout.js.map

package/dist/src/decision/acceptance.js

@@ -0,0 +1,175 @@
+import { DecisionValidationError } from './validate.js';
+const METRICS = {
+    'truth-probability': new Set(['yes-probability', 'calibrated-risk']),
+    choice: new Set(['selected-probability', 'native-confidence', 'top-two-margin', 'entropy', 'concentration', 'calibrated-risk']),
+    'ordinal-score': new Set(['expected-score', 'native-confidence', 'dispersion', 'concentration', 'calibrated-risk']),
+};
+export function validatePrimitiveAcceptancePolicy(policy, definition) {
+    if (!/^\d+\.\d+\.\d+$/.test(policy.version))
+        throw new DecisionValidationError('acceptance policy version must be semver');
+    if (!policy.compatibleUncertaintyProfiles.length
+        || new Set(policy.compatibleUncertaintyProfiles).size !== policy.compatibleUncertaintyProfiles.length
+        || policy.compatibleUncertaintyProfiles.some(profile => !profile.trim())) {
+        throw new DecisionValidationError('primitive acceptance requires unique non-empty compatible uncertainty profiles');
+    }
+    if (policy.precedence !== 'first-match')
+        throw new DecisionValidationError('acceptance policy requires explicit first-match precedence');
+    const ids = new Set();
+    for (const rule of policy.rules) {
+        if (!rule.id || ids.has(rule.id))
+            throw new DecisionValidationError('acceptance rule IDs must be non-empty and unique');
+        ids.add(rule.id);
+        if (!rule.all.length)
+            throw new DecisionValidationError(`acceptance rule '${rule.id}' must contain a condition`);
+        for (const condition of rule.all)
+            if (!METRICS[rule.primitive].has(condition.metric)) {
+                throw new DecisionValidationError(`acceptance metric '${condition.metric}' is incompatible with ${rule.primitive}`);
+            }
+        for (const condition of rule.all)
+            validateCondition(condition);
+        validateRoute(rule.route);
+    }
+    [policy.defaultRoute, policy.missingEvidenceRoute, policy.invalidEvidenceRoute, policy.tieRoute].forEach(validateRoute);
+    if (policy.requiredOptions) {
+        if (!policy.requiredOptions.length || new Set(policy.requiredOptions).size !== policy.requiredOptions.length
+            || policy.requiredOptions.some(option => !option)) {
+            throw new DecisionValidationError('required Choice options must be unique non-empty IDs');
+        }
+        if (definition?.spec.answer.kind !== 'choice')
+            throw new DecisionValidationError('requiredOptions is valid only for Choice policies');
+        const options = new Set(definition.spec.answer.options.map(option => option.id));
+        if (policy.requiredOptions.some(option => !options.has(option))) {
+            throw new DecisionValidationError('Choice definition is missing an option required by its acceptance policy');
+        }
+    }
+}
+export function applyPrimitiveAcceptance(definition, policy, observation) {
+    if (observation.status !== 'success')
+        return observation;
+    validatePrimitiveAcceptancePolicy(policy, definition);
+    const uncertaintyProfile = observation.uncertainty?.profile;
+    if (!uncertaintyProfile) {
+        return routed(observation, policy, policy.missingEvidenceRoute, 'missing-evidence', {});
+    }
+    if (!policy.compatibleUncertaintyProfiles.includes(uncertaintyProfile)) {
+        return routed(observation, policy, policy.invalidEvidenceRoute, 'invalid-evidence', {});
+    }
+    const evidence = deriveEvidence(definition, observation);
+    if (!evidence)
+        return routed(observation, policy, policy.invalidEvidenceRoute, 'invalid-evidence', {});
+    if (policy.calibration === 'required' && evidence['calibrated-risk'] === undefined) {
+        return routed(observation, policy, policy.missingEvidenceRoute, 'calibration-required', evidence);
+    }
+    if (definition.spec.answer.kind === 'choice' && evidence['top-two-margin']?.normalizedBps === 0) {
+        return routed(observation, policy, policy.tieRoute, 'tie', evidence);
+    }
+    for (const rule of policy.rules) {
+        if (rule.primitive !== definition.spec.answer.kind)
+            continue;
+        const conditionValues = rule.all.map(condition => evidence[condition.metric]);
+        if (conditionValues.some(value => value === undefined)) {
+            return routed(observation, policy, policy.missingEvidenceRoute, 'missing-evidence', evidence);
+        }
+        if (rule.all.every((condition, index) => matches(conditionValues[index].normalizedBps, condition))) {
+            return routed(observation, policy, rule.route, 'matched', evidence, rule.id);
+        }
+    }
+    return routed(observation, policy, policy.defaultRoute, 'default', evidence);
+}
+function deriveEvidence(definition, observation) {
+    const values = {};
+    const add = (metric, value, normalized, provenance, calibrationRef = null) => {
+        if (!Number.isFinite(value) || !Number.isFinite(normalized) || normalized < 0 || normalized > 1)
+            return false;
+        // Preserve the raw statistic and remove only IEEE-754 representation noise
+        // from the separate basis-point comparison value (eight decimal places).
+        const normalizedBps = Math.round(normalized * 1_000_000_000_000) / 100_000_000;
+        values[metric] = { value, normalizedBps, provenance, calibrationRef };
+        return true;
+    };
+    const uncertainty = observation.uncertainty;
+    if (uncertainty?.calibratedRisk
+        && !add('calibrated-risk', uncertainty.calibratedRisk.value, uncertainty.calibratedRisk.value, 'calibrated', uncertainty.calibratedRisk.calibrationRef))
+        return null;
+    const kind = definition.spec.answer.kind;
+    if (kind === 'truth-probability') {
+        return typeof observation.value === 'number' && add('yes-probability', observation.value, observation.value, 'provider-value') ? values : null;
+    }
+    const distribution = uncertainty?.distribution;
+    if (!distribution)
+        return values;
+    const probabilities = Object.values(distribution);
+    if (!probabilities.length)
+        return null;
+    const concentration = probabilities.reduce((sum, probability) => sum + probability ** 2, 0);
+    if (!add('concentration', concentration, concentration, 'derived'))
+        return null;
+    if (uncertainty.confidence !== null && !add('native-confidence', uncertainty.confidence, uncertainty.confidence, 'provider-confidence'))
+        return null;
+    if (kind === 'choice') {
+        if (typeof observation.value !== 'string' || distribution[observation.value] === undefined)
+            return null;
+        const sorted = [...probabilities].sort((a, b) => b - a);
+        const selected = distribution[observation.value];
+        const margin = selected - (sorted[1] ?? 0);
+        const entropy = probabilities.length <= 1 ? 0
+            : -probabilities.reduce((sum, probability) => sum + (probability === 0 ? 0 : probability * Math.log(probability)), 0) / Math.log(probabilities.length);
+        if (!add('selected-probability', selected, selected, 'provider-distribution')
+            || !add('top-two-margin', margin, margin, 'derived')
+            || !add('entropy', entropy, entropy, 'derived'))
+            return null;
+        return values;
+    }
+    const range = definition.spec.answer.levels.length - 1;
+    if (range <= 0)
+        return null;
+    const expected = Object.entries(distribution).reduce((sum, [level, probability]) => sum + Number(level) * probability, 0);
+    const variance = Object.entries(distribution).reduce((sum, [level, probability]) => sum + (Number(level) - expected) ** 2 * probability, 0);
+    if (!add('expected-score', expected, expected / range, 'derived')
+        || !add('dispersion', variance, variance / (range ** 2), 'derived'))
+        return null;
+    return values;
+}
+function routed(observation, policy, route, reason, values, matchedRule = null) {
+    const acceptance = {
+        policyVersion: policy.version, uncertaintyProfile: observation.uncertainty?.profile ?? null,
+        disposition: route.disposition, matchedRule, reason, values,
+        ...(route.fallbackTarget ? { fallbackTarget: route.fallbackTarget } : {}),
+    };
+    if (route.disposition === 'act')
+        return { ...observation, acceptance };
+    return { ...observation, status: 'abstained', reason: 'low-confidence', acceptance };
+}
+function matches(value, condition) {
+    switch (condition.op) {
+        case 'lt': return value < condition.thresholdBps;
+        case 'lte': return value <= condition.thresholdBps;
+        case 'gt': return value > condition.thresholdBps;
+        case 'gte': return value >= condition.thresholdBps;
+        case 'between': return value >= condition.minimumBps && value <= condition.maximumBps;
+        case 'outside': return value < condition.minimumBps || value > condition.maximumBps;
+    }
+}
+function validateCondition(condition) {
+    const scalar = condition.op === 'lt' || condition.op === 'lte' || condition.op === 'gt' || condition.op === 'gte';
+    if (scalar) {
+        if (!Number.isInteger(condition.thresholdBps) || condition.thresholdBps < 0 || condition.thresholdBps > 10_000
+            || condition.minimumBps !== undefined || condition.maximumBps !== undefined) {
+            throw new DecisionValidationError('scalar acceptance conditions require one thresholdBps in [0,10000]');
+        }
+    }
+    else if (!Number.isInteger(condition.minimumBps) || !Number.isInteger(condition.maximumBps)
+        || condition.minimumBps < 0 || condition.maximumBps > 10_000 || condition.minimumBps > condition.maximumBps
+        || condition.thresholdBps !== undefined) {
+        throw new DecisionValidationError('range acceptance conditions require ordered minimumBps/maximumBps in [0,10000]');
+    }
+}
+function validateRoute(route) {
+    if (route.disposition === 'fallback') {
+        if (!route.fallbackTarget)
+            throw new DecisionValidationError('fallback route requires fallbackTarget');
+    }
+    else if (route.fallbackTarget !== undefined)
+        throw new DecisionValidationError('fallbackTarget is valid only for fallback routes');
+}
+//# sourceMappingURL=acceptance.js.map