release-skill 0.1.4 → 0.1.5

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.4",
+      "version": "0.1.5",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.1.4.",
+      "Prepare a release plan for version 0.1.5.",
       "Help me understand the release workflow."
     ]
   }

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to the `release-skill` plugin will be documented in this
 file. The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.1.5] - 2026-07-21
+
+### Added
+
+- **Explicit marketplace install timeout (`timeoutMs`)**: Claude and Codex
+  plugin marketplace distributions now accept an optional `timeoutMs` integer
+  field (range 30,000--900,000 ms; default 300,000 ms). The resolved value is
+  frozen into each marketplace install action's `parameters.timeoutMs` during
+  `prepare`, making it part of the plan digest, approval binding, and plan
+  integrity. The `plugin-marketplace` adapter's marketplace add, plugin install,
+  and plugin list commands all use the same frozen timeout, replacing the
+  previous hardcoded 30-second limit that caused `PARTIAL` failures on real
+  network installations requiring 40--105 seconds.
+- **Old plan backward compatibility**: plans created before v0.1.5 that lack
+  `parameters.timeoutMs` on marketplace install actions default to 300,000 ms,
+  so existing `PARTIAL` runs can be reconciled without upgrading the plan.
+
+### Fixed
+
+- **Marketplace consumer install timeout**: v0.1.4 production releases hit
+  `PARTIAL` because Claude Code and Codex plugin marketplace add commands
+  required 40--105 seconds on real networks, while the adapter hardcoded a
+  30-second subprocess timeout. The timeout is now explicitly configurable per
+  distribution and verified through injected-executor tests. Invalid values
+  (non-integer, non-finite, out-of-range) fail closed rather than being
+  silently clamped.
+
 ## [0.1.4] - 2026-07-19
 
 ### Added

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.1.4 -->
+<!-- release-skill:release-version: 0.1.5 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later

