Merge branch 'main' into fix/qwen-hook-fallback-fail-closed

Author: josstei

.github/workflows/release.yml

@@ -139,7 +139,7 @@ jobs:
           fi
 
           TAG="v${PKG_VERSION}"
-          TAG_SHA=$(git rev-parse "$TAG^{commit}" 2>/dev/null || true)
+          TAG_SHA=$(git rev-parse --verify --quiet "$TAG^{commit}" 2>/dev/null || true)
           if [ -n "$TAG_SHA" ]; then
             if [ "$TAG_SHA" != "$TARGET_SHA" ]; then
               echo "::error::Tag $TAG exists at $TAG_SHA, not target commit $TARGET_SHA"
@@ -191,8 +191,8 @@ jobs:
             exit 1
           fi
 
-          if git rev-parse "$VERSION" >/dev/null 2>&1; then
-            EXISTING_SHA=$(git rev-parse "$VERSION^{commit}")
+          EXISTING_SHA=$(git rev-parse --verify --quiet "$VERSION^{commit}" 2>/dev/null || true)
+          if [ -n "$EXISTING_SHA" ]; then
             if [ "$EXISTING_SHA" = "$TARGET_SHA" ]; then
               echo "Tag $VERSION already exists at $EXISTING_SHA. Skipping."
               exit 0

CHANGELOG.md

@@ -15,10 +15,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **npm package identity**: renamed the planned npm package to `@josstei/maestro`, added `hello@josstei.dev` to public author metadata, and moved the stable release publish path toward GitHub Actions trusted publishing.
+- **npm package identity**: renamed the planned npm package to `@josstei/maestro`, added `hello@josstei.dev` to public author metadata, and moved the stable release publish path into GitHub Actions with npm token authentication.
 
 ### Fixed
 
+- **Stable npm release recovery**: Release now uses `NPM_TOKEN` for stable publishes, uses verified Git tag lookups, supports manual recovery from an existing `vX.Y.Z` tag and target SHA, and enforces a stable-only `latest` dist-tag through the idempotent npm publish helper. Prerelease publishes defer stale `latest` repair when no stable version exists instead of attempting to delete npm's `latest` tag.
 - **Codex plugin MCP server fails to start**: corrected `npx` args in `plugins/maestro/.mcp.json` — added `-p`/`--package` flag so `maestro-mcp-server` is resolved as the binary name rather than an argument to the package's default binary.
 - **Release metadata drift**: runtime manifests, marketplace entries, detached payload versions, and Codex MCP package specs are now generated from `package.json` so stable and prerelease packages stay self-consistent.
 

docs/cicd.md

@@ -655,4 +655,4 @@ The `RELEASE_TOKEN` used by Prepare Release is a personal access token with elev
 | `preview` | PR preview build | `X.Y.Z-preview.SHORT_SHA` | Preview Build |
 | `nightly` | Daily main snapshot | `X.Y.Z-nightly.YYYYMMDD` | Nightly Build |
 
-`latest` must never point at `rc`, `preview`, or `nightly`. If a prerelease publish or idempotent skip sees `latest` pointing to a prerelease, the helper repairs it by moving `latest` back to the highest published stable version or removing it when no stable exists.
+`latest` must never intentionally point at `rc`, `preview`, or `nightly`. If a prerelease publish or idempotent skip sees `latest` pointing to a prerelease and at least one stable version exists, the helper repairs it by moving `latest` back to the highest published stable version. If no stable version exists yet, the helper logs a warning and defers repair until the stable Release workflow publishes `X.Y.Z`; it does not delete `latest`.

scripts/npm-publish-idempotent.js

@@ -206,45 +206,79 @@ function validatePublishTag(pkg, tag) {
   }
 }
 
