fix: pin mcp shim to matching core

CONTRIBUTING.md

@@ -98,13 +98,13 @@ Maintainers cut releases. Every bump touches 9 release surfaces in lockstep:
 2. `pnpm-lock.yaml` (resolved graph after the version bump)
 3. `plugin/.claude-plugin/plugin.json`
 4. `plugin/plugin.json`
-5. `packages/mcp/package.json` (self version; keep the source dependency as `workspace:~`)
+5. `packages/mcp/package.json` (self version; keep the source dependency as `workspace:*`)
 6. `src/version.ts` (extend the union, assign)
 7. `src/types.ts` (`ExportData.version` union)
 8. `src/functions/export-import.ts` (`supportedVersions` Set)
 9. `test/export-import.test.ts` (assertion)
 
-Then: `corepack pnpm install --lockfile-only --ignore-scripts`, package dry-runs, CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance. The MCP shim is packed and published with pnpm so `workspace:~` is rewritten to the npm consumer semver range.
+Then: `corepack pnpm install --lockfile-only --ignore-scripts`, package dry-runs, CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance. The MCP shim is packed and published with pnpm so `workspace:*` is rewritten to the exact matching npm dependency version.
 
 ## Security issues
 

deploy/helm/agentmemory/README.md

@@ -107,7 +107,7 @@ Upgrade by setting the new image tag:
 
 ```bash
 helm upgrade agentmemory deploy/helm/agentmemory \
-  --set image.tag=0.9.28
+  --set image.tag=<version>
 ```
 
 By default, Helm deletes chart-managed PVCs on uninstall. To keep memories after uninstalling the release, either use `persistence.existingClaim` or preserve the chart-created claim with a Helm resource-policy annotation:

docs/todos/2026-06-19-issue-267-pin-mcp-core-version/plan.md

@@ -0,0 +1,105 @@
+# Pin MCP Core Version Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Publish future `@agentmemory/mcp` packages with an exact dependency on the matching `@agentmemory/agentmemory` version.
+
+**Architecture:** Keep the MCP package as a pnpm workspace shim, but switch its source dependency from `workspace:~` to `workspace:*` so pnpm packs it as an exact dependency. Bump the coordinated current version to `0.9.28` because `0.9.27` is already published with bad npm metadata and the publish workflow correctly skips existing versions.
+
+**Tech Stack:** TypeScript, pnpm 11 workspace protocol, Vitest, npm package tarball inspection, GitHub Actions release workflow metadata.
+
+---
+
+## Files
+
+- Modify: `packages/mcp/package.json`
+- Modify: `pnpm-lock.yaml`
+- Modify: `package.json`
+- Modify: `src/version.ts`
+- Modify: `src/types.ts`
+- Modify: `src/functions/export-import.ts`
+- Modify: `test/export-import.test.ts`
+- Modify: `test/quality-gates.test.ts`
+- Modify: `test/plugin-surface-contract.test.ts`
+- Modify: plugin manifests with the current package version
+- Modify: OpenClaw manifests with the current package version
+- Modify: deploy Dockerfiles, Helm values/chart, managed-platform image references, deploy docs, `README.md`
+- Modify: `CONTRIBUTING.md`
+- Modify: `AGENTS.md`
+
+## Task 1: Write Failing Package Contract Tests
+
+- [ ] Change `test/quality-gates.test.ts` so the MCP dependency test expects `workspace:*` and names the exact-publish intent.
+- [ ] Change `test/plugin-surface-contract.test.ts` so the MCP package contract expects `workspace:*` and asserts the MCP package version equals root `package.json` version.
+- [ ] Run `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts`.
+- [ ] Expected RED: tests fail because current source still uses `workspace:~`; no implementation files changed yet.
+
+## Task 2: Implement Exact Workspace Dependency
+
+- [ ] Change `packages/mcp/package.json` dependency `@agentmemory/agentmemory` from `workspace:~` to `workspace:*`.
+- [ ] Run `corepack pnpm install --lockfile-only --ignore-scripts`.
+- [ ] Confirm `pnpm-lock.yaml` records `specifier: workspace:*` for `packages/mcp`.
+- [ ] Rerun `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts`.
+- [ ] Expected GREEN: package contract tests pass.
+
+## Task 3: Bump Coordinated Version To 0.9.28
+
+- [ ] Update root and MCP package versions to `0.9.28`.
+- [ ] Update `src/version.ts`, `src/types.ts`, `src/functions/export-import.ts`, and `test/export-import.test.ts` for current export version `0.9.28` while keeping older import versions supported.
+- [ ] Update plugin and OpenClaw current-version manifests that track the root version.
+- [ ] Update deploy image defaults, Helm app version/tag, and deploy docs from `0.9.27` to `0.9.28`.
+- [ ] Update `AGENTS.md` current stats heading from `v0.9.27` to `v0.9.28`.
+- [ ] Leave independently versioned packages alone: `integrations/filesystem-watcher/package.json`, `website/package.json`, and `plugin/opencode/plugin.json`.
+
+## Task 4: Update Release Process Docs
+
+- [ ] Update `CONTRIBUTING.md` so the release checklist says the MCP source dependency stays `workspace:*`.
+- [ ] Update the release-process explanation so pnpm publish rewrites `workspace:*` to an exact npm dependency.
+- [ ] Review `deploy/helm/agentmemory/README.md` so the upgrade example does not merely repeat the default image tag.
+
+## Task 5: Verify Package Metadata And Tests
+
+- [ ] Run focused tests:
+
+```bash
+corepack pnpm exec vitest run \
+  test/quality-gates.test.ts \
+  test/plugin-surface-contract.test.ts \
+  test/consistency.test.ts \
+  test/export-import.test.ts \
+  test/deploy-version-contract.test.ts \
+  test/copilot-plugin.test.ts \
+  test/codex-plugin.test.ts \
+  test/factory-plugin.test.ts
+```
+
+- [ ] Pack and inspect the MCP tarball:
+
+```bash
+PACK_DIR="$(mktemp -d)"
+corepack pnpm --dir packages/mcp pack --pack-destination "$PACK_DIR" --json
+tar -xOf "$PACK_DIR"/agentmemory-mcp-0.9.28.tgz package/package.json \
+  | jq -r '.version, .dependencies["@agentmemory/agentmemory"]'
+```
+
+- [ ] Expected pack output:
+
+```text
+0.9.28
+0.9.28
+```
+
+- [ ] Run `corepack pnpm test` if dependency setup allows it.
+
+## Task 6: Security And Handoff
+
+- [ ] Run `rg -n 'workspace:~|0\.9\.27|0\.9\.28'` over touched surfaces and classify remaining historical fixtures.
+- [ ] Run `git diff --check`.
+- [ ] Run `osv-scanner scan source .`.
+- [ ] Run `semgrep scan --config p/default --error --metrics=off .`.
+- [ ] Before any commit, stage only intended files and run `gitleaks protect --staged --redact`.
+- [ ] Update `docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md` with verification evidence, caveats, and final matrix status.
+
+## Approval Boundaries
+
+- Do not push, publish, create a PR, tag, deprecate npm packages, change npm dist-tags, deploy, merge, close the issue, or archive this thread without explicit current-turn approval.

