release-skill 0.9.35 → 0.9.37

package/src/adapters/plugin-marketplace.mjs

@@ -823,6 +823,88 @@ export function normalizeCodeBuddySkillsRel(skillsRaw) {
   return rel;
 }
 
+/**
+ * Resolve a Codex entry skill using the plugin manifest at the actual plugin
+ * root. An omitted `skills` field keeps Codex's conventional `skills/` root;
+ * an explicit declaration is authoritative and must be valid and present.
+ *
+ * The short-name layout keeps priority over the plugin-prefixed layout, but
+ * fallback is allowed only when the short-name candidate is absent. Existing
+ * unsafe candidates are errors and cannot be hidden by a second layout.
+ *
+ * @param {string} pluginRoot - Real plugin root derived from source or install.
+ * @param {string} entrySkill - Frozen entry-skill id.
+ * @param {string} pluginName - Frozen plugin id used by the legacy prefix.
+ * @returns {Promise<string>} Absolute path to a regular, non-symlink SKILL.md.
+ */
+async function resolveCodexEntrySkillFile(pluginRoot, entrySkill, pluginName) {
+  const { normalizeGenericSkillsRel } = await import('../core/surface-host-bindings.mjs');
+  if (!entrySkill || typeof entrySkill !== 'string' || !SAFE_ID_RE.test(entrySkill)) {
+    throw new Error(`unsafe entrySkill: "${entrySkill}"`);
+  }
+
+  const platform = getPlatform('codex');
+  const manifestPath = await resolveContained(pluginRoot, platform.manifestPaths.plugin);
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Codex plugin manifest cannot be read: ${err.message}`);
+  }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    throw new Error('Codex plugin manifest must be an object');
+  }
+
+  const skillsRel = Object.hasOwn(manifest, 'skills')
+    ? normalizeGenericSkillsRel(manifest.skills)
+    : 'skills';
+  const skillsRoot = await resolveContained(pluginRoot, skillsRel);
+  let skillsRootStat;
+  try {
+    skillsRootStat = await lstat(skillsRoot);
+  } catch {
+    throw new Error(`Codex manifest skills root does not exist: ${manifest.skills ?? skillsRel}`);
+  }
+  if (skillsRootStat.isSymbolicLink() || !skillsRootStat.isDirectory()) {
+    throw new Error(`Codex manifest skills root must be a real directory: ${manifest.skills ?? skillsRel}`);
+  }
+
+  const findCandidate = async (skillDirName) => {
+    const skillDir = await resolveContained(pluginRoot, `${skillsRel}/${skillDirName}`);
+    let skillDirStat;
+    try {
+      skillDirStat = await lstat(skillDir);
+    } catch (err) {
+      if (err?.code === 'ENOENT') return null;
+      throw err;
+    }
+    if (skillDirStat.isSymbolicLink() || !skillDirStat.isDirectory()) {
+      throw new Error(`Codex entry skill directory must be a real directory: ${skillsRel}/${skillDirName}`);
+    }
+
+    const skillFile = await resolveContained(pluginRoot, `${skillsRel}/${skillDirName}/SKILL.md`);
+    let skillStat;
+    try {
+      skillStat = await lstat(skillFile);
+    } catch (err) {
+      if (err?.code === 'ENOENT') return null;
+      throw err;
+    }
+    if (skillStat.isSymbolicLink() || !skillStat.isFile()) {
+      throw new Error(`Codex entry skill must be a regular non-symlink file: ${skillsRel}/${skillDirName}/SKILL.md`);
+    }
+    return skillFile;
+  };
+
+  const shortNameEntry = await findCandidate(entrySkill);
+  if (shortNameEntry) return shortNameEntry;
+  if (pluginName && SAFE_ID_RE.test(pluginName)) {
+    const prefixedEntry = await findCandidate(`${pluginName}-${entrySkill}`);
+    if (prefixedEntry) return prefixedEntry;
+  }
+  throw new Error(`Codex entry skill not found: ${skillsRel}/${entrySkill}/SKILL.md`);
+}
+
 /**
  * CodeBuddy equivalent of resolveKimiEntrySkillFile (parallel implementation,
  * codebuddy wording; the kimi helper above is intentionally left untouched).
@@ -2110,8 +2192,8 @@ export function createPluginMarketplaceAdapter(deps = {}) {
           // snapshot, so the snapshot marketplace-manifest section is skipped
           // entirely. The plugin manifest is read directly from the snapshot
           // root and the frozen external identity fields are validated. ref was
-          // already injection-checked above (step 2); the entry skill reuses the
-          // automatable fixed layout validated below.
+          // already injection-checked above (step 2); Codex entry lookup reads
+          // the plugin manifest from this snapshot root.
           if (
             typeof action.marketplaceCommitSha !== 'string'
             || !/^[0-9a-f]{40}$/.test(action.marketplaceCommitSha)
@@ -2315,13 +2397,10 @@ export function createPluginMarketplaceAdapter(deps = {}) {
           }
           }
 
-          // Verify the entry skill exists in the snapshot.
-          // Structured-cli platforms' manifests always declare ./skills/, so the
-          // fixed skills/<entrySkill>/SKILL.md layout is authoritative for
-          // them. A human-attestation platform (kimi, codebuddy) resolves the
-          // entry skill via the manifest-declared skills root (MAJOR-4): the
-          // root is validated + realpath-contained, and omitted `skills` means
-          // the official single-skill root SKILL.md.
+          // Verify the entry skill exists in the snapshot. Kimi/CodeBuddy use
+          // their existing manifest-specific rules; Codex resolves its own
+          // manifest-declared skills root below. Claude keeps its established
+          // conventional skills/ lookup and prefixed fallback.
           if (platformRoute.route === 'human-attestation') {
             const resolveEntrySkillFile = consumer === 'codebuddy'
               ? resolveCodeBuddyEntrySkillFile
@@ -2335,6 +2414,17 @@ export function createPluginMarketplaceAdapter(deps = {}) {
                 error: `entry skill not resolvable in snapshot: ${entryErr.message}`,
               });
             }
+          } else if (consumer === 'codex') {
+            const pluginRootForSkill = pluginRootForEntrySkill || snapshotDirReal;
+            try {
+              await resolveCodexEntrySkillFile(pluginRootForSkill, action.entrySkill, action.plugin);
+            } catch (entryErr) {
+              return createResult({
+                actionType,
+                status: ActionStatus.PREFLIGHT_FAILED,
+                error: `entry skill not resolvable in snapshot: ${entryErr.message}`,
+              });
+            }
           } else {
             // Entry skill 相对插件根解析（嵌套布局时 pluginRoot != snapshotRoot）。
             // pluginRootForEntrySkill 在非 external 结构化 CLI 路径中已确定；
@@ -3735,48 +3825,67 @@ export function createPluginMarketplaceAdapter(deps = {}) {
           }
 
           // Verify entry skill exists as a regular file in install dir.
-          // Prefixed skill-directory fallback (0.5.1 entry-skill-prefix fix):
-          // mirror the preflight resolution — `skills/<entrySkill>` first,
-          // then `skills/<plugin>-<entrySkill>` when the plugin is known.
-          let entrySkillPath = resolve(installPath, 'skills', action.entrySkill, 'SKILL.md');
-          let entrySkillFound = false;
-          try {
-            const skillStat = await lstat(entrySkillPath);
-            if (skillStat.isFile() && !skillStat.isSymbolicLink()) {
-              entrySkillFound = true;
+          // Codex uses its actual installed plugin manifest for the skills
+          // root, keeping observation aligned with frozen-source preflight.
+          if (consumer === 'codex') {
+            try {
+              await resolveCodexEntrySkillFile(installPath, action.entrySkill, action.plugin);
+            } catch (entryErr) {
+              return createResult({
+                actionType,
+                status: ActionStatus.OBSERVED,
+                observation: {
+                  installed: true,
+                  installPath,
+                  entrySkillFound: false,
+                  error: `entry skill not resolvable in installed plugin: ${entryErr.message}`,
+                },
+              });
             }
-          } catch {
-            // entry skill not found in unprefixed layout
-          }
-          if (!entrySkillFound && action.plugin) {
-            const prefixedPath = resolve(
-              installPath,
-              'skills',
-              `${action.plugin}-${action.entrySkill}`,
-              'SKILL.md',
-            );
+          } else {
+            // Prefixed skill-directory fallback (0.5.1 entry-skill-prefix fix):
+            // mirror the preflight resolution — `skills/<entrySkill>` first,
+            // then `skills/<plugin>-<entrySkill>` when the plugin is known.
+            let entrySkillPath = resolve(installPath, 'skills', action.entrySkill, 'SKILL.md');
+            let entrySkillFound = false;
             try {
-              const skillStat = await lstat(prefixedPath);
+              const skillStat = await lstat(entrySkillPath);
               if (skillStat.isFile() && !skillStat.isSymbolicLink()) {
-                entrySkillPath = prefixedPath;
                 entrySkillFound = true;
               }
             } catch {
-              // both layouts miss; report below
+              // entry skill not found in unprefixed layout
             }
-          }
-
-          if (!entrySkillFound) {
-            return createResult({
-              actionType,
-              status: ActionStatus.OBSERVED,
-              observation: {
-                installed: true,
+            if (!entrySkillFound && action.plugin) {
+              const prefixedPath = resolve(
                 installPath,
-                entrySkillFound: false,
-                error: `entry skill not found: skills/${action.entrySkill}/SKILL.md`,
-              },
-            });
+                'skills',
+                `${action.plugin}-${action.entrySkill}`,
+                'SKILL.md',
+              );
+              try {
+                const skillStat = await lstat(prefixedPath);
+                if (skillStat.isFile() && !skillStat.isSymbolicLink()) {
+                  entrySkillPath = prefixedPath;
+                  entrySkillFound = true;
+                }
+              } catch {
+                // both layouts miss; report below
+              }
+            }
+
+            if (!entrySkillFound) {
+              return createResult({
+                actionType,
+                status: ActionStatus.OBSERVED,
+                observation: {
+                  installed: true,
+                  installPath,
+                  entrySkillFound: false,
+                  error: `entry skill not found: skills/${action.entrySkill}/SKILL.md`,
+                },
+              });
+            }
           }
 
           // Bind the installed payload back to the sealed authority while

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

@@ -846,7 +846,7 @@ async function observeQoderPlugin(target, command, env, run) {
   };
 }
 
-async function readQoderManifest(root, label) {
+async function readQoderManifest(root, label, target) {
   const candidates = [];
   for (const manifestPath of ['.qoder-plugin/plugin.json', '.claude-plugin/plugin.json']) {
     let text;
@@ -860,10 +860,11 @@ async function readQoderManifest(root, label) {
     if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
       throw new Error(`${label} (${manifestPath}) did not return an object`);
     }
+    await assertQoderPluginManifest(target, manifest, `${label} (${manifestPath})`, root);
     candidates.push({ manifestPath, manifest });
   }
   if (candidates.length === 0) throw new Error(`${label} has no native or compatible plugin manifest`);
-  if (candidates.length === 2 && ['name', 'version', 'skills'].some((field) => (
+  if (candidates.length === 2 && ['name', 'version'].some((field) => (
     candidates[0].manifest[field] !== candidates[1].manifest[field]
   ))) {
     throw new Error(`${label} does not match the frozen Qoder plugin identity and projection path: conflicting native and compatible manifests`);
@@ -894,31 +895,49 @@ async function assertFrozenQoderManifest(target, root) {
     snapshotPath: target.snapshotPath,
     expectedDigest: target.manifestDigest,
   });
-  const { manifestPath, manifest } = await readQoderManifest(snapshotRoot, 'frozen Qoder plugin manifest');
+  const { manifestPath, manifest } = await readQoderManifest(snapshotRoot, 'frozen Qoder plugin manifest', target);
   const skills = await assertQoderPluginManifest(target, manifest, 'frozen Qoder plugin manifest', snapshotRoot);
   return { manifestPath, skills };
 }
 
 async function assertQoderHubEntry(target, marketplaceRoot) {
-  const marketplace = parseJson(
-    await readFileContained(marketplaceRoot, 'marketplace.json', { encoding: 'utf8' }),
-    'Qoder Hub marketplace manifest',
-  );
-  if (marketplace?.name !== target.marketplace || !Array.isArray(marketplace.plugins)) {
-    throw new Error('Qoder Hub marketplace manifest does not match the frozen marketplace');
-  }
-  const matches = marketplace.plugins.filter((entry) => entry?.name === target.plugin);
-  if (matches.length !== 1) {
-    throw new Error(`Qoder Hub marketplace manifest must contain exactly one ${target.plugin} entry`);
-  }
-  const source = matches[0]?.source;
-  if (
-    source?.source !== 'url'
-    || normalizeHubGitSource(source.url, target.hub.githubHost) !== target.pluginRepo
-    || source.sha !== target.pluginCommit
-  ) {
-    throw new Error('Qoder Hub entry does not match the frozen public source identity');
+  let found = false;
+  for (const indexPath of ['marketplace.json', '.claude-plugin/marketplace.json']) {
+    let text;
+    try {
+      text = await readFileContained(marketplaceRoot, indexPath, { encoding: 'utf8' });
+    } catch (error) {
+      if (error?.code === 'SFC2004' && error?.details?.kind === 'missing-resource') continue;
+      throw error;
+    }
+    found = true;
+    const marketplace = parseJson(text, `Qoder Hub marketplace manifest (${indexPath})`);
+    if (!marketplace || typeof marketplace !== 'object' || Array.isArray(marketplace)
+      || marketplace.name !== target.marketplace || !Array.isArray(marketplace.plugins)) {
+      throw new Error('Qoder Hub marketplace manifest does not match the frozen marketplace');
+    }
+    if (indexPath === '.claude-plugin/marketplace.json') {
+      if (target.hub.githubHost !== 'github.com' || typeof target.frozenTag !== 'string' || target.frozenTag.length === 0) {
+        throw new Error('Qoder compatible Hub entry requires a frozen GitHub tag identity');
+      }
+      await assertHubHostEntry({ ...target, host: 'claude', pluginTag: target.frozenTag, githubHost: target.hub.githubHost }, marketplaceRoot);
+      continue;
+    }
+    const matches = marketplace.plugins.filter((entry) => entry?.name === target.plugin);
+    if (matches.length !== 1) {
+      throw new Error(`Qoder Hub marketplace manifest must contain exactly one ${target.plugin} entry`);
+    }
+    const entry = matches[0];
+    const source = entry.source;
+    if (source?.source !== 'url'
+      || normalizeHubGitSource(source.url, target.hub.githubHost) !== target.pluginRepo
+      || source.sha !== target.pluginCommit
+      || (entry.version !== undefined && entry.version !== target.version)
+      || (source.ref !== undefined && (typeof target.frozenTag !== 'string' || source.ref !== target.frozenTag))) {
+      throw new Error('Qoder Hub entry does not match the frozen public source identity');
+    }
   }
+  if (!found) throw new Error('Qoder Hub has no native or compatible marketplace manifest');
 }
 
 async function verifyQoderInstalledPayload({
@@ -928,7 +947,7 @@ async function verifyQoderInstalledPayload({
   frozenManifest,
   verifyInstalledPayload,
 }) {
-  const { manifestPath, manifest } = await readQoderManifest(installPath, 'installed Qoder plugin manifest');
+  const { manifestPath, manifest } = await readQoderManifest(installPath, 'installed Qoder plugin manifest', target);
   if (manifestPath !== frozenManifest.manifestPath) {
     throw new Error('installed Qoder plugin manifest path differs from the frozen manifest selection');
   }

package/src/commands/verify.mjs

@@ -57,7 +57,7 @@ import {
   consumePublicSourceAuthorityReceipt,
   verifySourceAuthorityReceipt,
 } from '../core/source-authority.mjs';
-import { verifyFrozenFile } from '../snapshot/frozen.mjs';
+import { computeFrozenSnapshot, resolveFrozenPath, verifyFrozenFile } from '../snapshot/frozen.mjs';
 import {
   deriveBaselineAdvances,
   applyBaselineAdvances,
@@ -87,6 +87,7 @@ import {
   checkSkillResourceClosure,
   createSkillResourceClosureReceipt,
   evaluateConsumerSkillResourceClosureReceipts,
+  TRANSPORT_EXCLUSIONS,
 } from '../core/skill-resource-closure.mjs';
 import { deriveSurfaceHostBinding, pluginRootFromManifestRelativePath } from '../core/surface-host-bindings.mjs';
 import { isRemoteWriteAction, isMarketplaceAction } from '../core/checkpoints.mjs';
@@ -131,6 +132,61 @@ export const VERIFICATION_RESOLVED_TYPES = Object.freeze({
   NOT_REQUIRED_UNCHANGED: 'NOT_REQUIRED_UNCHANGED',
 });
 
+/** Ignore only write bits; retain type, size, content, and non-write mode bits. */
+const WRITE_BITS = 0o222;
+const PAYLOAD_CONFLICT_REPORT_CAP = 10;
+
+function transportIdentityEntries(entries) {
+  return entries.map(({ path, type, mode, size, contentDigest }) => ({
+    path,
+    type,
+    mode: mode & ~WRITE_BITS,
+    size,
+    contentDigest,
+  }));
+}
+
+function compareInstallToFrozenTransport(frozenEntries, installedEntries) {
+  const frozen = transportIdentityEntries(frozenEntries);
+  const installed = transportIdentityEntries(installedEntries);
+  const installedByPath = new Map(installed.map((entry) => [entry.path, entry]));
+  const conflicts = [];
+  for (const frozenEntry of frozen) {
+    const installedEntry = installedByPath.get(frozenEntry.path);
+    if (!installedEntry) {
+      conflicts.push(`missing: ${frozenEntry.path}`);
+      continue;
+    }
+    if (installedEntry.type !== frozenEntry.type) {
+      conflicts.push(`type mismatch: ${frozenEntry.path}`);
+    } else if (
+      installedEntry.size !== frozenEntry.size
+      || installedEntry.contentDigest !== frozenEntry.contentDigest
+    ) {
+      conflicts.push(`content mismatch: ${frozenEntry.path}`);
+    } else if (installedEntry.mode !== frozenEntry.mode) {
+      conflicts.push(`mode mismatch: ${frozenEntry.path}`);
+    }
+  }
+  const frozenPaths = new Set(frozen.map((entry) => entry.path));
+  for (const installedEntry of installed) {
+    if (!frozenPaths.has(installedEntry.path)) {
+      conflicts.push(`extra: ${installedEntry.path}`);
+    }
+  }
+  return conflicts;
+}
+
+function frozenSnapshotRelativePath(unit, actions, unitId) {
+  if (typeof unit?.frozenSnapshot?.path === 'string' && unit.frozenSnapshot.path.length > 0) {
+    return unit.frozenSnapshot.path;
+  }
+  const action = (actions ?? []).find((item) => item.unitId === unitId
+    && typeof item.parameters?.snapshotPath === 'string'
+    && item.parameters.snapshotPath.length > 0);
+  return action?.parameters?.snapshotPath ?? null;
+}
+
 /** Verify actionless Cursor distributions through their frozen host contract. */
 export async function verifyCursorHostDistributions({
   plan,
@@ -2265,25 +2321,75 @@ export async function verifyRelease(options) {
             );
           }
           // For single-plugin units (the root-surface distributions this
-          // design covers) the install payload IS the frozen snapshot, so the
-          // recomputed receipt must equal the frozen unit receipt field for
-          // field (checker version, input digest, surface/skill/reference/
-          // finding counts, receipt digest). Record-layer fields (preparedAt,
-          // exitCode) are carried from the frozen receipt — the same rule
-          // publish's recheck uses.
+          // design covers) the install payload IS the frozen snapshot.
+          // Frozen snapshot + original receipt stay on the strict prepare/
+          // publish rule. Install-versus-frozen comparison follows the
+          // existing transport policy (mode & ~0o222) so a sealed 0444
+          // tree may legally reappear as 0644 after marketplace extract.
           const pluginDistCount = (surface.unit?.distributions ?? [])
             .filter((d) => d.type !== 'npm').length;
           if (pluginDistCount === 1 && surface.frozenPluginRoot === '.') {
-            const observedReceipt = createSkillResourceClosureReceipt(closureResult, {
-              unitId: surface.unitId,
-              preparedAt: expectedUnitReceipt.preparedAt ?? null,
-              exitCode: expectedUnitReceipt.exitCode ?? 0,
-            });
-            assertSkillResourceClosureReceipt(
-              expectedUnitReceipt,
-              observedReceipt,
-              `unit "${surface.unitId}"`,
-            );
+            const frozenRel = frozenSnapshotRelativePath(surface.unit, actions, surface.unitId);
+            if (frozenRel) {
+              const frozenDir = await resolveFrozenPath(root, frozenRel, 'frozen snapshot path');
+              const frozenClosure = await checkSkillResourceClosure({
+                snapshotDir: frozenDir,
+                host: surface.host,
+                surfaceHostBindings: [{ surfaceId: surface.surfaceId, host: surface.host }],
+              });
+              const frozenReceipt = createSkillResourceClosureReceipt(frozenClosure, {
+                unitId: surface.unitId,
+                preparedAt: expectedUnitReceipt.preparedAt ?? null,
+                exitCode: expectedUnitReceipt.exitCode ?? 0,
+              });
+              assertSkillResourceClosureReceipt(
+                expectedUnitReceipt,
+                frozenReceipt,
+                `unit "${surface.unitId}"`,
+              );
+              const frozenSnap = await computeFrozenSnapshot(frozenDir, {
+                excludeRootEntries: TRANSPORT_EXCLUSIONS,
+              });
+              const installedSnap = await computeFrozenSnapshot(surface.installPath, {
+                excludeRootEntries: TRANSPORT_EXCLUSIONS,
+              });
+              const conflicts = compareInstallToFrozenTransport(
+                frozenSnap.entries,
+                installedSnap.entries,
+              );
+              await evidence.append({
+                phase: 'verify',
+                step: 'skill-resource-closure',
+                status: 'install-comparison',
+                unitId: surface.unitId,
+                frozenInputDigest: frozenSnap.digest,
+                installedInputDigest: installedSnap.digest,
+                frozenModes: frozenSnap.entries.map((entry) => ({ path: entry.path, mode: entry.mode })),
+                installedModes: installedSnap.entries.map((entry) => ({ path: entry.path, mode: entry.mode })),
+              });
+              if (conflicts.length > 0) {
+                const listed = conflicts.slice(0, PAYLOAD_CONFLICT_REPORT_CAP).join('; ');
+                const overflow = conflicts.length > PAYLOAD_CONFLICT_REPORT_CAP
+                  ? `; and ${conflicts.length - PAYLOAD_CONFLICT_REPORT_CAP} more conflicting path(s)`
+                  : '';
+                throw new ReleaseError(
+                  POST_PUBLISH_VERIFY_FAILED,
+                  `installed plugin root differs in path, bytes, size, or non-write mode bits for unit "${surface.unitId}": ${listed}${overflow}`,
+                  { unitId: surface.unitId, conflicts },
+                );
+              }
+            } else {
+              const observedReceipt = createSkillResourceClosureReceipt(closureResult, {
+                unitId: surface.unitId,
+                preparedAt: expectedUnitReceipt.preparedAt ?? null,
+                exitCode: expectedUnitReceipt.exitCode ?? 0,
+              });
+              assertSkillResourceClosureReceipt(
+                expectedUnitReceipt,
+                observedReceipt,
+                `unit "${surface.unitId}"`,
+              );
+            }
           }
         }
         skillResourceClosureReceipts.push(createSkillResourceClosureReceipt(

package/src/core/skill-resource-closure.mjs

@@ -51,7 +51,7 @@ const GLOB_PATTERN = /[*?\[]/u;
 // the token was extracted. A prose marker elsewhere on the line exempts
 // nothing (fail-closed over a line-wide false pass).
 const SOURCE_ONLY_MARKER = /(?:\bsource-only\b|仅源码包)/iu;
-const TRANSPORT_EXCLUSIONS = Object.freeze([
+export const TRANSPORT_EXCLUSIONS = Object.freeze([
   '.git',
   'node_modules',
   '.in_use',