release-skill 0.9.4 → 0.9.5

package/src/commands/prepare.mjs

@@ -77,7 +77,11 @@ import { acquireProjectLock } from '../artifacts/project-lock.mjs';
 import { observePreviousPublicBaseline } from '../core/previous-public-baseline.mjs';
 import { verifyFrozenNpmTarballContract } from '../adapters/npm.mjs';
 import { createProductionPrepareRunDir } from '../core/run.mjs';
-import { PLATFORMS, normalizeHostId } from '../platforms/registry.mjs';
+import {
+  PLATFORMS,
+  normalizeHostId,
+  buildExpectedStandaloneIndexInstallIdentity,
+} from '../platforms/registry.mjs';
 import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
 import { validateMarketplaceSourceSelection, MARKETPLACE_SOURCE_TYPES, resolvePluginManifestFromMarketplaceEntrySource, resolveMarketplaceRoot } from '../adapters/plugin-marketplace.mjs';
 import { buildInstallationContract, computeInstallationContractDigest, INSTALLATION_CONTRACT_ALGORITHM_VERSION } from '../core/installation-contract.mjs';
@@ -97,6 +101,7 @@ import { digestReleaseAssetIdentities } from '../core/release-assets.mjs';
 
 /** 消费端安装验证配方版本。算法变更时递增。 */
 const CONSUMER_INSTALL_RECIPE_VERSION = 'consumer-install-v1';
+const FIRST_RELEASE_BOOTSTRAP_MODE = 'manual-index-checkpoint';
 
 // ---------------------------------------------------------------------------
 // Version resolution
@@ -1498,6 +1503,72 @@ async function defaultFetchExternalMarketplaceIndex(repo, manifestPath, ref, { g
   }
 }
 
