@aiwg/cli 2026.8.10 → 2026.8.11

package/dist/src/agents/packaged-agent-inventory.js

@@ -1,4 +1,5 @@
 import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 const MANAGED_MARKER_RE = /(?:^|\n)(?:#|<!--)\s*aiwg:managed\s+v?([^\s]+)\s+([^\s>]+)(?:\s*-->)?/;
 /** Normalize provider-specific deployed filenames to the source agent id. */
@@ -12,6 +13,31 @@ export function parseManagedArtifactMarker(content) {
     const match = MANAGED_MARKER_RE.exec(content);
     return match ? { version: match[1], source: match[2] } : null;
 }
+/** Extract the developer-instruction body from a canonical Markdown agent. */
+export function extractAgentInstructionBody(content) {
+    if (!content.startsWith('---'))
+        return content.trim();
+    const withoutFrontmatter = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+    return withoutFrontmatter.trim();
+}
+function instructionHash(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function extractDeployedInstructions(filename, content) {
+    if (!filename.toLowerCase().endsWith('.toml')) {
+        return extractAgentInstructionBody(content);
+    }
+    const match = content.match(/^developer_instructions\s*=\s*(.+)$/m);
+    if (!match)
+        return null;
+    try {
+        const value = JSON.parse(match[1]);
+        return typeof value === 'string' ? value.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function collectAgentSources(frameworkRoot, rootDir, inventory, allMarkdownFiles) {
     let entries;
     try {
@@ -31,8 +57,12 @@ async function collectAgentSources(frameworkRoot, rootDir, inventory, allMarkdow
         if (!allMarkdownFiles && path.basename(rootDir) !== 'agents')
             return;
         let stat;
+        let content;
         try {
-            stat = await fs.stat(absolute);
+            [stat, content] = await Promise.all([
+                fs.stat(absolute),
+                fs.readFile(absolute, 'utf8'),
+            ]);
         }
         catch {
             return;
@@ -42,6 +72,7 @@ async function collectAgentSources(frameworkRoot, rootDir, inventory, allMarkdow
         sources.push({
             path: path.relative(frameworkRoot, absolute),
             size: stat.size,
+            instructionHash: instructionHash(extractAgentInstructionBody(content)),
         });
         inventory.set(name, sources);
     }));
@@ -67,6 +98,11 @@ export function diagnoseOversizedAgent(filename, content, inventory, ceilingByte
     const packaged = inventory.get(normalizeAgentArtifactName(filename)) ?? [];
     if (packaged.some((source) => source.size > ceilingBytes))
         return 'current-package';
+    const deployedInstructions = extractDeployedInstructions(filename, content);
+    if (deployedInstructions !== null
+        && packaged.some((source) => source.instructionHash === instructionHash(deployedInstructions))) {
+        return 'current-package';
+    }
     const marker = parseManagedArtifactMarker(content);
     if (marker?.source === 'bundled')
         return 'stale-deployment';

package/dist/src/artifacts/fortemi-core-sync.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { GRAPH_CONFIGS, getProjectIndexRoot, loadGlobalGraphConfigs } from "./types.js";
 import { buildAiwgFortemiIndexExport, } from "./browser-export.js";
 import { loadGraphIndexFile } from "./index-reader.js";
@@ -25,7 +26,7 @@ function findPackageRoot(startDir) {
     }
 }
 function prebuiltDir(graph) {
-    const moduleDir = path.dirname(new URL(import.meta.url).pathname);
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
     const packageRoot = findPackageRoot(moduleDir);
     if (!packageRoot)
         return null;
@@ -215,17 +216,31 @@ export function getFortemiCorePrebuiltStatus(graph = "framework") {
             reason: manifestReadReason,
         };
     }
+    const prebuiltManifest = manifest;
     const exportExists = fs.existsSync(exportPath);
     let reason = null;
     if (exportExists) {
         try {
             const exportText = fs.readFileSync(exportPath, "utf-8");
             const exported = JSON.parse(exportText);
-            if (sha256(exportText) !== manifest.export_checksum) {
+            if (prebuiltManifest.schema_version !== "aiwg.fortemi.prebuilt.v1" ||
+                prebuiltManifest.backend !== "fortemi-core" ||
+                prebuiltManifest.graph !== graph ||
+                prebuiltManifest.export_path !== "aiwg-fortemi-index-v2.json" ||
+                prebuiltManifest.export_schema_version !== "aiwg.fortemi.index.export.v2") {
+                reason = "prebuilt manifest is incompatible with the requested graph";
+            }
+            else if (sha256(exportText) !== prebuiltManifest.export_checksum) {
                 reason = "prebuilt export checksum does not match manifest";
             }
-            else if (exported.schema_version !== manifest.export_schema_version) {
-                reason = `prebuilt export schema '${exported.schema_version}' does not match manifest '${manifest.export_schema_version}'`;
+            else if (exported.schema_version !== prebuiltManifest.export_schema_version) {
+                reason = `prebuilt export schema '${exported.schema_version}' does not match manifest '${prebuiltManifest.export_schema_version}'`;
+            }
+            else if (exported.source?.graph !== graph) {
+                reason = `prebuilt export graph '${exported.source?.graph ?? "unknown"}' does not match requested graph '${graph}'`;
+            }
+            else if (!Array.isArray(exported.items) || exported.items.length !== prebuiltManifest.item_count) {
+                reason = "prebuilt export item count does not match manifest";
             }
         }
         catch (err) {
@@ -241,10 +256,10 @@ export function getFortemiCorePrebuiltStatus(graph = "framework") {
         exportPath,
         built: exportExists,
         stale: !exportExists || reason !== null,
-        itemCount: manifest.item_count,
-        exportChecksum: manifest.export_checksum,
-        generatedAt: manifest.generated_at,
-        sourceIndexBuiltAt: manifest.source_index_built_at,
+        itemCount: prebuiltManifest.item_count,
+        exportChecksum: prebuiltManifest.export_checksum,
+        generatedAt: prebuiltManifest.generated_at,
+        sourceIndexBuiltAt: prebuiltManifest.source_index_built_at,
         reason: !exportExists ? "prebuilt manifest exists but export file is missing" : reason,
     };
 }

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

@@ -15,6 +15,7 @@
 import { promises as fs } from 'fs';
 import path from 'path';
 import { createScriptRunner } from './script-runner.js';
+import { createUseHandler } from './use.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { refreshAllPackages } from '../../packages/registry.js';
 import { resolveActiveProvider } from '../provider-resolution.js';
@@ -97,7 +98,14 @@ export async function pruneStaleManagedAgentFiles(options) {
                 continue;
             const artifactName = normalizeAgentArtifactName(entry.name);
             const missingFromCurrentPackage = !desired.has(artifactName);
-            const fromOlderPackage = currentVersion !== null && isOlderManagedVersion(marker.version, currentVersion);
+            // Addons have independent manifest versions. Comparing their managed
+            // marker to the top-level package version makes a successful refresh
+            // delete freshly restored addon agents. Version-based cleanup remains
+            // valid for other provider trees that were not refreshed, while the
+            // active provider removes only artifacts absent from current sources.
+            const fromOlderPackage = provider !== options.provider
+                && currentVersion !== null
+                && isOlderManagedVersion(marker.version, currentVersion);
             if (!missingFromCurrentPackage && !fromOlderPackage)
                 continue;
             const relFile = path.relative(options.projectRoot, file);
@@ -163,6 +171,7 @@ export const refreshHandler = {
         const modelDeployArgs = collectModelDeployArgs(ctx.args);
         const frameworkRoot = await getFrameworkRoot();
         const runner = createScriptRunner(frameworkRoot);
+        const activeUseHandler = createUseHandler();
         if (!quiet) {
             ui.blank();
             // Deprecation notice when invoked as 'sync'
@@ -195,6 +204,7 @@ export const refreshHandler = {
         // Step 2.5: Refresh remote packages (always, unless --packages-only skips npm)
         if (!quiet)
             ui.info(dryRun ? 'Would refresh remote packages...' : 'Refreshing remote packages...');
+        const deploymentFailures = [];
         if (!dryRun) {
             try {
                 const refreshed = await refreshAllPackages();
@@ -259,13 +269,30 @@ export const refreshHandler = {
                 ui.dim('  No installed frameworks or addons to re-deploy');
             }
             for (const fw of frameworks) {
-                const providerArgs = ['--provider', detectedProvider, ...modelDeployArgs];
-                const useResult = await runner.run('tools/cli/deploy.mjs', [fw, ...providerArgs], { capture: quiet });
+                // Invoke the active installation's handler directly. The historical
+                // deploy.mjs bridge shells out to the first `aiwg` on PATH, which can
+                // be a different version/root and therefore cannot safely refresh
+                // addons installed by this package (#143/#2102).
+                const useResult = await activeUseHandler.execute({
+                    ...ctx,
+                    cwd: ctx.cwd,
+                    frameworkRoot,
+                    args: [
+                        fw,
+                        '--provider', detectedProvider,
+                        '--target', ctx.cwd,
+                        '--yes',
+                        '--json',
+                        ...modelDeployArgs,
+                    ],
+                    rawArgs: ['use', fw],
+                });
                 if (useResult.exitCode === 0) {
                     if (!quiet)
                         ui.success(`Deployed: ${fw}`);
                 }
                 else {
+                    deploymentFailures.push(fw);
                     if (!quiet)
                         ui.warn(`Deploy issue: ${fw} (exit ${useResult.exitCode})`);
                 }
@@ -281,11 +308,10 @@ export const refreshHandler = {
             }
         }
         // Step 4.25: Report planned project-local deploys (#1035).
-        // The actual deploy is performed by `aiwg use` underneath via deploy.mjs;
-        // this block surfaces what *would* happen during dry-run and what was
-        // covered during a real refresh.
+        // The active use handler performs the actual project-local deploy during
+        // framework refresh; this block surfaces dry-run and completion details.
         try {
-            const plDiscovery = await discoverProjectLocalBundles(process.cwd());
+            const plDiscovery = await discoverProjectLocalBundles(ctx.cwd);
             const plCount = plDiscovery.bundles.length;
             if (plCount > 0) {
                 if (dryRun) {
@@ -312,11 +338,12 @@ export const refreshHandler = {
         if (!quiet)
             ui.info('Checking for stale deployments...');
         let staleAgentRemovals = [];
-        if (!dryRun) {
+        if (!dryRun && deploymentFailures.length === 0) {
             try {
                 staleAgentRemovals = await pruneStaleManagedAgentFiles({
                     projectRoot: ctx.cwd,
                     frameworkRoot,
+                    provider: detectedProvider,
                 });
                 if (staleAgentRemovals.length > 0 && !quiet) {
                     const total = staleAgentRemovals.reduce((sum, item) => sum + item.paths.length, 0);
@@ -435,10 +462,17 @@ export const refreshHandler = {
                 skipUpdate,
                 channel: channel || undefined,
                 staleAgentRemovals,
+                deploymentFailures,
             });
             console.log(output);
         }
-        return { exitCode: dryRun ? 0 : 0 };
+        if (deploymentFailures.length > 0) {
+            return {
+                exitCode: 1,
+                message: `Failed to re-deploy installed bundle(s): ${deploymentFailures.join(', ')}`,
+            };
+        }
+        return { exitCode: 0 };
     },
 };
 //# sourceMappingURL=refresh.js.map

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

@@ -1673,6 +1673,20 @@ async function ensurePostDeployPhases(opts) {
             // The shared verifier reports the index failure with stable remediation.
         }
     }
+    // The Fortemi export is the default discovery backend. Rebuilding only the
+    // source graph makes any existing export stale, so every successful use
+    // must leave the shared cache synchronized (#142/#2103). This also
+    // materializes a fresh-install cache without requiring a manual index sync.
+    try {
+        const { getFortemiCoreSyncStatus, syncFortemiCoreIndex, } = await import('../../artifacts/fortemi-core-sync.js');
+        const status = getFortemiCoreSyncStatus(opts.frameworkRoot, 'framework');
+        if (!status.built || status.stale) {
+            syncFortemiCoreIndex(opts.frameworkRoot, { graph: 'framework' });
+        }
+    }
+    catch {
+        // The shared verifier reports discovery failures with stable remediation.
+    }
     if (opts.args.includes('--no-context-files'))
         return;
     const paths = getProviderPaths(opts.provider);
@@ -3152,6 +3166,8 @@ export class UseHandler {
                     // project (#1217). The output index location is XDG-shared
                     // regardless of build cwd.
                     await buildIndex(aiwgRootForIndex, { graph: 'framework', explicit: false });
+                    const { syncFortemiCoreIndex } = await import('../../artifacts/fortemi-core-sync.js');
+                    syncFortemiCoreIndex(aiwgRootForIndex, { graph: 'framework' });
                     console.log = origLog;
                     const indexElapsedSec = ((Date.now() - indexStart) / 1000).toFixed(1);
                     ui.success(`Capability index ready (${indexElapsedSec}s).`);

package/package.json

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

package/tools/agents/providers/base.mjs

@@ -180,8 +180,11 @@ const MANIFEST_FILENAME = '.aiwg-manifest.json';
  *
  * Idempotent — skips if either form of the marker is already present.
  */
-export function addManagedMarker(content, version, source) {
+export function addManagedMarker(content, version, source, style = 'markdown') {
   if (MANAGED_MARKER_RE.test(content)) return content;
+  if (style === 'line-comment') {
+    return `# aiwg:managed v${version} ${source}\n${content}`;
+  }
   // Frontmatter present → inject as YAML comment after the opening `---\n`.
   if (content.startsWith('---\n')) {
     return content.replace(
@@ -680,9 +683,18 @@ export function deployFiles(files, destDir, opts, transformFn) {
       transformedContent = injectPlatformInContent(transformedContent, platformName);
     }
 
-    // Add managed marker for .md / .mdc files (#749; .mdc for Cursor native rules)
+    // Add managed marker for provider artifacts (#749). TOML accepts `#`
+    // comments, which lets doctor attribute transformed Codex agents even
+    // though their YAML frontmatter is removed during serialization.
     if (base.endsWith('.md') || base.endsWith('.mdc')) {
       transformedContent = addManagedMarker(transformedContent, deployVersion, deploySource);
+    } else if (base.endsWith('.toml')) {
+      transformedContent = addManagedMarker(
+        transformedContent,
+        deployVersion,
+        deploySource,
+        'line-comment',
+      );
     }
 
     // Compute content hash for sidecar comparison