@aiwg/cli 2026.10.1 → 2026.10.4

package/bin/aiwg.mjs

@@ -30,41 +30,52 @@ import { randomUUID } from 'crypto';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, '..');
+process.env['AIWG_LAUNCHER_ROOT'] = packageRoot;
 
-function readPackageVersion() {
+function readPackageVersion(root = packageRoot) {
   try {
-    const pkg = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
     return typeof pkg.version === 'string' ? pkg.version : '(unknown)';
   } catch {
     return '(unknown)';
   }
 }
 
-function detectVersionChannel(version) {
-  if (version.includes('-rc.')) return 'rc';
-  if (version.includes('-beta.')) return 'beta';
-  if (version.includes('-alpha.')) return 'alpha';
-  if (version.includes('-nightly.')) return 'nightly';
+function readVersionConfig() {
   try {
     const legacyDir = path.join(os.homedir(), '.aiwg');
     const xdgDir = path.join(os.homedir(), '.config', 'aiwg');
     const configDir = process.env.AIWG_CONFIG
       ? path.resolve(process.env.AIWG_CONFIG)
       : existsSync(legacyDir) ? legacyDir : existsSync(xdgDir) ? xdgDir : legacyDir;
+    let config = {};
+    try {
+      config = JSON.parse(readFileSync(path.join(configDir, 'channel.json'), 'utf8'));
+    } catch { /* Legacy config is optional. */ }
     const installationFile = path.join(configDir, 'installation.json');
     if (existsSync(installationFile)) {
       const installation = JSON.parse(readFileSync(installationFile, 'utf8'));
-      if (installation?.runMode === 'development') return 'dev';
-      if (typeof installation?.channel === 'string') return installation.channel;
+      return {
+        ...config,
+        devMode: installation?.runMode === 'development',
+        channel: installation?.channel,
+        edgePath: installation?.edgePath ?? config.edgePath,
+      };
     }
-    const raw = readFileSync(path.join(configDir, 'channel.json'), 'utf8');
-    const cfg = JSON.parse(raw);
-    if (cfg?.devMode) return 'dev';
-    if (typeof cfg?.channel === 'string') return cfg.channel;
+    return config;
   } catch {
     // Default below.
   }
-  return 'stable';
+  return {};
+}
+
+function detectVersionChannel(version, config) {
+  if (config.devMode) return 'dev';
+  if (version.includes('-rc.')) return 'rc';
+  if (version.includes('-beta.')) return 'beta';
+  if (version.includes('-alpha.')) return 'alpha';
+  if (version.includes('-nightly.')) return 'nightly';
+  return config.channel || 'stable';
 }
 
 function maybeHandleFastVersion(args) {
@@ -72,8 +83,15 @@ function maybeHandleFastVersion(args) {
   if (args[0] !== '--version' && args[0] !== '-version') return false;
 
   const version = readPackageVersion();
-  const channel = detectVersionChannel(version);
+  const config = readVersionConfig();
+  const channel = detectVersionChannel(version, config);
+  const runtimePath = config.devMode && config.edgePath ? config.edgePath : packageRoot;
   console.log(`  aiwg  ${version}  [${channel}]`);
+  if (config.devMode) {
+    console.log(`    launcher: ${version}`);
+    console.log(`    runtime: ${readPackageVersion(runtimePath)}`);
+    console.log(`    runtime path: ${runtimePath}`);
+  }
   console.log(`    path: ${packageRoot}`);
   return true;
 }
@@ -240,14 +258,91 @@ maybeWarnUnbuiltDist();
 
 // Propagate the strict no-write contract through helpers that may resolve
 // installation/channel state before the command context exists.
-if (process.argv.slice(2).includes('--dry-run')) {
+function isReadOnlyReport(args) {
+  return (args[0] === 'rules' && ['inventory', 'list'].includes(args[1]))
+    || (['doctor', '-doctor', '--doctor'].includes(args[0]) && args.includes('--decision-offload'))
+    || (args[0] === 'steward' && args[1] === 'decision-offload');
+}
+const readOnlyReport = isReadOnlyReport(process.argv.slice(2));
+if (process.argv.slice(2).includes('--dry-run') || readOnlyReport) {
   process.env['AIWG_CLI_DRY_RUN'] = '1';
 }
 
+// Startup tracing — set AIWG_TRACE_STARTUP=1 to print per-phase timings to
+// stderr. Useful for diagnosing cold-start regressions, and for a test to
+// observe whether the credential-handling skip below actually fired,
+// without needing the update notifier to otherwise be eligible to run (it
+// also needs a real terminal — see `isCredentialHandlingCommand()`'s own
+// tests). No-op by default so it doesn't cost anything on the hot path.
+// Defined ahead of its first use below (moved up from just before
+// `resolveRouterPath()`, where it used to sit) so the notifier gate can use
+// it too.
+const traceStartup = process.env['AIWG_TRACE_STARTUP'] === '1' ||
+  process.env['AIWG_TRACE_STARTUP']?.toLowerCase() === 'true';
+const startHr = process.hrtime.bigint();
+function trace(phase) {
+  if (!traceStartup) return;
+  const ms = Number(process.hrtime.bigint() - startHr) / 1_000_000;
+  process.stderr.write(`[trace] +${ms.toFixed(1)}ms ${phase}\n`);
+}
+trace('bin:entry');
+
+/**
+ * True iff this invocation is a command that reads a secret directly from
+ * the environment or from an argument as part of its own documented
+ * contract (go/no-go review, blocker 1A). Checked from argv alone — no
+ * dist/ import, no router resolution — so it costs nothing on the
+ * `--version`/`--help` fast paths and can run before any bootstrap
+ * subprocess starts.
+ *
+ * No bootstrap subprocess may start before dispatch for one of these,
+ * because a bootstrap child that copies the parent's environment (or is
+ * merely spawned while `NODE_DEBUG=child_process` is set) would otherwise
+ * see whatever the command's own secret-bearing variable holds, before the
+ * command itself ever ran. Scrubbing a specific variable out of every
+ * possible bootstrap child is not attempted here — not starting the
+ * bootstrap at all for these commands is the smaller, certain fix. (The
+ * background update-check child also gets its own environment allow-list,
+ * independent of this list — see `notifierChildEnv()` in
+ * `src/update/notifier.mjs` — so a secret in the parent's environment that
+ * this list does not yet name is still not copied into that one child.)
+ *
+ * Qualifying commands, and why:
+ *   - `mcp profile login` — reads an API key via `--api-key-env`,
+ *     `--api-key-stdin`, or `--api-key-file`.
+ *   - `decision setup jev` — without `--token-stdin`, reads the token
+ *     directly from `JEV_API_KEY`/`AIWG_DECISION_JEV_API_KEY`.
+ *
+ * Checked and left out, with reasons (see the go/no-go review response):
+ *   - `auth login` — an OAuth device/browser flow; it does not read a
+ *     pre-existing secret from the environment or argv at invocation, it
+ *     obtains one over the network after the user authorizes it.
+ *   - `mcp inject` / `mcp add` / `mcp update` (including `--header-env`) —
+ *     `headerEnv`/`envFrom` references only ever carry a variable *name*
+ *     into a provider's config (resolved by that provider later, not by
+ *     this process); a literal `--env NAME=value` on `mcp add` is stored
+ *     to the registry file and never touches `process.env` here.
+ */
+function isCredentialHandlingCommand(args) {
+  const positionals = [];
+  for (const arg of args) {
+    if (arg === '--') break;
+    if (!arg.startsWith('-')) {
+      positionals.push(arg);
+      if (positionals.length >= 3) break;
+    }
+  }
+  if (positionals[0] === 'mcp' && positionals[1] === 'profile' && positionals[2] === 'login') return true;
+  if (positionals[0] === 'decision' && positionals[1] === 'setup' && positionals[2] === 'jev') return true;
+  return false;
+}
+
 // Display a cached notice and schedule its refresh before every eligible CLI
 // path, including fast help/version, channel recovery, and later preflight
-// failures. This local-only bootstrap never waits on the registry and failures
-// are deliberately ignored so update advice cannot change command behavior.
+// failures — except a credential-handling command (above), which never gets
+// this or any other bootstrap subprocess before dispatch. This local-only
+// bootstrap never waits on the registry and failures are deliberately
+// ignored so update advice cannot change command behavior.
 async function runUpdateNotifierBootstrap() {
   try {
     const notifierPath = path.join(packageRoot, 'dist', 'src', 'update', 'notifier.mjs');
@@ -260,12 +355,21 @@ async function runUpdateNotifierBootstrap() {
   }
 }
 
-await runUpdateNotifierBootstrap();
+const cliArgs = process.argv.slice(2);
+const indexRefresh = cliArgs[0] === 'index' && cliArgs[1] === 'refresh';
+if (indexRefresh || readOnlyReport) {
+  trace(`notifier:skip (${indexRefresh ? 'index refresh' : 'read-only report'})`);
+} else if (isCredentialHandlingCommand(cliArgs)) {
+  trace('notifier:skip (credential-handling command)');
+} else {
+  await runUpdateNotifierBootstrap();
+  trace('notifier:bootstrap-complete');
+}
 
-if (maybeHandleFastVersion(process.argv.slice(2))) {
+if (maybeHandleFastVersion(cliArgs)) {
   process.exit(0);
 }
-if (maybeHandleFastHelp(process.argv.slice(2))) {
+if (maybeHandleFastHelp(cliArgs)) {
   process.exit(0);
 }
 
@@ -286,19 +390,6 @@ function ensureInvocationId() {
 }
 const invocationId = ensureInvocationId();
 
-// Startup tracing — set AIWG_TRACE_STARTUP=1 to print per-phase timings to
-// stderr. Useful for diagnosing cold-start regressions. No-op by default so
-// it doesn't cost anything on the hot path.
-const traceStartup = process.env['AIWG_TRACE_STARTUP'] === '1' ||
-  process.env['AIWG_TRACE_STARTUP']?.toLowerCase() === 'true';
-const startHr = process.hrtime.bigint();
-function trace(phase) {
-  if (!traceStartup) return;
-  const ms = Number(process.hrtime.bigint() - startHr) / 1_000_000;
-  process.stderr.write(`[trace] +${ms.toFixed(1)}ms ${phase}\n`);
-}
-trace('bin:entry');
-
 /**
  * Resolve the path to the compiled router.
  *
@@ -309,10 +400,11 @@ trace('bin:entry');
  * emit a clear error and exit rather than falling back to a tsx fork.
  */
 async function resolveRouterPath() {
-  const { loadConfig } = await import('../dist/src/channel/manager.mjs');
+  const { loadConfig, resolveEffectiveInstallationRoot } = await import('../dist/src/channel/manager.mjs');
   const config = await loadConfig({ createIfMissing: !process.argv.slice(2).includes('--dry-run') });
-  if (config.devMode && config.edgePath && config.edgePath !== packageRoot) {
-    const devRouter = path.join(config.edgePath, 'dist', 'src', 'cli', 'router.js');
+  const effectiveRoot = resolveEffectiveInstallationRoot(packageRoot, config);
+  if (effectiveRoot !== packageRoot) {
+    const devRouter = path.join(effectiveRoot, 'dist', 'src', 'cli', 'router.js');
     if (!existsSync(devRouter)) {
       console.error(`Dev mode: compiled router not found at ${devRouter}`);
       console.error(`  Run: (cd ${config.edgePath} && npm run build)`);
@@ -376,7 +468,7 @@ async function applyVerbosityFromArgs(args, routerPath) {
       setInvocationId(invocationId);
       // One-shot prune of old JSONL files on startup. Bounded work; safe to
       // call on every invocation because the work is a single directory list.
-      pruneOldLogs();
+      if (!readOnlyReport) pruneOldLogs();
     }
   } catch {
     // If the logger isn't importable yet (fresh clone without dist/), the
@@ -398,6 +490,7 @@ const RECOVERY_SAFE_COMMANDS = new Set([
 const RECOVERY_SAFE_INDEX_SUBCOMMANDS = new Set(['query', 'deps', 'stats']);
 
 function isRecoverySafeCommand(args) {
+  if (isReadOnlyReport(args)) return true;
   const command = args.find((arg) => !arg.startsWith('-'));
   if (!command) return false;
   if (RECOVERY_SAFE_COMMANDS.has(command)) return true;
@@ -447,8 +540,8 @@ async function main() {
       console.error(`  Or switch back: aiwg --use-stable`);
       process.exit(1);
     }
-    const { assertCanonicalInstallation } = await import(pathToFileURL(identityPath).href);
-    const readOnlyPreview = args.includes('--dry-run');
+    const { assertCanonicalInstallation, formatInstallationDiagnostic } = await import(pathToFileURL(identityPath).href);
+    const readOnlyPreview = args.includes('--dry-run') || indexRefresh || readOnlyReport;
     try {
       assertCanonicalInstallation({
         actualRoot: activePackageRoot,
@@ -467,12 +560,7 @@ async function main() {
         drift,
       });
       process.stderr.write(
-        `aiwg: warning: installation identity drift detected; \`${args[0]}\` is read-only and continues, ` +
-        'but update, refresh, and deployment stay blocked until the identity is repaired.\n' +
-        drift.map((item) => `- ${item}\n`).join('') +
-        'Inspect: aiwg installation show\n' +
-        'Adopt this installation: aiwg installation adopt\n' +
-        'Switch deliberately: aiwg installation switch --root <path> --method <npm|web|source> [--manager <absolute-path>]\n',
+        `aiwg: warning: ${formatInstallationDiagnostic(error.status, { readOnlyCommand: args[0] })}\n`,
       );
     }
   }
@@ -480,7 +568,7 @@ async function main() {
   // Wire up the logger level from -v/-vv/--quiet/AIWG_LOG_LEVEL before any
   // handler runs, and stamp the top-level invocation ID so the logger can
   // tag every record with it.
-  await applyVerbosityFromArgs(args, routerPath);
+  if (!indexRefresh) await applyVerbosityFromArgs(args, routerPath);
 
   // Top-level cancellation controller. SIGINT / SIGTERM flip it, long-running
   // handlers plumb ctx.signal through fetches and loops so Ctrl-C cancels

package/dist/src/a2a/codecs.js

@@ -1,3 +1,4 @@
+import { assertMissionWorkerHandoff } from '../mission-protocol/codecs.js';
 export function encodePushNotificationConfig(version, config) {
     assertNonEmptyString(version, '$.url', config.url);
     if (version === '0.3') {
@@ -81,6 +82,7 @@ const V1_TO_STATE = {
 };
 const STATE_TO_V1 = Object.fromEntries(Object.entries(V1_TO_STATE).map(([wire, normalized]) => [normalized, wire]));
 export function encodeMessage(version, message) {
+    assertMissionWorkerHandoff(message, 'a2a');
     assertNonEmptyString(version, '$.messageId', message.messageId);
     if (message.role !== 'user' && message.role !== 'agent') {
         fail(version, '$.role', 'must be user or agent');
@@ -101,6 +103,7 @@ export function encodeMessage(version, message) {
     return out;
 }
 export function decodeMessage(version, input, path = '$') {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     const messageId = stringAt(version, `${path}.messageId`, obj.messageId);
     const role = decodeRole(version, obj.role, `${path}.role`);
@@ -120,6 +123,7 @@ export function decodeMessage(version, input, path = '$') {
     return message;
 }
 export function encodeTask(version, task) {
+    assertMissionWorkerHandoff(task, 'a2a');
     assertNonEmptyString(version, '$.id', task.id);
     const out = {
         id: task.id,
@@ -137,6 +141,7 @@ export function encodeTask(version, task) {
     return out;
 }
 export function decodeTask(version, input, path = '$') {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     if (version === '1.0' && typeof obj.kind === 'string') {
         fail(version, `${path}.kind`, 'legacy kind discriminator is not valid in 1.0');
@@ -219,6 +224,7 @@ export function decodeStatus(version, input, path = '$') {
     return status;
 }
 export function encodeArtifact(version, artifact, path = '$') {
+    assertMissionWorkerHandoff(artifact, 'a2a');
     assertNonEmptyString(version, `${path}.artifactId`, artifact.artifactId);
     if (!Array.isArray(artifact.parts) || artifact.parts.length === 0) {
         fail(version, `${path}.parts`, 'must contain at least one part');
@@ -234,6 +240,7 @@ export function encodeArtifact(version, artifact, path = '$') {
     return out;
 }
 export function decodeArtifact(version, input, path = '$') {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     const partsRaw = arrayAt(version, `${path}.parts`, obj.parts);
     if (partsRaw.length === 0)
@@ -260,6 +267,7 @@ function encodeMessageAt(version, message, path) {
     }
 }
 function encodePart(version, part, path) {
+    assertMissionWorkerHandoff(part, 'a2a');
     const common = {};
     copyJsonObject(version, common, 'metadata', part.metadata, `${path}.metadata`);
     copyOptional(common, version === '0.3' ? 'mimeType' : 'mediaType', part.mediaType);
@@ -288,6 +296,7 @@ function encodePart(version, part, path) {
     };
 }
 function decodePart(version, input, path) {
+    assertMissionWorkerHandoff(input, 'a2a');
     const obj = objectAt(version, path, input);
     if (version === '0.3')
         return decodeLegacyPart(obj, path);

package/dist/src/agents/grounding/knowledge-base.js

@@ -108,7 +108,11 @@ export class KnowledgeStore {
             .slice(0, limit);
     }
     /**
-     * Verify a claim against domain knowledge
+     * Verify literal support against the top three retrieved knowledge entries.
+     * Only a whole-entry statement match establishes support; direct copular
+     * negation vetoes it. Other wording abstains, including paraphrases and
+     * multi-sentence passages. This is not a general semantic entailment judge
+     * or a check that the stored knowledge is itself true.
      */
     verifyClaim(claim, domain) {
         const fragments = this.search(claim, { domain, limit: 3 });
@@ -118,17 +122,31 @@ export class KnowledgeStore {
                 verified: false,
                 confidence: 0,
                 sources: [],
+                evidence: [],
                 correction: 'No relevant knowledge found in knowledge base',
             };
         }
-        // Simple verification: check if top fragments support or contradict
-        const topFragment = fragments[0];
-        const confidence = Math.min(topFragment.relevance_score, 1.0);
+        // Relevance selects candidates; only their content can establish support.
+        const evidence = fragments.map((fragment) => ({
+            source: fragment.source,
+            entry_id: fragment.metadata?.id,
+            content: fragment.content,
+            relation: compareStatements(claim, fragment.content),
+        }));
+        const contradictions = evidence.filter((item) => item.relation === 'contradicts');
+        const verified = contradictions.length === 0
+            && evidence.some((item) => item.relation === 'supports');
         return {
             claim,
-            verified: confidence > 0.3,
-            confidence,
+            verified,
+            confidence: verified ? 1 : 0,
             sources: fragments.map((f) => f.source),
+            evidence,
+            ...(!verified && {
+                correction: contradictions.length > 0
+                    ? `Conflicting knowledge: ${contradictions.map((item) => item.content).join(' | ')}`
+                    : 'Relevant knowledge was retrieved, but explicit support was not established',
+            }),
         };
     }
     listDomains() {
@@ -144,6 +162,36 @@ export class KnowledgeStore {
 // ============================================================================
 // Helpers
 // ============================================================================
+function normalizeStatement(text) {
+    // Preserve case, numbers and internal punctuation: they can change meaning.
+    return text.trim().replace(/\s+/g, ' ').replace(/\.$/, '');
+}
+function compareStatements(claim, content) {
+    const statement = normalizeStatement(claim);
+    const evidence = normalizeStatement(content);
+    if (!statement || !evidence)
+        return 'unknown';
+    // Do not extract assertions from questions, quotations or multi-sentence text.
+    if ([statement, evidence].some((text) => /[?!;"“”]|\.(?:\s|$)/.test(text)))
+        return 'unknown';
+    if (statement === evidence)
+        return 'supports';
+    // A deliberately limited conflict rule: the same whole statement with a
+    // single "not" following is/are/was/were. Never infer support by dropping
+    // negation, and abstain on complex negation (e.g. "not only" or "not always").
+    const affirmative = (text) => {
+        if (/[.!?;:\n]/.test(text))
+            return undefined;
+        const match = text.match(/^(.+?\b(?:is|are|was|were)) not (.+)$/);
+        if (!match || /\b(?:not|only|just|always|necessarily)\b/.test(match[2]))
+            return undefined;
+        return `${match[1]} ${match[2]}`;
+    };
+    if (affirmative(statement) === evidence || affirmative(evidence) === statement) {
+        return 'contradicts';
+    }
+    return 'unknown';
+}
 function calculateRelevance(entry, queryTerms) {
     const searchable = [
         entry.topic,

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

@@ -455,6 +455,12 @@ function recordForEntry(cwd, entry, graphName, dependencyGraph, privacy, schemaV
                             ? { aiwg_search_terms: uniqueSorted(entry.searchTerms) }
                             : {}),
                         ...(entry.script ? { aiwg_script: entry.script } : {}),
+                        ...(entry.activation ? { activation: entry.activation } : {}),
+                        ...(entry.bound_to ? { bound_to: entry.bound_to } : {}),
+                        ...(entry.ruleEnforcement ? { enforcement: entry.ruleEnforcement } : {}),
+                        ...(entry.rulePaths ? { paths: entry.rulePaths } : {}),
+                        ...(entry.governedPaths ? { aiwg_governed_paths: entry.governedPaths } : {}),
+                        ...(entry.ruleSummary !== undefined ? { summary: entry.ruleSummary } : {}),
                     },
                 },
             }

package/dist/src/artifacts/checksum-manifest.js

@@ -58,6 +58,7 @@ export function writeManifest(indexDir, manifest) {
         version: 1,
         generated: new Date().toISOString(),
         entries: manifest.entries,
+        ...(manifest.receipt ? { receipt: manifest.receipt } : {}),
     };
     fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf-8');
     fs.renameSync(tmpPath, manifestPath);