release: align the repo version with the shipped 0.2.1 and guard future tags (#219)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

.github/workflows/release.yml

@@ -116,10 +116,31 @@ jobs:
       # message) and both standalone installers. The stamped installers then select the same immutable OSS/GitHub
       # release when run directly. BUILD_DATE is stamped alongside core with this run's UTC date.
       - name: Stamp release version
+        env:
+          # Referenced as a plain shell variable so the run block stays free of GitHub
+          # expressions: scripts/test-installer.sh replays this block verbatim as sh.
+          EVENT_NAME: ${{ github.event_name }}
         run: |
           TAG="${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}"
           V="${TAG#v}"
           printf '%s\n' "$TAG" | grep -Eq '^v[0-9A-Za-z][0-9A-Za-z._-]*$'
+          # Guard: release prep must bump the repo to the tag's version (root + packages/*/package.json
+          # and core's VERSION constant move together in the release: X.Y.Z PR). v0.2.1 was tagged with
+          # a 0.2.0 repo, so every dev/source build nagged about updates until the repo caught up —
+          # fail the tag push instead. Manual dispatch (EVENT_NAME unset in replays) only warns,
+          # keeping legacy tags rebuildable; installer-test fixtures have no package.json, so the
+          # check self-skips there.
+          if [ -f package.json ]; then
+            PKG_V="$(node -p 'require("./package.json").version')"
+            if [ "$PKG_V" != "$V" ]; then
+              MSG="tag $TAG does not match the repo version $PKG_V; bump root + packages/*/package.json and core VERSION during release prep, then re-tag (see CONTRIBUTING.md)."
+              if [ "${EVENT_NAME:-}" = "push" ]; then
+                echo "error: $MSG" >&2
+                exit 1
+              fi
+              echo "warning: $MSG (continuing: manual dispatch)" >&2
+            fi
+          fi
           grep -q 'export const VERSION = "' packages/core/src/index.ts
           sed -i "s/export const VERSION = \"[^\"]*\"/export const VERSION = \"$V\"/" packages/core/src/index.ts
           SH_MARKER='EMBEDDED_RELEASE_VERSION="__PENGUIN_RELEASE_VERSION__"'
@@ -506,9 +527,27 @@ jobs:
       # workspace:* dep to the dependency's current version, so the versions must match.
       # BUILD_DATE is stamped alongside VERSION with this run's UTC date (the repo keeps null for dev builds).
       - name: Stamp release version
+        env:
+          # Same shell-variable indirection as the release job's stamp step (no GitHub
+          # expressions in the body; see scripts/test-installer.sh).
+          EVENT_NAME: ${{ github.event_name }}
         run: |
           TAG="${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref_name }}"
           V="${TAG#v}"
+          # Same repo-version guard as the release job: both jobs start from a tag push in
+          # parallel, so the check must fail here too or npm would publish from a tag whose
+          # repo version was never bumped. Manual dispatch only warns (legacy-tag retries).
+          if [ -f package.json ]; then
+            PKG_V="$(node -p 'require("./package.json").version')"
+            if [ "$PKG_V" != "$V" ]; then
+              MSG="tag $TAG does not match the repo version $PKG_V; bump root + packages/*/package.json and core VERSION during release prep, then re-tag (see CONTRIBUTING.md)."
+              if [ "${EVENT_NAME:-}" = "push" ]; then
+                echo "error: $MSG" >&2
+                exit 1
+              fi
+              echo "warning: $MSG (continuing: manual dispatch)" >&2
+            fi
+          fi
           grep -q 'export const VERSION = "' packages/core/src/index.ts
           sed -i "s/export const VERSION = \"[^\"]*\"/export const VERSION = \"$V\"/" packages/core/src/index.ts
           D="$(date -u +%Y-%m-%d)"

CONTRIBUTING.md

@@ -109,6 +109,12 @@ pnpm test:e2e                                        # core live-model e2e, need
   before creating the tag** — the release workflow reads it from the tag's checkout, so a
   file added later never reaches the Release page. Without it the workflow falls back to
   GitHub's auto-generated notes.
+- **Release prep bumps the repo version**: the same `release: X.Y.Z` PR that renames
+  `changelog/unreleased/` also bumps the root and every `packages/*/package.json`
+  `version`, plus core's `VERSION` constant (`packages/core/src/index.ts`), to the release
+  version. The release workflow refuses a tag push whose version does not match the
+  repo's, so a forgotten bump fails before anything is published (v0.2.1 was tagged with a
+  0.2.0 repo, and every dev build nagged about an update until the repo caught up).
 - README assets under `assets/readme/` are generated — the benchmark charts from the
   landing benchmark data, and the demo screenshots via
   `node packages/landing/scripts/capture-readme-demo.mjs` (build first; needs Playwright

package.json

@@ -1,6 +1,6 @@
 {
   "name": "penguin-harness",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "description": "PenguinHarness \u2014 TypeScript AI Agent (SDK + CLI).",

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "PenguinHarness CLI: interactive REPL and single-task runner over @prismshadow/penguin-core.",
   "license": "Apache-2.0",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "PenguinHarness core SDK: context_engine, OmniMessage protocol, LLM/Environment interfaces.",
   "license": "Apache-2.0",

packages/core/src/index.ts

@@ -59,7 +59,7 @@ export { Agent, createAgent } from "./agent.js";
 export type { CreateAgentOptions, CreateSessionOptions, ResumeSessionOptions } from "./agent.js";
 
 /** SDK version number. */
-export const VERSION = "0.2.0";
+export const VERSION = "0.2.1";
 /** Release build date (UTC yyyy-mm-dd), stamped by the release workflow next to VERSION; null in a dev/source build. */
 export const BUILD_DATE: string | null = null;
 // Version-string helpers (shared by the CLI's `penguin update` and the server's update check).

packages/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-desktop",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "description": "PenguinHarness desktop app: Electron shell running @prismshadow/penguin-server as a utilityProcess, window on http://localhost (same-origin HTTP/SSE, no private IPC).",

packages/docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-docs",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "description": "PenguinHarness documentation site (React + Vite + Tailwind CSS): bilingual zh/en Markdown pages with light/dark themes and per-page Copy Markdown, deployed to GitHub Pages under /docs/ next to the landing page.",

packages/landing/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-landing",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "description": "PenguinHarness landing page (React + Vite + Tailwind CSS): multilingual, light/dark themes, benchmark showcase, and a local Markdown blog, deployed to GitHub Pages via GitHub Actions.",

packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "PenguinHarness web server: multi-user authentication and authorization, Session execution with SSE streaming, and usage accounting, built on @prismshadow/penguin-core.",
   "license": "Apache-2.0",

packages/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-skills",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "PenguinHarness skill library: built-in SKILL.md documents and skill groups, decoupled from core.",
   "license": "Apache-2.0",

packages/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismshadow/penguin-web",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "description": "PenguinHarness web frontend SPA: React + Vite + Tailwind CSS, rendering conversations streamed over the OmniMessage protocol, plus Agent configuration, model configuration, usage stats, and Traces.",