docs/todos/2026-06-19-issue-267-pin-mcp-core-version/todo.md

@@ -0,0 +1,93 @@
+# Issue 267 Pin MCP Core Version
+
+## Scope
+
+- Worktree: `/Users/A1538552/.codex/worktrees/424b/agentmemory`
+- Branch: `issue/267-pin-mcp-core-version`
+- Base inspected: `eacce17e`
+- Remote target: `origin` (`https://github.com/wbugitlab1/agentmemory.git`)
+- Issue: GitHub issue #267, `@agentmemory/mcp does not pin the matching core version, allowing fixed MCP behavior to regress`
+
+## Sprint Contract
+
+- Goal: ensure every newly published `@agentmemory/mcp@X.Y.Z` depends on exactly `@agentmemory/agentmemory@X.Y.Z`.
+- Scope: MCP shim package metadata, lockfile importer, version-aligned release surfaces for the next patch release, tests, and release-process docs that describe the MCP dependency rewrite.
+- Non-goals: no publishing, push, PR creation, tag, npm deprecation, dist-tag change, deployment, or remote project/account state change.
+- Acceptance criteria:
+  - `packages/mcp/package.json` uses `workspace:*` for `@agentmemory/agentmemory`.
+  - Packed MCP package metadata rewrites that dependency to exact `0.9.28`.
+  - The coordinated current version is bumped from `0.9.27` to `0.9.28` on repo surfaces required by AGENTS.md and current tests.
+  - Tests guard exact MCP/core version alignment.
+  - Release docs no longer tell maintainers to keep `workspace:~`.
+- Intended verification:
+  - Focused Vitest contract/version tests.
+  - `corepack pnpm --dir packages/mcp pack --pack-destination ... --json` plus tarball manifest inspection.
+  - `corepack pnpm test` if dependencies are available.
+  - Required security scans for manifest/lockfile/config/instruction changes.
+- Known boundaries:
+  - Remote writes and credentialed GitHub/npm state changes require explicit current-turn approval.
+  - If chosen version `0.9.28` is already published, stop and choose the next unpublished patch only after recording evidence.
+  - Do not touch parent checkout or issue 821-830 worktrees.
+- Stop conditions:
+  - Any branch creation conflict, unexpected unrelated dirty files in task-owned paths, repeated verification failure without a diagnosed cause, or required scanner finding not accepted by the user.
+
+## Validity Evidence
+
+- Local source at start had `packages/mcp/package.json` dependency `"@agentmemory/agentmemory": "workspace:~"`.
+- Local tests `test/quality-gates.test.ts` and `test/plugin-surface-contract.test.ts` also expected `workspace:~`.
+- Public unauthenticated GitHub API confirmed issue #267 is open and describes `@agentmemory/mcp@0.9.22` depending on `~0.9.0`.
+- Public npm metadata check showed `npm view @agentmemory/mcp@0.9.27 dependencies --json` returns `{"@agentmemory/agentmemory":"~0.9.0"}`.
+- `.github/workflows/publish.yml` skips already-published MCP package versions, so a source-only fix at `0.9.27` would not repair npm consumers.
+
+## Arena Synthesis
+
+- Candidates: `/tmp/arena-issue267/candidate-1/strategy.md`, `/tmp/arena-issue267/candidate-2/strategy.md`, `/tmp/arena-issue267/candidate-3/strategy.md`.
+- Judge report: `/tmp/arena-issue267/judge.md`.
+- Base: Candidate 2.
+- Grafts:
+  - Candidate 3: explicit non-goal for npm deprecation and unrelated packages not to bump.
+  - Candidate 1: review Helm README examples so override text does not just repeat the new default image tag.
+- Rejected:
+  - Keeping `workspace:~`, because pnpm publishes it as a range.
+  - Literal source dependency on `0.9.28`, because local workspace installs should keep linking the local root package.
+  - Rewriting publish skip behavior, because npm package versions are immutable and the skip is correct.
+
+## Feature / Verification Matrix
+
+| Change | Verification method | Status | Evidence |
+| --- | --- | --- | --- |
+| Exact MCP/core dependency | Pack tarball manifest and focused package tests | Done | RED: focused tests failed on `workspace:~`; GREEN: `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts` passed after `workspace:*`. Pack tarball inspection printed `0.9.28` and dependency `0.9.28`. |
+| Coordinated version bump | Consistency/export/deploy/plugin tests and stale-string search | Done | `corepack pnpm exec vitest run test/quality-gates.test.ts test/plugin-surface-contract.test.ts test/consistency.test.ts test/export-import.test.ts test/deploy-version-contract.test.ts test/copilot-plugin.test.ts test/codex-plugin.test.ts test/factory-plugin.test.ts` passed: 8 files, 83 tests. Stale-string search found no active `workspace:~` or `0.9.27` in source/release surfaces; remaining `0.9.27` is backward-compatible export/import support or task evidence. |
+| Release-process docs | Read diff and search for `workspace:~` | Done | `CONTRIBUTING.md` now documents `workspace:*` and exact npm dependency rewrite; `deploy/helm/agentmemory/README.md` upgrade example now uses `<version>` instead of repeating the new default tag. |
+| Full repo behavior | `corepack pnpm test` or closest targeted substitute | Done | `corepack pnpm test` passed: 202 files, 2,797 tests. |
+| Security gates | OSV, Semgrep, staged Gitleaks before commit | Done | `git diff --check` passed. `osv-scanner scan source .` passed with the repo's existing GHSA-8988-4f7v-96qf waiver applied and no unfiltered issues. `semgrep scan --config p/default --error --metrics=off .` passed with 0 findings. `gitleaks protect --staged --redact` passed with no leaks found. |
+
+## Subagent Ledger
+
+| Workstream | Scope | Edits allowed | Expected output | Result | Residual risk |
+| --- | --- | --- | --- | --- | --- |
+| Arena candidate 1 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-1/strategy.md` | Recommended `workspace:*` plus `0.9.28` | Missed some plugin surfaces |
+| Arena candidate 2 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-2/strategy.md` | Chosen base; included `CONTRIBUTING.md` | Broader verification than minimum |
+| Arena candidate 3 | Strategy for issue #267 | No repo edits | `/tmp/arena-issue267/candidate-3/strategy.md` | Strong scope/non-goals grafted | Missed `CONTRIBUTING.md` |
+| Arena judge | Score strategies | No repo edits | `/tmp/arena-issue267/judge.md` | Candidate 2 base, grafts from 1 and 3 | None known |
+| Final security review | Security and supply-chain diff review | No repo edits | ACCEPT or High/Medium findings | ACCEPT; no High/Medium findings | Did not rerun already-passed commands |
+| Final test coverage review | Test and verification evidence review | No repo edits | ACCEPT or High/Medium findings | Medium finding: task record still showed pending verification | Fixed in this task-record update |
+| Final maintainability review | Scope and release consistency review | No repo edits | ACCEPT or High/Medium findings | Medium finding duplicated task-record evidence gap | Fixed in this task-record update |
+
+## Progress
+
+- 2026-06-19: Created and switched to branch `issue/267-pin-mcp-core-version` from detached `eacce17e`.
+- 2026-06-19: Validated issue as still relevant for npm consumers using public issue metadata and public npm metadata.
+- 2026-06-19: Ran arena strategy phase and recorded synthesis.
+- 2026-06-19: Implemented `workspace:*` MCP dependency, `0.9.28` coordinated version bump, release-process docs, deploy/plugin/OpenClaw/version surfaces, and package contract tests.
+- 2026-06-19: Verification passed: focused RED/GREEN package tests, focused version/deploy/plugin suite, MCP tarball exact dependency inspection, full `corepack pnpm test`, `git diff --check`, OSV, and Semgrep.
+- 2026-06-19: Final review passed after task-record evidence gap was fixed. Security review accepted the diff; test coverage and maintainability reviewers found only this task-record update requirement.
+
+## Review Notes And Caveats
+
+- Dependency setup: first `corepack pnpm exec vitest ...` auto-install was blocked by pnpm ignored-build hardening. Per AGENTS.md, `corepack pnpm install --frozen-lockfile --ignore-scripts` was run and completed. It emitted the expected pre-build `packages/mcp` bin-link warning for missing `dist/cli.mjs`.
+- OSV: the repository's existing `osv-scanner.toml` filtered GHSA-8988-4f7v-96qf for the known transitive `iii-sdk@0.11.2` OpenTelemetry 1.x issue; no unfiltered issues were found.
+- `website/lib/generated-meta.json` still reports `0.9.27`; maintainability review inspected it and did not classify it as a blocking finding because website scripts regenerate metadata during normal website dev/build. It is outside this issue-scoped release-package fix.
+- Staged Gitleaks passed after staging the intended issue-owned files.
+- Remote writes, issue closure, PR creation, PR merge, npm publish/deprecation, tags, deployment, and thread archival have not been approved or performed.
+- Mandatory archival contract from parent triage: if this valid issue later reaches a PR merge request, the approval request must bundle PR merge into `origin/main` and archiving this Codex thread after successful merge. Only after a successful merge should `set_thread_archived({ archived: true })` be called for this current thread.