package/INSTALL.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.1.4 -->
+<!-- release-skill:release-version: 0.1.5 -->
 ## 前置条件
 
 - Node.js 22.0.0 或更高版本

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.zh-CN.md) · Installation: [English](INSTALL.md) / [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.1.4 -->
+<!-- release-skill:release-version: 0.1.5 -->
 Release preparation for Claude Code and Codex, with human-edited files kept intact.
 
 release-skill helps a maintainer answer three questions: what will be released,
@@ -11,7 +11,7 @@ reviewed artifacts first and publishes those same artifacts later; it does not
 regenerate a README or re-pack the live workspace at the last step.
 
 <!-- release-skill:capability:external-write-boundary -->
-> **Current boundary:** v0.1.4 is the current release. v0.1.1 completed a real production release
+> **Current boundary:** v0.1.5 is the current release. v0.1.1 completed a real production release
 > to GitHub and npm — the first production-verified milestone — followed by
 > exact npm installation and Claude/Codex consumer installation verification
 > from the frozen Git ref; "current release" and "first production-verified
@@ -27,7 +27,7 @@ regenerate a README or re-pack the live workspace at the last step.
 > publish global preflight.
 
 <!-- release-skill:capability:safe-first-command -->
-> **Production path verified since the v0.1.1 milestone; v0.1.4 is the current
+> **Production path verified since the v0.1.1 milestone; v0.1.5 is the current
 > release.** The npm-installed CLI is the supported user entry. Source checkout
 > is the development/contributor fallback.
 >
@@ -626,10 +626,12 @@ releaseUnits:
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # optional; range 30000-900000; default 300000
       - type: codex-plugin
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # optional; range 30000-900000; default 300000
     publicFiles:
       - from: packages/plugin/.claude-plugin/plugin.json
         to: .claude-plugin/plugin.json
@@ -676,6 +678,14 @@ the entry Skill, and all required public files. A CLI smoke (`smokeBin`) is
 optional for plugin units and only applies when the published npm package
 exposes a CLI binary.
 
+Plugin distributions may declare `timeoutMs` (range 30,000--900,000 ms; default
+300,000 ms). This sets the subprocess timeout for the marketplace add, plugin
+install, and plugin list commands. On real networks these commands can take
+40--105 seconds; the default 300-second timeout avoids false `PARTIAL` failures.
+The resolved value is frozen into the plan and approved along with all other
+action parameters. Old plans without `timeoutMs` default to 300,000 ms at
+execution time for backward compatibility.
+
 ### PARTIAL recovery and reconcile
 
 When `publish` succeeds at some checkpoints but fails at others, the run enters

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.1.4 -->
+<!-- release-skill:release-version: 0.1.5 -->
 面向 Claude Code 和 Codex 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终
@@ -10,7 +10,7 @@ release-skill 帮助维护者回答三个问题：准备发布什么、还有哪
 最后一步重新生成 README、重新打包活动工作区或覆盖人工内容。
 
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** v0.1.4 是当前发布版本。v0.1.1 已完成 GitHub 与 npm 的
+> **当前边界：** v0.1.5 是当前发布版本。v0.1.1 已完成 GitHub 与 npm 的
 > 真实生产发布，是首次生产验证的历史里程碑，并从冻结 Git ref 完成精确 npm
 > 安装及 Claude/Codex 消费者安装验证；“当前发布版本”与“首次生产验证里程碑”
 > 是两个不同的事实，不得混写成同一含义。同一工作流还通过了本地
@@ -22,7 +22,7 @@ release-skill 帮助维护者回答三个问题：准备发布什么、还有哪
 > 远端唯一性检查在 `publish` 全局预检执行。
 
 <!-- release-skill:capability:safe-first-command -->
-> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.4 是当前发布版本。**
+> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.5 是当前发布版本。**
 > npm 安装的 CLI 是受支持的用户入口；源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**
@@ -582,10 +582,12 @@ releaseUnits:
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # 可选；范围 30000–900000；默认 300000
       - type: codex-plugin
         plugin: my-plugin
         marketplace: my-plugin
         entrySkill: my-plugin-help
+        timeoutMs: 300000     # 可选；范围 30000–900000；默认 300000
     publicFiles:
       - from: packages/plugin/.claude-plugin/plugin.json
         to: .claude-plugin/plugin.json
@@ -631,6 +633,12 @@ releaseUnits:
 入口 Skill 和全部 required public files。CLI 冒烟（`smokeBin`）对插件单元
 是可选项，仅当发布包同时暴露 CLI 二进制时才适用。
 
+插件分发可声明 `timeoutMs`（范围 30,000–900,000 毫秒；默认 300,000 毫秒），
+用于设置 marketplace add、plugin install 和 plugin list 三条命令的子进程超时。
+真实网络下这些命令可能需要 40–105 秒；默认 300 秒超时避免误报 `PARTIAL`。
+解析后的值冻结到计划中，与其他动作参数一起接受批准。无 `timeoutMs` 的旧计划
+在执行时默认回退到 300,000 毫秒以保证向后兼容。
+
 ### PARTIAL 恢复与 reconcile
 
 当 `publish` 在部分检查点成功但在其他检查点失败时，运行进入 `PARTIAL`

package/adapters/claude/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.4",
+      "version": "0.1.5",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/adapters/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"

package/adapters/claude/bin/release-skill.bundle.mjs

@@ -19947,7 +19947,7 @@ async function writePlanImmutable(planPath, plan) {
   }
   return { planPath, planDigest };
 }
