@aiwg/cli 2026.8.17 → 2026.8.19

package/dist/src/artifacts/stats.js

@@ -7,7 +7,7 @@
  * @source @src/artifacts/types.ts
  * @tests @test/unit/artifacts/stats.test.ts
  */
-import { GRAPH_CONFIGS, loadUserGraphConfigs } from './types.js';
+import { GRAPH_CONFIGS, loadGlobalGraphConfigs, loadUserGraphConfigs } from './types.js';
 import { loadIndexStats, loadGraphIndexFile } from './index-reader.js';
 import { collectGraphIndexFiles, indexPathFor } from './index-files.js';
 /** Calculate coverage over the same current file set used by the index builder. */
@@ -30,6 +30,8 @@ async function calculateCoverage(cwd, stats, graphType) {
  */
 export async function showStats(cwd, options = {}) {
     const { graph } = options;
+    loadUserGraphConfigs(cwd);
+    loadGlobalGraphConfigs();
     if (graph) {
         // Single graph mode
         const stats = loadGraphIndexFile(cwd, 'stats.json', graph);
@@ -42,7 +44,6 @@ export async function showStats(cwd, options = {}) {
         return;
     }
     // No graph specified: show all graphs with defaultBuild=true
-    loadUserGraphConfigs(cwd);
     const graphTypes = Object.entries(GRAPH_CONFIGS)
         .filter(([, config]) => config.defaultBuild)
         .map(([name]) => name);
@@ -128,6 +129,9 @@ async function renderStats(cwd, stats, options, graphType) {
     // Dependency graph
     console.log('Dependency Graph:');
     console.log(`  Total edges:        ${stats.graphMetrics.totalEdges}`);
+    if (stats.graphMetrics.markdownLinkEdges !== undefined) {
+        console.log(`  Markdown link edges:${String(stats.graphMetrics.markdownLinkEdges).padStart(3)}`);
+    }
     if (stats.graphMetrics.canonicalEdges !== undefined) {
         console.log(`  Canonical edges:    ${stats.graphMetrics.canonicalEdges}`);
         console.log(`  Outgoing declares:  ${stats.graphMetrics.outgoingDeclarations}`);

package/dist/src/artifacts/types.js

@@ -104,7 +104,7 @@ export const INDEX_VERSION = '1.0.0';
  * making the serialized index schema incompatible; a mismatch simply forces a
  * one-time content re-extraction during the next incremental build.
  */
-export const INDEX_EXTRACTOR_VERSION = '2026.07.21.2';
+export const INDEX_EXTRACTOR_VERSION = '2026.08.24.1';
 /**
  * Built-in graph definitions
  */

package/dist/src/audit/operator-decision.js

@@ -22,8 +22,9 @@ export function createDecisionRecord(input, previousHash) {
     const actor = redact(input.actor);
     const correlation = redact(input.correlation);
     const runtime = input.runtime ? redact(input.runtime) : undefined;
+    const graph = input.graph ? redact(input.graph) : undefined;
     const reason = redact(input.reason);
-    const detected = [...actor.paths, ...correlation.paths, ...(runtime?.paths ?? []), ...reason.paths];
+    const detected = [...actor.paths, ...correlation.paths, ...(runtime?.paths ?? []), ...(graph?.paths ?? []), ...reason.paths];
     const unsigned = {
         schema_version: OPERATOR_DECISION_SCHEMA,
         event_id: input.event_id ?? randomUUID(),
@@ -36,6 +37,7 @@ export function createDecisionRecord(input, previousHash) {
         classification: input.classification,
         correlation: correlation.value,
         ...(runtime ? { runtime: runtime.value } : {}),
+        ...(graph ? { graph: graph.value } : {}),
         ...(input.policy_ref ? { policy_ref: input.policy_ref } : {}),
         redacted_fields: [...new Set([...(input.redacted_fields ?? []), ...detected])].sort(),
         previous_hash: previousHash,
@@ -74,6 +76,15 @@ export function toOpenTelemetryLog(record) {
             'aiwg.provider.id': record.correlation.provider_id,
             'aiwg.sandbox.task_id': record.correlation.sandbox_task_id,
             'aiwg.prompt.id': record.correlation.prompt_id,
+            'aiwg.graph.id': record.graph?.graph_id,
+            'aiwg.graph.version': record.graph?.graph_version,
+            'aiwg.graph.run_id': record.graph?.run_id,
+            'aiwg.graph.node_id': record.graph?.node_id,
+            'aiwg.graph.node_run_id': record.graph?.node_run_id,
+            'aiwg.graph.edge_id': record.graph?.edge_id,
+            'aiwg.graph.route_name': record.graph?.route_name,
+            'aiwg.graph.checkpoint_id': record.graph?.checkpoint_id,
+            'aiwg.graph.replay_parent_run_id': record.graph?.replay_parent_run_id,
         }).filter(([, value]) => value !== undefined).map(([key, value]) => ({
             key,
             value: { stringValue: String(value) },
@@ -135,6 +146,9 @@ function validateInput(input) {
         throw new Error('a non-empty operator reason is required');
     if (!Object.values(input.correlation).some(Boolean))
         throw new Error('at least one correlation identifier is required');
+    if (input.graph && ![input.graph.graph_id, input.graph.graph_version, input.graph.run_id, input.graph.node_id, input.graph.node_run_id].every(value => typeof value === 'string' && value.length > 0)) {
+        throw new Error('graph decision context requires graph, run, node, and node-run identity');
+    }
     if (input.timestamp && !Number.isFinite(Date.parse(input.timestamp)))
         throw new Error('timestamp must be valid ISO time');
 }

package/dist/src/channel/manager.mjs

@@ -13,8 +13,17 @@ import fs from 'fs/promises';
 import { readFileSync, existsSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync, spawn } from 'child_process';
+import { execFileSync, execSync, spawn } from 'child_process';
 import os from 'os';
+import { resolveUserConfigDir } from '../config/user-config-dir.mjs';
+import {
+  assertCanonicalInstallation,
+  createInstallationIdentity,
+  inferInstallationMethod,
+  inspectInstallation,
+  loadInstallationIdentity,
+  saveInstallationIdentity,
+} from '../installation/manager.mjs';
 
 /**
  * Run a command with inherited stdio, applying a wall-clock timeout so a
@@ -80,8 +89,6 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // Configuration paths
-const CONFIG_DIR = path.join(os.homedir(), '.aiwg');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'channel.json');
 const EDGE_INSTALL_PATH = path.join(os.homedir(), '.local', 'share', 'ai-writing-guide');
 const REPO_URL = 'https://github.com/jmagly/aiwg.git';
 
@@ -132,22 +139,65 @@ export function getPackageRoot() {
  * Load channel configuration
  * @returns {Promise<object>} Channel configuration
  */
-export async function loadConfig() {
+export async function loadConfig(options = {}) {
+  const configDir = resolveUserConfigDir(options);
+  const configFile = path.join(configDir, 'channel.json');
+  let legacy = {};
   try {
-    const data = await fs.readFile(CONFIG_FILE, 'utf8');
-    return { ...DEFAULT_CONFIG, ...JSON.parse(data) };
+    const data = await fs.readFile(configFile, 'utf8');
+    legacy = JSON.parse(data);
   } catch {
-    return { ...DEFAULT_CONFIG };
+    // Legacy state is optional. The canonical identity below is authoritative.
   }
+  const actualRoot = options.actualRoot ?? getPackageRoot();
+  const identity = loadInstallationIdentity({ ...options, actualRoot, legacyConfig: legacy });
+  if (!identity) return { ...DEFAULT_CONFIG, ...legacy };
+  return {
+    ...DEFAULT_CONFIG,
+    ...legacy,
+    channel: identity.channel,
+    edgePath: identity.edgePath ?? legacy.edgePath ?? EDGE_INSTALL_PATH,
+    devMode: identity.runMode === 'development',
+    lastUpdateCheck: identity.lastUpdateCheck,
+    updateCheckInterval: identity.updateCheckInterval,
+    checkOnStartup: identity.checkOnStartup,
+    installation: identity,
+  };
 }
 
 /**
  * Save channel configuration
  * @param {object} config - Configuration to save
  */
-export async function saveConfig(config) {
-  await fs.mkdir(CONFIG_DIR, { recursive: true });
-  await fs.writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+export async function saveConfig(config, options = {}) {
+  const configDir = resolveUserConfigDir(options);
+  const configFile = path.join(configDir, 'channel.json');
+  await fs.mkdir(configDir, { recursive: true });
+  const { installation: _installation, ...legacyConfig } = config;
+  await fs.writeFile(configFile, `${JSON.stringify(legacyConfig, null, 2)}\n`);
+
+  const actualRoot = options.actualRoot ?? getPackageRoot();
+  const previous = loadInstallationIdentity({ ...options, actualRoot, legacyConfig: config });
+  if (previous) {
+    const development = config.devMode === true;
+    const root = development && config.edgePath ? config.edgePath : previous.root;
+    const method = development ? 'source' : previous.method;
+    saveInstallationIdentity(createInstallationIdentity({
+      ...options,
+      actualRoot,
+      root,
+      method,
+      runMode: development ? 'development' : 'normal',
+      channel: config.channel ?? previous.channel,
+      edgePath: config.edgePath ?? previous.edgePath,
+      managerExecutable: development ? undefined : previous.managerExecutable,
+      updateStrategy: development ? 'source-git' : previous.updateStrategy,
+      lastUpdateCheck: config.lastUpdateCheck ?? previous.lastUpdateCheck,
+      updateCheckInterval: config.updateCheckInterval ?? previous.updateCheckInterval,
+      checkOnStartup: config.checkOnStartup ?? previous.checkOnStartup,
+      recordedAt: previous.recordedAt,
+    }), options);
+  }
 }
 
 /**
@@ -178,7 +228,7 @@ export async function getFrameworkRoot() {
     }
   }
 
-  return getPackageRoot();
+  return config.installation?.root ?? getPackageRoot();
 }
 
 /**
@@ -316,12 +366,16 @@ export async function switchToDev(devPath) {
  */
 export async function switchToNext() {
   const config = await loadConfig();
+  const status = assertCanonicalInstallation({ actualRoot: getPackageRoot() });
+  if (status.identity.method !== 'npm' || !status.identity.managerExecutable) {
+    throw new Error('The next channel requires a canonical npm installation with a recorded package-manager executable.');
+  }
 
   console.log('Switching to next channel (alpha/beta/RC — latest pre-release)...');
   console.log('');
 
   try {
-    execSync('npm install -g aiwg@next', { stdio: 'inherit' });
+    execFileSync(status.identity.managerExecutable, ['install', '--global', 'aiwg@next'], { stdio: 'inherit' });
   } catch (error) {
     console.error('Failed to install aiwg@next:', error.message);
     console.error('Check that npm is available and you have write access to the global prefix.');
@@ -346,12 +400,16 @@ export async function switchToNext() {
  */
 export async function switchToNightly() {
   const config = await loadConfig();
+  const status = assertCanonicalInstallation({ actualRoot: getPackageRoot() });
+  if (status.identity.method !== 'npm' || !status.identity.managerExecutable) {
+    throw new Error('The nightly channel requires a canonical npm installation with a recorded package-manager executable.');
+  }
 
   console.log('Switching to nightly channel (latest automated snapshot)...');
   console.log('');
 
   try {
-    execSync('npm install -g aiwg@nightly', { stdio: 'inherit' });
+    execFileSync(status.identity.managerExecutable, ['install', '--global', 'aiwg@nightly'], { stdio: 'inherit' });
   } catch (error) {
     console.error('Failed to install aiwg@nightly:', error.message);
     console.error('Check that npm is available and you have write access to the global prefix.');
@@ -376,17 +434,29 @@ export async function switchToNightly() {
 export async function switchToStable() {
   const config = await loadConfig();
 
-  console.log('Switching to stable channel (npm package)...');
+  console.log('Switching to the stable channel...');
   console.log('');
 
   config.channel = 'stable';
   config.devMode = false;
   await saveConfig(config);
+  const actualRoot = getPackageRoot();
+  saveInstallationIdentity(createInstallationIdentity({
+    actualRoot,
+    root: actualRoot,
+    method: inferInstallationMethod(actualRoot),
+    runMode: 'normal',
+    channel: 'stable',
+    edgePath: config.edgePath,
+    lastUpdateCheck: config.lastUpdateCheck,
+    updateCheckInterval: config.updateCheckInterval,
+    checkOnStartup: config.checkOnStartup,
+  }));
 
   console.log('Switched to stable channel.');
-  console.log('You are now using the npm-installed package.');
+  console.log('You are now using the canonical installed package.');
   console.log('');
-  console.log('To update: npm install -g aiwg@latest');
+  console.log('To update: aiwg refresh --channel latest');
   console.log('To switch to edge: aiwg --use-main');
 }
 
@@ -415,6 +485,7 @@ function normalizeRepoUrl(repository) {
 export async function getVersionInfo() {
   const config = await loadConfig();
   const packageRoot = getPackageRoot();
+  const installation = inspectInstallation({ actualRoot: packageRoot, identity: config.installation });
 
   // Read package.json version
   const packageJsonPath = path.join(packageRoot, 'package.json');
@@ -441,6 +512,7 @@ export async function getVersionInfo() {
     version,
     channel,
     packageRoot,
+    installation,
     devMode: config.devMode || false,
     // Public-facing URLs — single source of truth is package.json, so user-visible
     // stamps/links never hardcode the internal build origin. The published package
@@ -480,7 +552,7 @@ export async function updateEdge() {
   const config = await loadConfig();
 
   if (config.channel !== 'edge') {
-    console.log('Not in edge channel. Use npm install -g aiwg@latest for stable channel.');
+    console.log('Not in edge channel. Use `aiwg update` for the canonical installed channel.');
     return;
   }
 

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

@@ -63,12 +63,13 @@ import { costReportHandler } from './cost-report.js';
 import { evidenceHandler } from './evidence.js';
 import { artifactVerifyHandler } from './artifact-verify.js';
 import { outputModeHandler } from './output-mode.js';
+import { installationHandler } from './installation.js';
 // Re-export individual handlers
 export { 
 // Maintenance
 helpHandler, versionHandler, authHandler, doctorHandler, contextFirewallHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, jobHandler, costReportHandler, evidenceHandler, artifactVerifyHandler, outputModeHandler, installationHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -125,6 +126,7 @@ export const allHandlers = [
     contextFirewallHandler,
     updateHandler,
     refreshHandler,
+    installationHandler,
     regenerateHandler,
     workspaceContextHandler,
     // Framework management

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

@@ -0,0 +1,79 @@
+import { getPackageRoot } from '../../channel/manager.mjs';
+import { adoptInstallation, inspectInstallation, loadInstallationIdentity, switchInstallation, } from '../../installation/manager.mjs';
+function valueAfter(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function display(status, json) {
+    if (json) {
+        console.log(JSON.stringify(status, null, 2));
+        return;
+    }
+    console.log('\nCanonical AIWG Installation');
+    console.log('===========================');
+    console.log(`State:             ${status.state}`);
+    console.log(`Canonical method:  ${status.identity?.method ?? '(unrecorded)'}`);
+    console.log(`Canonical root:    ${status.identity?.root ?? '(unrecorded)'}`);
+    console.log(`Manager:           ${status.identity?.managerExecutable ?? '(internal)'}`);
+    console.log(`Update strategy:   ${status.identity?.updateStrategy ?? '(unrecorded)'}`);
+    console.log(`Run mode:          ${status.identity?.runMode ?? '(unrecorded)'}`);
+    console.log(`Release channel:   ${status.identity?.channel ?? '(unrecorded)'}`);
+    console.log(`Actual method:     ${status.actualMethod}`);
+    console.log(`Actual root:       ${status.actualRoot}`);
+    if (status.drift.length > 0) {
+        console.log('Drift:');
+        for (const item of status.drift)
+            console.log(`  - ${item}`);
+    }
+    console.log('');
+}
+export const installationHandler = {
+    id: 'installation',
+    name: 'Installation',
+    description: 'Inspect, adopt, or deliberately switch the canonical global installation',
+    category: 'maintenance',
+    aliases: [],
+    async execute(ctx) {
+        const [action = 'show'] = ctx.args;
+        const json = ctx.args.includes('--json');
+        const actualRoot = getPackageRoot();
+        const common = {
+            actualRoot,
+            configDir: valueAfter(ctx.args, '--config-dir'),
+            managerExecutable: valueAfter(ctx.args, '--manager'),
+            channel: valueAfter(ctx.args, '--channel'),
+        };
+        if (action === 'show') {
+            const identity = loadInstallationIdentity({ ...common, createIfMissing: true });
+            display(inspectInstallation({ ...common, identity, probeManager: true }), json);
+            return { exitCode: 0 };
+        }
+        if (action === 'adopt') {
+            const method = valueAfter(ctx.args, '--method');
+            const status = adoptInstallation({
+                ...common,
+                method,
+                runMode: valueAfter(ctx.args, '--run-mode'),
+            });
+            display(status, json);
+            return { exitCode: 0 };
+        }
+        if (action === 'switch') {
+            const root = valueAfter(ctx.args, '--root');
+            const method = valueAfter(ctx.args, '--method');
+            if (!root || !method) {
+                return { exitCode: 2, message: 'Usage: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]' };
+            }
+            const status = switchInstallation({
+                ...common,
+                root,
+                method,
+                runMode: valueAfter(ctx.args, '--run-mode'),
+            });
+            display(status, json);
+            return { exitCode: 0 };
+        }
+        return { exitCode: 2, message: 'Usage: aiwg installation <show|adopt|switch> [options]' };
+    },
+};
+//# sourceMappingURL=installation.js.map

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

@@ -205,6 +205,7 @@ export const refreshHandler = {
         if (!quiet)
             ui.info(dryRun ? 'Would refresh remote packages...' : 'Refreshing remote packages...');
         const deploymentFailures = [];
+        let updateFailure = null;
         if (!dryRun) {
             try {
                 const refreshed = await refreshAllPackages();
@@ -242,8 +243,10 @@ export const refreshHandler = {
                         ui.success('Package up to date');
                 }
                 else {
-                    if (!quiet)
-                        ui.warn('Update check returned non-zero (may already be current)');
+                    updateFailure = { exitCode: updateResult.exitCode };
+                    if (!quiet) {
+                        ui.warn('Installation update failed; continuing with re-deployment. Run `aiwg installation show` for canonical-install diagnostics.');
+                    }
                 }
             }
         }
@@ -463,6 +466,7 @@ export const refreshHandler = {
                 channel: channel || undefined,
                 staleAgentRemovals,
                 deploymentFailures,
+                updateFailure,
             });
             console.log(output);
         }

package/dist/src/cli/handlers/runtime-info.js

@@ -10,6 +10,8 @@
  */
 import path from 'path';
 import { AiwgError, EXIT_CODES, handlerResultFromError } from '../errors.js';
+import { getPackageRoot } from '../../channel/manager.mjs';
+import { inspectInstallation } from '../../installation/manager.mjs';
 function isMissingRuntimeCatalogError(error) {
     return error instanceof Error && error.message.includes('No catalog found');
 }
@@ -237,8 +239,9 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             await discovery.discover();
             summary = await discovery.getSummary();
         }
+        const installation = inspectInstallation({ actualRoot: getPackageRoot() });
         if (hasJson) {
-            console.log(JSON.stringify(summary, null, 2));
+            console.log(JSON.stringify({ ...summary, installation }, null, 2));
         }
         else {
             console.log(`\nRuntime Environment Summary`);
@@ -256,6 +259,11 @@ async function handleRuntimeInfo(args, cwd = process.cwd()) {
             console.log(`\nTotal: ${summary.totalTools} verified tools`);
             console.log(`\nLast Discovery: ${summary.lastDiscovery}`);
             console.log(`Catalog: ${summary.catalogPath}`);
+            console.log(`\nAIWG Installation:`);
+            console.log(`  Canonical: ${installation.identity?.method ?? 'unrecorded'} at ${installation.identity?.root ?? '(unrecorded)'}`);
+            console.log(`  Actual:    ${installation.actualMethod} at ${installation.actualRoot}`);
+            console.log(`  Run mode:  ${installation.identity?.runMode ?? '(unrecorded)'}`);
+            console.log(`  State:     ${installation.state}`);
             // Scheduler backend detection
             const { execSync } = await import('child_process');
             let schedulerBackend = 'external trigger required (system cron/systemd/CI)';

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

@@ -27,8 +27,14 @@ const pushSecretRegistry = new PushSecretRegistry();
 const webhookIdempotency = new IdempotencyCache();
 const DEFAULT_PORT = 7337;
 const DEFAULT_HOST = '127.0.0.1';
+function readA2AProtocolPolicy(value) {
+    const policy = value ?? '0.3';
+    if (policy === '0.3' || policy === '1.0' || policy === 'auto')
+        return policy;
+    throw new Error(`AIWG_A2A_PROTOCOL_POLICY must be 0.3, 1.0, or auto (received '${policy}')`);
+}
 /**
- * Parse --port, --bind, --no-open, --read-only flags from args
+ * Parse dashboard and A2A negotiation flags from args.
  */
 function parseServeArgs(args) {
     let port = DEFAULT_PORT;
@@ -36,6 +42,9 @@ function parseServeArgs(args) {
     let open = true;
     let readOnly = false;
     let sandbox = null;
+    let a2aProtocolPolicy;
+    let allowA2AProtocolFallback;
+    let allowLegacyExecutorFallback;
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
         if (arg === '--port' && args[i + 1]) {
@@ -58,8 +67,33 @@ function parseServeArgs(args) {
         else if (arg === '--read-only') {
             readOnly = true;
         }
+        else if (arg === '--a2a-protocol' && args[i + 1]) {
+            a2aProtocolPolicy = readA2AProtocolPolicy(args[i + 1]);
+            i++;
+        }
+        else if (arg === '--a2a-protocol-fallback') {
+            allowA2AProtocolFallback = true;
+        }
+        else if (arg === '--no-a2a-protocol-fallback') {
+            allowA2AProtocolFallback = false;
+        }
+        else if (arg === '--a2a-legacy-executor-fallback') {
+            allowLegacyExecutorFallback = true;
+        }
+        else if (arg === '--no-a2a-legacy-executor-fallback') {
+            allowLegacyExecutorFallback = false;
+        }
     }
-    return { port, host, open, readOnly, sandbox };
+    return {
+        port,
+        host,
+        open,
+        readOnly,
+        sandbox,
+        ...(a2aProtocolPolicy ? { a2aProtocolPolicy } : {}),
+        ...(allowA2AProtocolFallback !== undefined ? { allowA2AProtocolFallback } : {}),
+        ...(allowLegacyExecutorFallback !== undefined ? { allowLegacyExecutorFallback } : {}),
+    };
 }
 // ============================================================
 // WebSocket routing (#851)
@@ -499,6 +533,13 @@ async function setupWebSockets(httpServer, readOnly) {
  * @see #1277 — moves the integration suite off spawn-based testing
  */
 export async function startServer(opts) {
+    const configuredA2AProtocolPolicy = opts.a2aProtocolPolicy
+        ?? readA2AProtocolPolicy(process.env['AIWG_A2A_PROTOCOL_POLICY']);
+    const configuredA2AProtocolFallback = opts.allowA2AProtocolFallback
+        ?? process.env['AIWG_A2A_PROTOCOL_FALLBACK'] === 'true';
+    const configuredLegacyExecutorFallback = configuredA2AProtocolPolicy !== '1.0'
+        && (opts.allowLegacyExecutorFallback
+            ?? process.env['AIWG_A2A_LEGACY_EXECUTOR_FALLBACK'] !== 'false');
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let honoMod;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -760,8 +801,32 @@ export async function startServer(opts) {
         let a2aInstanceId;
         let dispatchPath = 'v2';
         let a2aTask = undefined;
+        let a2aProtocolVersion;
+        let a2aInterface;
+        let a2aFallbackReason;
+        const a2aProtocolPolicy = configuredA2AProtocolPolicy;
         try {
             const result = await routeDispatch(executor, payload, {
+                a2aProtocolPolicy,
+                allowA2AProtocolFallback: configuredA2AProtocolFallback,
+                allowLegacyExecutorFallback: configuredLegacyExecutorFallback,
+                onA2AProtocolSelection: (info) => {
+                    telemetryStore.ingest(createEvent('a2a.protocol.selected', sessionId, {
+                        selected_version: info.selected,
+                        policy: info.policy,
+                        ...(info.interface ? {
+                            protocol_binding: info.interface.protocolBinding,
+                            interface_url: info.interface.url,
+                        } : {}),
+                    }, missionId));
+                },
+                onA2AProtocolFallback: (info) => {
+                    telemetryStore.ingest(createEvent('a2a.protocol.fallback', sessionId, {
+                        from_version: info.from,
+                        to_version: info.to,
+                        reason: info.reason,
+                    }, missionId));
+                },
                 onV1Fallback: (info) => {
                     logServeWarn('dispatch', `v1 fallback for executor ${info.executorId}: ${info.reason}`);
                     telemetryStore.ingest(createEvent('v1.dispatch.fallback', sessionId, info, missionId));
@@ -775,6 +840,9 @@ export async function startServer(opts) {
             dispatchPath = result.dispatchPath;
             a2aInstanceId = result.a2aInstanceId;
             a2aTask = result.task;
+            a2aProtocolVersion = result.a2aProtocolVersion;
+            a2aInterface = result.a2aInterface;
+            a2aFallbackReason = result.a2aFallbackReason;
             if (result.estimatedStart)
                 estimatedStart = result.estimatedStart;
         }
@@ -796,12 +864,22 @@ export async function startServer(opts) {
             return c.json({ error: errorTag, detail: msg }, status);
         }
         // 4. Record the mission and emit telemetry
+        if (a2aProtocolVersion && a2aInterface) {
+            executorRegistry.recordA2AProtocolSelection(executor.executorId, {
+                policy: a2aProtocolPolicy,
+                selectedVersion: a2aProtocolVersion,
+                interface: a2aInterface,
+                ...(a2aFallbackReason ? { fallbackReason: a2aFallbackReason } : {}),
+            });
+        }
         executorRegistry.assignMission(missionId, executor.executorId);
         if (dispatchPath === 'v2' && a2aTask && a2aInstanceId) {
             void observeA2ATerminalState(executorRegistry, executor, missionId, a2aInstanceId, a2aTask, {
                 onError: (err) => {
                     logServeWarn('dispatch', `A2A terminal observer failed for mission ${missionId}: ${err.message ?? String(err)}`);
                 },
+                ...(a2aProtocolVersion ? { protocolVersion: a2aProtocolVersion } : {}),
+                ...(a2aInterface ? { selectedInterface: a2aInterface } : {}),
             });
         }
         telemetryStore.ingest(createEvent('mission.dispatch', sessionId, {
@@ -809,6 +887,8 @@ export async function startServer(opts) {
             executorId: executor.executorId,
             objective: payload.objective,
             completion: payload.completion,
+            ...(a2aProtocolVersion ? { a2a_protocol_version: a2aProtocolVersion } : {}),
+            ...(a2aFallbackReason ? { a2a_fallback_reason: a2aFallbackReason } : {}),
         }, missionId));
         // 5. Return 202 Accepted
         const dispatchResp = {
@@ -819,6 +899,14 @@ export async function startServer(opts) {
         };
         if (a2aInstanceId)
             dispatchResp.a2a_instance_id = a2aInstanceId;
+        if (a2aProtocolVersion)
+            dispatchResp.a2a_protocol_version = a2aProtocolVersion;
+        if (a2aInterface) {
+            dispatchResp.a2a_protocol_binding = a2aInterface.protocolBinding;
+            dispatchResp.a2a_interface_url = a2aInterface.url;
+        }
+        if (a2aFallbackReason)
+            dispatchResp.a2a_fallback_reason = a2aFallbackReason;
         if (estimatedStart)
             dispatchResp.estimated_start = estimatedStart;
         return c.json(dispatchResp, 202);
@@ -947,6 +1035,7 @@ export async function startServer(opts) {
         const result = await handleWebhook(configId, bodyBuf, signature, eventId, {
             registry: pushSecretRegistry,
             idempotency: webhookIdempotency,
+            contentType: c.req.header('content-type') ?? undefined,
             route: async (entry, event) => {
                 // Append to mission recentEvents via a synthesized envelope.
                 // The 'mission.webhook' event type falls through the registry's
@@ -990,11 +1079,17 @@ export async function startServer(opts) {
         if (!p.secret || typeof p.secret !== 'string' || p.secret.length < 16) {
             return c.json({ error: 'secret is required and must be ≥16 chars' }, 400);
         }
+        if (p.protocolVersion === '1.0' && !p.taskId) {
+            return c.json({ error: 'taskId is required for A2A 1.0 push ownership scope' }, 400);
+        }
         pushSecretRegistry.register({
             configId: p.configId,
             secret: p.secret,
             ...(p.missionId ? { missionId: p.missionId } : {}),
             ...(p.taskId ? { taskId: p.taskId } : {}),
+            ...(p.contextId ? { contextId: p.contextId } : {}),
+            ...(p.protocolVersion ? { protocolVersion: p.protocolVersion } : {}),
+            ...(p.taskOwner ? { taskOwner: p.taskOwner } : {}),
             ...(p.metadata ? { metadata: p.metadata } : {}),
         });
         return c.json({ ok: true, configId: p.configId }, 201);
@@ -1749,10 +1844,18 @@ export const serveHandler = {
     category: 'project',
     aliases: [],
     async execute(ctx) {
-        const { port, host, open, readOnly } = parseServeArgs(ctx.args);
+        const { port, host, open, readOnly, a2aProtocolPolicy, allowA2AProtocolFallback, allowLegacyExecutorFallback, } = parseServeArgs(ctx.args);
         let server;
         try {
-            server = await startServer({ port, host, readOnly, frameworkRoot: ctx.frameworkRoot });
+            server = await startServer({
+                port,
+                host,
+                readOnly,
+                frameworkRoot: ctx.frameworkRoot,
+                ...(a2aProtocolPolicy ? { a2aProtocolPolicy } : {}),
+                ...(allowA2AProtocolFallback !== undefined ? { allowA2AProtocolFallback } : {}),
+                ...(allowLegacyExecutorFallback !== undefined ? { allowLegacyExecutorFallback } : {}),
+            });
         }
         catch (error) {
             const { handlerResultFromError } = await import('../errors.js');