@baize-ai/core 0.3.13 → 0.3.15

package/.dockerignore

@@ -6,5 +6,3 @@
 !templates/pm2/ecosystem.config.cjs
 !.claude-local/claude
 !.claude-local/claude.version
-!skills/
-!.docker-local-skills/

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to baize-core will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.15] - 2026-08-31
+
+### Fixed
+- A2A daemon 监控自愈统一收编 `baize init`（D49）：init 幂等 bootstrap（enabled → detached `cli.js start --background` → daemon-ctl pm2+waitReady → pm2 save），结果落 `components/a2a/bootstrap-state.json` 并在 web 状态卡展示；Docker 与裸机同一路径，entrypoint 的 Docker 专属 Step 3b（D48）删除
+- core pm2 ecosystem 不再纳管 baize-a2a（D49）：其生命周期唯一归属 daemon-ctl——消除三条启动路径并存导致的 8443 双实例竞态
+
+### Added
+- `baize upgrade <name> --file <tgz>`（D49）：商业组件离线升级——manifest/版本闸（新 > 旧）、备份回滚、既有 9 步管线；step8 重启钩子对 baize-a2a 优先走其 `cli.js restart`（覆盖 nohup daemon，pm2-only 路径的盲区修复）
+- getLocalVersion 优先读组件 package.json（SKILL.md frontmatter 曾恒 0.1.0 → 升级判定失真）
+- Web 控制台 A2A 上传：已安装 = 升级（版本闸 409 version_not_higher + 备份回滚 + 自动重启 daemon），安装/升级双语义
+- docker-compose healthcheck：A2A enabled 时追加 TCP 8443 就绪探测（pm2 list 无法发现静默空转的 daemon）
+
+## [0.3.14] - 2026-08-30
+
+### Fixed
+- A2A 容器重启自愈（D48）：entrypoint 检查 A2A config.enabled → 自动启动 baize-a2a daemon——容器重启后 A2A 零手动恢复
+- Web A2A 状态卡证书徽章（D48）：显示证书链状态（certValid）——daemon 在线时"自动处理中"、离线时提示"待续签"
+
 ## [0.3.13] - 2026-08-28
 
 ### Fixed

package/Dockerfile

@@ -82,11 +82,6 @@ ENV WEB_CONSOLE_BIND=0.0.0.0
 # build context) — source stays private, the image matches the npm version
 # exactly. Build with: docker build --build-arg BAZE_CORE_VERSION=0.2.0 .
 ARG BAZE_CORE_VERSION=latest
-# Local-development override: when building from source with
-# --build-arg BAIZE_LOCAL_SKILLS=1, copy the LOCAL skills over the npm-package
-# skills so un-released fixes (e.g. D44) land in the image without publishing.
-# Official builds leave this off — the published npm package is authoritative.
-ARG BAIZE_LOCAL_SKILLS=0
 WORKDIR /home/baize
 RUN npm install -g @baize-ai/core@${BAZE_CORE_VERSION} \
     && baize --version \
@@ -129,14 +124,6 @@ RUN npm install -g @baize-ai/core@${BAZE_CORE_VERSION} \
     && node -e "const D=require('/home/baize/baize/.claude/skills/web-console/node_modules/better-sqlite3'); new D(':memory:')" \
     && echo "native modules OK (locally compiled, baked into runtime skills)"
 
-# ── Local-source skills override (BAIZE_LOCAL_SKILLS=1) ─────────────────────
-# docker-publish.sh stages the repo's skills/ into .docker-local-skills/ when
-# BAIZE_LOCAL_SKILLS=1 (empty directory otherwise). They land in
-# /home/baize/.local-skills and are applied by entrypoint AFTER init, because
-# init's postinstall syncSkills uses the npm-package skills as source and
-# would otherwise overwrite them. Official images carry an empty dir — no-op.
-COPY --chown=baize:baize .docker-local-skills/ /home/baize/.local-skills/
-
 # ── Workspace directories ─────────────────────────────────────────────────────
 # ~/baize is mounted as a single volume in docker-compose.yml.
 # Creating subdirectories here ensures correct ownership in the image.

package/cli/commands/add.js

