release-skill 0.9.4 → 0.9.6

package/src/commands/post-release-local.mjs

@@ -1,4 +1,4 @@
-import { access } from 'node:fs/promises';
+import { access, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, relative } from 'node:path';
 
@@ -12,6 +12,8 @@ import {
 import { getPlatform } from '../platforms/registry.mjs';
 import { resolveCodeBuddyMarketplace } from '../platforms/codebuddy.mjs';
 import { verifyInstalledMarketplacePayload } from '../adapters/plugin-marketplace.mjs';
+import { normalizePostPublishView, postPublishActionId } from '../core/postpublish.mjs';
+import { loadRun, validateRunLineage } from '../core/run.mjs';
 
 const HOSTS_BY_ACTION = Object.freeze({
   'claude-marketplace-install': ['claude'],
@@ -34,6 +36,7 @@ const SAFE_ENV_KEYS = Object.freeze([
   'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'http_proxy', 'https_proxy', 'no_proxy',
   'SSL_CERT_FILE', 'SSL_CERT_DIR', 'NODE_EXTRA_CA_CERTS',
   'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'KIMI_CONFIG_DIR',
+  'CODEBUDDY_CONFIG_DIR', 'WORKBUDDY_CONFIG_DIR',
 ]);
 const CODEBUDDY_PLUGIN_LIST_ARGS = Object.freeze(['plugin', 'list', '--json']);
 const CODEBUDDY_MARKETPLACE_LIST_ARGS = Object.freeze(['plugin', 'marketplace', 'list']);
@@ -169,7 +172,27 @@ function assertExecutableTarget(target) {
   }
 }
 
-export function derivePostReleaseChecklist(plan) {
+function buildShipNextStep({ root, statePath, unitIds }) {
+  const argv = ['release-skill', 'ship'];
+  if (typeof root === 'string' && root.length > 0) argv.push('--root', root);
+  if (typeof statePath === 'string' && statePath.length > 0) argv.push('--state', statePath);
+  if (Array.isArray(unitIds) && unitIds.length > 0) {
+    for (const unitId of unitIds) argv.push('--unit', unitId);
+  }
+  return {
+    code: 'COMPLETE_POST_VERIFY',
+    message: 'Complete the postVerify phase with ship before running post-release.',
+    argv,
+  };
+}
+
+export function derivePostReleaseChecklist(plan, {
+  runPath,
+  root,
+  statePath,
+  unitIds,
+  postVerifyComplete = false,
+} = {}) {
   if (!plan || typeof plan !== 'object' || typeof plan.digest !== 'string') {
     throw new Error('a frozen release plan with digest is required');
   }
@@ -178,6 +201,9 @@ export function derivePostReleaseChecklist(plan) {
     !BRANCH_ACTION_INCLUDED.has(unit.productionConfig?.branchStrategy)
   ));
   const targets = pluginTargets(plan);
+  const hasPendingPostVerify = postVerifyHooks(plan).length > 0 && !postVerifyComplete && targets.length > 0;
+  const hasStatePath = typeof statePath === 'string' && statePath.length > 0;
+  const selectedUnitIds = Array.isArray(unitIds) ? unitIds : undefined;
   return {
     command: 'post-release',
     status: 'AWAITING_USER_DECISION',
@@ -193,14 +219,173 @@ export function derivePostReleaseChecklist(plan) {
       })),
     },
     localHostUpdate: {
-      promptRequired: targets.length > 0,
-      available: targets.length > 0,
+      promptRequired: targets.length > 0 && !hasPendingPostVerify,
+      available: targets.length > 0 && !hasPendingPostVerify,
+      ...(!hasPendingPostVerify && runPath ? { runPath } : {}),
+      ...(hasPendingPostVerify ? {
+        ...(hasStatePath ? { nextSteps: [buildShipNextStep({ root, statePath, unitIds: selectedUnitIds })] } : {}),
+      } : {}),
       hosts: [...new Set(targets.map((target) => target.host))].sort(),
       targets,
     },
   };
 }
 
