@aiwg/cli 2026.8.16 → 2026.8.18

package/dist/src/a2a/webhook.js

@@ -15,6 +15,7 @@
 //
 // @issue #1256
 import { createHmac, timingSafeEqual } from 'node:crypto';
+import { decodeStreamResponse, A2AEventReconciler } from './events.js';
 /** Header name (case-insensitive). */
 export const SIGNATURE_HEADER = 'x-aiwg-signature';
 /** Five minutes — RFC 8941 timestamp tolerance. */
@@ -111,6 +112,7 @@ function constantTimeHexEqual(a, b) {
 export class IdempotencyCache {
     capacity;
     seen = new Set();
+    pending = new Set();
     order = [];
     constructor(capacity = DEFAULT_IDEMPOTENCY_CAPACITY) {
         this.capacity = Math.max(16, capacity);
@@ -119,6 +121,23 @@ export class IdempotencyCache {
     markFresh(id) {
         if (this.seen.has(id))
             return false;
+        this.commit(id);
+        return true;
+    }
+    /** Reserve an event before parsing/routing so concurrent deliveries cannot race. */
+    begin(id) {
+        if (this.seen.has(id))
+            return 'duplicate';
+        if (this.pending.has(id))
+            return 'pending';
+        this.pending.add(id);
+        return 'fresh';
+    }
+    /** Mark a successfully routed reservation as completed. */
+    commit(id) {
+        this.pending.delete(id);
+        if (this.seen.has(id))
+            return;
         this.seen.add(id);
         this.order.push(id);
         while (this.order.length > this.capacity) {
@@ -126,7 +145,10 @@ export class IdempotencyCache {
             if (evicted !== undefined)
                 this.seen.delete(evicted);
         }
-        return true;
+    }
+    /** Release a failed reservation so a later retry can be processed. */
+    release(id) {
+        this.pending.delete(id);
     }
     size() {
         return this.seen.size;
@@ -134,15 +156,35 @@ export class IdempotencyCache {
 }
 export class PushSecretRegistry {
     entries = new Map();
+    reconcilers = new Map();
     register(entry) {
+        if (entry.protocolVersion === '1.0' && !entry.taskId) {
+            throw new Error('A2A 1.0 push config registration requires taskId ownership scope');
+        }
         this.entries.set(entry.configId, entry);
+        if (entry.taskId) {
+            this.reconcilers.set(entry.configId, new A2AEventReconciler({
+                taskId: entry.taskId,
+                ...(entry.contextId ? { contextId: entry.contextId } : {}),
+            }));
+        }
     }
     lookup(configId) {
         return this.entries.get(configId) ?? null;
     }
     unregister(configId) {
+        this.reconcilers.delete(configId);
         return this.entries.delete(configId);
     }
+    reconcile(configId, event) {
+        const entry = this.entries.get(configId);
+        const eventOwner = ownerOf(event);
+        if (entry?.taskOwner && eventOwner && entry.taskOwner !== eventOwner) {
+            throw new Error(`A2A event belongs to owner ${eventOwner}, expected ${entry.taskOwner}`);
+        }
+        const reconciler = this.reconcilers.get(configId);
+        return reconciler ? reconciler.accept(event) : event;
+    }
     /** Test/debug helper. */
     size() {
         return this.entries.size;
@@ -193,40 +235,83 @@ export async function handleWebhook(configId, body, signature, eventId, opts) {
     // Idempotency check — duplicate event-ids are accepted with 200 but
     // not re-routed. The executor's retry logic depends on a 2xx response
     // to mark delivery complete; failing here would cause infinite retry.
-    const fresh = opts.idempotency.markFresh(eventId);
-    if (!fresh) {
+    const entryForScope = opts.registry.lookup(configId);
+    const protocolVersion = entryForScope?.protocolVersion ?? '0.3';
+    const scopedEventId = [
+        configId,
+        protocolVersion,
+        entryForScope?.taskOwner ?? '',
+        entryForScope?.taskId ?? '',
+        eventId,
+    ].join('|');
+    const reservation = opts.idempotency.begin(scopedEventId);
+    if (reservation === 'duplicate') {
         return { status: 200, body: { ok: true, deduped: true } };
     }
+    if (reservation === 'pending') {
+        return {
+            status: 409,
+            body: errorBody('aiwg.webhook_event_in_progress', 'a concurrent delivery is still being processed'),
+        };
+    }
     // Route the verified payload. Errors thrown here become 500 so the
     // executor will retry — pick the abstraction carefully on the
     // mission-state side.
     const entry = opts.registry.lookup(configId);
     if (!entry) {
         // Edge case: secret was unregistered between verify and route.
+        opts.idempotency.release(scopedEventId);
         return {
             status: 404,
             body: errorBody('aiwg.webhook_secret_unknown', `configId='${configId}' no longer registered`),
         };
     }
+    if (protocolVersion === '1.0' && opts.contentType?.split(';')[0]?.trim().toLowerCase() !== 'application/a2a+json') {
+        opts.idempotency.release(scopedEventId);
+        return {
+            status: 415,
+            body: errorBody('aiwg.webhook_content_type_invalid', 'A2A 1.0 push requires application/a2a+json'),
+        };
+    }
     let parsed;
     try {
         parsed = JSON.parse(body.toString('utf8'));
     }
     catch (e) {
+        opts.idempotency.release(scopedEventId);
         return {
             status: 400,
             body: errorBody('aiwg.webhook_body_not_json', e.message),
         };
     }
+    let event;
     try {
-        await opts.route(entry, parsed);
+        event = decodeStreamResponse(protocolVersion, parsed, { eventId });
+        const accepted = opts.registry.reconcile(configId, event);
+        if (!accepted) {
+            opts.idempotency.commit(scopedEventId);
+            return { status: 200, body: { ok: true, deduped: true } };
+        }
+        event = accepted;
     }
     catch (e) {
+        opts.idempotency.release(scopedEventId);
+        return {
+            status: 400,
+            body: errorBody('aiwg.webhook_event_invalid', e.message),
+        };
+    }
+    try {
+        await opts.route(entry, event);
+    }
+    catch (e) {
+        opts.idempotency.release(scopedEventId);
         return {
             status: 500,
             body: errorBody('aiwg.webhook_route_failed', e.message),
         };
     }
+    opts.idempotency.commit(scopedEventId);
     return { status: 200, body: { ok: true } };
 }
 function errorBody(code, detail) {
@@ -237,4 +322,16 @@ function errorBody(code, detail) {
         detail,
     };
 }
+function ownerOf(event) {
+    const metadata = event.type === 'task'
+        ? event.task.metadata
+        : event.type === 'message'
+            ? event.message.metadata
+            : event.metadata;
+    const owner = metadata?.['task_owner']
+        ?? metadata?.['taskOwner']
+        ?? metadata?.['tenant_id']
+        ?? metadata?.['tenantId'];
+    return typeof owner === 'string' && owner ? owner : undefined;
+}
 //# sourceMappingURL=webhook.js.map

package/dist/src/artifacts/browser-export.js

@@ -454,6 +454,7 @@ function recordForEntry(cwd, entry, graphName, dependencyGraph, privacy, schemaV
                         ...(entry.searchTerms?.length
                             ? { aiwg_search_terms: uniqueSorted(entry.searchTerms) }
                             : {}),
+                        ...(entry.script ? { aiwg_script: entry.script } : {}),
                     },
                 },
             }

package/dist/src/artifacts/cli.js

@@ -494,7 +494,7 @@ async function handleBuild(args) {
         console.log('');
         console.log('Default behavior (no --graph): builds all graphs with defaultBuild: true');
         console.log('Multi-graph builds run by buildOrder/buildTier (refs → citations → bibliography before heavy graphs)');
-        console.log('  Built-in defaults: project (always), codebase (skipped if src/test/tools absent)');
+        console.log('  Built-in defaults: project (always), codebase (auto-detects JavaScript/TypeScript and Python layouts)');
         console.log('');
         console.log('Examples:');
         console.log('  aiwg index build');

package/dist/src/artifacts/fortemi-core-query-adapter.js

@@ -210,6 +210,7 @@ function artifactTypeFromRecord(record) {
 function entryFromRecord(record) {
     const indexedFrontmatter = record.search?.frontmatter ?? {};
     const indexedSearchTerms = indexedFrontmatter.aiwg_search_terms;
+    const indexedScript = indexedFrontmatter.aiwg_script;
     return {
         path: record.source.path,
         type: artifactTypeFromRecord(record),
@@ -245,6 +246,11 @@ function entryFromRecord(record) {
         kernel: typeof record.search?.frontmatter?.kernel === "boolean"
             ? record.search.frontmatter.kernel
             : undefined,
+        script: indexedScript && typeof indexedScript === "object"
+            && typeof indexedScript.entrypoint === "string"
+            && typeof indexedScript.runtime === "string"
+            ? indexedScript
+            : undefined,
         operationalState: record.operational_state,
     };
 }

package/dist/src/artifacts/types.js

@@ -195,6 +195,60 @@ export const BUILTIN_GRAPH_CONFIGS = {
  * @implements #426
  */
 export const GRAPH_CONFIGS = { ...BUILTIN_GRAPH_CONFIGS };
+function freshBuiltinGraphConfig(name) {
+    const config = BUILTIN_GRAPH_CONFIGS[name];
+    return {
+        ...config,
+        scanDirs: [...config.scanDirs],
+        extensions: [...config.extensions],
+    };
+}
+/**
+ * Detect conventional Python layouts without treating every top-level folder
+ * as source. A Python project manifest activates `.py`/`.pyi` support; package
+ * roots are immediate directories containing `__init__.py`, plus the common
+ * `tests/` and `scripts/` roots when present.
+ */
+function detectPythonCodebaseConfig(cwd, base) {
+    const hasPythonManifest = ['pyproject.toml', 'setup.py', 'setup.cfg']
+        .some((manifest) => fs.existsSync(path.join(cwd, manifest)));
+    if (!hasPythonManifest)
+        return base;
+    const detectedRoots = [];
+    for (const root of ['tests', 'scripts']) {
+        if (fs.existsSync(path.join(cwd, root)))
+            detectedRoots.push(root);
+    }
+    const excluded = new Set([
+        '.aiwg', '.git', '.github', '.venv', 'venv', 'node_modules',
+        'src', 'test', 'tests', 'tools', 'scripts', 'docs', 'documentation',
+    ]);
+    try {
+        for (const entry of fs.readdirSync(cwd, { withFileTypes: true })) {
+            if (!entry.isDirectory() || excluded.has(entry.name) || entry.name.startsWith('.'))
+                continue;
+            if (fs.existsSync(path.join(cwd, entry.name, '__init__.py')))
+                detectedRoots.push(entry.name);
+        }
+    }
+    catch {
+        // Layout detection is best-effort; the immutable defaults still apply.
+    }
+    return {
+        ...base,
+        scanDirs: [...new Set([...base.scanDirs, ...detectedRoots])],
+        extensions: [...new Set([...base.extensions, '.py', '.pyi'])],
+    };
+}
+function applyBuiltinGraphOverride(base, override) {
+    if (!override)
+        return base;
+    return {
+        ...base,
+        scanDirs: override.scanDirs ? [...override.scanDirs] : base.scanDirs,
+        extensions: override.extensions ? [...override.extensions] : base.extensions,
+    };
+}
 /**
  * Normalize metadataSupplements entries.
  *
@@ -400,6 +454,11 @@ export function loadModuleGraphConfigs(cwd, diagnostics) {
  * @implements #426 #726
  */
 export function loadUserGraphConfigs(cwd, diagnostics) {
+    // Built-ins are immutable in index.graphs, but codebase roots/extensions may
+    // be adapted through the explicitly bounded graphOverrides contract (#2123).
+    // Reset on every project load so a prior cwd cannot leak its override or
+    // detected Python package roots into a later build in the same process.
+    GRAPH_CONFIGS.codebase = detectPythonCodebaseConfig(cwd, freshBuiltinGraphConfig('codebase'));
     // Load module-declared graphs first (frameworks/addons)
     const moduleLoaded = loadModuleGraphConfigs(cwd, diagnostics);
     const loaded = [...moduleLoaded];
@@ -408,6 +467,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
     // config.yaml is a
     // deprecated fallback so un-migrated corpora keep working.
     let graphs;
+    let graphOverrides;
     let fromDeprecatedYaml = false;
     // (a) Canonical: .aiwg/aiwg.config (JSON).
     try {
@@ -418,6 +478,9 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
             const g = idx?.graphs;
             if (g && typeof g === 'object')
                 graphs = g;
+            const overrides = idx?.graphOverrides;
+            if (overrides && typeof overrides === 'object')
+                graphOverrides = overrides;
         }
     }
     catch {
@@ -430,7 +493,7 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
         });
     }
     // (b) Fallback: legacy .aiwg/config.yaml.
-    if (!graphs) {
+    if (!graphs && !graphOverrides) {
         try {
             const configPath = projectAiwgPath(cwd, 'config.yaml');
             if (fs.existsSync(configPath)) {
@@ -441,12 +504,21 @@ export function loadUserGraphConfigs(cwd, diagnostics) {
                     graphs = g;
                     fromDeprecatedYaml = true;
                 }
+                const overrides = idx?.graphOverrides;
+                if (overrides && typeof overrides === 'object') {
+                    graphOverrides = overrides;
+                    fromDeprecatedYaml = true;
+                }
             }
         }
         catch {
             // best-effort
         }
     }
+    const codebaseOverride = graphOverrides?.codebase;
+    if (codebaseOverride && typeof codebaseOverride === 'object' && !Array.isArray(codebaseOverride)) {
+        GRAPH_CONFIGS.codebase = applyBuiltinGraphOverride(GRAPH_CONFIGS.codebase, codebaseOverride);
+    }
     if (!graphs)
         return loaded;
     if (fromDeprecatedYaml && !yamlIndexDeprecationWarned) {

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/agent-spawn.js

@@ -27,8 +27,10 @@ export const PROVIDER_CONFIGS = {
     },
     codex: {
         binary: 'codex',
-        // Codex supports --full-auto (no approval prompts) and --approval-mode full-auto
-        dangerousFlag: '--full-auto',
+        // Current Codex releases use the explicit bypass flag for unrestricted,
+        // non-interactive execution. Keep this centralized so every launcher maps
+        // AIWG's --dangerous option consistently.
+        dangerousFlag: '--dangerously-bypass-approvals-and-sandbox',
         name: 'OpenAI Codex',
     },
     hermes: {

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

@@ -3,6 +3,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { formatCockpitDoctor, runCockpitDoctor, } from '../../cockpit/doctor.js';
 export const COCKPIT_PACKAGE_NAME = '@aiwg/cockpit';
 export function cockpitHome() {
     return process.env.AIWG_COCKPIT_HOME || path.join(homedir(), '.aiwg', 'cockpit', 'package');
@@ -22,6 +23,16 @@ async function coreVersion(frameworkRoot) {
 function packageRoot(home = cockpitHome()) {
     return path.join(home, 'node_modules', '@aiwg', 'cockpit');
 }
+function valueAfter(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function doctorFormat(args) {
+    if (args.includes('--json'))
+        return 'json';
+    const value = valueAfter(args, '--format');
+    return value === 'json' || value === 'markdown' ? value : 'text';
+}
 export async function resolveCockpitInstall(home = cockpitHome()) {
     const root = packageRoot(home);
     const pkg = await readJson(path.join(root, 'package.json'));
@@ -95,6 +106,36 @@ export const cockpitHandler = {
         const install = await resolveCockpitInstall();
         const version = await coreVersion(ctx.frameworkRoot);
         const autoInstall = ctx.args.includes('--install') || ctx.args.includes('--yes') || ctx.args.includes('-y');
+        if (ctx.args[0] === 'doctor' || ctx.args.includes('--doctor')) {
+            const sourcePackageRoot = path.join(ctx.frameworkRoot, 'apps', 'cockpit');
+            const sourcePackage = !install.installed ? await readJson(path.join(sourcePackageRoot, 'package.json')) : null;
+            const doctorInstall = install.installed ? install : {
+                installed: Boolean(sourcePackage),
+                version: typeof sourcePackage?.version === 'string' ? sourcePackage.version : undefined,
+                packageRoot: sourcePackageRoot,
+            };
+            const topologyValue = valueAfter(ctx.args, '--topology');
+            const topology = topologyValue === 'ssh-local' || topologyValue === 'ssh-reverse'
+                ? topologyValue
+                : 'same-host';
+            const report = await runCockpitDoctor({
+                coreVersion: version,
+                cockpitInstalled: doctorInstall.installed,
+                cockpitVersion: doctorInstall.version,
+                cockpitPackageRoot: doctorInstall.packageRoot,
+                topology,
+                cockpitHost: valueAfter(ctx.args, '--cockpit-host'),
+                executorHost: valueAfter(ctx.args, '--executor-host'),
+                expectedExecutorVersion: valueAfter(ctx.args, '--executor-version'),
+                forwardEndpoint: valueAfter(ctx.args, '--forward-endpoint'),
+                runtimeFile: valueAfter(ctx.args, '--runtime-file'),
+            });
+            return {
+                exitCode: report.status === 'blocked' ? 1 : 0,
+                message: formatCockpitDoctor(report, doctorFormat(ctx.args)),
+                rawOutput: true,
+            };
+        }
         if (ctx.args.includes('--status')) {
             return {
                 exitCode: 0,