packages/mcp/package.json

@@ -29,7 +29,7 @@
   "homepage": "https://github.com/rohitg00/agentmemory#readme",
   "bugs": "https://github.com/rohitg00/agentmemory/issues",
   "dependencies": {
-    "@agentmemory/agentmemory": "workspace:~"
+    "@agentmemory/agentmemory": "workspace:*"
   },
   "publishConfig": {
     "access": "public",

test/plugin-surface-contract.test.ts

@@ -117,17 +117,20 @@ describe("Package and integration manifests", () => {
     const pkg = readJson<{
       name: string;
       type: string;
+      version: string;
       bin: Record<string, string>;
       files: string[];
       dependencies: Record<string, string>;
       publishConfig: { access: string; provenance: boolean };
     }>(join(repoRoot, "packages/mcp/package.json"));
+    const rootPkg = readJson<{ version: string }>(join(repoRoot, "package.json"));
 
     expect(pkg.name).toBe("@agentmemory/mcp");
+    expect(pkg.version).toBe(rootPkg.version);
     expect(pkg.type).toBe("module");
     expect(pkg.bin["agentmemory-mcp"]).toBe("./bin.mjs");
     expect(pkg.files).toEqual(expect.arrayContaining(["bin.mjs", "README.md", "LICENSE"]));
-    expect(pkg.dependencies["@agentmemory/agentmemory"]).toBe("workspace:~");
+    expect(pkg.dependencies["@agentmemory/agentmemory"]).toBe("workspace:*");
     expect(pkg.publishConfig).toMatchObject({ access: "public", provenance: true });
     expect(existsSync(join(repoRoot, "packages/mcp", pkg.bin["agentmemory-mcp"]))).toBe(true);
   });

test/quality-gates.test.ts

@@ -392,10 +392,10 @@ describe("root quality gates", () => {
     expect(readText("website/.gitignore")).not.toMatch(/^pnpm-lock\.yaml$/m);
   });
 
-  it("uses a pnpm workspace dependency for the MCP shim source package", () => {
+  it("uses an exact pnpm workspace dependency for the MCP shim source package", () => {
     const mcp = JSON.parse(readText("packages/mcp/package.json")) as PackageJson;
 
-    expect(mcp.dependencies?.["@agentmemory/agentmemory"]).toBe("workspace:~");
+    expect(mcp.dependencies?.["@agentmemory/agentmemory"]).toBe("workspace:*");
   });
 
   it("keeps published Node engine guidance aligned with package manifests", () => {