@aiwg/cli 2026.8.16 → 2026.8.18

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

@@ -53,6 +53,7 @@ function collectFingerprint(versionInfo) {
             logFile: loggerInfo.logFile,
         },
         invocation_id: loggerInfo.provenance.invocation_id,
+        installation: versionInfo.installation,
     };
     if (versionInfo.gitHash) {
         fp.git = {
@@ -115,6 +116,9 @@ async function displayVersion(opts) {
         ui.dim(`    path:      ${fp.packageRoot}`);
     }
     ui.dim(`    channel:   ${fp.channel}`);
+    ui.dim(`    install:   ${fp.installation.identity?.method ?? 'unrecorded'} (${fp.installation.state})`);
+    ui.dim(`    canonical: ${fp.installation.identity?.root ?? '(unrecorded)'}`);
+    ui.dim(`    actual:    ${fp.installation.actualRoot}`);
     ui.dim(`    node:      ${fp.node}`);
     ui.dim(`    platform:  ${fp.platform.os} ${fp.platform.arch} (${fp.platform.release})`);
     ui.dim(`    tty:       stdin=${fp.tty.stdin} stdout=${fp.tty.stdout} stderr=${fp.tty.stderr}`);

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

@@ -12,6 +12,23 @@ import { createScriptRunner } from './script-runner.js';
 import { getFrameworkRoot } from '../../channel/manager.mjs';
 import { maybePrintCommunityFooter } from '../../community/footer.js';
 import { buildDeploymentStatusProbe } from '../services/deployment-verification.js';
+import { detectScope } from '../scope-resolver.js';
+function statusProjectRoot(args, fallback) {
+    const valueFlags = new Set(['--scope', '--provider', '--bundle']);
+    for (let index = 0; index < args.length; index += 1) {
+        if (valueFlags.has(args[index])) {
+            index += 1;
+            continue;
+        }
+        if (!args[index].startsWith('-'))
+            return args[index];
+    }
+    return fallback;
+}
+function statusFlagValue(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
 /**
  * Handler for workspace status command
  *
@@ -31,8 +48,13 @@ export const statusHandler = {
     aliases: ['-status', '--status'],
     async execute(ctx) {
         if (ctx.args.includes('--probe')) {
-            const projectRoot = ctx.args.find((arg) => !arg.startsWith('-')) ?? ctx.cwd ?? process.cwd();
-            const probe = await buildDeploymentStatusProbe(projectRoot, ctx.frameworkRoot);
+            const projectRoot = statusProjectRoot(ctx.args, ctx.cwd ?? process.cwd());
+            const scope = detectScope(ctx.args);
+            const probe = await buildDeploymentStatusProbe(projectRoot, ctx.frameworkRoot, {
+                scope,
+                provider: statusFlagValue(ctx.args, '--provider'),
+                bundle: statusFlagValue(ctx.args, '--bundle'),
+            });
             return {
                 exitCode: probe.status === 'needs-repair' ? 1 : 0,
                 message: JSON.stringify(probe, null, 2),

package/dist/src/cli/services/deployment-verification.js

@@ -142,6 +142,13 @@ const RECEIPT_DRIFT_POLICY = {
         severity: 'advisory',
         remediation: 'Re-run the same aiwg use command to establish provider transformation evidence.',
     },
+    'policy-exempt': {
+        severity: 'info',
+    },
+    'source-evidence-unavailable': {
+        severity: 'advisory',
+        remediation: 'Run aiwg auth login, then aiwg versions resolve <installed-version> once online to warm the verified cache; re-run the same aiwg use command afterward.',
+    },
 };
 async function collectProviderReceiptFindings(options, provider) {
     try {
@@ -497,8 +504,8 @@ export async function verifyConfiguredDeployments(projectRoot, filters = {}, fra
     }
     return aggregateUseDeploymentResult({ projectRoot, frameworkRoot, scope: filters.scope ?? 'project', requestedBundles: bundles, providers: results });
 }
-export async function buildDeploymentStatusProbe(projectRoot, frameworkRoot = process.env.AIWG_ROOT || projectRoot) {
-    const result = await verifyConfiguredDeployments(projectRoot, {}, frameworkRoot);
+export async function buildDeploymentStatusProbe(projectRoot, frameworkRoot = process.env.AIWG_ROOT || projectRoot, filters = {}) {
+    const result = await verifyConfiguredDeployments(projectRoot, filters, frameworkRoot);
     const notConfigured = result.requestedBundles.length === 0
         && result.findings.length > 0
         && result.findings.every((item) => item.id === 'deployment-not-configured');

package/dist/src/cockpit/doctor.js

@@ -0,0 +1,257 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { homedir, hostname, platform } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+const execFile = promisify(execFileCallback);
+export const COCKPIT_DOCTOR_SCHEMA = 'aiwg.cockpit-doctor/v1';
+function safeText(value) {
+    return String(value ?? '')
+        .replace(/((?:bearer|token|nonce|secret|password|authorization)\s*)[:=]\s*[^\s,;]+/gi, '$1=[redacted]')
+        .replace(/([?#](?:token|nonce|secret|password|authorization)=)[^&#\s]+/gi, '$1[redacted]')
+        .slice(0, 240);
+}
+function evidence(values) {
+    return Object.fromEntries(Object.entries(values).map(([key, value]) => [
+        key,
+        typeof value === 'string' ? safeText(value) : value,
+    ]));
+}
+function row(id, status, code, summary, values, recovery) {
+    return { id, status, code, summary, evidence: evidence(values), recovery: status === 'pass' ? null : recovery };
+}
+function overall(rows) {
+    if (rows.some(item => item.status === 'blocked'))
+        return 'blocked';
+    if (rows.some(item => item.status === 'warn'))
+        return 'warn';
+    return 'pass';
+}
+function isLoopback(host) {
+    return ['127.0.0.1', 'localhost', '::1', '[::1]'].includes(host.toLowerCase());
+}
+function looksMock(body) {
+    const text = JSON.stringify({
+        service: body?.service,
+        name: body?.name,
+        executor: body?.executor,
+        implementation: body?.implementation,
+        mock: body?.mock,
+    }).toLowerCase();
+    return body?.mock === true || /mock[-_ ]?executor|cockpit[-_ ]?mock/.test(text);
+}
+function listenerRows(stdout) {
+    const lines = stdout.split(/\r?\n/).filter(line => /:(8120|8121|8122|8140)\b/.test(line));
+    const publicLines = lines.filter(line => /(?:0\.0\.0\.0|\[::\]|\*):(8120|8121|8122|8140)\b/.test(line));
+    if (publicLines.length > 0)
+        return row('listeners', 'blocked', 'public_bind', 'A Cockpit or executor listener is publicly bound.', { checked_ports: '8120-8122,8140', public_listener_count: publicLines.length }, 'Bind the named service to 127.0.0.1 and restart only that service.');
+    return row('listeners', lines.length > 0 ? 'pass' : 'warn', lines.length > 0 ? 'loopback_only' : 'listeners_not_observed', lines.length > 0 ? 'Observed application listeners are loopback-only.' : 'No application listeners were observed locally.', { checked_ports: '8120-8122,8140', observed_listener_count: lines.length }, 'Start the expected user services, then rerun the doctor.');
+}
+export function defaultCockpitDoctorProbes(cockpitPackageRoot) {
+    return {
+        async readRuntime(file) {
+            const [raw, info] = await Promise.all([readFile(file, 'utf8'), stat(file)]);
+            const record = JSON.parse(raw);
+            if (!record.token && record.token_ref && cockpitPackageRoot) {
+                try {
+                    const keychain = await import(pathToFileURL(path.join(cockpitPackageRoot, 'shell-core', 'keychain.mjs')).href);
+                    record.token = await keychain.readCockpitToken(record.token_ref);
+                }
+                catch { /* authentication row reports a focused failure */ }
+            }
+            return { record, mode: info.mode & 0o777, owned: info.uid === process.getuid?.() };
+        },
+        async fetchJson(url, headers = {}) {
+            const response = await fetch(url, { headers, signal: AbortSignal.timeout(2500) });
+            let body = null;
+            try {
+                body = await response.json();
+            }
+            catch {
+                body = null;
+            }
+            return { status: response.status, body };
+        },
+        async command(command, args) {
+            try {
+                const result = await execFile(command, args, { timeout: 3000, maxBuffer: 1024 * 1024 });
+                return { ok: true, stdout: result.stdout };
+            }
+            catch (error) {
+                return { ok: false, stdout: typeof error?.stdout === 'string' ? error.stdout : '' };
+            }
+        },
+        pathExists: existsSync,
+        hostName: hostname,
+        platform,
+    };
+}
+export async function runCockpitDoctor(options, probes = defaultCockpitDoctorProbes(options.cockpitPackageRoot)) {
+    const topology = options.topology ?? 'same-host';
+    const cockpitHost = options.cockpitHost ?? probes.hostName();
+    const executorHost = options.executorHost ?? (topology === 'same-host' ? cockpitHost : 'unspecified');
+    const rows = [];
+    rows.push(options.cockpitInstalled
+        ? row('package', options.cockpitVersion === options.coreVersion ? 'pass' : 'blocked', options.cockpitVersion === options.coreVersion ? 'version_lockstep' : 'version_skew', options.cockpitVersion === options.coreVersion ? 'Cockpit and AIWG versions match.' : 'Cockpit and AIWG versions differ.', {
+            core_version: options.coreVersion,
+            cockpit_version: options.cockpitVersion ?? 'unknown',
+            source: options.cockpitPackageRoot?.includes('node_modules') ? 'managed-package' : 'source-workspace',
+            location: options.cockpitPackageRoot?.includes('node_modules')
+                ? '$AIWG_COCKPIT_HOME/node_modules/@aiwg/cockpit'
+                : 'apps/cockpit',
+        }, 'Run `aiwg use cockpit` to install the core-matched Cockpit package.')
+        : row('package', 'blocked', 'cockpit_not_installed', 'Cockpit is not installed.', { core_version: options.coreVersion, cockpit_version: null, source: 'absent' }, 'Run `aiwg use cockpit`.'));
+    const runtimeFile = options.runtimeFile ?? path.join(homedir(), '.aiwg', 'cockpit', 'runtime', 'bridge.json');
+    let runtime = null;
+    try {
+        const observed = await probes.readRuntime(runtimeFile);
+        runtime = observed.record;
+        const secure = observed.mode === 0o600 && observed.owned && Boolean(runtime.port) && Boolean(runtime.token || runtime.token_ref);
+        rows.push(row('bridge-runtime', secure ? 'pass' : 'blocked', secure ? 'runtime_secure' : 'runtime_insecure', secure ? 'Bridge runtime metadata has the required ownership and mode.' : 'Bridge runtime metadata is missing or insecure.', { mode: observed.mode.toString(8), owned_by_current_user: observed.owned, credential_present: Boolean(runtime.token || runtime.token_ref), port: runtime.port ?? null }, 'Stop Cockpit, restrict the runtime directory to 0700 and bridge.json to 0600, then restart Cockpit.'));
+    }
+    catch {
+        rows.push(row('bridge-runtime', 'blocked', 'runtime_missing', 'Bridge runtime metadata is unavailable.', { runtime_file: 'default-cockpit-runtime', credential_present: false }, 'Start Cockpit as the intended user, then rerun the doctor.'));
+    }
+    let bridgeHealth = null;
+    if (runtime?.port) {
+        const base = `http://127.0.0.1:${runtime.port}`;
+        try {
+            const live = await probes.fetchJson(`${base}/healthz`);
+            if (live.status < 200 || live.status >= 300)
+                throw new Error('not live');
+            const token = typeof runtime.token === 'string' ? runtime.token : '';
+            const authed = await probes.fetchJson(`${base}/api/health`, token ? { authorization: `Bearer ${token}` } : {});
+            if ([401, 403].includes(authed.status)) {
+                rows.push(row('bridge', 'blocked', 'bridge_unauthenticated', 'Bridge is reachable but authentication failed.', { reachable: true, authenticated: false }, 'Restart the Bridge to mint fresh runtime credentials, then rerun the doctor.'));
+            }
+            else if (authed.status >= 200 && authed.status < 300) {
+                bridgeHealth = authed.body;
+                rows.push(row('bridge', 'pass', 'bridge_authenticated', 'Bridge is reachable and authenticated.', { reachable: true, authenticated: true, port: runtime.port }, null));
+            }
+            else
+                throw new Error('unexpected response');
+        }
+        catch {
+            rows.push(row('bridge', 'blocked', 'bridge_unreachable', 'Bridge is not reachable through its runtime endpoint.', { reachable: false, authenticated: false, port: runtime.port }, 'Restart the Cockpit user service and rerun the doctor.'));
+        }
+    }
+    else {
+        rows.push(row('bridge', 'blocked', 'bridge_unreachable', 'Bridge endpoint is unknown.', { reachable: false, authenticated: false }, 'Start Cockpit as the intended user, then rerun the doctor.'));
+    }
+    const executorUrlText = typeof bridgeHealth?.executor_url === 'string' ? bridgeHealth.executor_url : '';
+    if (executorUrlText) {
+        let executorUrl = null;
+        try {
+            executorUrl = new URL(executorUrlText);
+        }
+        catch { /* reported as unreachable */ }
+        const hostMatches = executorUrl && (topology === 'same-host'
+            ? isLoopback(executorUrl.hostname)
+            : executorHost !== 'unspecified' && executorUrl.hostname === executorHost);
+        if (!hostMatches) {
+            rows.push(row('executor', 'blocked', 'wrong_host', 'Bridge targets a host inconsistent with the declared topology.', { topology, expected_host: executorHost, configured_host: executorUrl?.hostname ?? 'invalid' }, 'Correct the declared executor host or the Bridge executor URL; do not create a tunnel until they agree.'));
+        }
+        else {
+            try {
+                const bridgeExecutor = bridgeHealth?.executor;
+                const deep = bridgeExecutor && typeof bridgeExecutor === 'object'
+                    ? { status: bridgeExecutor.status === 'ok' ? 200 : 503, body: bridgeExecutor }
+                    : await probes.fetchJson(`${executorUrlText.replace(/\/$/, '')}/healthz/deep`);
+                if ([401, 403].includes(deep.status)) {
+                    rows.push(row('executor', 'blocked', 'executor_unauthenticated', 'Executor is reachable but authentication failed.', { reachable: true, authenticated: false, host_matches: true }, 'Configure the Bridge executor credential file with mode 0600, then restart the Bridge.'));
+                }
+                else if (deep.status < 200 || deep.status >= 300)
+                    throw new Error('deep health failed');
+                else if (deep.body?.real_executor === false || looksMock(deep.body)) {
+                    rows.push(row('executor', 'blocked', 'mock_executor', 'Configured executor identifies as a mock.', { reachable: true, authenticated: true, real_executor: false }, 'Point the Bridge at the real Agentic Sandbox executor and restart it without mock allowance.'));
+                }
+                else {
+                    const observedVersion = safeText(deep.body?.version ?? deep.body?.commit ?? 'unknown');
+                    const skew = Boolean(options.expectedExecutorVersion && observedVersion !== options.expectedExecutorVersion);
+                    rows.push(row('executor', skew ? 'blocked' : 'pass', skew ? 'version_skew' : 'executor_ready', skew ? 'Executor identity does not match the expected version.' : 'Real executor deep health is ready.', { reachable: true, authenticated: true, real_executor: true, version_or_commit: observedVersion, auth_configured: Boolean(bridgeHealth.executor_auth_configured) }, 'Install or select the expected Agentic Sandbox release, then restart the executor and Bridge.'));
+                }
+            }
+            catch {
+                rows.push(row('executor', 'blocked', 'executor_unreachable', 'Executor deep health is unreachable.', { reachable: false, host_matches: true }, 'Start the executor on the declared host and verify only its required transport before retrying.'));
+            }
+        }
+    }
+    else {
+        rows.push(row('executor', 'blocked', 'executor_unreachable', 'Bridge did not report an executor endpoint.', { reachable: false, host_matches: false }, 'Configure the Bridge executor URL and restart the Bridge.'));
+    }
+    rows.push(row('host-runtime', 'pass', 'host_ready', 'Host runtime is available.', { platform: probes.platform(), node: process.version }, null));
+    const docker = await probes.command('docker', ['info', '--format', '{{json .ServerVersion}}']);
+    rows.push(row('docker-runtime', docker.ok ? 'pass' : 'warn', docker.ok ? 'docker_ready' : 'docker_unavailable', docker.ok ? 'Docker runtime is reachable.' : 'Docker runtime is not reachable.', { ready: docker.ok }, 'Start Docker or choose the host runtime tier; host readiness is independent.'));
+    const kvm = probes.pathExists('/dev/kvm');
+    rows.push(row('vm-runtime', kvm ? 'pass' : 'warn', kvm ? 'kvm_ready' : 'kvm_unavailable', kvm ? 'KVM device is available.' : 'VM readiness is not claimed because KVM is unavailable.', { kvm_available: kvm }, 'Enable KVM access only if the VM runtime tier is required.'));
+    const listeners = await probes.command('ss', ['-ltn']);
+    rows.push(listeners.ok ? listenerRows(listeners.stdout) : row('listeners', 'warn', 'listener_inspection_unavailable', 'Listener inspection is unavailable.', { checked_ports: '8120-8122,8140' }, 'Install `ss` support or inspect these listeners locally, then rerun the doctor.'));
+    const cockpitEnabled = await probes.command('systemctl', ['--user', 'is-enabled', 'aiwg-cockpit.service']);
+    const executorEnabled = await probes.command('systemctl', ['--user', 'is-enabled', 'agentic-sandbox.service']);
+    const cockpitUnit = await probes.command('systemctl', ['--user', 'show', 'aiwg-cockpit.service', '--property=ActiveState,After,Requires,Restart']);
+    const executorUnit = await probes.command('systemctl', ['--user', 'show', 'agentic-sandbox.service', '--property=ActiveState,Restart']);
+    const linger = await probes.command('loginctl', ['show-user', process.env.USER ?? '', '--property=Linger', '--value']);
+    const dependencyOrdered = topology !== 'same-host' || /(?:After|Requires)=.*agentic-sandbox\.service/.test(cockpitUnit.stdout);
+    const restartReady = /Restart=(?:on-failure|always)/.test(cockpitUnit.stdout)
+        && /Restart=(?:on-failure|always)/.test(executorUnit.stdout);
+    const active = /ActiveState=active/.test(cockpitUnit.stdout) && /ActiveState=active/.test(executorUnit.stdout);
+    const persistent = cockpitEnabled.ok && executorEnabled.ok && linger.ok && linger.stdout.trim() === 'yes'
+        && cockpitUnit.ok && executorUnit.ok && dependencyOrdered && restartReady && active;
+    rows.push(row('persistence', persistent ? 'pass' : 'warn', persistent ? 'user_systemd_ready' : 'user_systemd_incomplete', persistent ? 'User services and linger support persistence.' : 'User-service persistence is incomplete or unavailable.', {
+        cockpit_enabled: cockpitEnabled.ok,
+        executor_enabled: executorEnabled.ok,
+        units_active: active,
+        linger_enabled: linger.stdout.trim() === 'yes',
+        dependency_order_ready: dependencyOrdered,
+        restart_recovery_ready: restartReady,
+    }, 'Enable only the Cockpit and executor user units, then enable linger for the service account.'));
+    const topologyValid = topology === 'same-host' ? cockpitHost === executorHost : executorHost !== 'unspecified';
+    if (topology !== 'same-host' && options.forwardEndpoint) {
+        try {
+            const endpoint = new URL(options.forwardEndpoint);
+            const forward = await probes.fetchJson(`${options.forwardEndpoint.replace(/\/$/, '')}/healthz`);
+            const safeEndpoint = `${endpoint.protocol}//${endpoint.hostname}:${endpoint.port || 'default'}`;
+            rows.push(row('ssh-forward', forward.status >= 200 && forward.status < 300 ? 'pass' : 'blocked', forward.status >= 200 && forward.status < 300 ? 'forward_ready' : 'forward_unreachable', forward.status >= 200 && forward.status < 300 ? 'Declared SSH forward reaches the expected service.' : 'Declared SSH forward is unreachable.', { kind: topology, endpoint: safeEndpoint, reachable: forward.status >= 200 && forward.status < 300 }, 'Correct only the declared SSH forward endpoint, then rerun the doctor.'));
+        }
+        catch {
+            rows.push(row('ssh-forward', 'blocked', 'forward_unreachable', 'Declared SSH forward is invalid or unreachable.', { kind: topology, reachable: false }, 'Correct only the declared SSH forward endpoint, then rerun the doctor.'));
+        }
+    }
+    rows.push(row('topology', topologyValid ? 'pass' : 'blocked', topologyValid ? 'topology_declared' : 'topology_ambiguous', topologyValid ? 'Cockpit, executor, and operator access topology is explicit.' : 'Executor host is not explicitly declared.', { kind: topology, cockpit_host: cockpitHost, executor_host: executorHost, operator_access: topology === 'same-host' ? 'local' : topology === 'ssh-local' ? 'ssh-local-forward' : 'ssh-reverse-forward' }, 'Declare the executor host before generating or validating any forward.'));
+    return {
+        schema: COCKPIT_DOCTOR_SCHEMA,
+        generated_at: (options.now ?? (() => new Date()))().toISOString(),
+        topology: {
+            kind: topology,
+            cockpit_host: safeText(cockpitHost),
+            executor_host: safeText(executorHost),
+            operator_access: topology === 'same-host' ? 'local' : topology === 'ssh-local' ? 'ssh-local-forward' : 'ssh-reverse-forward',
+        },
+        status: overall(rows),
+        rows,
+    };
+}
+export function formatCockpitDoctor(report, format) {
+    if (format === 'json')
+        return JSON.stringify(report, null, 2);
+    if (format === 'markdown') {
+        return [
+            `# Cockpit Connection Doctor`,
+            '',
+            `Status: **${report.status}**  `,
+            `Topology: \`${report.topology.kind}\``,
+            '',
+            '| Check | Status | Code | Summary | Recovery |',
+            '|---|---|---|---|---|',
+            ...report.rows.map(item => `| ${item.id} | ${item.status} | ${item.code} | ${item.summary} | ${item.recovery ?? '—'} |`),
+        ].join('\n');
+    }
+    return [
+        `Cockpit connection doctor: ${report.status}`,
+        `Topology: ${report.topology.kind} (${report.topology.cockpit_host} -> ${report.topology.executor_host})`,
+        ...report.rows.map(item => `${item.status.toUpperCase().padEnd(7)} ${item.id.padEnd(16)} ${item.code}: ${item.summary}${item.recovery ? ` Recovery: ${item.recovery}` : ''}`),
+    ].join('\n');
+}
+//# sourceMappingURL=doctor.js.map