+function postVerifyHooks(plan) {
+  if (plan?.planVersion === undefined) return [];
+  return normalizePostPublishView(plan).flatMap((declaration) => (
+    (declaration.hooks ?? [])
+      .filter((hook) => hook.phase === 'postVerify')
+      .map((hook) => ({
+        actionId: postPublishActionId({ planVersion: plan.planVersion, unitId: declaration.unitId, localId: hook.id }),
+        hook,
+        unitId: declaration.unitId,
+      }))
+  ));
+}
+
+function localFinishEvidenceError(message, { cause, root, statePath, unitIds } = {}) {
+  const error = new Error(`local host update evidence is not ready: ${message}; next step: obtain approval if required, then complete the postVerify phase with ship before rerunning post-release`);
+  error.code = 'LOCAL_FINISH_EVIDENCE_NOT_READY';
+  const hasStatePath = typeof statePath === 'string' && statePath.length > 0;
+  error.details = {
+    cause: {
+      code: cause?.code ?? 'LOCAL_FINISH_EVIDENCE_NOT_READY',
+      message: cause?.message ?? message,
+    },
+    ...(hasStatePath ? {
+      nextSteps: [buildShipNextStep({ root, statePath, unitIds })],
+    } : {}),
+  };
+  return error;
+}
+
+/**
+ * Validate the frozen run authority before allowing any local host command.
+ * This is the only exported entry that can perform local host writes.
+ */
+export async function updateLocalHostPlugins({
+  plan: _suppliedPlan,
+  planPath,
+  runPath,
+  runRecord: _suppliedRunRecord,
+  production: _suppliedProduction,
+  root = process.cwd(),
+  statePath,
+  unitIds,
+  ...options
+} = {}) {
+  if (!planPath || !runPath) {
+    throw localFinishEvidenceError(
+      'planPath and runPath are required before local host updates',
+      { root, statePath, unitIds },
+    );
+  }
+  let plan;
+  let runRecord;
+  try {
+    plan = JSON.parse(await readFile(planPath, 'utf8'));
+    runRecord = await loadRun(runPath, {
+      requireDigest: true,
+      authorityPlanPath: planPath,
+    });
+  } catch (cause) {
+    throw localFinishEvidenceError(cause.message, { cause, root, statePath, unitIds });
+  }
+  await assertLocalFinishRun({
+    plan,
+    planPath,
+    runPath,
+    runRecord,
+    production: Boolean(plan.production),
+    root,
+    statePath,
+    unitIds,
+  });
+  return updateLocalHostPluginsInternal({
+    plan,
+    root,
+    ...options,
+  });
+}
+
+/** Validate the explicit run supplied to local-finish before any host probe. */
+export async function assertLocalFinishRun({
+  plan,
+  planPath,
+  runPath,
+  runRecord,
+  production = false,
+  root,
+  statePath,
+  unitIds,
+} = {}) {
+  const hooks = postVerifyHooks(plan);
+  if (hooks.length === 0) {
+    try {
+      await validateRunLineage(runRecord, { plan, planPath, runPath, production });
+      assertVerifiedReleaseRun(plan, runRecord);
+    } catch (cause) {
+      throw localFinishEvidenceError(cause.message, { cause, root, statePath, unitIds, plan });
+    }
+    return { runPath, phase: 'verify' };
+  }
+  if (runRecord?.command !== 'postverify' || runRecord?.status !== 'DISTRIBUTED') {
+    throw localFinishEvidenceError('the plan declares postVerify hooks, so the supplied verify run cannot authorize local-finish', { root, statePath, unitIds, plan });
+  }
+  if (runRecord.planDigest !== plan?.digest) {
+    throw localFinishEvidenceError('postVerify run is not bound to the frozen plan', { root, statePath, unitIds, plan });
+  }
+  if (typeof runRecord.sourceRunPath !== 'string' || typeof runRecord.sourceRunId !== 'string' || typeof runRecord.sourceRunDigest !== 'string') {
+    throw localFinishEvidenceError('completed postVerify run has incomplete verify-run lineage', { root, statePath, unitIds, plan });
+  }
+  const checkpoints = Array.isArray(runRecord.checkpoints) ? runRecord.checkpoints : null;
+  const expectedIds = hooks.map(({ actionId }) => actionId);
+  const actualIds = checkpoints?.map((checkpoint) => checkpoint?.actionId) ?? [];
+  if (
+    !checkpoints
+    || actualIds.length !== expectedIds.length
+    || new Set(actualIds).size !== actualIds.length
+    || actualIds.some((id) => !expectedIds.includes(id))
+    || expectedIds.some((id) => !actualIds.includes(id))
+    || checkpoints.some((checkpoint) => (
+      checkpoint.actionType !== 'postpublish-hook'
+      || !['succeeded', 'NO_CHANGE'].includes(checkpoint.status)
+    ))
+  ) {
+    throw localFinishEvidenceError('postVerify checkpoints must match each declared hook exactly and be succeeded or NO_CHANGE', { root, statePath, unitIds, plan });
+  }
+  let sourceRun;
+  try {
+    sourceRun = await loadRun(runRecord.sourceRunPath, {
+      requireDigest: true,
+      authorityPlanPath: planPath,
+    });
+  } catch (cause) {
+    throw localFinishEvidenceError(cause.message, { cause, root, statePath, unitIds, plan });
+  }
+  if (
+    sourceRun.command !== 'verify'
+    || sourceRun.status !== 'VERIFIED'
+    || sourceRun.runId !== runRecord.sourceRunId
+    || sourceRun.runDigest !== runRecord.sourceRunDigest
+    || sourceRun.planDigest !== plan.digest
+  ) {
+    throw localFinishEvidenceError('postVerify lineage does not point to the same-plan VERIFIED run', { root, statePath, unitIds, plan });
+  }
+  try {
+    await validateRunLineage(sourceRun, {
+      plan,
+      planPath,
+      runPath: runRecord.sourceRunPath,
+      production,
+    });
+  } catch (cause) {
+    throw localFinishEvidenceError(cause.message, { cause, root, statePath, unitIds, plan });
+  }
+  return { runPath, sourceRunPath: runRecord.sourceRunPath, phase: 'postverify' };
+}
+
 export function unavailablePostReleaseChecklist(plan, error) {
   return {
     command: 'post-release',
@@ -232,7 +417,11 @@ function hostEnvironment(host, { kimiHome } = {}) {
   env.HOME ??= homedir();
   env.PATH ??= '/usr/bin:/bin';
   env.GIT_TERMINAL_PROMPT = '0';
-  if (host === 'workbuddy') env.CODEBUDDY_CONFIG_DIR = join(env.HOME, '.workbuddy');
+  if (host === 'codebuddy') env.CODEBUDDY_CONFIG_DIR = join(env.HOME, '.codebuddy');
+  if (host === 'workbuddy') {
+    env.CODEBUDDY_CONFIG_DIR = join(env.HOME, '.workbuddy');
+    env.WORKBUDDY_CONFIG_DIR = join(env.HOME, '.workbuddy');
+  }
   if (host === 'kimi' && kimiHome) env.KIMI_CONFIG_DIR = kimiHome;
   return env;
 }
@@ -286,12 +475,17 @@ async function commandAvailable(command, host, run) {
 }
 
 async function defaultDetect(host, run = defaultRun) {
-  if (host === 'codebuddy' || host === 'workbuddy') {
-    for (const command of ['codebuddy', 'cbc', CODEBUDDY_MACOS_PATH]) {
+  if (host === 'codebuddy') {
+    for (const command of ['codebuddy', 'cbc']) {
       if (await commandAvailable(command, host, run)) return { available: true, command };
     }
     return { available: false, reason: 'CodeBuddy/WorkBuddy CLI not found' };
   }
+  if (host === 'workbuddy') {
+    if (process.platform !== 'darwin') return { available: false, status: 'SKIPPED_UNSUPPORTED_PLATFORM', reason: 'WorkBuddy local update is supported only on macOS' };
+    if (await commandAvailable(CODEBUDDY_MACOS_PATH, host, run)) return { available: true, command: CODEBUDDY_MACOS_PATH };
+    return { available: false, reason: 'WorkBuddy embedded CLI not found' };
+  }
   if (host === 'kimi') {
     if (!await commandAvailable('kimi', host, run)) return { available: false, reason: 'kimi CLI not found' };
     try {
@@ -894,7 +1088,7 @@ function failedHostResult(target, error) {
   };
 }
 
-export async function updateLocalHostPlugins({
+async function updateLocalHostPluginsInternal({
   plan,
   root = process.cwd(),
   confirmPlanDigest,
@@ -905,7 +1099,7 @@ export async function updateLocalHostPlugins({
   verifyInstalledPayload = verifyInstalledMarketplacePayload,
 } = {}) {
   const effectiveKimiHome = kimiHome ?? process.env.KIMI_CONFIG_DIR ?? join(homedir(), '.kimi-code');
-  const checklist = derivePostReleaseChecklist(plan);
+  const checklist = derivePostReleaseChecklist(plan, { postVerifyComplete: true });
   if (confirmPlanDigest !== plan.digest) {
     throw new Error('plan digest confirmation does not match the frozen release plan');
   }
@@ -923,7 +1117,7 @@ export async function updateLocalHostPlugins({
         results.push({
           host: target.host,
           unitId: target.unitId,
-          status: 'SKIPPED_NOT_INSTALLED',
+          status: detected?.status ?? 'SKIPPED_NOT_INSTALLED',
           reason: detected?.reason ?? 'host unavailable',
         });
         continue;

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);
 }