@aiwg/cli 2026.8.16 → 2026.8.18

package/dist/src/serve/mission-conductor.js

@@ -46,6 +46,9 @@ export class MissionConductor {
      * crash-resilient resume path; their prior results are carried forward.
      */
     async conduct(plan, pool, resumeFrom) {
+        if (plan.cycles.some((cycle) => cycle.graph) && !plan.graph) {
+            throw new Error('Graph-projected worker cycles require MissionPlan.graph identity.');
+        }
         const carried = new Map();
         if (resumeFrom) {
             for (const c of resumeFrom.cycles) {
@@ -62,10 +65,17 @@ export class MissionConductor {
             totalCost: 0,
             checkpoint: { completed: [], pending: [], failed: [] },
             runtimesUsed: [],
+            ...(plan.graph ? { graph: structuredClone(plan.graph) } : {}),
         };
         ledger.activityLog.push(`mission ${plan.missionId} start — goal: ${plan.goal} — ${plan.cycles.length} cycle(s)` +
             (resumeFrom ? ` (resume: ${carried.size} carried)` : ''));
         for (const cycle of plan.cycles) {
+            const graph = plan.graph && cycle.graph ? {
+                ...structuredClone(plan.graph),
+                ...structuredClone(cycle.graph),
+                schemaVersion: 'graph.flow.aiwg.io/v1',
+                nodeRunId: cycle.graph.nodeRunId ?? `${plan.graph.runId}:${cycle.graph.nodeId}`,
+            } : undefined;
             // Resume: carry a previously-completed cycle forward, identical bookkeeping.
             const prior = carried.get(cycle.id);
             if (prior) {
@@ -86,6 +96,7 @@ export class MissionConductor {
                     routed: false,
                     reason: `no stack adapter registered for runtime '${cycle.runtime}'`,
                     cost: 0,
+                    ...(graph ? { graph } : {}),
                 };
                 ledger.cycles.push(result);
                 ledger.checkpoint.failed.push(cycle.id);
@@ -104,6 +115,7 @@ export class MissionConductor {
                     routed: false,
                     reason: `no connected executor advertises ${filter.capabilities.join(', ')}`,
                     cost: 0,
+                    ...(graph ? { graph } : {}),
                 };
                 ledger.cycles.push(result);
                 ledger.checkpoint.failed.push(cycle.id);
@@ -111,7 +123,7 @@ export class MissionConductor {
                 continue;
             }
             const executor = routing.selected.executor;
-            const invocation = adapter.invoke(cycle.prompt);
+            const invocation = adapter.invoke(cycle.prompt, graph);
             ledger.activityLog.push(`cycle ${cycle.id} → executor ${executor.name} (${executor.executorId}) on ${cycle.runtime}: ${invocation.describe}`);
             let output;
             let cost = 0;
@@ -129,6 +141,7 @@ export class MissionConductor {
                     routed: true,
                     reason: `worker error: ${err instanceof Error ? err.message : String(err)}`,
                     cost: 0,
+                    ...(graph ? { graph } : {}),
                 };
                 ledger.cycles.push(result);
                 ledger.checkpoint.failed.push(cycle.id);
@@ -144,6 +157,7 @@ export class MissionConductor {
                 reason: routing.selected.matchReason,
                 output,
                 cost,
+                ...(graph ? { graph } : {}),
             };
             ledger.cycles.push(result);
             ledger.checkpoint.completed.push(cycle.id);

package/dist/src/serve/pty-bridge.js

@@ -695,19 +695,14 @@ export async function handlePtyConnection(sessionId, ws, command = 'aiwg', cmdAr
         }
     }
     else if (!session.exited) {
-        // Reconnect to existing session — replay buffer
+        // Reconnect to an existing session by replaying the complete retained
+        // buffer. Do not trim at the last full-screen erase: terminal erase
+        // sequences repaint the current viewport but xterm still needs the bytes
+        // that preceded them to reconstruct scrollback when a user switches away
+        // from a session and later returns (#2146).
         registry.addClient(sessionId, clientId, ws);
         if (session.outputBuffer) {
-            // Trim replay to start from the last full-screen erase so that tmux's
-            // screen-init sequences (cursor moves, status-bar paint) from before the
-            // erase don't render as literal garbage in a fresh xterm.js context.
-            // Everything before \x1b[2J would be cleared by the erase anyway;
-            // everything after is the session content tmux redrew (MOTD, history, etc).
-            // If no erase is found, replay the whole buffer unchanged.
-            const ERASE = '\x1b[2J';
-            const lastErase = session.outputBuffer.lastIndexOf(ERASE);
-            const replay = lastErase !== -1 ? session.outputBuffer.slice(lastErase) : session.outputBuffer;
-            ws.send(JSON.stringify({ type: 'data', payload: replay }));
+            ws.send(JSON.stringify({ type: 'data', payload: session.outputBuffer }));
         }
     }
     else {

package/dist/src/serve/stack-adapters.js

@@ -23,7 +23,7 @@ function makeAdapter(runtime, primitive) {
         runtime,
         runtimeCapability,
         primitive,
-        invoke(prompt) {
+        invoke(prompt, graph) {
             // prompt is carried by the dispatch payload; the descriptor records the
             // mechanism so the conductor's ledger is identical-shape across stacks.
             const trimmed = prompt.length > 60 ? `${prompt.slice(0, 57)}...` : prompt;
@@ -31,6 +31,7 @@ function makeAdapter(runtime, primitive) {
                 runtimeCapability,
                 primitive,
                 describe: `dispatch worker to ${runtime} executor via ${primitive} (${trimmed})`,
+                ...(graph ? { graph: structuredClone(graph) } : {}),
             };
         },
     };

package/dist/src/serve/telemetry.js

@@ -130,7 +130,10 @@ export const telemetryStore = new TelemetryStore();
 // Event Factory
 // ============================================================
 let eventCounter = 0;
-export function createEvent(type, sessionId, payload, missionId) {
+export function createEvent(type, sessionId, payload, missionId, graph) {
+    if (type.startsWith('graph.') && !graph) {
+        throw new Error(`Telemetry event '${type}' requires graph execution metadata.`);
+    }
     return {
         id: `evt-${Date.now()}-${++eventCounter}`,
         sessionId,
@@ -138,6 +141,7 @@ export function createEvent(type, sessionId, payload, missionId) {
         timestamp: new Date().toISOString(),
         type,
         payload,
+        ...(graph ? { graph: structuredClone(graph) } : {}),
     };
 }
 //# sourceMappingURL=telemetry.js.map

package/dist/src/skills/run.js

@@ -25,6 +25,8 @@ import { spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import * as path from 'node:path';
 import { resolveRuntime, supportedRuntimes } from './runtime.js';
+import { recordTypeForEntry, stableRecordId } from '../artifacts/browser-export.js';
+import { loadFortemiCoreMetadataEntries } from '../artifacts/fortemi-core-query-adapter.js';
 /**
  * Resolve the AIWG installation root. Prefers `$AIWG_ROOT` env, falls
  * back to the channel manager's framework-root resolver.
@@ -53,22 +55,29 @@ async function findSkillEntry(cwd, name) {
     const reader = await import('../artifacts/index-reader.js');
     const entries = [];
     for (const g of ['framework', 'project', 'codebase']) {
-        const idx = reader.loadGraphIndexFile(cwd, 'metadata.json', g);
-        if (idx)
-            entries.push(...Object.values(idx.entries));
+        const canonical = loadFortemiCoreMetadataEntries(cwd, g);
+        if (canonical.entries.length > 0) {
+            entries.push(...canonical.entries);
+        }
+        else {
+            const idx = reader.loadGraphIndexFile(cwd, 'metadata.json', g);
+            if (idx)
+                entries.push(...Object.values(idx.entries));
+        }
     }
     if (entries.length === 0) {
         const legacy = reader.loadMetadataIndex(cwd);
         if (legacy)
             entries.push(...Object.values(legacy.entries));
     }
-    const skills = entries.filter(e => e.type === 'skill');
+    const skills = entries.filter(e => e.type === 'skill' || e.type === 'aiwg.skill');
     const needle = name.trim();
     // Basename match — skills are conventionally `<dir>/SKILL.md`
     const matches = skills.filter(e => {
         const dir = path.basename(path.dirname(e.path));
         const stem = path.basename(e.path).replace(/\.[^.]+$/, '');
-        return dir === needle || stem === needle || e.path === needle;
+        const id = stableRecordId(recordTypeForEntry({ ...e, type: 'skill' }, 'v2'), e.path);
+        return id === needle || e.name === needle || dir === needle || stem === needle || e.path === needle;
     });
     if (matches.length === 0)
         return null;
@@ -248,7 +257,7 @@ export async function main(args, env) {
     });
 }
 function printUsage() {
-    console.log('Usage: aiwg run skill <name> [--cwd <path>] [-- <args...>]');
+    console.log('Usage: aiwg run skill <stable-id-or-name> [--cwd <path>] [-- <args...>]');
     console.log('');
     console.log('Examples:');
     console.log('  aiwg run skill voice-apply -- --voice technical-authority --input draft.md');

package/dist/src/update/checker.mjs

@@ -15,6 +15,7 @@ import https from 'https';
 import { execSync } from 'child_process';
 import { createInterface } from 'readline';
 import { loadConfig, saveConfig, getChannel, getPackageRoot } from '../channel/manager.mjs';
+import { updateInstallation } from './service.mjs';
 
 const NPM_REGISTRY = 'https://registry.npmjs.org/aiwg';
 
@@ -212,13 +213,13 @@ async function checkStableUpdates(config) {
         console.log('');
         console.log('Updating aiwg...');
         try {
-          execSync('npm install -g aiwg@latest', { stdio: 'inherit' });
+          await updateInstallation({ config, channel: 'stable' });
           console.log('Update complete! Please restart your terminal.');
         } catch (error) {
-          console.error('Update failed. Run manually: npm install -g aiwg@latest');
+          console.error('Update failed. Run manually: aiwg update');
         }
       } else {
-        console.log('Update skipped. Run `npm install -g aiwg@latest` when ready.');
+        console.log('Update skipped. Run `aiwg update` when ready.');
       }
       console.log('');
     }
@@ -251,13 +252,13 @@ async function checkNextUpdates(config) {
         console.log('');
         console.log('Updating aiwg@next...');
         try {
-          execSync('npm install -g aiwg@next', { stdio: 'inherit' });
+          await updateInstallation({ config, channel: 'next' });
           console.log('Update complete! Please restart your terminal.');
         } catch {
-          console.error('Update failed. Run manually: npm install -g aiwg@next');
+          console.error('Update failed. Run manually: aiwg update');
         }
       } else {
-        console.log('Update skipped. Run `npm install -g aiwg@next` when ready.');
+        console.log('Update skipped. Run `aiwg update` when ready.');
       }
       console.log('');
     }
@@ -290,13 +291,13 @@ async function checkNightlyUpdates(config) {
         console.log('');
         console.log('Updating aiwg@nightly...');
         try {
-          execSync('npm install -g aiwg@nightly', { stdio: 'inherit' });
+          await updateInstallation({ config, channel: 'nightly' });
           console.log('Update complete! Please restart your terminal.');
         } catch {
-          console.error('Update failed. Run manually: npm install -g aiwg@nightly');
+          console.error('Update failed. Run manually: aiwg update');
         }
       } else {
-        console.log('Update skipped. Run `npm install -g aiwg@nightly` when ready.');
+        console.log('Update skipped. Run `aiwg update` when ready.');
       }
       console.log('');
     }
@@ -348,13 +349,13 @@ export async function forceUpdateCheck() {
     console.log('Checking for updates on next channel...');
     const latestVersion = await fetchNpmDistTag('next');
     if (!latestVersion) {
-      console.log('Could not check npm registry. Try: npm install -g aiwg@next');
+      console.log('Could not check npm registry. Try: aiwg update');
       return;
     }
     if (currentVersion !== latestVersion) {
       console.log(`Update available: ${currentVersion} → ${latestVersion}`);
       console.log('');
-      console.log('Run: npm install -g aiwg@next');
+      console.log('Run: aiwg update');
     } else {
       console.log(`You are on the latest next release: ${currentVersion}`);
     }
@@ -362,13 +363,13 @@ export async function forceUpdateCheck() {
     console.log('Checking for updates on nightly channel...');
     const latestVersion = await fetchNpmDistTag('nightly');
     if (!latestVersion) {
-      console.log('Could not check npm registry. Try: npm install -g aiwg@nightly');
+      console.log('Could not check npm registry. Try: aiwg update');
       return;
     }
     if (currentVersion !== latestVersion) {
       console.log(`Update available: ${currentVersion} → ${latestVersion}`);
       console.log('');
-      console.log('Run: npm install -g aiwg@nightly');
+      console.log('Run: aiwg update');
     } else {
       console.log(`You are on the latest nightly snapshot: ${currentVersion}`);
     }
@@ -381,14 +382,14 @@ export async function forceUpdateCheck() {
     const latestVersion = await fetchLatestNpmVersion();
 
     if (!latestVersion) {
-      console.log('Could not check npm registry. Try: npm install -g aiwg@latest');
+      console.log('Could not check npm registry. Try: aiwg update');
       return;
     }
 
     if (isNewerVersion(currentVersion, latestVersion)) {
       console.log(`Update available: ${currentVersion} → ${latestVersion}`);
       console.log('');
-      console.log('Run: npm install -g aiwg@latest');
+      console.log('Run: aiwg update');
     } else {
       console.log(`You are on the latest version: ${currentVersion}`);
     }

package/dist/src/update/notifier.mjs

@@ -27,12 +27,13 @@
 
 import https from 'https';
 import path from 'path';
-import os from 'os';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
+import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
+import { loadInstallationIdentity } from '../installation/manager.mjs';
 
-const CACHE_DIR = path.join(os.homedir(), '.aiwg');
+const CACHE_DIR = resolveUserConfigDir();
 const CACHE_FILE = path.join(CACHE_DIR, 'update-notifier.json');
 
 /**
@@ -191,11 +192,13 @@ async function runCheck(packageRoot) {
  */
 export function scheduleBackgroundCheck(packageRoot) {
   if (isDisabled()) return;
+  const installation = loadInstallationIdentity({ actualRoot: packageRoot, createIfMissing: false });
+  if (installation?.checkOnStartup === false) return;
 
   const cache = readCache();
   if (cacheMatchesPackage(cache, packageRoot) && cache?.lastCheckAt) {
     const age = Date.now() - new Date(cache.lastCheckAt).getTime();
-    if (age < CHECK_INTERVAL_MS) return; // recent enough — skip
+    if (age < (installation?.updateCheckInterval ?? CHECK_INTERVAL_MS)) return; // recent enough — skip
   }
 
   try {
@@ -225,6 +228,8 @@ export function scheduleBackgroundCheck(packageRoot) {
  */
 export function maybePrintNotice(packageRoot) {
   if (isDisabled()) return;
+  const installation = loadInstallationIdentity({ actualRoot: packageRoot, createIfMissing: false });
+  if (installation?.checkOnStartup === false) return;
   const cache = readCache();
   if (!cacheMatchesPackage(cache, packageRoot)) return;
   if (!cache?.hasUpdate || !cache.current || !cache.latest) return;

package/dist/src/update/service.mjs

@@ -10,6 +10,12 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { getPackageRoot, loadConfig } from '../channel/manager.mjs';
+import {
+  assertCanonicalInstallation,
+  createInstallationIdentity,
+  loadInstallationIdentity,
+  saveInstallationIdentity,
+} from '../installation/manager.mjs';
 
 const VALID_MODES = new Set(['npm', 'web', 'source']);
 
@@ -24,14 +30,42 @@ function readPackageName(packageRoot) {
 export async function detectInstallMode(options = {}) {
   const packageRoot = options.packageRoot ?? getPackageRoot();
   const override = options.env?.AIWG_INSTALL_MODE ?? process.env.AIWG_INSTALL_MODE;
+  const config = options.config ?? await loadConfig(options);
+  let identity = options.identity ?? config.installation ?? null;
+  let identityPersistent = Boolean(config.installation) || options.identityPersistent === true;
+  if (!identity && options.config) {
+    const method = override ?? (readPackageName(packageRoot) === '@aiwg/cli'
+      ? 'web'
+      : (config.devMode || config.channel === 'edge' || existsSync(path.join(packageRoot, '.git'))) ? 'source' : 'npm');
+    identity = createInstallationIdentity({
+      ...options,
+      actualRoot: packageRoot,
+      method,
+      channel: config.channel,
+      runMode: config.devMode ? 'development' : undefined,
+    });
+  } else if (!identity) {
+    identity = loadInstallationIdentity({ ...options, actualRoot: packageRoot });
+    identityPersistent = Boolean(identity);
+  }
+
+  if (override && !VALID_MODES.has(override)) {
+    throw new Error(`AIWG_INSTALL_MODE must be one of: ${[...VALID_MODES].join(', ')}`);
+  }
+  if (override && identity && override !== identity.method) {
+    throw new Error(`AIWG_INSTALL_MODE=${override} conflicts with the canonical installation method ${identity.method}. Use \`aiwg installation switch\` instead.`);
+  }
+  if (identity) {
+    const status = assertCanonicalInstallation({ ...options, actualRoot: packageRoot, identity });
+    return { mode: identity.method, packageRoot, packageName: readPackageName(packageRoot), identity, identityPersistent, installation: status };
+  }
+
   if (override) {
     if (!VALID_MODES.has(override)) {
       throw new Error(`AIWG_INSTALL_MODE must be one of: ${[...VALID_MODES].join(', ')}`);
     }
     return { mode: override, packageRoot, packageName: readPackageName(packageRoot) };
   }
-
-  const config = options.config ?? await loadConfig();
   const packageName = readPackageName(packageRoot);
   if (packageName === '@aiwg/cli') return { mode: 'web', packageRoot, packageName };
   if (config.devMode || config.channel === 'edge' || existsSync(path.join(packageRoot, '.git'))) {
@@ -56,7 +90,7 @@ function npmTag(channel) {
 export async function updateInstallation(options = {}) {
   const config = options.config ?? await loadConfig();
   const detected = await detectInstallMode({ ...options, config });
-  const channel = options.channel ?? config.channel ?? 'stable';
+  const channel = options.channel ?? detected.identity?.channel ?? config.channel ?? 'stable';
   const dryRun = options.dryRun === true;
   const offline = options.offline === true;
 
@@ -84,6 +118,9 @@ export async function updateInstallation(options = {}) {
       return resolveWebRelease({ selector });
     });
     const release = await refreshWebResources(channel);
+    if (detected.identity && detected.identityPersistent && options.persistIdentity !== false) {
+      saveInstallationIdentity({ ...detected.identity, channel }, options);
+    }
     return {
       ...detected,
       channel,
@@ -106,16 +143,23 @@ export async function updateInstallation(options = {}) {
 
   const tag = npmTag(channel);
   const command = ['install', '--global', `aiwg@${tag}`];
+  const managerExecutable = detected.identity?.managerExecutable;
+  if (!managerExecutable) {
+    throw new Error('Canonical npm installation has no package-manager executable. Run `aiwg installation adopt --manager <absolute-path-to-npm>`.');
+  }
   if (!dryRun) {
     const execute = options.execute ?? ((file, args) => execFileSync(file, args, { stdio: 'inherit' }));
-    execute('npm', command);
+    execute(managerExecutable, command);
+    if (detected.identity && detected.identityPersistent && options.persistIdentity !== false) {
+      saveInstallationIdentity({ ...detected.identity, channel }, options);
+    }
   }
   return {
     ...detected,
     channel,
     status: dryRun ? 'dry-run' : 'updated',
     changed: !dryRun,
-    command: `npm ${command.join(' ')}`,
+    command: `${managerExecutable} ${command.join(' ')}`,
     message: dryRun
       ? `Would update the full AIWG npm distribution on the '${tag}' channel.`
       : `Updated the full AIWG npm distribution on the '${tag}' channel.`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.16",
+  "version": "2026.8.18",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -67,6 +67,7 @@
   "dependencies": {
     "@fortemi/core": "2026.7.15",
     "@modelcontextprotocol/sdk": "^1.30.0",
+    "ajv": "^8.20.0",
     "chalk": "^4.1.2",
     "chokidar": "^4.0.3",
     "commander": "^12.1.0",