-function validatePlanActionCompleteness(plan) {
+function validatePlanActionCompleteness(plan, options = {}) {
   const failures = [];
   if (!plan || typeof plan !== "object") {
     return { passed: false, details: { failures: ["plan is null or not an object"], expectedCount: 0, actualCount: 0 } };
@@ -20254,6 +20254,26 @@ function validatePlanActionCompleteness(plan) {
           _checkRequired(action, "parameters.ref", action.parameters?.ref, expectedTag, unitId, failures);
           _checkRequired(action, "parameters.manifestDigest", action.parameters?.manifestDigest, frozen?.manifestDigest, unitId, failures);
         }
+        {
+          const raw = action.parameters?.timeoutMs;
+          if (raw === void 0) {
+            if (!options.legacyCompatibility) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs is missing, expected a valid timeout (30000-900000)`
+              );
+            }
+          } else {
+            if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw)) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be a finite integer, got: ${JSON.stringify(raw)}`
+              );
+            } else if (raw < 3e4 || raw > 9e5) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be between 30000 and 900000, got: ${raw}`
+              );
+            }
+          }
+        }
         _checkRequired(action, "expected.installed", action.expected?.installed, true, unitId, failures);
         _checkRequired(action, "expected.plugin", action.expected?.plugin, plugin, unitId, failures);
         _checkRequired(action, "expected.marketplace", action.expected?.marketplace, marketplace, unitId, failures);
@@ -20322,6 +20342,26 @@ function validatePlanActionCompleteness(plan) {
           _checkRequired(action, "parameters.ref", action.parameters?.ref, expectedTag, unitId, failures);
           _checkRequired(action, "parameters.manifestDigest", action.parameters?.manifestDigest, frozen?.manifestDigest, unitId, failures);
         }
+        {
+          const raw = action.parameters?.timeoutMs;
+          if (raw === void 0) {
+            if (!options.legacyCompatibility) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs is missing, expected a valid timeout (30000-900000)`
+              );
+            }
+          } else {
+            if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw)) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be a finite integer, got: ${JSON.stringify(raw)}`
+              );
+            } else if (raw < 3e4 || raw > 9e5) {
+              failures.push(
+                `unit "${unitId}", action "${action.id}": parameters.timeoutMs must be between 30000 and 900000, got: ${raw}`
+              );
+            }
+          }
+        }
         _checkRequired(action, "expected.installed", action.expected?.installed, true, unitId, failures);
         _checkRequired(action, "expected.plugin", action.expected?.plugin, plugin, unitId, failures);
         _checkRequired(action, "expected.marketplace", action.expected?.marketplace, marketplace, unitId, failures);
@@ -68159,6 +68199,7 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
       const claudeDist = (unit.distributions ?? []).find((d) => d.type === "claude-plugin");
       if (claudeDist) {
         const identity = marketplaceIdentity(claudeDist);
+        const claudeTimeoutMs = Number.isInteger(claudeDist.timeoutMs) ? claudeDist.timeoutMs : 3e5;
         actions.push({
           id: `claude-marketplace-install-${unit.id}`,
           type: "claude-marketplace-install",
@@ -68170,7 +68211,8 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
             marketplace: identity.marketplace,
             repo: unit.publicRepo,
             version,
-            entrySkill: identity.entrySkill
+            entrySkill: identity.entrySkill,
+            timeoutMs: claudeTimeoutMs
           },
           expected: {
             installed: true,
@@ -68185,6 +68227,7 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
       const codexDist = (unit.distributions ?? []).find((d) => d.type === "codex-plugin");
       if (codexDist) {
         const identity = marketplaceIdentity(codexDist);
+        const codexTimeoutMs = Number.isInteger(codexDist.timeoutMs) ? codexDist.timeoutMs : 3e5;
         actions.push({
           id: `codex-marketplace-install-${unit.id}`,
           type: "codex-marketplace-install",
@@ -68196,7 +68239,8 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
             marketplace: identity.marketplace,
             repo: unit.publicRepo,
             version,
-            entrySkill: identity.entrySkill
+            entrySkill: identity.entrySkill,
+            timeoutMs: codexTimeoutMs
           },
           expected: {
             installed: true,
@@ -68336,6 +68380,7 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
     const claudeDist = (unit.distributions ?? []).find((d) => d.type === "claude-plugin");
     if (claudeDist) {
       const identity = marketplaceIdentity(claudeDist);
+      const claudeTimeoutMs = Number.isInteger(claudeDist.timeoutMs) ? claudeDist.timeoutMs : 3e5;
       actions.push({
         id: `claude-marketplace-install-${unit.id}`,
         type: "claude-marketplace-install",
@@ -68350,7 +68395,8 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
           version: unitVersion,
           entrySkill: identity.entrySkill,
           snapshotPath: asset.snapshotPath,
-          manifestDigest: asset.manifestDigest
+          manifestDigest: asset.manifestDigest,
+          timeoutMs: claudeTimeoutMs
         },
         expected: {
           installed: true,
@@ -68370,6 +68416,7 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
     const codexDist = (unit.distributions ?? []).find((d) => d.type === "codex-plugin");
     if (codexDist) {
       const identity = marketplaceIdentity(codexDist);
+      const codexTimeoutMs = Number.isInteger(codexDist.timeoutMs) ? codexDist.timeoutMs : 3e5;
       actions.push({
         id: `codex-marketplace-install-${unit.id}`,
         type: "codex-marketplace-install",
@@ -68384,7 +68431,8 @@ function buildExternalActions(unitResults, resolvedVersions, productionAssets) {
           version: unitVersion,
           entrySkill: identity.entrySkill,
           snapshotPath: asset.snapshotPath,
-          manifestDigest: asset.manifestDigest
+          manifestDigest: asset.manifestDigest,
+          timeoutMs: codexTimeoutMs
         },
         expected: {
           installed: true,
@@ -69526,7 +69574,7 @@ async function reconcileRelease(options) {
     }
     await evidence.append({ phase: "safety-gate", gate: "plan-digest", status: "passed" });
     await evidence.append({ phase: "safety-gate", gate: "action-completeness", status: "started" });
-    const completenessResult = validatePlanActionCompleteness(plan);
+    const completenessResult = validatePlanActionCompleteness(plan, { legacyCompatibility: true });
     if (!completenessResult.passed) {
       await evidence.append({
         phase: "safety-gate",
@@ -71194,6 +71242,23 @@ function validateMarketplaceParams(params) {
   }
   return { valid: true, error: null };
 }
+function resolveTimeoutMs(action) {
+  const raw = action?.timeoutMs;
+  if (raw === void 0) {
+    return 3e5;
+  }
+  if (raw === null || typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw)) {
+    throw new Error(
+      `action.timeoutMs must be a finite integer, got: ${JSON.stringify(raw)}`
+    );
+  }
+  if (raw < 3e4 || raw > 9e5) {
+    throw new Error(
+      `action.timeoutMs must be between 30000 and 900000, got: ${raw}`
+    );
+  }
+  return raw;
+}
 async function run4(cmd, args2, options = {}) {
   return execFile9(cmd, args2, {
     shell: false,
@@ -71663,11 +71728,21 @@ function createPluginMarketplaceAdapter(deps = {}) {
             ...baseEnv,
             ...consumer === "claude" ? { HOME: isolatedHome, CLAUDE_CONFIG_DIR: resolve18(isolatedHome, ".claude") } : { HOME: isolatedHome, CODEX_HOME: isolatedHome }
           };
+          let frozenTimeoutMs;
+          try {
+            frozenTimeoutMs = resolveTimeoutMs(action);
+          } catch (timeoutErr) {
+            return createResult({
+              actionType,
+              status: ActionStatus.EXECUTE_FAILED,
+              error: timeoutErr.message
+            });
+          }
           const ref = action.ref ?? `v${action.version}`;
           let addOutput;
           const marketplaceArgs = consumer === "claude" ? ["plugin", "marketplace", "add", `${action.repo}@${ref}`] : ["plugin", "marketplace", "add", action.repo, "--ref", ref, "--json"];
           try {
-            const addResult = await exec(cliCmd, marketplaceArgs, { env, cwd: context.root });
+            const addResult = await exec(cliCmd, marketplaceArgs, { env, cwd: context.root, timeout: frozenTimeoutMs });
             if (consumer === "codex") {
               try {
                 addOutput = JSON.parse(addResult.stdout);
@@ -71703,7 +71778,7 @@ function createPluginMarketplaceAdapter(deps = {}) {
           let installOutput;
           const installArgs = consumer === "claude" ? ["plugin", "install", `${action.plugin}@${action.marketplace}`] : ["plugin", "add", `${action.plugin}@${action.marketplace}`, "--json"];
           try {
-            const installResult = await exec(cliCmd, installArgs, { env, cwd: context.root });
+            const installResult = await exec(cliCmd, installArgs, { env, cwd: context.root, timeout: frozenTimeoutMs });
             if (consumer === "codex") {
               try {
                 installOutput = JSON.parse(installResult.stdout);
@@ -71893,6 +71968,17 @@ function createPluginMarketplaceAdapter(deps = {}) {
             ...baseEnv,
             ...consumer === "claude" ? { HOME: isolatedHome, CLAUDE_CONFIG_DIR: resolve18(isolatedHome, ".claude") } : { HOME: isolatedHome, CODEX_HOME: isolatedHome }
           };
+          let frozenTimeoutMs;
+          try {
+            frozenTimeoutMs = resolveTimeoutMs(action);
+          } catch (timeoutErr) {
+            return createResult({
+              actionType,
+              status: ActionStatus.OBSERVED,
+              observation: { installed: false, error: timeoutErr.message },
+              error: timeoutErr.message
+            });
+          }
           let evidence = null;
           try {
             const evidenceRaw = await readFile16(resolve18(runDir, "evidence", `${consumer}-${action.plugin}`, "release-skill-install-evidence.json"), "utf8");
@@ -71920,7 +72006,7 @@ function createPluginMarketplaceAdapter(deps = {}) {
           const listArgs = consumer === "claude" ? ["plugin", "list", "--json"] : ["plugin", "list", "--json"];
           let listOutput;
           try {
-            const result = await exec(cliCmd, listArgs, { env, cwd: context.root });
+            const result = await exec(cliCmd, listArgs, { env, cwd: context.root, timeout: frozenTimeoutMs });
             listOutput = JSON.parse(result.stdout);
           } catch (listErr) {
             return createResult({
@@ -72248,6 +72334,7 @@ var init_plugin_marketplace = __esm({
     STRICT_SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
     __name(validateSafeRef, "validateSafeRef");
     __name(validateMarketplaceParams, "validateMarketplaceParams");
+    __name(resolveTimeoutMs, "resolveTimeoutMs");
     __name(run4, "run");
     __name(validateManifestFile, "validateManifestFile");
     __name(checkRequiredFiles, "checkRequiredFiles");
@@ -72668,7 +72755,7 @@ async function verifyRelease(options) {
       }
       validateApproval(plan, approval, { clock: clockFn, requireUnexpired: false });
     }
-    const completenessResult = validatePlanActionCompleteness(plan);
+    const completenessResult = validatePlanActionCompleteness(plan, { legacyCompatibility: true });
     if (!completenessResult.passed) {
       throw new ReleaseError(
         GATE_FAILED,

package/adapters/claude/schemas/release-project.schema.json

@@ -200,6 +200,12 @@
                 },
                 "smokeExpectedJson": {
                   "type": "object"
+                },
+                "timeoutMs": {
+                  "type": "integer",
+                  "minimum": 30000,
+                  "maximum": 900000,
+                  "description": "Timeout in milliseconds for plugin marketplace install commands. Only valid for claude-plugin and codex-plugin distributions."
                 }
               },
               "allOf": [
@@ -219,6 +225,23 @@
                     ]
                   }
                 },
+                {
+                  "if": {
+                    "required": [
+                      "timeoutMs"
+                    ]
+                  },
+                  "then": {
+                    "properties": {
+                      "type": {
+                        "enum": [
+                          "claude-plugin",
+                          "codex-plugin"
+                        ]
+                      }
+                    }
+                  }
+                },
                 {
                   "if": {
                     "properties": {

package/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.1.4.",
+      "Prepare a release plan for version 0.1.5.",
       "Help me understand the release workflow."
     ]
   }