-function ensureLatestTagPolicy(pkg, runner) {
+function ensureLatestTagPolicy(pkg, runner, logger = console) {
   const tags = getDistTags(pkg.name, runner);
-  const latest = tags.latest;
+  const latest = tags.latest || null;
 
   if (isPrereleaseVersion(pkg.version)) {
     if (!latest || !isPrereleaseVersion(latest)) {
-      return;
+      return {
+        latest,
+        reason: latest
+          ? `latest already points to stable version ${latest}.`
+          : 'latest dist-tag is not set.',
+        status: 'ok',
+        target: null,
+      };
     }
 
     const stableVersion = highestStableVersion(getPublishedVersions(pkg.name, runner));
     if (stableVersion) {
       runner('npm', ['dist-tag', 'add', `${pkg.name}@${stableVersion}`, 'latest'], {
         stdio: 'inherit',
       });
-    } else {
-      runner('npm', ['dist-tag', 'rm', pkg.name, 'latest'], {
-        stdio: 'inherit',
-      });
+      logger.log(`Moved npm latest dist-tag from ${latest} to stable ${stableVersion}.`);
+      return {
+        latest,
+        reason: `latest pointed to prerelease ${latest}; moved it back to stable ${stableVersion}.`,
+        status: 'moved',
+        target: stableVersion,
+      };
     }
-    return;
+
+    const reason = `latest points to prerelease ${latest}, but no stable versions are published; stable release must move latest.`;
+    logger.warn(`Warning: ${reason}`);
+    return {
+      latest,
+      reason,
+      status: 'deferred',
+      target: null,
+    };
   }
 
   if (latest !== pkg.version) {
     runner('npm', ['dist-tag', 'add', `${pkg.name}@${pkg.version}`, 'latest'], {
       stdio: 'inherit',
     });
+    logger.log(`Moved npm latest dist-tag from ${latest || '<unset>'} to stable ${pkg.version}.`);
+    return {
+      latest,
+      reason: `latest pointed to ${latest || '<unset>'}; moved it to stable ${pkg.version}.`,
+      status: 'moved',
+      target: pkg.version,
+    };
   }
+
+  return {
+    latest,
+    reason: `latest already points to stable version ${pkg.version}.`,
+    status: 'ok',
+    target: pkg.version,
+  };
 }
 
 function publishIfNeeded(options = {}) {
   const root = options.root || ROOT;
   const runner = options.execFileSync || execFileSync;
+  const logger = options.logger || console;
   const pkg = readPackage(root);
   const packageSpec = `${pkg.name}@${pkg.version}`;
   validatePublishTag(pkg, options.tag);
 
   if (packageVersionExists(packageSpec, runner)) {
-    ensureLatestTagPolicy(pkg, runner);
+    const latestPolicy = ensureLatestTagPolicy(pkg, runner, logger);
     return {
+      latestPolicy,
       packageSpec,
       published: false,
     };
@@ -261,9 +295,10 @@ function publishIfNeeded(options = {}) {
     stdio: 'inherit',
   });
 
-  ensureLatestTagPolicy(pkg, runner);
+  const latestPolicy = ensureLatestTagPolicy(pkg, runner, logger);
 
   return {
+    latestPolicy,
     packageSpec,
     published: true,
   };

tests/unit/npm-publish-idempotent.test.js

@@ -38,6 +38,7 @@ describe('idempotent npm publish', () => {
     try {
       const result = publishIfNeeded({
         root,
+        logger: { log: () => {}, warn: () => {} },
         tag: 'rc',
         execFileSync: (cmd, args) => {
           calls.push([cmd, args]);
@@ -48,10 +49,9 @@ describe('idempotent npm publish', () => {
         },
       });
 
-      assert.deepEqual(result, {
-        packageSpec: '@josstei/maestro@1.2.3-rc.1',
-        published: false,
-      });
+      assert.equal(result.packageSpec, '@josstei/maestro@1.2.3-rc.1');
+      assert.equal(result.published, false);
+      assert.equal(result.latestPolicy.status, 'ok');
       assert.deepEqual(calls, [
         ['npm', ['view', '@josstei/maestro@1.2.3-rc.1', 'version']],
         ['npm', ['dist-tag', 'ls', '@josstei/maestro']],
@@ -68,6 +68,7 @@ describe('idempotent npm publish', () => {
     try {
       const result = publishIfNeeded({
         root,
+        logger: { log: () => {}, warn: () => {} },
         tag: 'preview',
         access: 'public',
         execFileSync: (cmd, args) => {
@@ -82,10 +83,9 @@ describe('idempotent npm publish', () => {
         },
       });
 
-      assert.deepEqual(result, {
-        packageSpec: '@josstei/maestro@1.2.3-preview.abcdef0',
-        published: true,
-      });
+      assert.equal(result.packageSpec, '@josstei/maestro@1.2.3-preview.abcdef0');
+      assert.equal(result.published, true);
+      assert.equal(result.latestPolicy.status, 'ok');
       assert.deepEqual(calls[1], ['npm', ['publish', '--tag', 'preview', '--access', 'public']]);
     } finally {
       fs.rmSync(root, { recursive: true, force: true });
@@ -99,6 +99,7 @@ describe('idempotent npm publish', () => {
     try {
       const result = publishIfNeeded({
         root,
+        logger: { log: () => {}, warn: () => {} },
         access: 'public',
         execFileSync: (cmd, args) => {
           calls.push([cmd, args]);
@@ -112,10 +113,11 @@ describe('idempotent npm publish', () => {
         },
       });
 
-      assert.deepEqual(result, {
-        packageSpec: '@josstei/maestro@1.2.3',
-        published: true,
-      });
+      assert.equal(result.packageSpec, '@josstei/maestro@1.2.3');
+      assert.equal(result.published, true);
+      assert.equal(result.latestPolicy.status, 'moved');
+      assert.equal(result.latestPolicy.latest, '1.2.2');
+      assert.equal(result.latestPolicy.target, '1.2.3');
       assert.deepEqual(calls[1], ['npm', ['publish', '--access', 'public']]);
       assert.deepEqual(calls.at(-1), [
         'npm',
@@ -126,6 +128,40 @@ describe('idempotent npm publish', () => {
     }
   });
 
+  it('moves latest from a prerelease to stable when stable already exists', () => {
+    const root = createPackageRoot('1.2.3');
+    const calls = [];
+
+    try {
+      const result = publishIfNeeded({
+        root,
+        logger: { log: () => {}, warn: () => {} },
+        execFileSync: (cmd, args) => {
+          calls.push([cmd, args]);
+          if (args[0] === 'view') {
+            return '1.2.3\n';
+          }
+          if (args[0] === 'dist-tag' && args[1] === 'ls') {
+            return 'latest: 1.2.4-rc.1\nrc: 1.2.4-rc.1\n';
+          }
+          return '';
+        },
+      });
+
+      assert.equal(result.packageSpec, '@josstei/maestro@1.2.3');
+      assert.equal(result.published, false);
+      assert.equal(result.latestPolicy.status, 'moved');
+      assert.equal(result.latestPolicy.latest, '1.2.4-rc.1');
+      assert.equal(result.latestPolicy.target, '1.2.3');
+      assert.deepEqual(calls.at(-1), [
+        'npm',
+        ['dist-tag', 'add', '@josstei/maestro@1.2.3', 'latest'],
+      ]);
+    } finally {
+      fs.rmSync(root, { recursive: true, force: true });
+    }
+  });
+
   it('rejects prerelease versions published without a prerelease tag', () => {
     const root = createPackageRoot('1.2.3-rc.1');
 
@@ -165,13 +201,15 @@ describe('idempotent npm publish', () => {
     }
   });
 
-  it('removes latest when it points to a prerelease and no stable exists', () => {
+  it('defers latest repair when it points to a prerelease and no stable exists', () => {
     const root = createPackageRoot('1.2.3-rc.1');
     const calls = [];
+    const warnings = [];
 
     try {
-      publishIfNeeded({
+      const result = publishIfNeeded({
         root,
+        logger: { log: () => {}, warn: (message) => warnings.push(message) },
         tag: 'rc',
         execFileSync: (cmd, args) => {
           calls.push([cmd, args]);
@@ -188,7 +226,15 @@ describe('idempotent npm publish', () => {
         },
       });
 
-      assert.deepEqual(calls.at(-1), ['npm', ['dist-tag', 'rm', '@josstei/maestro', 'latest']]);
+      assert.equal(result.latestPolicy.status, 'deferred');
+      assert.equal(result.latestPolicy.latest, '1.2.3-rc.1');
+      assert.equal(result.latestPolicy.target, null);
+      assert.match(result.latestPolicy.reason, /no stable versions are published/);
+      assert.match(warnings[0], /stable release must move latest/);
+      assert.equal(
+        calls.some(([, args]) => args[0] === 'dist-tag' && args[1] === 'rm'),
+        false
+      );
     } finally {
       fs.rmSync(root, { recursive: true, force: true });
     }
@@ -199,8 +245,9 @@ describe('idempotent npm publish', () => {
     const calls = [];
 
     try {
-      publishIfNeeded({
+      const result = publishIfNeeded({
         root,
+        logger: { log: () => {}, warn: () => {} },
         tag: 'rc',
         execFileSync: (cmd, args) => {
           calls.push([cmd, args]);
@@ -217,6 +264,9 @@ describe('idempotent npm publish', () => {
         },
       });
 
+      assert.equal(result.latestPolicy.status, 'moved');
+      assert.equal(result.latestPolicy.latest, '1.3.0-rc.1');
+      assert.equal(result.latestPolicy.target, '1.2.0');
       assert.deepEqual(calls.at(-1), [
         'npm',
         ['dist-tag', 'add', '@josstei/maestro@1.2.0', 'latest'],
@@ -263,4 +313,14 @@ describe('idempotent npm publish', () => {
     });
     assert.equal(highestStableVersion(['1.2.9', '1.10.0', '2.0.0-rc.1']), '1.10.0');
   });
+
+  it('does not remove latest through npm dist-tag policy', () => {
+    const source = fs.readFileSync(
+      path.resolve(__dirname, '..', '..', 'scripts', 'npm-publish-idempotent.js'),
+      'utf8'
+    );
+
+    assert.doesNotMatch(source, /dist-tag['"],\s*['"]rm/);
+    assert.doesNotMatch(source, /dist-tag rm/);
+  });
 });

tests/unit/workflow-security.test.js

@@ -103,6 +103,8 @@ describe('workflow shell security', () => {
     assert.match(content, /NPM_TOKEN: \$\{\{ secrets\.NPM_TOKEN \}\}/);
     assert.match(content, /NODE_AUTH_TOKEN: \$\{\{ env\.NPM_TOKEN \}\}/);
     assert.match(content, /NPM_TOKEN is required for stable release publishing/);
+    assert.match(content, /git rev-parse --verify --quiet "\$TAG\^\{commit\}"/);
+    assert.match(content, /git rev-parse --verify --quiet "\$VERSION\^\{commit\}"/);
     assert.match(content, /Manual release recovery requires existing tag \$TAG/);
     assert.match(content, /Tag \$TAG exists at \$TAG_SHA, not target commit \$TARGET_SHA/);
   });