+/**
+ * Observe the plugin repository before a first standalone-index release.
+ * This is deliberately a read-only, fail-closed observation: an empty
+ * repository, no target tag, and no target GitHub Release are all required.
+ */
+export function parseFirstReleasePluginRepositoryRefs(stdout, tag) {
+  if (typeof stdout !== 'string' || typeof tag !== 'string' || tag.length === 0) {
+    return { hasRefs: false, tagExists: false };
+  }
+  const refs = [];
+  let hasRefs = false;
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    const tabIndex = line.indexOf('\t');
+    if (tabIndex < 0) continue;
+    const sha = line.slice(0, tabIndex);
+    const ref = line.slice(tabIndex + 1);
+    if (EXTERNAL_MARKETPLACE_SHA_RE.test(sha)) {
+      hasRefs = true;
+      if (ref && ref !== 'HEAD') refs.push(ref);
+    }
+  }
+  const target = `refs/tags/${tag}`;
+  return {
+    hasRefs,
+    tagExists: refs.includes(target) || refs.includes(`${target}^{}`),
+  };
+}
+
+async function defaultObserveFirstReleasePluginRepository(repo, tag, { githubHost = 'github.com' } = {}) {
+  const url = `https://${githubHost}/${repo}.git`;
+  let repositoryRefs;
+  try {
+    const { stdout } = await execFile(
+      'git', ['ls-remote', '--symref', url],
+      { shell: false, encoding: 'utf8', timeout: 30000 },
+    );
+    repositoryRefs = parseFirstReleasePluginRepositoryRefs(String(stdout ?? ''), tag);
+  } catch (error) {
+    return { status: 'unknown', error: error.message };
+  }
+
+  let releaseExists = false;
+  try {
+    await execFile(
+      'gh', ['api', `repos/${repo}/releases/tags/${tag}`],
+      {
+        shell: false,
+        encoding: 'utf8',
+        timeout: 30000,
+        env: { ...process.env, GH_HOST: githubHost },
+      },
+    );
+    releaseExists = true;
+  } catch (error) {
+    const diagnostic = `${error?.stderr ?? ''} ${error?.message ?? ''}`;
+    if (!/\b404\b|not found/i.test(diagnostic)) {
+      return { status: 'unknown', error: error.message };
+    }
+  }
+  return { status: repositoryRefs.hasRefs ? 'non-empty' : 'empty', tagExists: repositoryRefs.tagExists, releaseExists };
+}
+
+function isFirstReleaseBootstrap(dist) {
+  return dist?.firstReleaseBootstrap === FIRST_RELEASE_BOOTSTRAP_MODE;
+}
+
 /**
  * Freeze the external marketplace HEAD for every claude/codex distribution
  * that declares `marketplaceRepo` (production + online only). For each such
@@ -1518,6 +1589,8 @@ export async function resolveExternalMarketplaceFreezes({
   evidence,
   observeHeadFn,
   fetchIndexFn,
+  productionAssets = null,
+  observePluginRepositoryFn = defaultObserveFirstReleasePluginRepository,
 }) {
   const freezes = new Map();
   for (let index = 0; index < unitResults.length; index += 1) {
@@ -1525,10 +1598,26 @@ export async function resolveExternalMarketplaceFreezes({
     const version = resolvedVersions[index];
     const githubHost = unit.production?.githubHost ?? 'github.com';
     for (const dist of unit.distributions ?? []) {
+      if (isFirstReleaseBootstrap(dist) && dist.marketplaceSourceType !== 'standalone-index') {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" ${dist.type} first-release bootstrap requires marketplaceSourceType standalone-index`,
+          { unitId: unit.id, distributionType: dist.type },
+        );
+      }
       // 只处理 standalone-index 来源；bundled-family 不需要外部冻结。
       if (dist.marketplaceSourceType !== 'standalone-index') continue;
       // standalone-index 必须有 marketplaceRepo；没有则跳过（兼容旧配置）。
-      if (!dist.marketplaceRepo) continue;
+      if (!dist.marketplaceRepo) {
+        if (isFirstReleaseBootstrap(dist)) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" ${dist.type} first-release bootstrap requires marketplaceRepo`,
+            { unitId: unit.id, distributionType: dist.type },
+          );
+        }
+        continue;
+      }
       const platform = PLATFORMS.find((p) => p.distributionType === dist.type);
       if (!platform) {
         throw new ReleaseError(
@@ -1545,6 +1634,13 @@ export async function resolveExternalMarketplaceFreezes({
           { unitId: unit.id, marketplaceSourceType: dist.marketplaceSourceType },
         );
       }
+      if (isFirstReleaseBootstrap(dist) && dist.type !== 'claude-plugin' && dist.type !== 'codex-plugin') {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" ${dist.type} first-release bootstrap is supported only for claude-plugin or codex-plugin standalone-index distributions`,
+          { unitId: unit.id, distributionType: dist.type },
+        );
+      }
       const observed = await observeHeadFn(dist.marketplaceRepo, { githubHost });
       if (observed.status !== 'observed' || !EXTERNAL_MARKETPLACE_SHA_RE.test(observed.sha ?? '') || !observed.defaultBranch) {
         throw new ReleaseError(
@@ -1581,23 +1677,65 @@ export async function resolveExternalMarketplaceFreezes({
           { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
         );
       }
-      const pluginEntries = Array.isArray(marketplaceIndex.plugins)
-        ? marketplaceIndex.plugins.filter((entry) => entry && entry.name === dist.plugin)
-        : [];
-      if (pluginEntries.length !== 1) {
+      if (!Array.isArray(marketplaceIndex.plugins)) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" ${dist.type} external marketplace index plugins must be an array`,
+          { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
+        );
+      }
+      const pluginEntries = marketplaceIndex.plugins.filter((entry) => entry && entry.name === dist.plugin);
+      if (isFirstReleaseBootstrap(dist) && pluginEntries.length > 0) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `unit "${unit.id}" first-release bootstrap requires the marketplace entry to be absent, found ${pluginEntries.length} matching entries`,
+          { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
+        );
+      }
+      if (pluginEntries.length !== 1 && !isFirstReleaseBootstrap(dist)) {
         throw new ReleaseError(
           GATE_FAILED,
           `unit "${unit.id}" external marketplace index must contain exactly one plugin entry named "${dist.plugin}", found ${pluginEntries.length}`,
           { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
         );
       }
-      if (platform.marketplaceEntryCarriesVersion && pluginEntries[0].version !== version) {
+      let selectedEntry = pluginEntries[0];
+      if (!isFirstReleaseBootstrap(dist) && platform.marketplaceEntryCarriesVersion && selectedEntry.version !== version) {
         throw new ReleaseError(
           GATE_FAILED,
           `unit "${unit.id}" external marketplace index entry version "${pluginEntries[0].version}" does not match target version "${version}"`,
           { unitId: unit.id, marketplaceRepo: dist.marketplaceRepo },
         );
       }
+      if (isFirstReleaseBootstrap(dist)) {
+        const asset = productionAssets?.[index];
+        if (!asset || !EXTERNAL_MARKETPLACE_SHA_RE.test(asset.commit ?? '') || !asset.tag) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" first-release bootstrap requires a frozen plugin tag and commit`,
+            { unitId: unit.id, distributionType: dist.type },
+          );
+        }
+        const pluginState = await observePluginRepositoryFn(unit.publicRepo, asset.tag, { githubHost });
+        if (
+          pluginState?.status !== 'empty'
+          || pluginState.tagExists !== false
+          || pluginState.releaseExists !== false
+        ) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" first-release bootstrap requires an empty plugin repository without the target tag or release`,
+            { unitId: unit.id, publicRepo: unit.publicRepo, tag: asset.tag, observed: pluginState },
+          );
+        }
+        selectedEntry = buildExpectedStandaloneIndexInstallIdentity(platform, {
+          name: dist.plugin,
+          repo: unit.publicRepo,
+          tag: asset.tag,
+          sha: asset.commit,
+          version,
+        });
+      }
       // marketplaceRef：Claude 使用默认分支名（name-ref），其余平台使用提交 SHA。
       // 无 CLI 的平台（kimi、codebuddy）也必须能冻结，ref 用 SHA。
       const marketplaceRef = platform.marketplaceRefForm === 'name' ? observed.defaultBranch : sha;
@@ -1612,7 +1750,10 @@ export async function resolveExternalMarketplaceFreezes({
         marketplaceRef,
         marketplaceIndexPath: manifestPath,
         marketplaceName: marketplaceIndex.name,
-        selectedEntry: pluginEntries[0],
+        selectedEntry,
+        ...(isFirstReleaseBootstrap(dist)
+          ? { firstReleaseBootstrap: FIRST_RELEASE_BOOTSTRAP_MODE, marketplaceIndexSha: null }
+          : {}),
       });
       await evidence.append({
         phase: 'external-marketplace-freeze',
@@ -1624,7 +1765,10 @@ export async function resolveExternalMarketplaceFreezes({
         marketplaceRef,
         marketplaceIndexPath: manifestPath,
         marketplaceName: marketplaceIndex.name,
-        selectedEntry: pluginEntries[0],
+        selectedEntry,
+        ...(isFirstReleaseBootstrap(dist)
+          ? { firstReleaseBootstrap: FIRST_RELEASE_BOOTSTRAP_MODE, marketplaceIndexSha: null }
+          : {}),
         defaultBranch: observed.defaultBranch,
       });
     }
@@ -2043,6 +2187,10 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
             marketplaceIndexPath: freeze.marketplaceIndexPath,
             marketplaceName: freeze.marketplaceName,
             selectedEntry: freeze.selectedEntry,
+            ...(freeze.firstReleaseBootstrap ? {
+              firstReleaseBootstrap: freeze.firstReleaseBootstrap,
+              marketplaceIndexSha: null,
+            } : {}),
           } : {}),
         },
         expected: {
@@ -2058,6 +2206,10 @@ export function buildExternalActions(unitResults, resolvedVersions, productionAs
           entrySkillFound: true,
           manifestDigest: asset.manifestDigest,
           ...(externalMarketplace ? { marketplaceLocation: 'external', marketplaceCommitSha: freeze.marketplaceCommitSha } : {}),
+          ...(externalMarketplace && freeze?.firstReleaseBootstrap ? {
+            firstReleaseBootstrap: freeze.firstReleaseBootstrap,
+            marketplaceIndexSha: null,
+          } : {}),
         },
         status: 'PENDING',
       });
@@ -4242,6 +4394,17 @@ export async function prepareRelease(options) {
     // and validate the marketplace index entry at that sha before freezing the
     // add-ref. The remote is only ever read (git ls-remote / gh api), never
     // written, and it is only ever reached AFTER the local closure passed.
+    for (const { unit } of unitResults) {
+      for (const dist of unit.distributions ?? []) {
+        if (isFirstReleaseBootstrap(dist) && (!production || offline)) {
+          throw new ReleaseError(
+            GATE_FAILED,
+            `unit "${unit.id}" ${dist.type} first-release bootstrap requires online production prepare`,
+            { unitId: unit.id, distributionType: dist.type },
+          );
+        }
+      }
+    }
     const externalMarketplaceFreezes = production
       ? await resolveExternalMarketplaceFreezes({
           unitResults,
@@ -4250,6 +4413,8 @@ export async function prepareRelease(options) {
           evidence,
           observeHeadFn: options.observeExternalMarketplaceHeadFn ?? defaultObserveExternalMarketplaceHead,
           fetchIndexFn: options.fetchExternalMarketplaceIndexFn ?? defaultFetchExternalMarketplaceIndex,
+          productionAssets,
+          observePluginRepositoryFn: options.observeFirstReleasePluginRepositoryFn ?? defaultObserveFirstReleasePluginRepository,
         })
       : new Map();
 
@@ -4353,6 +4518,10 @@ export async function prepareRelease(options) {
             frozenDist.marketplaceIndexPath = freeze.marketplaceIndexPath;
             frozenDist.marketplaceName = freeze.marketplaceName;
             frozenDist.selectedEntry = freeze.selectedEntry;
+            if (freeze.firstReleaseBootstrap) {
+              frozenDist.firstReleaseBootstrap = freeze.firstReleaseBootstrap;
+              frozenDist.marketplaceIndexSha = null;
+            }
           }
         }
 

package/src/commands/ship.mjs

@@ -174,7 +174,8 @@ async function defaultDependencies() {
   };
 }
 
-function publicState(state) {
+function publicState(state, { postRelease } = {}) {
+  const visiblePostRelease = postRelease === undefined ? state.postRelease : postRelease;
   return {
     command: 'ship',
     status: state.status,
@@ -199,7 +200,7 @@ function publicState(state) {
     ...(state.requirements ? { requirements: state.requirements } : {}),
     ...(state.manualFollowUps ? { manualFollowUps: state.manualFollowUps } : {}),
     ...(state.metadataUpdate ? { metadataUpdate: state.metadataUpdate } : {}),
-    ...(state.postRelease ? { postRelease: state.postRelease } : {}),
+    ...(visiblePostRelease ? { postRelease: visiblePostRelease } : {}),
     externalActionsIncludedInPlanApproval: true,
     verificationGatesIncludedInPlanApproval: true,
     postPublishCheckpointApprovalsIncludedInPlanApproval: false,
@@ -718,15 +719,6 @@ export async function advanceShip(options = {}, injected = {}) {
         updatedAt: new Date().toISOString(),
       };
       await writeJsonAtomic(statePath, state);
-      if (verified.status === 'VERIFIED') {
-        try {
-          state.postRelease = derivePostReleaseChecklist(plan);
-        } catch (error) {
-          state.postRelease = unavailablePostReleaseChecklist(plan, error);
-        }
-        state.updatedAt = new Date().toISOString();
-        await writeJsonAtomic(statePath, state);
-      }
     } catch (error) {
       if (error?.code !== CONSUMER_VERIFICATION_DEFERRED) throw error;
       state = {
@@ -835,5 +827,28 @@ export async function advanceShip(options = {}, injected = {}) {
     }
   }
 
+  if (state.status === 'VERIFIED') {
+    const finalPlan = JSON.parse(await readFile(state.planPath, 'utf8'));
+    const hasPostVerify = normalizePostPublishView(finalPlan).some((declaration) => (
+      (declaration.hooks ?? []).some((hook) => hook.phase === 'postVerify')
+    ));
+    const localFinishRunPath = hasPostVerify
+      ? (state.postVerify?.status === 'DISTRIBUTED' ? state.postVerify.runPath : undefined)
+      : state.verifyRunPath;
+    let postRelease;
+    try {
+      postRelease = derivePostReleaseChecklist(finalPlan, {
+        root,
+        statePath,
+        unitIds: state.selectedUnitIds,
+        runPath: localFinishRunPath,
+        postVerifyComplete: !hasPostVerify || state.postVerify?.status === 'DISTRIBUTED',
+      });
+    } catch (error) {
+      postRelease = unavailablePostReleaseChecklist(finalPlan, error);
+    }
+    return publicState(state, { postRelease });
+  }
+
   return publicState(state);
 }

package/src/commands/verify.mjs

@@ -68,6 +68,7 @@ import {
   verifyFrozenPluginWithFoundation,
 } from '../core/foundation-plugin-verification.mjs';
 import { resolveUnitScopedPath } from '../snapshot/public-path.mjs';
+import { canonicalJson } from '../core/digest.mjs';
 import {
   normalizeRegistry,
   registryTokenKey,
@@ -83,7 +84,7 @@ import {
 } from '../core/skill-resource-closure.mjs';
 import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
 import { isRemoteWriteAction, isMarketplaceAction } from '../core/checkpoints.mjs';
-import { PLATFORMS, normalizeHostId } from '../platforms/registry.mjs';
+import { PLATFORMS, normalizeHostId, projectObservedStandaloneIndexInstallIdentity } from '../platforms/registry.mjs';
 import {
   shouldSkipVerification,
   INSTALLATION_CONTRACT_ALGORITHM_VERSION,
@@ -183,6 +184,140 @@ function defaultClock() {
   return new Date().toISOString();
 }
 
+const FIRST_RELEASE_BOOTSTRAP_MODE = 'manual-index-checkpoint';
+const EXTERNAL_MARKETPLACE_SHA_RE = /^[0-9a-f]{40}$/;
+
+function parseMarketplaceHead(stdout) {
+  if (typeof stdout !== 'string') return null;
+  let sha = null;
+  let defaultBranch = null;
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    const tab = line.indexOf('\t');
+    if (tab < 0) continue;
+    const left = line.slice(0, tab);
+    const right = line.slice(tab + 1);
+    if (right !== 'HEAD') continue;
+    if (left.startsWith('ref: refs/heads/')) defaultBranch = left.slice('ref: refs/heads/'.length);
+    else if (EXTERNAL_MARKETPLACE_SHA_RE.test(left)) sha = left;
+  }
+  return sha && defaultBranch ? { sha, defaultBranch } : null;
+}
+
+async function defaultObserveMarketplaceHead(repo, { githubHost = 'github.com' } = {}) {
+  try {
+    const { stdout } = await execFile('git', [
+      'ls-remote', '--symref', `https://${githubHost}/${repo}.git`, 'HEAD',
+    ], { shell: false, encoding: 'utf8', timeout: 30000 });
+    const parsed = parseMarketplaceHead(stdout);
+    return parsed ? { status: 'observed', ...parsed } : { status: 'unknown', error: 'could not resolve marketplace HEAD' };
+  } catch (error) {
+    return { status: 'unknown', error: error.message };
+  }
+}
+
+function decodeMarketplaceIndex(content) {
+  if (typeof content !== 'string') return null;
+  try {
+    return JSON.parse(Buffer.from(content.replace(/\s/g, ''), 'base64').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function defaultFetchMarketplaceIndex(repo, path, ref, { githubHost = 'github.com' } = {}) {
+  try {
+    const { stdout } = await execFile('gh', [
+      'api', `repos/${repo}/contents/${path}?ref=${ref}`, '--jq', '.content',
+    ], {
+      shell: false,
+      encoding: 'utf8',
+      timeout: 30000,
+      env: { ...process.env, GH_HOST: githubHost },
+    });
+    const index = decodeMarketplaceIndex(stdout);
+    return index && typeof index === 'object'
+      ? { status: 'fetched', index }
+      : { status: 'unknown', error: 'could not decode marketplace index' };
+  } catch (error) {
+    return { status: 'unknown', error: error.message };
+  }
+}
+
+async function verifyFirstReleaseBootstrapIndexes({
+  actions,
+  plan,
+  evidence,
+  observeHeadFn,
+  fetchIndexFn,
+}) {
+  const bindings = new Map();
+  for (const action of actions) {
+    if (action.parameters?.firstReleaseBootstrap !== FIRST_RELEASE_BOOTSTRAP_MODE) continue;
+    const params = action.parameters;
+    const githubHost = params.githubHost ?? 'github.com';
+    const failDeferred = async (reason, observed = null) => {
+      await evidence.append({
+        phase: 'verify-marketplace-bootstrap-index',
+        actionId: action.id,
+        actionType: action.type,
+        status: 'needs-input',
+        reason,
+        ...(observed ? { observed } : {}),
+      });
+      throw new ReleaseError(
+        CONSUMER_VERIFICATION_DEFERRED,
+        `first-release bootstrap marketplace index is not an exact match for action "${action.id}"; complete the manual index checkpoint and retry verify with the same plan`,
+        { actionId: action.id, reason, observed, nextState: 'NEEDS_MANUAL_ATTESTATIONS' },
+      );
+    };
+    const observed = await observeHeadFn(params.repo, { githubHost });
+    if (observed?.status !== 'observed' || !EXTERNAL_MARKETPLACE_SHA_RE.test(observed.sha ?? '') || !observed.defaultBranch) {
+      await failDeferred(`could not observe current marketplace HEAD: ${observed?.error ?? 'unknown'}`, observed);
+    }
+    const path = params.marketplaceIndexPath;
+    const fetched = await fetchIndexFn(params.repo, path, observed.sha, { githubHost });
+    if (fetched?.status !== 'fetched' || !fetched.index || typeof fetched.index !== 'object') {
+      await failDeferred(`could not read marketplace index at ${observed.sha}: ${fetched?.error ?? 'unknown'}`, observed);
+    }
+    const index = fetched.index;
+    if (index.name !== params.marketplaceName) {
+      await failDeferred(`marketplace name mismatch: expected ${params.marketplaceName}, got ${index.name}`, { ...observed, name: index.name });
+    }
+    if (!Array.isArray(index.plugins)) {
+      await failDeferred('marketplace index plugins must be an array', { ...observed, pluginsType: typeof index.plugins });
+    }
+    const entries = index.plugins.filter((entry) => entry && entry.name === params.plugin);
+    let projectedEntry = null;
+    if (entries.length === 1) {
+      try {
+        projectedEntry = projectObservedStandaloneIndexInstallIdentity(params.consumer, entries[0]);
+      } catch {
+        projectedEntry = null;
+      }
+    }
+    if (entries.length !== 1 || !projectedEntry || canonicalJson(projectedEntry) !== canonicalJson(params.selectedEntry)) {
+      await failDeferred('marketplace selectedEntry is missing, duplicated, or does not exactly match the plan-bound expected entry', {
+        ...observed,
+        entryCount: entries.length,
+        selectedEntry: projectedEntry ?? entries[0] ?? null,
+      });
+    }
+    bindings.set(action.id, {
+      marketplaceIndexSha: observed.sha,
+      marketplaceIndexRef: action.type === 'claude-marketplace-install' ? observed.defaultBranch : observed.sha,
+    });
+    await evidence.append({
+      phase: 'verify-marketplace-bootstrap-index',
+      actionId: action.id,
+      actionType: action.type,
+      status: 'observed',
+      marketplaceIndexSha: observed.sha,
+      marketplaceIndexRef: action.type === 'claude-marketplace-install' ? observed.defaultBranch : observed.sha,
+    });
+  }
+  return bindings;
+}
+
 /**
  * 验证摘要格式是否为合法的 64 位十六进制字符串。
  *
@@ -957,6 +1092,8 @@ export async function verifyRelease(options) {
     execFn,
     configPath: configPathOpt,
     runPluginVerificationFn,
+    observeFirstReleaseMarketplaceHeadFn,
+    fetchFirstReleaseMarketplaceIndexFn,
   } = options ?? {};
 
   const clockFn = typeof clockOpt === 'function' ? clockOpt : defaultClock;
@@ -1265,6 +1402,19 @@ export async function verifyRelease(options) {
     const consumerVerificationReceipts = [];
     const actions = plan.externalActions ?? [];
 
+    // A bootstrap plan intentionally leaves the final marketplace index SHA
+    // pending. Before any marketplace adapter call, observe the current
+    // remote index and require an exact match for the plan-bound entry. A
+    // mismatch is the existing deferred/manual-attestation state; no add or
+    // install command is reached on this path.
+    const bootstrapIndexBindings = await verifyFirstReleaseBootstrapIndexes({
+      actions,
+      plan,
+      evidence,
+      observeHeadFn: observeFirstReleaseMarketplaceHeadFn ?? defaultObserveMarketplaceHead,
+      fetchIndexFn: fetchFirstReleaseMarketplaceIndexFn ?? defaultFetchMarketplaceIndex,
+    });
+
     // --- 自动发现可信消费端验证收据 ---
     // 收据选择逻辑（per-action 从所有候选中选最新匹配）：
     // - 只读取同一权威 .release-skill/runs 的真实直接子目录
@@ -1533,10 +1683,21 @@ export async function verifyRelease(options) {
           runDir,
         };
 
+        const bootstrapBinding = bootstrapIndexBindings.get(action.id) ?? null;
         const actionInput = {
           actionType: adapterActionType,
           ...action.parameters,
         };
+        if (bootstrapBinding) {
+          actionInput.marketplaceCommitSha = bootstrapBinding.marketplaceIndexSha;
+          actionInput.marketplaceIndexSha = bootstrapBinding.marketplaceIndexSha;
+          actionInput.ref = bootstrapBinding.marketplaceIndexRef;
+          actionInput.sourceDescriptor = {
+            ...actionInput.sourceDescriptor,
+            marketplaceCommitSha: bootstrapBinding.marketplaceIndexSha,
+            ref: bootstrapBinding.marketplaceIndexRef,
+          };
+        }
 
         // --- 安装契约摘要免验检查 ---
         // 从计划中读取冻结的安装契约摘要。
@@ -1614,6 +1775,7 @@ export async function verifyRelease(options) {
               actionType: action.type,
               status: VERIFICATION_RESOLVED_TYPES.NOT_REQUIRED_UNCHANGED,
               installationContractDigest: currentDigest,
+              ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
               reason: '安装契约摘要未变化，跳过验证',
             });
 
@@ -1634,6 +1796,7 @@ export async function verifyRelease(options) {
               actionType: action.type,
               status: VERIFICATION_RESOLVED_TYPES.NOT_REQUIRED_UNCHANGED,
               installationContractDigest: currentDigest,
+              ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
             });
 
             return;
@@ -1657,8 +1820,16 @@ export async function verifyRelease(options) {
         }
 
         // Step 3c: Verify (observe + match against plan expected state)
+        const expectedInput = bootstrapBinding
+          ? {
+            ...action.expected,
+            marketplaceCommitSha: bootstrapBinding.marketplaceIndexSha,
+            marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha,
+            ref: bootstrapBinding.marketplaceIndexRef,
+          }
+          : action.expected;
         const verifyResult = await adapter.verify(
-          { ...actionInput, expected: action.expected },
+          { ...actionInput, expected: expectedInput },
           marketplaceContext,
         );
 
@@ -1676,6 +1847,7 @@ export async function verifyRelease(options) {
           status: resolvedStatus,
           observation: verifyResult.observation,
           error: verifyResult.error,
+          ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
           ...(dist?.installationContractDigest ? { installationContractDigest: dist.installationContractDigest } : {}),
         };
         adapterChecks.push(check);
@@ -1700,6 +1872,7 @@ export async function verifyRelease(options) {
           actionId: action.id,
           actionType: action.type,
           status: check.status,
+          ...(bootstrapBinding ? { marketplaceIndexSha: bootstrapBinding.marketplaceIndexSha, marketplaceIndexRef: bootstrapBinding.marketplaceIndexRef } : {}),
         });
 
         if (check.status === 'FAILED') {