@aiwg/cli 2026.8.5 → 2026.8.8

package/dist/src/artifacts/move.js

@@ -6,10 +6,24 @@ import { syncFortemiCoreIndex } from './fortemi-core-sync.js';
 import { PROJECT_AIWG_LOCATION_FILE, expandProjectArtifactPath, resolveProjectAiwgDir, } from '../config/project-artifacts.js';
 const GITIGNORE_BLOCK = [
     '',
-    '# AIWG artifact root pointer (local/private path)',
+    '# AIWG external artifact corpus (retain the project-local control plane)',
+    '!.aiwg/',
+    '.aiwg/*',
+    '!.aiwg/AIWG.md',
+    '!.aiwg/aiwg.config',
+    '!.aiwg/frameworks/',
+    '.aiwg/frameworks/*',
+    '!.aiwg/frameworks/registry.json',
+    '',
+    '# AIWG artifact root pointer (machine-local/private path)',
     PROJECT_AIWG_LOCATION_FILE,
     '',
 ].join('\n');
+const LOCAL_CONTROL_PLANE_FILES = [
+    'AIWG.md',
+    'aiwg.config',
+    path.join('frameworks', 'registry.json'),
+];
 async function exists(filePath) {
     try {
         await access(filePath);
@@ -49,7 +63,8 @@ async function ensureGitignorePointer(projectDir, dryRun) {
             throw error;
     }
     const lines = current.split(/\r?\n/).map(line => line.trim());
-    if (lines.includes(PROJECT_AIWG_LOCATION_FILE))
+    const required = GITIGNORE_BLOCK.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+    if (required.every(line => lines.includes(line)))
         return false;
     if (!dryRun) {
         const separator = current.length === 0 || current.endsWith('\n') ? '' : '\n';
@@ -57,6 +72,28 @@ async function ensureGitignorePointer(projectDir, dryRun) {
     }
     return true;
 }
+async function materializeLocalControlPlane(projectDir, artifactRoot, dryRun) {
+    const localRoot = path.join(projectDir, '.aiwg');
+    for (const relativePath of LOCAL_CONTROL_PLANE_FILES) {
+        const sourcePath = path.join(artifactRoot, relativePath);
+        if (!(await exists(sourcePath)))
+            continue;
+        const destinationPath = path.join(localRoot, relativePath);
+        const sourceContent = await readFile(sourcePath);
+        if (await exists(destinationPath)) {
+            const destinationContent = await readFile(destinationPath);
+            if (!sourceContent.equals(destinationContent)) {
+                throw new Error(`Local AIWG control-plane file differs from the external artifact root: ${destinationPath}. `
+                    + 'Reconcile the files before attaching the corpus.');
+            }
+            continue;
+        }
+        if (!dryRun) {
+            await mkdir(path.dirname(destinationPath), { recursive: true });
+            await writeFile(destinationPath, sourceContent);
+        }
+    }
+}
 async function writePointer(projectDir, pointerValue, dryRun) {
     const pointerPath = path.join(projectDir, PROJECT_AIWG_LOCATION_FILE);
     if (!dryRun) {
@@ -108,23 +145,33 @@ export async function moveProjectArtifacts(options) {
     const source = path.resolve(options.from ? expandProjectArtifactPath(options.from, projectDir) : resolveProjectAiwgDir(projectDir));
     const destination = path.resolve(expandProjectArtifactPath(options.to, projectDir));
     const dryRun = options.dryRun === true;
+    const attach = options.attach === true;
     const reindex = options.reindex !== false;
     const syncFortemi = options.syncFortemi !== false;
-    if (samePath(source, destination)) {
+    if (!attach && samePath(source, destination)) {
         throw new Error(`Source and destination are the same directory: ${source}`);
     }
-    if (!existsSync(source)) {
+    if (!attach && !existsSync(source)) {
         throw new Error(`Source AIWG artifact directory does not exist: ${source}`);
     }
-    if (existsSync(destination) && !(await isEmptyDirectory(destination))) {
+    if (attach) {
+        if (!existsSync(destination) || !(await stat(destination)).isDirectory()) {
+            throw new Error(`Artifact root to attach does not exist or is not a directory: ${destination}`);
+        }
+        if (!existsSync(path.join(destination, 'aiwg.config'))) {
+            throw new Error(`Artifact root to attach has no aiwg.config: ${destination}`);
+        }
+    }
+    else if (existsSync(destination) && !(await isEmptyDirectory(destination))) {
         throw new Error(`Destination already exists and is not empty: ${destination}`);
     }
     const pointerValue = pointerValueFor(projectDir, destination);
     const pointerPath = path.join(projectDir, PROJECT_AIWG_LOCATION_FILE);
     const gitignoreUpdated = await ensureGitignorePointer(projectDir, dryRun);
-    if (!dryRun) {
+    if (!dryRun && !attach) {
         await moveDirectory(source, destination);
     }
+    await materializeLocalControlPlane(projectDir, destination, dryRun);
     await writePointer(projectDir, pointerValue, dryRun);
     let reindexed = false;
     let fortemiSynced = false;
@@ -144,7 +191,8 @@ export async function moveProjectArtifacts(options) {
         to: destination,
         pointerPath,
         pointerValue,
-        moved: !dryRun,
+        moved: !dryRun && !attach,
+        attached: attach && !dryRun,
         gitignoreUpdated,
         reindexed,
         fortemiSynced,

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

@@ -5,9 +5,11 @@ function usage() {
         'aiwg artifacts — Manage the project AIWG artifact root',
         '',
         'Usage:',
-        '  aiwg artifacts move --to <path> [--from <path>] [--dry-run] [--force] [--no-reindex] [--no-sync]',
+        '  aiwg artifacts move --to <path> [--from <path>] [--dry-run] [--no-reindex] [--no-sync]',
+        '  aiwg artifacts attach --to <existing-path> [--dry-run] [--no-reindex] [--no-sync]',
         '',
         'Notes:',
+        '  move relocates a local artifact root; attach adopts an existing populated root.',
         '  --to points at the artifact directory itself, not its parent.',
         '  AIWG_ARTIFACTS_PATH overrides the generated .aiwg-location pointer.',
     ].join('\n');
@@ -30,7 +32,7 @@ export const artifactsHandler = {
         if (action === 'help' || ctx.args.includes('--help') || ctx.args.includes('-h')) {
             return { exitCode: 0, message: usage() };
         }
-        if (action !== 'move') {
+        if (action !== 'move' && action !== 'attach') {
             return { exitCode: 1, message: `Unknown artifacts action: ${action}\n\n${usage()}` };
         }
         const to = valueAfter(ctx.args, '--to');
@@ -42,12 +44,15 @@ export const artifactsHandler = {
                 projectDir: getProjectDir(ctx, ctx.args),
                 from: valueAfter(ctx.args, '--from'),
                 to,
+                attach: action === 'attach',
                 dryRun: ctx.dryRun || ctx.args.includes('--dry-run'),
                 force: ctx.args.includes('--force'),
                 reindex: !ctx.args.includes('--no-reindex'),
                 syncFortemi: !ctx.args.includes('--no-sync'),
             });
-            const verb = result.dryRun ? 'Would move' : 'Moved';
+            const verb = result.dryRun
+                ? (action === 'attach' ? 'Would attach' : 'Would move')
+                : (result.attached ? 'Attached' : 'Moved');
             return {
                 exitCode: 0,
                 message: [

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

@@ -26,6 +26,7 @@ import { generate as generateContextFiles, discoverDeployedArtifacts, shouldEmit
 import { resolveActiveProvider } from '../provider-resolution.js';
 import { getProviderContextDiscoveryPathStrings } from '../../providers/provider-definitions.js';
 import { projectAiwgPath } from '../../config/project-artifacts.js';
+import { selectRegenerateBranch } from '../regenerate-selector.js';
 async function handleRegenerate(args, cwd) {
     if (args.includes('--help') || args.includes('-h')) {
         console.log(`
@@ -40,7 +41,8 @@ async function handleRegenerate(args, cwd) {
     or commands — use 'aiwg refresh' for that.
 
   Options:
-    --workspace             Canonical WORKSPACE.md → AIWG.md graph (default)
+    (no branch flag)        Intelligently select workspace refresh or adoption preview
+    --workspace             Explicit canonical WORKSPACE.md → AIWG.md graph
     --existing-project      Transactionally extract an established project into WORKSPACE.md
     --legacy, --full-inject Legacy inline compatibility branch
     --apply                 Apply --existing-project after its mandatory preflight
@@ -57,6 +59,7 @@ async function handleRegenerate(args, cwd) {
     aiwg regenerate --workspace
     aiwg regenerate --existing-project --dry-run
     aiwg regenerate --existing-project --apply
+    aiwg regenerate --apply
     aiwg regenerate --full-inject
     aiwg regenerate --dry-run
     aiwg regenerate --provider codex
@@ -69,9 +72,9 @@ async function handleRegenerate(args, cwd) {
     const skipAiwgMd = args.includes('--no-aiwg-md');
     const skipAgentsMd = args.includes('--no-agents-md');
     const skipWorkspaceMd = args.includes('--no-workspace-md');
-    const legacy = args.includes('--legacy') || args.includes('--full-inject');
-    const workspace = args.includes('--workspace');
-    const existingProject = args.includes('--existing-project');
+    const requestedLegacy = args.includes('--legacy') || args.includes('--full-inject');
+    const requestedWorkspace = args.includes('--workspace');
+    const requestedExistingProject = args.includes('--existing-project');
     const apply = args.includes('--apply');
     const valueFlags = new Set(['--provider']);
     const booleanFlags = new Set([
@@ -95,23 +98,27 @@ async function handleRegenerate(args, cwd) {
             });
         }
     }
-    const selectedBranches = Number(legacy) + Number(workspace) + Number(existingProject);
+    const selectedBranches = Number(requestedLegacy) + Number(requestedWorkspace) + Number(requestedExistingProject);
     if (selectedBranches > 1)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
             message: 'Choose exactly one regenerate branch: --workspace, --existing-project, or --full-inject.',
             exitCode: EXIT_CODES.USAGE,
         });
-    if (apply && !existingProject)
+    if (dryRun && apply)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
-            message: '--apply is only valid with --existing-project.',
+            message: 'Choose either --dry-run or --apply.',
             exitCode: EXIT_CODES.USAGE,
         });
-    if (existingProject && dryRun && apply)
+    const selection = await selectRegenerateBranch(cwd, args);
+    const legacy = selection.branch === 'legacy';
+    const existingProject = selection.branch === 'existing-project';
+    if (apply && !existingProject)
         throw new AiwgError({
             code: 'ERR_USAGE_CONFLICTING_FLAGS',
-            message: 'Choose either --dry-run or --apply for --existing-project.',
+            message: '--apply is only valid when the existing-project branch is selected.',
+            hint: 'Use `aiwg regenerate --existing-project --apply`, or run without --apply to inspect the selected branch.',
             exitCode: EXIT_CODES.USAGE,
         });
     if (existingProject && (force || skipAiwgMd || skipAgentsMd || skipWorkspaceMd))
@@ -140,6 +147,9 @@ async function handleRegenerate(args, cwd) {
     console.log(`  Provider: ${provider}`);
     console.log(`  Target:   ${target}`);
     console.log(`  Branch:   ${legacy ? 'legacy full injection' : existingProject ? 'canonical existing-project extraction' : 'canonical workspace graph'}`);
+    console.log(`  Selected: ${selection.explicit ? 'explicit' : 'inferred'} — ${selection.reason}`);
+    if (selection.evidence.length > 0)
+        console.log(`  Evidence: ${selection.evidence.join(', ')}`);
     if (existingProject) {
         const preflight = await migrateWorkspaceContext(target, {
             dryRun: true,

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

@@ -1203,15 +1203,16 @@ function projectRootCandidate(start) {
     catch {
         current = resolve(start);
     }
-    let gitRoot = null;
     while (true) {
         if (existsSync(resolve(current, '.aiwg', 'aiwg.config')))
             return current;
-        if (!gitRoot && existsSync(resolve(current, '.git')))
-            gitRoot = current;
+        // A repository root is the project boundary. Do not let an unrelated
+        // ancestor workspace configuration capture session catalog reads.
+        if (existsSync(resolve(current, '.git')))
+            return current;
         const parent = dirname(current);
         if (parent === current)
-            return gitRoot;
+            return null;
         current = parent;
     }
 }

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

@@ -47,6 +47,8 @@ export const quickrefHandler = {
                 console.log(`${verb} ${result.skillName}`);
                 console.log(`  Source: ${result.sourcePath}`);
                 console.log(`  Output: ${result.outputPath}`);
+                for (const warning of result.warnings)
+                    console.log(`  Warning: ${warning}`);
                 if (ctx.dryRun) {
                     console.log('\n--- preview ---\n');
                     console.log(result.content);
@@ -850,6 +852,26 @@ export const promoteHandler = {
             console.log(`✓ Promoted '${positional}' → ${result.plan?.destination}`);
             if (cleanup) {
                 console.log('  Source removed from .aiwg/');
+                try {
+                    const { deployProjectQuickref, generateProjectQuickref, hasProjectQuickref } = await import('../../extensions/project-quickref.js');
+                    if (await hasProjectQuickref(projectDir)) {
+                        if (config.providers.length > 0) {
+                            for (const provider of config.providers)
+                                await deployProjectQuickref(projectDir, provider);
+                            console.log(`  Managed project quickref refreshed for: ${config.providers.join(', ')}.`);
+                        }
+                        else {
+                            await generateProjectQuickref(projectDir);
+                            console.log('  Managed project quickref generated; no providers are configured for deployment.');
+                        }
+                    }
+                    else {
+                        console.log('  Managed project quickref is now empty; run `aiwg doctor --project-local` to inspect deployed stale copies.');
+                    }
+                }
+                catch (error) {
+                    console.log(`  Managed project quickref refresh failed: ${error.message}`);
+                }
             }
             return { exitCode: 0 };
         }
@@ -956,6 +978,14 @@ export const newBundleHandler = {
             catch {
                 // .gitignore management is best-effort; don't fail the scaffold
             }
+            try {
+                const { generateProjectQuickref } = await import('../../extensions/project-quickref.js');
+                await generateProjectQuickref(ctx.cwd);
+                console.log('  → Managed project quickref refreshed from discovered capabilities.');
+            }
+            catch (error) {
+                console.log(`  → Managed project quickref refresh deferred: ${error.message}`);
+            }
             // #1235 / #1758 — auto-rebuild the project graph and refresh the
             // Fortemi Core static cache so the new bundle is immediately
             // discoverable via top-level `aiwg discover` / `aiwg show`.

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

@@ -1079,18 +1079,17 @@ async function deployProjectLocalBundles(opts) {
         : discovery.bundles.filter(b => b.type !== 'provider');
     if (targetBundles.length === 0) {
         if (!onlyBundleId) {
-            const { loadProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
-            const quickref = await loadProjectQuickref(projectDir);
-            if (quickref.exists) {
-                try {
+            const { hasProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
+            try {
+                if (await hasProjectQuickref(projectDir)) {
                     await deployProjectQuickref(projectDir, provider, { dryRun });
                     if (verbose || dryRun)
                         ui.dim(`  + project quickref -> ${provider}`);
                 }
-                catch (error) {
-                    ui.warn(`Project quickref deployment failed: ${error.message}`);
-                    return { deployed: 0, failed: 1, bundles: [] };
-                }
+            }
+            catch (error) {
+                ui.warn(`Project quickref deployment failed: ${error.message}`);
+                return { deployed: 0, failed: 1, bundles: [] };
             }
         }
         return { deployed: 0, failed: 0, bundles: [] };
@@ -1204,22 +1203,20 @@ async function deployProjectLocalBundles(opts) {
             }
         }
     }
-    // A committed `.aiwg/quickref.json` is the canonical orientation source.
-    // Refresh its provider kernel copy whenever project-local bundles deploy so
-    // `aiwg use <bundle>` keeps the always-visible surface in sync.
-    const { loadProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
-    const quickref = await loadProjectQuickref(projectDir);
-    if (quickref.exists) {
-        try {
+    // Refresh the project kernel quickref from either legacy operator input or
+    // managed project-local discovery whenever bundles deploy.
+    const { hasProjectQuickref, deployProjectQuickref } = await import('../../extensions/project-quickref.js');
+    try {
+        if (await hasProjectQuickref(projectDir)) {
             const quickrefResult = await deployProjectQuickref(projectDir, provider, { dryRun });
             if (verbose || dryRun) {
                 ui.dim(`  + project quickref -> ${quickrefResult.provider}${quickrefResult.emulated ? ' (emulated)' : ''}`);
             }
         }
-        catch (error) {
-            failed++;
-            ui.warn(`Project quickref deployment failed: ${error.message}`);
-        }
+    }
+    catch (error) {
+        failed++;
+        ui.warn(`Project quickref deployment failed: ${error.message}`);
     }
     return { deployed, failed, bundles: targetBundles };
 }

package/dist/src/cli/regenerate-selector.js

@@ -0,0 +1,94 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import { auditWorkspaceContext, PROJECT_EXTRACTION_END, PROJECT_EXTRACTION_START, WORKSPACE_MANAGED_END, WORKSPACE_MANAGED_START, WORKSPACE_OPERATOR_END, WORKSPACE_OPERATOR_START, } from '../smiths/context-pipeline/index.js';
+import { AiwgError, EXIT_CODES } from './errors.js';
+function markerPair(content, start, end) {
+    const startIndex = content.indexOf(start);
+    const endIndex = content.indexOf(end);
+    const present = startIndex >= 0 || endIndex >= 0;
+    return {
+        present,
+        valid: !present || (startIndex >= 0 && endIndex > startIndex
+            && content.indexOf(start, startIndex + start.length) < 0
+            && content.indexOf(end, endIndex + end.length) < 0),
+    };
+}
+function malformedWorkspace(message) {
+    throw new AiwgError({
+        code: 'ERR_USAGE_REGENERATE_STATE_MALFORMED',
+        message,
+        hint: 'Repair the managed marker pair or restore WORKSPACE.md from version control, then rerun `aiwg regenerate --dry-run`.',
+        exitCode: EXIT_CODES.USAGE,
+    });
+}
+async function readOptional(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function selectRegenerateBranch(cwd, args) {
+    const legacy = args.includes('--legacy') || args.includes('--full-inject');
+    const workspace = args.includes('--workspace');
+    const existingProject = args.includes('--existing-project');
+    if (legacy)
+        return { branch: 'legacy', state: 'legacy-context', reason: 'explicit legacy compatibility branch', evidence: ['--legacy/--full-inject'], explicit: true };
+    if (workspace)
+        return { branch: 'workspace', state: 'fresh', reason: 'explicit canonical workspace branch', evidence: ['--workspace'], explicit: true };
+    if (existingProject)
+        return { branch: 'existing-project', state: 'established-unextracted', reason: 'explicit existing-project adoption branch', evidence: ['--existing-project'], explicit: true };
+    const workspaceContent = await readOptional(path.join(cwd, 'WORKSPACE.md'));
+    let workspaceMarkers = null;
+    if (workspaceContent !== null) {
+        workspaceMarkers = {
+            managed: markerPair(workspaceContent, WORKSPACE_MANAGED_START, WORKSPACE_MANAGED_END),
+            operator: markerPair(workspaceContent, WORKSPACE_OPERATOR_START, WORKSPACE_OPERATOR_END),
+            extraction: markerPair(workspaceContent, PROJECT_EXTRACTION_START, PROJECT_EXTRACTION_END),
+        };
+        const { managed, operator, extraction } = workspaceMarkers;
+        if (!managed.valid || !operator.valid || !extraction.valid) {
+            malformedWorkspace('WORKSPACE.md contains an incomplete, duplicated, or out-of-order AIWG managed marker pair.');
+        }
+        if (extraction.present && !managed.present)
+            malformedWorkspace('WORKSPACE.md contains a project-extraction block without the canonical workspace managed graph.');
+        if (managed.present !== operator.present)
+            malformedWorkspace('WORKSPACE.md contains only part of the canonical managed/operator structure.');
+    }
+    const audit = await auditWorkspaceContext(cwd);
+    const projectSources = audit.plan.projectSources;
+    const operatorSources = audit.sources
+        .filter((source) => source.path !== 'WORKSPACE.md' && source.operatorContent.trim().length > 0)
+        .map((source) => source.path);
+    if (workspaceContent !== null) {
+        const { managed, extraction } = workspaceMarkers;
+        if (managed.present && extraction.present)
+            return {
+                branch: 'workspace', state: 'adopted', reason: 'canonical workspace already contains an extracted project snapshot', evidence: ['WORKSPACE.md project-extraction marker'], explicit: false,
+            };
+        if (managed.present && projectSources.length > 0)
+            return {
+                branch: 'existing-project', state: 'canonical-unextracted', reason: 'canonical workspace exists but stable project metadata has not been adopted', evidence: projectSources, explicit: false,
+            };
+        if (managed.present)
+            return {
+                branch: 'workspace', state: 'fresh', reason: 'canonical workspace exists and no stable project sources were detected', evidence: ['WORKSPACE.md managed graph'], explicit: false,
+            };
+        return {
+            branch: 'existing-project', state: 'operator-owned-workspace', reason: 'operator-owned WORKSPACE.md requires transactional adoption before canonical refresh', evidence: ['WORKSPACE.md without AIWG managed markers', ...projectSources], explicit: false,
+        };
+    }
+    if (projectSources.length > 0)
+        return {
+            branch: 'existing-project', state: 'established-unextracted', reason: 'stable existing-project sources were detected without an extracted workspace snapshot', evidence: projectSources, explicit: false,
+        };
+    if (audit.legacyCompatible || operatorSources.length > 0)
+        return {
+            branch: 'existing-project', state: 'legacy-context', reason: 'operator-authored provider context requires transactional adoption', evidence: operatorSources, explicit: false,
+        };
+    return { branch: 'workspace', state: 'fresh', reason: 'no prior workspace setup or stable project sources were detected', evidence: [], explicit: false };
+}
+//# sourceMappingURL=regenerate-selector.js.map

package/dist/src/extensions/project-local-doctor.js

@@ -54,12 +54,15 @@ export async function buildProjectLocalDoctorSection(opts) {
     const quickrefAudit = await auditProjectQuickref(projectDir, config?.providers ?? []);
     const quickrefErrors = [...quickrefAudit.errors];
     if (quickrefAudit.exists) {
-        const quickrefRelPath = projectRelativePathIfInside(projectDir, projectAiwgPath(projectDir, 'quickref.json'));
-        const ignored = quickrefRelPath
-            ? await checkBundleManifestIgnored(projectDir, quickrefRelPath)
-            : null;
-        if (ignored === true && quickrefRelPath) {
-            quickrefErrors.push(`${quickrefRelPath} is ignored by git; canonical project quickref source must be committed`);
+        for (const name of ['quickref.json', 'quickref.config.json']) {
+            const sourcePath = projectAiwgPath(projectDir, name);
+            const quickrefRelPath = projectRelativePathIfInside(projectDir, sourcePath);
+            const ignored = quickrefRelPath
+                ? await checkBundleManifestIgnored(projectDir, quickrefRelPath)
+                : null;
+            if (ignored === true && quickrefRelPath) {
+                quickrefErrors.push(`${quickrefRelPath} is ignored by git; operator project quickref input must be committed`);
+            }
         }
     }
     // No project-local content → no section at all
@@ -236,6 +239,7 @@ export async function buildProjectLocalDoctorSection(opts) {
             }
             lines.push('    Project-local bundle source should be tracked. Add to .gitignore:');
             lines.push('      !.aiwg/quickref.json');
+            lines.push('      !.aiwg/quickref.config.json');
             lines.push('      !.aiwg/addons/');
             lines.push('      !.aiwg/extensions/');
             lines.push('      !.aiwg/frameworks/');

package/dist/src/extensions/project-local-gitignore.js

@@ -39,6 +39,7 @@ export const AIWG_GITIGNORE_BLOCK = [
     AIWG_GITIGNORE_SENTINEL,
     '!.aiwg/aiwg.config',
     '!.aiwg/quickref.json',
+    '!.aiwg/quickref.config.json',
     '!.aiwg/addons/',
     '!.aiwg/extensions/',
     '!.aiwg/frameworks/',
@@ -120,11 +121,14 @@ export async function appendAiwgSourceTrackBlock(projectDir) {
     // runs.
     if (report.hasManagedBlock) {
         const path = join(projectDir, '.gitignore');
-        const existing = await readFile(path, 'utf8');
-        if (!existing.split(/\r?\n/).some(line => line.trim() === '!.aiwg/quickref.json')) {
+        let existing = await readFile(path, 'utf8');
+        const required = ['!.aiwg/quickref.json', '!.aiwg/quickref.config.json'];
+        const missing = required.filter(negation => !existing.split(/\r?\n/).some(line => line.trim() === negation));
+        if (missing.length > 0) {
             const sep = existing.endsWith('\n') ? '' : '\n';
-            await writeFile(path, `${existing}${sep}!.aiwg/quickref.json\n`, 'utf8');
-            return { added: true, reason: 'updated managed block to track .aiwg/quickref.json' };
+            existing = `${existing}${sep}${missing.join('\n')}\n`;
+            await writeFile(path, existing, 'utf8');
+            return { added: true, reason: `updated managed block to track ${missing.join(', ')}` };
         }
         return { added: false, reason: 'block already present — no change' };
     }

package/dist/src/extensions/project-quickref.js

@@ -7,13 +7,15 @@
  */
 import { createHash } from 'crypto';
 import { access, mkdir, readFile, readdir, rm, writeFile } from 'fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'path';
+import { basename, dirname, isAbsolute, join, resolve } from 'path';
 import { homedir } from 'os';
 import { z } from 'zod';
 import { getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
 import { OPERATIONAL_SHOW_TYPES } from '../artifacts/types.js';
 import { projectAiwgPath } from '../config/project-artifacts.js';
 import { appendAiwgSourceTrackBlock } from './project-local-gitignore.js';
+import { discoverProjectLocalBundles } from './project-local-discovery.js';
+import { enumerateBundleArtifacts } from './shadow-resolver.js';
 const OWNERSHIP_MARKER = '.aiwg-project-quickref.json';
 const ShowHintSchema = z.object({
     type: z.enum(OPERATIONAL_SHOW_TYPES),
@@ -35,6 +37,25 @@ export const ProjectQuickrefSchema = z.object({
     precedence: z.string().min(1).max(1024),
     entries: z.array(QuickrefEntrySchema).min(1).max(50),
 }).strict();
+const QuickrefOverrideSchema = z.object({
+    title: z.string().min(1).max(128).optional(),
+    summary: z.string().min(1).max(512).optional(),
+    discover: z.array(z.string().min(1).max(256)).max(10).optional(),
+    show: z.array(ShowHintSchema).max(20).optional(),
+    hidden: z.boolean().optional(),
+    order: z.number().int().optional(),
+}).strict();
+export const ProjectQuickrefConfigSchema = z.object({
+    version: z.literal('1'),
+    project: ProjectQuickrefSchema.shape.project.optional(),
+    precedence: z.string().min(1).max(1024).optional(),
+    entries: z.array(QuickrefEntrySchema).max(50).default([]),
+    discovery: z.object({
+        enabled: z.boolean().default(true),
+        excludeBundles: z.array(z.string().min(1)).max(200).default([]),
+        overrides: z.record(z.string(), QuickrefOverrideSchema).default({}),
+    }).strict().default({ enabled: true, excludeBundles: [], overrides: {} }),
+}).strict();
 function sha256(content) {
     return createHash('sha256').update(content).digest('hex');
 }
@@ -78,6 +99,158 @@ export async function loadProjectQuickref(projectDir) {
         return { sourcePath, errors: [`${sourcePath}: invalid JSON: ${error.message}`], exists: true };
     }
 }
+function slug(value) {
+    const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    return normalized || 'project';
+}
+async function inferredProject(projectDir) {
+    let packageName = basename(resolve(projectDir));
+    let description = `Managed project-specific orientation for ${packageName}.`;
+    try {
+        const parsed = JSON.parse(await readFile(join(projectDir, 'package.json'), 'utf8'));
+        if (parsed.name)
+            packageName = parsed.name;
+        if (parsed.description)
+            description = parsed.description.slice(0, 512);
+    }
+    catch {
+        // package metadata is optional
+    }
+    const id = slug(packageName);
+    const name = packageName
+        .replace(/^@[^/]+\//, '')
+        .split(/[-_]/)
+        .filter(Boolean)
+        .map(part => part[0]?.toUpperCase() + part.slice(1))
+        .join(' ') || 'Project';
+    return { id, name, description };
+}
+async function loadManagedConfig(projectDir) {
+    const path = projectAiwgPath(projectDir, 'quickref.config.json');
+    const raw = await readIfPresent(path);
+    if (raw === null)
+        return { path };
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${path}: invalid JSON: ${error.message}`);
+    }
+    const parsed = ProjectQuickrefConfigSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new Error(parsed.error.issues.map(issue => `${path}: ${issue.path.join('.') || '(root)'}: ${issue.message}`).join('\n'));
+    }
+    return { path, config: parsed.data };
+}
+function dedupe(values) {
+    const seen = new Set();
+    return values.filter(value => {
+        const key = value.trim().toLowerCase();
+        if (!key || seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function dedupeShow(values) {
+    const seen = new Set();
+    return values.filter(value => {
+        const key = `${value.type}:${value.name.toLowerCase()}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Resolve legacy operator input or synthesize a managed definition from project-local bundles. */
+export async function resolveProjectQuickref(projectDir) {
+    const legacy = await loadProjectQuickref(projectDir);
+    if (legacy.exists) {
+        if (!legacy.definition)
+            throw new Error(legacy.errors.join('\n'));
+        return {
+            definition: legacy.definition,
+            exists: true,
+            sourcePath: legacy.sourcePath,
+            provenance: 'legacy',
+            warnings: [],
+        };
+    }
+    const managed = await loadManagedConfig(projectDir);
+    const discovery = await discoverProjectLocalBundles(projectDir);
+    if (discovery.errors.length > 0) {
+        throw new Error(discovery.errors.map(error => `${error.path}: ${error.field}: ${error.actual}`).join('\n'));
+    }
+    if (!managed.config && discovery.bundles.length === 0) {
+        return { exists: false, sourcePath: managed.path, provenance: 'managed', warnings: [] };
+    }
+    const config = managed.config ?? ProjectQuickrefConfigSchema.parse({ version: '1' });
+    const excluded = new Set(config.discovery.excludeBundles.map(id => id.toLowerCase()));
+    const warnings = [];
+    const candidates = [];
+    if (config.discovery.enabled) {
+        for (const bundle of discovery.bundles) {
+            if (excluded.has(bundle.id.toLowerCase()))
+                continue;
+            const override = config.discovery.overrides[bundle.id];
+            if (override?.hidden)
+                continue;
+            const artifacts = (await enumerateBundleArtifacts(bundle.artifactPath ?? bundle.bundlePath))
+                .sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+            const inferredShow = dedupeShow(artifacts.map(artifact => ({
+                type: artifact.type,
+                name: artifact.id,
+            }))).slice(0, 8);
+            if (artifacts.length > inferredShow.length && inferredShow.length === 8) {
+                warnings.push(`${bundle.id}: show hints truncated from ${artifacts.length} artifacts to 8`);
+            }
+            let discover = override?.discover ?? dedupe([
+                bundle.id,
+                bundle.manifest.name,
+                ...(bundle.manifest.keywords ?? []),
+            ]).slice(0, 3);
+            const show = override?.show ? dedupeShow(override.show) : inferredShow;
+            if (discover.length === 0 && show.length === 0)
+                discover = [bundle.id];
+            candidates.push({
+                order: override?.order ?? 0,
+                type: bundle.type,
+                id: bundle.id,
+                entry: {
+                    title: override?.title ?? bundle.manifest.name,
+                    summary: override?.summary ?? bundle.manifest.description,
+                    discover,
+                    show,
+                },
+            });
+        }
+    }
+    candidates.sort((a, b) => a.order - b.order || a.type.localeCompare(b.type) || a.id.localeCompare(b.id));
+    const discoveredEntries = candidates.map(candidate => candidate.entry);
+    const entries = [...discoveredEntries, ...config.entries];
+    if (entries.length > 50)
+        warnings.push(`quickref entries truncated from ${entries.length} to 50`);
+    const bounded = entries.slice(0, 50);
+    if (bounded.length === 0) {
+        return { exists: false, sourcePath: managed.path, provenance: 'managed', warnings };
+    }
+    return {
+        definition: {
+            version: '1',
+            project: config.project ?? await inferredProject(projectDir),
+            precedence: config.precedence ?? 'Use project-local capabilities before generic AIWG workflows when they apply.',
+            entries: bounded,
+        },
+        exists: true,
+        sourcePath: managed.path,
+        provenance: 'managed',
+        warnings,
+    };
+}
+export async function hasProjectQuickref(projectDir) {
+    return (await resolveProjectQuickref(projectDir)).exists;
+}
 export function renderProjectQuickref(definition) {
     const skillName = projectQuickrefSkillName(definition.project.id);
     const lines = [
@@ -111,11 +284,9 @@ export function renderProjectQuickref(definition) {
     return lines.join('\n');
 }
 export async function generateProjectQuickref(projectDir, options = {}) {
-    const loaded = await loadProjectQuickref(projectDir);
-    if (!loaded.exists)
+    const loaded = await resolveProjectQuickref(projectDir);
+    if (!loaded.exists || !loaded.definition)
         throw new Error(`Project quickref source not found: ${loaded.sourcePath}`);
-    if (!loaded.definition)
-        throw new Error(loaded.errors.join('\n'));
     if (!options.dryRun)
         await appendAiwgSourceTrackBlock(projectDir);
     const skillName = projectQuickrefSkillName(loaded.definition.project.id);
@@ -127,6 +298,14 @@ export async function generateProjectQuickref(projectDir, options = {}) {
         await mkdir(dirname(outputPath), { recursive: true });
         await writeFile(outputPath, content, 'utf8');
     }
+    if (!options.dryRun && loaded.provenance === 'managed') {
+        const snapshotPath = projectAiwgPath(projectDir, 'generated', 'project-quickref', 'definition.json');
+        const snapshot = JSON.stringify(loaded.definition, null, 2) + '\n';
+        if (await readIfPresent(snapshotPath) !== snapshot) {
+            await mkdir(dirname(snapshotPath), { recursive: true });
+            await writeFile(snapshotPath, snapshot, 'utf8');
+        }
+    }
     if (!options.dryRun) {
         const generatedRoot = projectAiwgPath(projectDir, 'generated', 'project-quickref');
         try {
@@ -149,6 +328,8 @@ export async function generateProjectQuickref(projectDir, options = {}) {
         content,
         changed,
         dryRun: options.dryRun ?? false,
+        provenance: loaded.provenance,
+        warnings: loaded.warnings,
     };
 }
 function resolveProviderSkillsRoot(provider, projectDir, homeDir) {
@@ -206,9 +387,9 @@ async function findStaleOwnedQuickrefs(root, projectDir, keepName, global) {
 }
 export async function deployProjectQuickref(projectDir, provider, options = {}) {
     const generated = await generateProjectQuickref(projectDir, { dryRun: options.dryRun });
-    const loaded = await loadProjectQuickref(projectDir);
+    const loaded = await resolveProjectQuickref(projectDir);
     if (!loaded.definition)
-        throw new Error(loaded.errors.join('\n'));
+        throw new Error(`Project quickref source not found: ${loaded.sourcePath}`);
     const target = resolveProviderSkillsRoot(provider, projectDir, options.homeDir ?? homedir());
     const targetDir = join(target.root, generated.skillName);
     const targetPath = join(targetDir, 'SKILL.md');
@@ -259,11 +440,17 @@ export async function deployProjectQuickref(projectDir, provider, options = {})
     };
 }
 export async function auditProjectQuickref(projectDir, providers, options = {}) {
-    const loaded = await loadProjectQuickref(projectDir);
+    let loaded;
+    try {
+        loaded = await resolveProjectQuickref(projectDir);
+    }
+    catch (error) {
+        return { exists: true, errors: [error.message], drift: [] };
+    }
     if (!loaded.exists)
-        return { exists: false, errors: loaded.errors, drift: [] };
+        return { exists: false, errors: [], drift: [] };
     if (!loaded.definition)
-        return { exists: true, errors: loaded.errors, drift: [] };
+        return { exists: true, errors: ['project quickref definition unavailable'], drift: [] };
     const content = renderProjectQuickref(loaded.definition);
     const skillName = projectQuickrefSkillName(loaded.definition.project.id);
     const generatedPath = projectAiwgPath(projectDir, 'generated', 'project-quickref', skillName, 'SKILL.md');

package/dist/src/mcp/cli.mjs

@@ -415,7 +415,7 @@ CORE TOOLS (15, always registered):
   command-run                       Allow-listed CLI dispatch; confirmation-gated when needed
   artifact-read / artifact-write    Project .aiwg/ artifact IO
 
-OPT-IN TOOLSETS (51 additional tools):
+OPT-IN TOOLSETS (60 additional tools):
   flows          flow-list / flow-show / flow-run
   missions       mission-guide / mission-dispatch / mission-status
   memory         memory-* and reflections-* storage operations
@@ -426,9 +426,10 @@ OPT-IN TOOLSETS (51 additional tools):
   ralph          start / status / abort / attach
   mc             start / dispatch / status / stop / list
   ops            status / list / use / push
+  sandbox        fleet inventory / mutation / reconciliation and governed activity
 
 Enable opt-in tools:
-  AIWG_MCP_TOOLSETS=flows,missions,memory,kb,ralph aiwg mcp serve
+  AIWG_MCP_TOOLSETS=flows,missions,memory,kb,ralph,sandbox aiwg mcp serve
   aiwg mcp serve --toolsets=all
 
 RESOURCES:
@@ -451,6 +452,8 @@ TRANSPORTS:
 ENVIRONMENT:
   AIWG_ROOT          Path to AIWG installation (default: ~/.local/share/ai-writing-guide)
   AIWG_MCP_TOOLSETS  Comma-separated opt-in toolsets; use all for every toolset
+  AIWG_SANDBOX_MANAGEMENT_URL         Sandbox management API origin (HTTPS except loopback)
+  AIWG_SANDBOX_MANAGEMENT_TOKEN_FILE  Mode-0600 management bearer file for sandbox tools
 
 Docs:
   docs/integrations/mcp-capability-audit.md

package/dist/src/mcp/server.mjs

@@ -68,7 +68,7 @@ export function createServer() {
   // Opt-in subsystem toolsets (#1322-#1332)
   //
   // Enabled via AIWG_MCP_TOOLSETS env or `aiwg mcp serve --toolsets=`.
-  // Known: flows, missions, memory, kb, research, activity-log, index, ralph, mc, ops, all
+  // Known: flows, missions, memory, kb, research, activity-log, index, ralph, mc, ops, sandbox, all
   // Default: none (core only — discovery + command-run)
   // ============================================
   const requested = parseToolsets(process.env.AIWG_MCP_TOOLSETS || '');

package/dist/src/mcp/tools/agentic-sandbox.mjs

@@ -0,0 +1,232 @@
+/**
+ * Governed Agentic Sandbox fleet and activity MCP surface.
+ *
+ * Credentials are file-backed server configuration, never tool arguments.
+ * Every tool in this module uses the management bearer domain; executor-plane
+ * credentials are deliberately out of scope and cannot be substituted.
+ *
+ * @implements #2015
+ */
+
+import { readFile, stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { mcpError, mcpJson } from '../helpers.mjs';
+
+const FLEET_VERSION = 'agentic-orchestration/v1';
+const ACTIVITY_VERSION = 'activity.event/v1';
+const SCOPE_HEADERS = {
+  tenant_id: 'x-agentic-tenant-id',
+  host_id: 'x-agentic-host-id',
+  instance_id: 'x-agentic-instance-id',
+  agent_id: 'x-agentic-agent-id',
+};
+const RESTRICTED_KEY = /(?:^|_)(?:content|terminal|prompt|environment|env|credential|secret|password|authorization|bearer|token|private_key|certificate|restricted_(?:url|uri|link))(?:$|_)/i;
+
+function configuredBaseUrl(env = process.env) {
+  const raw = String(env.AIWG_SANDBOX_MANAGEMENT_URL ?? '').trim();
+  if (!raw) throw new Error('AIWG_SANDBOX_MANAGEMENT_URL is required for the sandbox toolset');
+  const url = new URL(raw);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('AIWG_SANDBOX_MANAGEMENT_URL must be an HTTP(S) origin without credentials, query, or fragment');
+  }
+  if (url.protocol !== 'https:' && !['127.0.0.1', 'localhost', '::1'].includes(url.hostname)) {
+    throw new Error('AIWG_SANDBOX_MANAGEMENT_URL requires HTTPS outside loopback');
+  }
+  return url.toString().replace(/\/$/, '');
+}
+
+async function managementBearer(env = process.env) {
+  const tokenFile = String(env.AIWG_SANDBOX_MANAGEMENT_TOKEN_FILE ?? '').trim();
+  if (!tokenFile) throw new Error('AIWG_SANDBOX_MANAGEMENT_TOKEN_FILE is required for the sandbox toolset');
+  const metadata = await stat(tokenFile);
+  if (!metadata.isFile()) throw new Error('sandbox management token path is not a regular file');
+  if (process.platform !== 'win32' && (metadata.mode & 0o077) !== 0) {
+    throw new Error('sandbox management token file must not be accessible by group or other users');
+  }
+  const token = String(await readFile(tokenFile, 'utf8')).trim();
+  if (!token || /[\r\n]/.test(token)) throw new Error('sandbox management token file must contain one non-empty bearer token');
+  return token;
+}
+
+function containsRestricted(value) {
+  if (Array.isArray(value)) return value.some(containsRestricted);
+  if (!value || typeof value !== 'object') return false;
+  return Object.entries(value).some(([key, child]) => RESTRICTED_KEY.test(key) || containsRestricted(child));
+}
+
+function requireSafePayload(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  if (containsRestricted(value)) throw new Error(`${label} contains credential or restricted-content fields`);
+  return value;
+}
+
+function safeResponse(value) {
+  if (containsRestricted(value)) throw Object.assign(new Error('sandbox response contained prohibited credential or restricted-content fields'), { code: 'sandbox_restricted_response' });
+  return value;
+}
+
+function requireFleetRecord(record) {
+  requireSafePayload(record, 'fleet workload');
+  if (record.document_type !== 'workload' || record.api_version !== FLEET_VERSION) throw new Error(`fleet workload must use ${FLEET_VERSION}`);
+  if (!record.lineage || typeof record.lineage.child_id !== 'string' || !record.lineage.child_id) throw new Error('fleet workload requires lineage.child_id');
+  if (!record.status || !Number.isInteger(record.status.revision) || record.status.revision < 0) throw new Error('fleet workload requires a non-negative status.revision');
+  return record;
+}
+
+function requireInventory(value) {
+  safeResponse(value);
+  if (value?.document_type !== 'inventory' || value?.api_version !== FLEET_VERSION || !Number.isInteger(value?.inventory_revision) || !Array.isArray(value?.records)) {
+    throw new Error('invalid fleet inventory envelope');
+  }
+  value.records.forEach(requireFleetRecord);
+  return value;
+}
+
+function requireReconciliation(value) {
+  safeResponse(value);
+  if (value?.document_type !== 'reconciliation' || value?.api_version !== FLEET_VERSION || !Number.isInteger(value?.before_revision) || !Number.isInteger(value?.after_revision) || !Array.isArray(value?.rows)) {
+    throw new Error('invalid fleet reconciliation envelope');
+  }
+  return value;
+}
+
+function requireActivityEnvelope(value, scope, { eventsRequired = false, exportEnvelope = false } = {}) {
+  safeResponse(value);
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid activity envelope');
+  if (!exportEnvelope && value.schema_version !== ACTIVITY_VERSION) throw new Error(`activity envelope must use ${ACTIVITY_VERSION}`);
+  if (!exportEnvelope && (!Array.isArray(value.coverage) || typeof value.completeness?.complete !== 'boolean')) throw new Error('activity envelope requires coverage and completeness');
+  if (eventsRequired && !Array.isArray(value.events)) throw new Error('activity timeline requires events');
+  for (const event of value.events ?? []) {
+    if (
+      event?.schema_version !== ACTIVITY_VERSION
+      || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(event?.event_id ?? '')
+      || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/.test(event?.event_name ?? '')
+      || !['session', 'action', 'network', 'runtime', 'system', 'integrity'].includes(event?.plane)
+      || Number.isNaN(Date.parse(event?.occurred_at ?? ''))
+      || Number.isNaN(Date.parse(event?.observed_at ?? ''))
+      || !event?.source || typeof event.source.collector !== 'string' || !event.source.collector
+      || !['guest', 'runtime', 'host', 'control-plane', 'provider'].includes(event.source.layer)
+      || !['qemu-kvm', 'cloud-hypervisor', 'docker', 'host', 'unknown'].includes(event.source.runtime)
+      || !['observed', 'attested', 'self-reported', 'derived'].includes(event.source.trust)
+      || event?.sensitivity !== 'metadata'
+      || !['standard', 'security', 'forensic-hold', 'ephemeral'].includes(event?.retention_class)
+      || !event?.payload || typeof event.payload !== 'object' || Array.isArray(event.payload)
+      || !Number.isInteger(event?.integrity?.collector_sequence) || event.integrity.collector_sequence < 1
+    ) throw new Error('activity event violates schema or sensitivity policy');
+    for (const [key, expected] of Object.entries(scope)) if (event?.correlation?.[key] !== expected) throw new Error(`activity event ${key} scope mismatch`);
+  }
+  if (exportEnvelope) {
+    const manifest = value.manifest;
+    if (!manifest || manifest.tenant_id !== scope.tenant_id || !Number.isInteger(manifest.event_count) || manifest.event_count < 0 || !/^[0-9a-f]{64}$/.test(manifest.merkle_root ?? '') || typeof manifest.key_id !== 'string' || !manifest.key_id || typeof manifest.signature !== 'string' || !manifest.signature) {
+      throw new Error('activity export manifest is malformed or out of scope');
+    }
+  }
+  return value;
+}
+
+function typedResult(body, status, validate) {
+  if (status === 404 || status === 405) return mcpJson({ supported: false, reason: 'capability_absent', status });
+  if (status < 200 || status >= 300) {
+    const safe = safeResponse(body);
+    return {
+      ...mcpJson({ supported: true, ok: false, status, error_code: safe?.error ?? safe?.code ?? `http_${status}`, details: safe }),
+      isError: true,
+    };
+  }
+  return mcpJson({ supported: true, ok: true, status, data: validate(body) });
+}
+
+export class AgenticSandboxMcpClient {
+  constructor({ env = process.env, fetch = globalThis.fetch.bind(globalThis) } = {}) {
+    this.env = env;
+    this.fetch = fetch;
+  }
+
+  async request(path, { method = 'GET', body, headers = {}, validate = (value) => safeResponse(value) } = {}) {
+    const baseUrl = configuredBaseUrl(this.env);
+    const token = await managementBearer(this.env);
+    const response = await this.fetch(`${baseUrl}${path}`, {
+      method,
+      headers: { accept: 'application/json', authorization: `Bearer ${token}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }), ...headers },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    let parsed;
+    try {
+      parsed = await response.json();
+    } catch {
+      if (response.status === 404 || response.status === 405) parsed = {};
+      else return mcpError(`sandbox returned non-JSON HTTP ${response.status}`);
+    }
+    try {
+      return typedResult(parsed, response.status, validate);
+    } catch (error) {
+      return mcpError(`${error.code ?? 'sandbox_malformed_response'}: ${error.message}`);
+    }
+  }
+}
+
+const scopeSchema = {
+  tenant_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+  host_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+  instance_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+  agent_id: z.string().min(1).max(255).regex(/^[^\r\n]+$/),
+};
+const activityFilterSchema = z.object({
+  event_name: z.string().min(1).max(255).optional(), collector: z.string().min(1).max(255).optional(),
+  trust: z.string().min(1).max(255).optional(), plane: z.string().min(1).max(255).optional(),
+  outcome: z.string().min(1).max(255).optional(), session_id: z.string().min(1).max(255).optional(),
+  mission_id: z.string().min(1).max(255).optional(), task_id: z.string().min(1).max(255).optional(),
+  tool_call_id: z.string().min(1).max(255).optional(), command_id: z.string().min(1).max(255).optional(),
+  process_id: z.string().min(1).max(255).optional(), trace_id: z.string().regex(/^[0-9a-f]{32}$/).optional(),
+  since: z.string().datetime().optional(), until: z.string().datetime().optional(), limit: z.number().int().min(1).max(1000).optional(),
+}).strict().optional();
+
+function scopeHeaders(args) {
+  return Object.fromEntries(Object.entries(SCOPE_HEADERS).map(([key, header]) => [header, args[key]]));
+}
+
+function activityQuery(filter = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(filter)) query.set(key, String(value));
+  return query.size ? `?${query}` : '';
+}
+
+function confirmationError(name) {
+  return mcpError(`${name} requires confirmed=true`, { requiresConfirmation: true, remediation: 'Review the exact scope and payload, then re-invoke with confirmed=true.' });
+}
+
+export function registerAgenticSandboxToolset(server, { client = new AgenticSandboxMcpClient() } = {}) {
+  const register = (name, config, handler) => server.registerTool(name, config, async (args) => {
+    try { return await handler(args); } catch (error) { return mcpError(`${name}: ${error.message}`); }
+  });
+
+  register('sandbox-fleet-list', { title: 'List Agentic Sandbox fleet workloads', description: 'Read revisioned v2026.8.3+ fleet inventory using the management credential domain.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION) }, annotations: { readOnlyHint: true, destructiveHint: false } },
+    () => client.request('/api/v2/fleet/workloads', { validate: requireInventory }));
+  register('sandbox-fleet-get', { title: 'Get Agentic Sandbox fleet workload', description: 'Read one revisioned fleet workload by child identity.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), child_id: z.string().min(1).max(255) }, annotations: { readOnlyHint: true, destructiveHint: false } },
+    ({ child_id }) => client.request(`/api/v2/fleet/workloads/${encodeURIComponent(child_id)}`, { validate: requireFleetRecord }));
+  register('sandbox-fleet-reconcile-preview', { title: 'Preview fleet reconciliation', description: 'Compute a read-only reconciliation preview from inventory; never calls POST /reconcile.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), before_revision: z.number().int().min(0), child_ids: z.array(z.string().min(1).max(255)).max(1000) }, annotations: { readOnlyHint: true, destructiveHint: false } },
+    async ({ before_revision, child_ids }) => client.request('/api/v2/fleet/workloads', { validate: (value) => {
+      const inventory = requireInventory(value);
+      const byId = new Map(inventory.records.map((record) => [record.lineage.child_id, record]));
+      return { document_type: 'reconciliation-preview', api_version: FLEET_VERSION, before_revision, inventory_revision: inventory.inventory_revision, stale: before_revision !== inventory.inventory_revision, rows: child_ids.map((child_id) => ({ child_id, present: byId.has(child_id), observed_state: byId.get(child_id)?.status?.observed_state ?? 'unknown', revision: byId.get(child_id)?.status?.revision ?? null })) };
+    } }));
+  register('sandbox-fleet-admit', { title: 'Admit Agentic Sandbox fleet workload', description: 'Mutating fleet admission; requires an exact v1 workload and confirmed=true.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), workload: z.record(z.unknown()), confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    ({ workload, confirmed }) => confirmed ? client.request('/api/v2/fleet/workloads', { method: 'POST', body: requireFleetRecord(workload), validate: (value) => ({ replayed: value?.replayed === true, workload: requireFleetRecord(value?.workload) }) }) : confirmationError('sandbox-fleet-admit'));
+  register('sandbox-fleet-observe', { title: 'Record fleet workload observation', description: 'Mutating monotonic observation update; requires confirmed=true and expected revision.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), child_id: z.string().min(1).max(255), expected_revision: z.number().int().min(0), status: z.record(z.unknown()), runtime_identity: z.object({ session_id: z.string().optional(), task_id: z.string().optional(), command_id: z.string().optional() }).strict().optional(), confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    ({ child_id, expected_revision, status, runtime_identity, confirmed }) => confirmed ? client.request(`/api/v2/fleet/workloads/${encodeURIComponent(child_id)}/observations`, { method: 'POST', body: requireSafePayload({ expected_revision, status, ...(runtime_identity ? { runtime_identity } : {}) }, 'fleet observation'), validate: requireFleetRecord }) : confirmationError('sandbox-fleet-observe'));
+  register('sandbox-fleet-reconcile', { title: 'Reconcile fleet workloads', description: 'Mutating restart reconciliation; requires confirmed=true.', inputSchema: { contract_version: z.literal(FLEET_VERSION).default(FLEET_VERSION), before_revision: z.number().int().min(0), child_ids: z.array(z.string().min(1).max(255)).max(1000), confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    ({ before_revision, child_ids, confirmed }) => confirmed ? client.request('/api/v2/fleet/reconcile', { method: 'POST', body: { before_revision, child_ids }, validate: requireReconciliation }) : confirmationError('sandbox-fleet-reconcile'));
+
+  for (const [kind, eventsRequired] of [['coverage', false], ['timeline', true]]) {
+    register(`sandbox-activity-${kind}`, { title: `${kind === 'coverage' ? 'Inspect coverage for' : 'Read timeline from'} Agentic Sandbox activity`, description: `Read governed, exactly scoped activity ${kind}; preserves capability and authorization status.`, inputSchema: { contract_version: z.literal(ACTIVITY_VERSION).default(ACTIVITY_VERSION), ...scopeSchema, filter: activityFilterSchema }, annotations: { readOnlyHint: true, destructiveHint: false } },
+      (args) => { const scope = Object.fromEntries(Object.keys(SCOPE_HEADERS).map((key) => [key, args[key]])); return client.request(`/api/v2/activity/${kind}${activityQuery(args.filter)}`, { headers: scopeHeaders(args), validate: (value) => requireActivityEnvelope(value, scope, { eventsRequired }) }); });
+  }
+  register('sandbox-activity-export', { title: 'Export signed Agentic Sandbox activity evidence', description: 'Evidence export requires confirmed=true even though it does not mutate server state.', inputSchema: { contract_version: z.literal(ACTIVITY_VERSION).default(ACTIVITY_VERSION), ...scopeSchema, filter: activityFilterSchema, confirmed: z.boolean().default(false) }, annotations: { readOnlyHint: false, destructiveHint: true } },
+    (args) => { if (!args.confirmed) return confirmationError('sandbox-activity-export'); const scope = Object.fromEntries(Object.keys(SCOPE_HEADERS).map((key) => [key, args[key]])); return client.request('/api/v2/activity/export', { method: 'POST', headers: scopeHeaders(args), body: args.filter ?? {}, validate: (value) => requireActivityEnvelope(value, scope, { eventsRequired: true, exportEnvelope: true }) }); });
+}
+
+export const AGENTIC_SANDBOX_TOOL_NAMES = [
+  'sandbox-fleet-list', 'sandbox-fleet-get', 'sandbox-fleet-reconcile-preview',
+  'sandbox-fleet-admit', 'sandbox-fleet-observe', 'sandbox-fleet-reconcile',
+  'sandbox-activity-coverage', 'sandbox-activity-timeline', 'sandbox-activity-export',
+];

package/dist/src/mcp/tools/subsystems.mjs

@@ -17,6 +17,7 @@
 import { z } from 'zod';
 import { runAiwgCli, mcpError, mcpJson } from '../helpers.mjs';
 import { registerFlowToolset, registerMissionToolset } from './orchestration.mjs';
+import { registerAgenticSandboxToolset } from './agentic-sandbox.mjs';
 
 /**
  * Wrap an `aiwg <subsystem> <verb>` CLI call as an MCP tool.
@@ -586,6 +587,7 @@ const TOOLSET_REGISTRY = {
   ralph: registerRalphToolset,
   mc: registerMcToolset,
   ops: registerOpsToolset,
+  sandbox: registerAgenticSandboxToolset,
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.5",
+  "version": "2026.8.8",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",

package/tools/plugin/package-plugins.mjs

@@ -657,6 +657,13 @@ for (const [id, sourceRoot] of MANIFEST_PLUGIN_SOURCES) {
     keywords: manifest.keywords || manifest.tags || [],
     category: manifest.category || 'productivity',
     sourceRoot,
+    declaredSkills: manifest.skills ?? [],
+    // Plugin payloads run outside the checkout. Rewrite references back to
+    // their packaged root, including the pre-rename Ralph path retained by
+    // older Agent Loop documentation.
+    selfReferenceRoots: id === 'agent-loop'
+      ? [sourceRoot, 'agentic/code/addons/ralph']
+      : [sourceRoot],
   };
 }
 
@@ -774,6 +781,48 @@ function copyDir(src, dest, dryRun = false, filter = null) {
   return copied;
 }
 
+function rewritePackagedSelfReferences(pluginDir, roots = []) {
+  if (roots.length === 0) return;
+  const pending = [pluginDir];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(target);
+      } else if (entry.isFile() && /\.(?:md|json|ya?ml)$/.test(entry.name)) {
+        const original = fs.readFileSync(target, 'utf8');
+        let rewritten = original;
+        for (const root of roots) {
+          rewritten = rewritten.replaceAll(`${root}/`, '${CLAUDE_PLUGIN_ROOT}/');
+        }
+        if (rewritten !== original) fs.writeFileSync(target, rewritten, 'utf8');
+      }
+    }
+  }
+}
+
+function pruneUndeclaredPackagedSkills(pluginDir, declaredSkills) {
+  if (!declaredSkills) return;
+  const skillsRoot = path.join(pluginDir, 'skills');
+  if (!fs.existsSync(skillsRoot)) return;
+  const allowed = new Set(declaredSkills);
+  for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (entry.isDirectory() && !allowed.has(entry.name)) {
+      fs.rmSync(path.join(skillsRoot, entry.name), { recursive: true, force: true });
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      const skillId = path.basename(entry.name, '.md');
+      if (allowed.has(skillId)) {
+        const skillDir = path.join(skillsRoot, skillId);
+        fs.mkdirSync(skillDir, { recursive: true });
+        fs.renameSync(path.join(skillsRoot, entry.name), path.join(skillDir, 'SKILL.md'));
+      } else {
+        fs.rmSync(path.join(skillsRoot, entry.name), { force: true });
+      }
+    }
+  }
+}
+
 // Clean plugin directory (except .claude-plugin)
 function cleanPlugin(pluginDir) {
   if (!fs.existsSync(pluginDir)) return;
@@ -811,6 +860,10 @@ function packagePlugin(name, config, options) {
     console.log(`  📁 Copying self-contained source from ${config.sourceRoot}...`);
     const count = copyDir(config.sourceRoot, pluginDir, options.dryRun);
     console.log(`     ${count} files`);
+    if (!options.dryRun) {
+      rewritePackagedSelfReferences(pluginDir, config.selfReferenceRoots);
+      pruneUndeclaredPackagedSkills(pluginDir, config.declaredSkills);
+    }
   }
 
   // Copy sources