package/dist/src/config/aiwg-config.js

@@ -158,13 +158,46 @@ export function validateIndexConfig(index) {
     if (typeof index !== 'object' || Array.isArray(index)) {
         return ['index: must be an object'];
     }
-    const graphs = index.graphs;
+    const indexObject = index;
+    const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
+    const graphOverrides = indexObject.graphOverrides;
+    if (graphOverrides !== undefined) {
+        if (typeof graphOverrides !== 'object' || graphOverrides === null || Array.isArray(graphOverrides)) {
+            errors.push('index.graphOverrides: must be an object mapping supported built-in graph names to overrides');
+        }
+        else {
+            for (const [name, rawOverride] of Object.entries(graphOverrides)) {
+                const where = `index.graphOverrides.${name}`;
+                if (name !== 'codebase') {
+                    errors.push(`${where}: unsupported built-in graph override (supported: codebase)`);
+                    continue;
+                }
+                if (typeof rawOverride !== 'object' || rawOverride === null || Array.isArray(rawOverride)) {
+                    errors.push(`${where}: must be an object`);
+                    continue;
+                }
+                const override = rawOverride;
+                for (const field of Object.keys(override)) {
+                    if (field !== 'scanDirs' && field !== 'extensions') {
+                        errors.push(`${where}.${field}: unknown field (supported: scanDirs, extensions)`);
+                    }
+                }
+                if (override.scanDirs !== undefined && (!isStringArray(override.scanDirs) || override.scanDirs.length === 0)) {
+                    errors.push(`${where}.scanDirs: must be a non-empty array of strings`);
+                }
+                if (override.extensions !== undefined && (!isStringArray(override.extensions) || override.extensions.length === 0)) {
+                    errors.push(`${where}.extensions: must be a non-empty array of strings`);
+                }
+            }
+        }
+    }
+    const graphs = indexObject.graphs;
     if (graphs === undefined)
         return errors; // index with no graphs is permissible
     if (typeof graphs !== 'object' || graphs === null || Array.isArray(graphs)) {
-        return ['index.graphs: must be an object mapping graph names to definitions'];
+        errors.push('index.graphs: must be an object mapping graph names to definitions');
+        return errors;
     }
-    const isStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string');
     for (const [name, rawDef] of Object.entries(graphs)) {
         const where = `index.graphs.${name}`;
         if (typeof rawDef !== 'object' || rawDef === null || Array.isArray(rawDef)) {

package/dist/src/config/user-config-dir.mjs

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Resolve AIWG's global, provider-neutral user configuration directory.
+ *
+ * Contract: explicit override > AIWG_CONFIG > existing ~/.aiwg > existing
+ * ~/.config/aiwg > ~/.aiwg. Keeping this in a dependency-free ESM module lets
+ * the launcher, channel manager, updater, and TypeScript config API share the
+ * exact same resolution rules.
+ */
+export function resolveUserConfigDir(options = {}) {
+  if (options.configDir) return path.resolve(options.configDir);
+  const env = options.env ?? process.env;
+  if (env.AIWG_CONFIG) return path.resolve(env.AIWG_CONFIG);
+
+  const home = options.homeDir ?? os.homedir();
+  const legacy = path.join(home, '.aiwg');
+  const xdg = path.join(home, '.config', 'aiwg');
+  const pathExists = options.exists ?? existsSync;
+  if (pathExists(legacy)) return legacy;
+  if (pathExists(xdg)) return xdg;
+  return legacy;
+}
+
+export function userConfigFile(name, options = {}) {
+  return path.join(resolveUserConfigDir(options), name);
+}

package/dist/src/config/user-config.js

@@ -16,9 +16,9 @@
  * @implements #545
  */
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
-import { resolve } from 'path';
-import { homedir } from 'os';
 import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { resolveUserConfigDir } from './user-config-dir.mjs';
 /**
  * Known config files in the user config directory
  */
@@ -28,6 +28,7 @@ export const KNOWN_CONFIG_FILES = [
     { filename: 'ops.json', description: 'Ops workspace registry' },
     { filename: 'mcp-servers.json', description: 'MCP server registry (single source of truth)' },
     { filename: 'packages.yaml', description: 'Installed remote packages (aiwg install)' },
+    { filename: 'installation.json', description: 'Canonical global installation identity' },
 ];
 /**
  * Default user config values
@@ -60,26 +61,7 @@ export const DEFAULT_USER_CONFIG = {
  *   4. ~/.aiwg (default if neither exists)
  */
 export function resolveConfigDir(overridePath) {
-    // 1. Explicit override from env or CLI flag
-    const envOverride = process.env.AIWG_CONFIG;
-    if (overridePath) {
-        return resolve(overridePath);
-    }
-    if (envOverride) {
-        return resolve(envOverride);
-    }
-    // 2. Check primary path: ~/.aiwg
-    const primaryPath = resolve(homedir(), '.aiwg');
-    if (existsSync(primaryPath)) {
-        return primaryPath;
-    }
-    // 3. Check fallback path: ~/.config/aiwg
-    const fallbackPath = resolve(homedir(), '.config/aiwg');
-    if (existsSync(fallbackPath)) {
-        return fallbackPath;
-    }
-    // 4. Default to primary if neither exists
-    return primaryPath;
+    return resolveUserConfigDir({ configDir: overridePath });
 }
 /**
  * User-level configuration manager

package/dist/src/extensions/commands/definitions.js

@@ -164,6 +164,24 @@ export const updateCommand = {
         },
     },
 };
+export const installationCommand = {
+    id: 'installation',
+    type: 'command',
+    name: 'Installation Identity',
+    description: 'Inspect, adopt, or deliberately switch the canonical global AIWG installation',
+    version: '1.0.0',
+    capabilities: ['cli', 'installation', 'update', 'diagnostics', 'recovery'],
+    keywords: ['installation', 'canonical', 'adopt', 'switch', 'package-manager', 'drift'],
+    category: 'maintenance',
+    platforms: { claude: 'full', generic: 'full' },
+    deployment: { pathTemplate: '.{platform}/commands/{id}.md', core: true },
+    metadata: {
+        type: 'command',
+        template: 'utility',
+        argumentHint: '<show|adopt|switch> [--root <path>] [--method <npm|web|source>] [--manager <absolute-path>] [--json]',
+        allowedTools: ['Read', 'Write'],
+    },
+};
 // Renamed from `refreshCommand` as part of #694 (avoid collision with git sync
 // semantics) and re-linked to `refreshHandler` in #919. Users who type
 // `aiwg sync` still reach this handler via its 'sync' alias and see a
@@ -912,7 +930,7 @@ export const serveCommand = {
         triggerPhrases: ['serve dashboard', 'start server', 'open dashboard', 'aiwg serve'],
         commandHint: {
             template: 'utility',
-            argumentHint: '[--port <n>] [--bind <host>] [--no-open] [--read-only]',
+            argumentHint: '[--port <n>] [--bind <host>] [--no-open] [--read-only] [--a2a-protocol <0.3|1.0|auto>] [--a2a-protocol-fallback] [--no-a2a-legacy-executor-fallback]',
             allowedTools: ['Bash'],
         },
     },
@@ -3569,6 +3587,7 @@ export const commandDefinitions = [
     doctorCommand,
     contextFirewallCommand,
     updateCommand,
+    installationCommand,
     refreshCommand,
     regenerateCommand,
     workspaceContextCommand,

package/dist/src/features/catalog.js

@@ -72,7 +72,7 @@ export const FEATURE_CATALOG = [
     },
     {
         name: 'graph',
-        description: 'Graphology backend for rich artifact traversal and graph operators',
+        description: 'Graphology backend for artifact-index traversal only; not Flow graph execution',
         packages: ['graphology', 'graphology-operators', 'graphology-traversal'],
         packageSpecs: {
             graphology: '0.26.0',
@@ -82,6 +82,7 @@ export const FEATURE_CATALOG = [
         enables: [
             'index.graphBackend: graphology',
             'in-memory attributed graph traversal and operator workflows',
+            'artifact graph data operations (use graph-pattern addon for Flow execution graphs)',
         ],
         cost: '~2 MB — pure JS, no native deps',
     },

package/dist/src/flow/graph-metadata.js

@@ -0,0 +1,56 @@
+/** A2A/telemetry metadata key reserved for the optional Flow graph profile. */
+export const AIWG_GRAPH_METADATA_KEY = 'aiwg.flow.graph';
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function isGraphExecutionMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const item = value;
+    return item.schemaVersion === 'graph.flow.aiwg.io/v1'
+        && nonEmpty(item.graphId)
+        && nonEmpty(item.graphVersion)
+        && nonEmpty(item.runId)
+        && nonEmpty(item.nodeId)
+        && nonEmpty(item.nodeRunId);
+}
+export function graphMetadataRecord(value) {
+    return { [AIWG_GRAPH_METADATA_KEY]: value };
+}
+export function extractGraphMetadata(metadata) {
+    const value = metadata?.[AIWG_GRAPH_METADATA_KEY];
+    return isGraphExecutionMetadata(value) ? value : undefined;
+}
+/**
+ * Project graph metadata to an explicitly named audience. Public projection
+ * removes execution identifiers and decision evidence. Cockpit receives only
+ * the declared route-decision summary; arbitrary user/task context is never a
+ * member of this contract and is therefore dropped by construction.
+ */
+export function projectGraphMetadata(value, audience) {
+    if (!isGraphExecutionMetadata(value))
+        throw new Error('Invalid graph execution metadata.');
+    if (audience === 'internal')
+        return structuredClone(value);
+    const common = {
+        schemaVersion: value.schemaVersion,
+        graphVersion: value.graphVersion,
+        nodeId: value.nodeId,
+        ...(value.edgeId ? { edgeId: value.edgeId } : {}),
+        ...(value.routeName ? { routeName: value.routeName } : {}),
+        ...(value.runtimeBinding ? { runtimeBinding: value.runtimeBinding } : {}),
+        ...(value.nodeState ? { nodeState: value.nodeState } : {}),
+    };
+    if (audience === 'public')
+        return common;
+    return {
+        ...common,
+        graphId: value.graphId,
+        runId: value.runId,
+        nodeRunId: value.nodeRunId,
+        ...(value.checkpointId ? { checkpointId: value.checkpointId } : {}),
+        ...(value.routeReason ? { routeReason: value.routeReason } : {}),
+        ...(value.routeEvidence === undefined ? {} : { routeEvidence: structuredClone(value.routeEvidence) }),
+    };
+}
+//# sourceMappingURL=graph-metadata.js.map