@@ -714,6 +714,9 @@ async function installDeclarative(resolved, skillDir, skipConfirm, jsonOutput, b
       console.log(`  ${success(`${bold(service.name || ('baize-' + resolved.name))} started`)}`);
     } else {
       console.log(`  ${error(`Failed to start service: ${svcResult.error}`)}`);
+      if (name === 'a2a') {
+        console.log(`  ${dim('Run `baize a2a start` (or \`baize init\`) to bring the A2A daemon up.')}`);
+      }
       console.log(`  ${dim('You can start it manually later.')}`);
     }
   }

package/cli/commands/component.js

@@ -3,14 +3,15 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { BAIZE_DIR, SKILLS_DIR, COMPONENTS_DIR, getBaizeConfig } from '../lib/config.js';
 import { bold, dim, green, red, yellow, cyan, success, error, warn, heading } from '../lib/colors.js';
 import { loadRegistry } from '../lib/registry.js';
-import { searchNpmPackages, npmRegistryUrl } from '../lib/download.js';
+import { searchNpmPackages, npmRegistryUrl, acquireSource } from '../lib/download.js';
 import { loadComponents, saveComponents } from '../lib/components.js';
-import { checkForUpdates, getLocalSourceUpgradeError, getRepo, runUpgrade, downloadToTemp, readChangelog, filterChangelog, cleanupTemp } from '../lib/upgrade.js';
+import { checkForUpdates, getLocalVersion, getLocalSourceUpgradeError, getRepo, runUpgrade, downloadToTemp, readChangelog, filterChangelog, cleanupTemp } from '../lib/upgrade.js';
 import {
   checkForCoreUpdates, runSelfUpgrade,
   downloadCoreToTemp, readChangelog as readCoreChangelog,
@@ -21,7 +22,7 @@ import { parseSkillMd } from '../lib/skill.js';
 import { linkBins, unlinkBins } from '../lib/bin.js';
 import { removeCaddyRoutes } from '../lib/caddy.js';
 import { acquireLock, releaseLock } from '../lib/lock.js';
-import { fetchRawFile } from '../lib/github.js';
+import { fetchRawFile, compareSemverDesc } from '../lib/github.js';
 import { promptYesNo } from '../lib/prompts.js';
 import { evaluateUpgrade } from '../lib/claude-eval.js';
 
@@ -251,6 +252,8 @@ export async function upgradeComponent(args) {
   const skipEval = args.includes('--skip-eval');
   const beta = args.includes('--beta');
   const hasTempDirFlag = args.includes('--temp-dir');
+  const fileIndex = args.indexOf('--file');
+  const upgradeFile = fileIndex !== -1 ? args[fileIndex + 1] : null;
 
   if (hasTempDirFlag) {
     const msg = '--temp-dir is not supported.';
@@ -272,6 +275,17 @@ export async function upgradeComponent(args) {
     process.exit(1);
   }
 
+  if (fileIndex !== -1 && (!upgradeFile || upgradeFile.startsWith('-'))) {
+    console.error('Error: --file requires a path to a .tgz archive.');
+    process.exit(1);
+  }
+
+  // --file is a fully offline source: remote/branch resolution flags make no sense.
+  if (upgradeFile && (branch || beta)) {
+    console.error('Error: --file cannot be combined with --branch or --beta.');
+    process.exit(1);
+  }
+
   // --beta and --branch are mutually exclusive
   if (beta && branch) {
     console.error('Error: --beta and --branch are mutually exclusive.');
@@ -291,7 +305,7 @@ export async function upgradeComponent(args) {
   }
 
   // Get target component (filter out flags and flag values)
-  const flagsWithValues = new Set(['--branch', '--mode']);
+  const flagsWithValues = new Set(['--branch', '--mode', '--file']);
   const target = args.find((a, i) => {
     if (a.startsWith('-')) return false;
     if (a === 'confirm') return false;
@@ -300,6 +314,12 @@ export async function upgradeComponent(args) {
     return true;
   });
 
+  // --file upgrades one installed component from a local tarball.
+  if (upgradeFile && (upgradeAll || upgradeSelf)) {
+    console.error('Error: --file upgrades a single installed component; it cannot be combined with --all or --self.');
+    process.exit(1);
+  }
+
   // Handle --self: upgrade baize-core itself
   if (upgradeSelf) {
     if (checkOnly) {
@@ -326,6 +346,7 @@ export async function upgradeComponent(args) {
     console.log('  --yes, -y      Skip confirmation');
     console.log('  --skip-eval    Skip upgrade analysis of local changes');
     console.log('  --beta         Include prerelease (beta) versions');
+    console.log('  --file <tgz>   Upgrade from a local .tar.gz archive (offline delivery)');
     console.log('  --branch <b>   Upgrade from a specific branch (e.g. feat/xxx)');
     console.log('  --mode <m>     Merge mode: "merge" (default, smart three-way) or "overwrite"');
     console.log('\nExamples:');
@@ -356,20 +377,25 @@ export async function upgradeComponent(args) {
     process.exit(1);
   }
 
-  const localSourceError = getLocalSourceUpgradeError(target, components[target]);
-  if (localSourceError) {
-    const result = {
-      action: checkOnly ? 'check' : 'upgrade',
-      component: target,
-      ...localSourceError,
-      reply: localSourceError.message,
-    };
-    if (jsonOutput) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.error(`Error: ${localSourceError.message}`);
+  if (upgradeFile) {
+    // The tarball IS the local source for this upgrade — a local-source
+    // registration does not block it.
+  } else {
+    const localSourceError = getLocalSourceUpgradeError(target, components[target]);
+    if (localSourceError) {
+      const result = {
+        action: checkOnly ? 'check' : 'upgrade',
+        component: target,
+        ...localSourceError,
+        reply: localSourceError.message,
+      };
+      if (jsonOutput) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.error(`Error: ${localSourceError.message}`);
+      }
+      process.exit(1);
     }
-    process.exit(1);
   }
 
   if (!fs.existsSync(skillDir)) {
@@ -388,6 +414,17 @@ export async function upgradeComponent(args) {
     process.exit(1);
   }
 
+  // Mode 0: offline upgrade from a local tgz (K4 commercial delivery —
+  // baize-a2a never ships to npm; --file and web upload are the only channels).
+  if (upgradeFile) {
+    if (checkOnly) {
+      return handleFileCheckOnly(target, upgradeFile, { jsonOutput });
+    }
+    const ok = await handleFileUpgradeFlow(target, upgradeFile, { jsonOutput, skipConfirm: skipConfirm || explicitConfirm, mode });
+    if (!ok) process.exit(1);
+    return;
+  }
+
   // Mode 1: Check only (--check) — no lock, downloads to temp for file comparison
   if (checkOnly) {
     return handleCheckOnly(target, { jsonOutput, branch, beta });
@@ -717,29 +754,7 @@ async function handleUpgradeFlow(component, { jsonOutput, skipConfirm, skipEval,
     });
 
     if (result.success) {
-      // Phase C: Cleanup
-      // Update components.json
-      const components = loadComponents();
-      if (components[component]) {
-        components[component].version = result.to || components[component].version;
-        components[component].upgradedAt = new Date().toISOString();
-
-        // Update bin symlinks (remove old, create new)
-        const oldBin = components[component].bin;
-        if (oldBin) unlinkBins(oldBin);
-        const updatedSkill = parseSkillMd(skillDir);
-        const newBin = linkBins(skillDir, updatedSkill?.frontmatter?.bin);
-        if (newBin) {
-          components[component].bin = newBin;
-        } else {
-          delete components[component].bin;
-        }
-
-        saveComponents(components);
-      }
-
-      // Clean old backups (keep only the latest)
-      cleanOldBackups(skillDir);
+      applyUpgradeBookkeeping(component, skillDir, result);
     }
 
     // Output result
@@ -777,6 +792,240 @@ async function handleUpgradeFlow(component, { jsonOutput, skipConfirm, skipEval,
   }
 }
 
+/**
+ * Post-success bookkeeping shared by every upgrade path: bump components.json,
+ * refresh bin symlinks, prune old backups.
+ */
+function applyUpgradeBookkeeping(component, skillDir, result) {
+  const components = loadComponents();
+  if (components[component]) {
+    components[component].version = result.to || components[component].version;
+    components[component].upgradedAt = new Date().toISOString();
+
+    // Update bin symlinks (remove old, create new)
+    const oldBin = components[component].bin;
+    if (oldBin) unlinkBins(oldBin);
+    const updatedSkill = parseSkillMd(skillDir);
+    const newBin = linkBins(skillDir, updatedSkill?.frontmatter?.bin);
+    if (newBin) {
+      components[component].bin = newBin;
+    } else {
+      delete components[component].bin;
+    }
+
+    saveComponents(components);
+  }
+
+  // Clean old backups (keep only the latest)
+  cleanOldBackups(skillDir);
+}
+
+/**
+ * Resolve a --file path (~ expansion + absolutize).
+ */
+function resolveTgzPath(filePath) {
+  const expanded = filePath === '~'
+    ? os.homedir()
+    : filePath.startsWith('~/')
+      ? path.join(os.homedir(), filePath.slice(2))
+      : filePath;
+  return path.resolve(expanded);
+}
+
+/**
+ * Extract a local .tgz into a fresh temp dir and read its package manifest.
+ * Safety vetting (path traversal / links) is delegated to the local-tarball
+ * source resolver in cli/lib/download.js — the same gate `baize add` uses.
+ *
+ * @returns {{ ok: true, tempDir: string, version: string, name: string|null }
+ *          | { ok: false, error: string }}
+ */
+function extractTarballArtifact(tgzPath) {
+  if (!/\.(?:tar\.gz|tgz)$/i.test(tgzPath)) {
+    return { ok: false, error: `--file must be a .tgz archive: ${tgzPath}` };
+  }
+  if (!fs.existsSync(tgzPath)) {
+    return { ok: false, error: `File not found: ${tgzPath}` };
+  }
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'baize-upgrade-file-'));
+  const extract = acquireSource({ type: 'local-tarball', path: tgzPath }, tempDir);
+  if (!extract.success) {
+    cleanupTemp(tempDir);
+    return { ok: false, error: extract.error || 'Failed to extract tarball' };
+  }
+  let version = null;
+  let name = null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(tempDir, 'package.json'), 'utf8'));
+    if (typeof pkg.version === 'string' && pkg.version.trim()) version = pkg.version.trim();
+    if (typeof pkg.name === 'string' && pkg.name.trim()) name = pkg.name.trim();
+  } catch {
+    // missing/invalid package.json → version stays null, rejected by caller
+  }
+  if (!version) {
+    cleanupTemp(tempDir);
+    return { ok: false, error: 'Tarball has no package.json version' };
+  }
+  return { ok: true, tempDir, version, name };
+}
+
+/**
+ * K4: offline upgrade from a local .tgz (commercial delivery channel —
+ * baize-a2a never ships to npm, so --file and web upload are the only
+ * upgrade paths). Skips checkForUpdates/downloadToTemp: the tarball IS the
+ * source. Version gate: incoming semver must be strictly higher than the
+ * locally installed one (getLocalVersion reads package.json first — K6).
+ * Everything downstream reuses the existing 9-step runUpgrade pipeline
+ * (backup → smart merge → npm install → baseline → restart), including
+ * failure rollback.
+ *
+ * Returns true on success, false on failure. No process.exit() here.
+ */
+async function handleFileUpgradeFlow(component, filePath, { jsonOutput, skipConfirm, mode = 'merge' }) {
+  const skillDir = path.join(SKILLS_DIR, component);
+  let tempDir = null;
+
+  const failWith = (payload) => {
+    if (jsonOutput) {
+      const errOutput = { action: 'upgrade', component, success: false, ...payload };
+      errOutput.reply = formatC4Reply('error', { message: payload.message || payload.error });
+      console.log(JSON.stringify(errOutput, null, 2));
+    } else {
+      console.error(`Error: ${payload.message || payload.error}`);
+    }
+    return false;
+  };
+
+  const artifact = extractTarballArtifact(resolveTgzPath(filePath));
+  if (!artifact.ok) {
+    return failWith({ error: artifact.error });
+  }
+  tempDir = artifact.tempDir;
+
+  const lockResult = acquireLock(component);
+  if (!lockResult.success) {
+    return failWith({ error: lockResult.error });
+  }
+
+  try {
+    // Manifest sanity: the artifact must be the same package as installed.
+    let installedName = null;
+    try {
+      const localPkg = JSON.parse(fs.readFileSync(path.join(skillDir, 'package.json'), 'utf8'));
+      if (typeof localPkg.name === 'string') installedName = localPkg.name;
+    } catch {
+      // skill package.json is optional for the name check
+    }
+    if (installedName && artifact.name && artifact.name !== installedName) {
+      return failWith({ error: `manifest name mismatch: installed ${installedName}, tarball ${artifact.name}` });
+    }
+
+    const local = getLocalVersion(skillDir);
+    if (!local.success) {
+      return failWith({ error: `Cannot read current version: ${local.error}` });
+    }
+
+    if (compareSemverDesc(local.version, artifact.version) <= 0) {
+      return failWith({
+        error: 'version_not_higher',
+        message: `Incoming version ${artifact.version} is not higher than installed ${local.version} — nothing to upgrade.`,
+        local: local.version,
+        incoming: artifact.version,
+      });
+    }
+
+    if (!jsonOutput) {
+      console.log(`\n${bold(component)}: ${dim(local.version)} → ${bold(artifact.version)}`);
+      console.log(dim(`Source: local tarball (${filePath})`));
+    }
+
+    // Confirmation (no download/eval steps — the artifact is already local)
+    if (!skipConfirm) {
+      const confirmed = await promptYesNo('Proceed with upgrade? [y/N]: ');
+      if (!confirmed) {
+        console.log('Upgrade cancelled.');
+        return true; // Not an error — user chose to cancel
+      }
+    } else if (!jsonOutput) {
+      console.log(`Upgrading ${bold(component)}...`);
+    }
+
+    const result = runUpgrade(component, {
+      tempDir,
+      newVersion: artifact.version,
+      mode,
+      jsonOutput,
+      onStep: !jsonOutput ? printStep : undefined,
+    });
+
+    if (result.success) {
+      applyUpgradeBookkeeping(component, skillDir, result);
+    }
+
+    if (jsonOutput) {
+      const output = { ...result, source: { type: 'local-tarball', path: resolveTgzPath(filePath) } };
+      output.reply = formatC4Reply('upgrade', { component, ...result });
+      console.log(JSON.stringify(output, null, 2));
+    } else if (result.success) {
+      console.log(`\n${success(`${bold(component)} upgraded: ${dim(result.from)} → ${bold(result.to)}`)}`);
+    } else {
+      console.log(`\n${error(`Upgrade failed (step ${result.failedStep}): ${result.error}`)}`);
+      if (result.rollback?.performed) {
+        console.log(`\n${bold('Auto-rollback performed:')}`);
+        for (const r of result.rollback.steps) {
+          if (r.success) console.log(`  ${success(r.action)}`);
+          else console.log(`  ${error(r.action)}`);
+        }
+      }
+    }
+
+    return result.success;
+  } finally {
+    cleanupTemp(tempDir);
+    releaseLock(component);
+  }
+}
+
+/**
+ * K4 --check variant: compare a local tgz against the installed version
+ * without touching the installation (no lock needed).
+ */
+function handleFileCheckOnly(component, filePath, { jsonOutput }) {
+  const skillDir = path.join(SKILLS_DIR, component);
+  const artifact = extractTarballArtifact(resolveTgzPath(filePath));
+  if (!artifact.ok) {
+    if (jsonOutput) {
+      console.log(JSON.stringify({ action: 'check', component, success: false, error: artifact.error }, null, 2));
+    } else {
+      console.error(`Error: ${artifact.error}`);
+    }
+    process.exit(1);
+  }
+
+  const local = getLocalVersion(skillDir);
+  const hasUpdate = local.success && compareSemverDesc(local.version, artifact.version) > 0;
+  const result = {
+    action: 'check',
+    component,
+    success: local.success,
+    hasUpdate,
+    current: local.success ? local.version : null,
+    latest: artifact.version,
+    source: { type: 'local-tarball', path: resolveTgzPath(filePath) },
+    ...(local.success ? {} : { error: local.error }),
+  };
+  if (jsonOutput) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (hasUpdate) {
+    console.log(`${bold(component)}: ${dim(result.current)} → ${bold(result.latest)} (local tarball)`);
+  } else if (local.success) {
+    console.log(success(`${bold(component)} is up to date (v${result.current}); tarball v${artifact.version} is not higher.`));
+  } else {
+    console.error(`Error: ${local.error}`);
+    process.exit(1);
+  }
+}
+
 /**
  * Clean old .backup/ directories, keeping only the latest.
  */

package/cli/commands/init.js

@@ -1145,6 +1145,47 @@ function startCoreServices(webPassword = null) {
   }
 }
 
+// ── A2A daemon bootstrap (D49) ───────────────────────────────────
+
+/**
+ * Fire-and-forget A2A daemon bootstrap. When the commercial baize-a2a
+ * component is installed AND enabled, bring its daemon up through the
+ * component's own CLI (`start --background`), which:
+ *   - prefers pm2 (autorestart + `pm2 save`/resurrect survive reboots),
+ *   - waits for TCP + card-identity readiness (30s),
+ *   - falls back to a nohup daemon when pm2 is unavailable,
+ *   - records the outcome in components/a2a/bootstrap-state.json.
+ *
+ * CRITICAL: this must NEVER block init. The child runs detached; init does
+ * not wait and cannot fail because of it. Docker and bare metal take the
+ * exact same path — the Docker-only entrypoint self-heal (D48 Step 3b) was
+ * removed in favor of this unified bootstrap (user decision, 2026-08-31).
+ */
+function bootstrapA2aDaemon({ quiet = false } = {}) {
+  try {
+    const cli = path.join(SKILLS_DIR, 'a2a', 'scripts', 'cli.js');
+    const a2aConfigPath = path.join(COMPONENTS_DIR, 'a2a', 'config.json');
+    if (!fs.existsSync(cli) || !fs.existsSync(a2aConfigPath)) return;
+    let enabled = false;
+    try {
+      enabled = JSON.parse(fs.readFileSync(a2aConfigPath, 'utf8')).enabled === true;
+    } catch {
+      return;
+    }
+    if (!enabled) return;
+    fs.mkdirSync(path.join(COMPONENTS_DIR, 'a2a', 'logs'), { recursive: true });
+    const child = spawn(process.execPath, [cli, 'start', '--background'], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
+    child.unref();
+    if (!quiet) console.log(`  ${dim('A2A daemon bootstrap launched (background) — see components/a2a/bootstrap-state.json.')}`);
+  } catch (err) {
+    if (!quiet) console.log(`  ${warn(`A2A bootstrap failed to launch: ${err.message}`)}`);
+  }
+}
+
 // ── PM2 boot auto-start ──────────────────────────────────────────
 
 /**
@@ -2394,6 +2435,7 @@ export async function initCommand(args) {
     }
     if (!quiet) console.log(heading('Starting services...'));
     const servicesStarted = startCoreServices(opts.webPassword);
+    bootstrapA2aDaemon({ quiet });
     if (servicesStarted > 0) {
       setupPm2Startup();
       if (!quiet) console.log(`\n${green(`${servicesStarted} service(s) started.`)} ${dim('Run "baize status" to check.')}`);
@@ -2516,6 +2558,7 @@ export async function initCommand(args) {
   // Step 11: Start services
   if (!quiet) console.log(`\n${heading('Starting services...')}`);
   const servicesStarted = startCoreServices(opts.webPassword);
+  bootstrapA2aDaemon({ quiet });
 
   if (servicesStarted > 0) {
     setupPm2Startup();

package/cli/lib/upgrade.js

@@ -21,31 +21,35 @@ import { copyTree, syncTree } from './fs-utils.js';
 import { applyCaddyRoutes } from './caddy.js';
 import { smartSync, formatMergeResult } from './smart-merge.js';
 import { restartFromEcosystem, restartManagedProcess } from './pm2.js';
+import { a2aCliPath } from './a2a.js';
 
 // ---------------------------------------------------------------------------
 // Version helpers
 // ---------------------------------------------------------------------------
 
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
 /**
- * Read the local version from SKILL.md frontmatter, falling back to package.json.
+ * Read the local version of an installed component (K6).
+ * Primary: skillDir/package.json `version` (valid semver only — SKILL.md
+ * frontmatter historically stayed at 0.1.0 while package.json advanced, which
+ * broke upgrade version gating). Fallback: SKILL.md frontmatter.
  */
-function getLocalVersion(skillDir) {
-  // Primary: SKILL.md frontmatter
-  const parsed = parseSkillMd(skillDir);
-  if (parsed?.frontmatter?.version) {
-    return { success: true, version: String(parsed.frontmatter.version) };
-  }
-  // Fallback: package.json
+export function getLocalVersion(skillDir) {
   const pkgPath = path.join(skillDir, 'package.json');
   try {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    if (pkg.version) {
-      return { success: true, version: String(pkg.version) };
+    if (typeof pkg.version === 'string' && SEMVER_RE.test(pkg.version.trim())) {
+      return { success: true, version: pkg.version.trim() };
     }
   } catch {
-    // package.json doesn't exist or is invalid
+    // package.json missing or invalid — fall through to SKILL.md
+  }
+  const parsed = parseSkillMd(skillDir);
+  if (parsed?.frontmatter?.version) {
+    return { success: true, version: String(parsed.frontmatter.version) };
   }
-  return { success: false, error: 'Version not found in SKILL.md or package.json' };
+  return { success: false, error: 'Version not found in package.json or SKILL.md' };
 }
 
 /**
@@ -645,8 +649,27 @@ function truncateHookOutput(value, maxLength = 1000) {
   return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;
 }
 
+const A2A_CLI_RESTART_TIMEOUT_MS = 120000;
+
+/**
+ * Resolve the baize-a2a scripts/cli.js for the K5 restart hook. The component's
+ * own skill dir wins (that is where `baize add` / web install put it); the
+ * fallback reuses cli/lib/a2a.js resolution (env override included).
+ */
+function defaultResolveA2aCli(skillDir) {
+  const local = path.join(skillDir, 'scripts', 'cli.js');
+  if (fs.existsSync(local)) return local;
+  return a2aCliPath();
+}
+
 /**
- * Step 8: restart PM2 service (if it was running before upgrade)
+ * Step 8: restart the component service (if it was running before upgrade).
+ *
+ * K5 restart hook: a nohup-started a2a daemon (Docker entrypoint) is invisible
+ * to pm2, so the pm2-only restart below never refreshed its code (C6). For
+ * service name 'baize-a2a' the a2a CLI `restart` (daemon-ctl: nohup pid +
+ * pm2 + waitReady) is preferred — it covers both lifecycles — falling back to
+ * the existing pm2 path when the CLI is unavailable or fails.
  */
 export function step8_startService(ctx, deps = {}) {
   const startTime = Date.now();
@@ -654,13 +677,30 @@ export function step8_startService(ctx, deps = {}) {
   const exists = deps.existsSync ?? fs.existsSync;
   const restartManaged = deps.restartManagedProcess ?? restartManagedProcess;
   const restartViaEcosystem = deps.restartFromEcosystem ?? restartFromEcosystem;
+  const spawnSyncFn = deps.spawnSyncFn ?? spawnSync;
+  const resolveA2aCli = deps.resolveA2aCli ?? defaultResolveA2aCli;
+
+  const parsed = parseSkillMd(ctx.skillDir);
+  const serviceName = parsed?.frontmatter?.lifecycle?.service?.name || `baize-${ctx.component}`;
+
+  if (serviceName === 'baize-a2a') {
+    const cli = resolveA2aCli(ctx.skillDir);
+    if (cli) {
+      const res = spawnSyncFn(process.execPath, [cli, 'restart', '--json'], {
+        input: '',
+        encoding: 'utf8',
+        timeout: A2A_CLI_RESTART_TIMEOUT_MS,
+      });
+      if (!res.error && res.status === 0) {
+        return { step: 8, name: 'start_service', status: 'done', message: `${serviceName} (a2a cli restart)`, duration: Date.now() - startTime };
+      }
+    }
+  }
 
   if (!ctx.serviceWasRunning) {
     return { step: 8, name: 'start_service', status: 'skipped', message: 'was not running', duration: Date.now() - startTime };
   }
 
-  const parsed = parseSkillMd(ctx.skillDir);
-  const serviceName = parsed?.frontmatter?.lifecycle?.service?.name || `baize-${ctx.component}`;
   const ecosystemPath = path.join(ctx.skillDir, 'ecosystem.config.cjs');
 
   try {