fix(mcp): stop Sentry noise for unpublished HEAD on repo_open_session

[kentcdodds]

Summary

Sentry KODY issue 7642635997: repo_open_session threw a plain Error when Artifacts default-branch HEAD did not match published_commit.

That mismatch is expected after a git-lane push (package_get_git_remote) before package_publish_external_push or the reconcile cron lands. The production source-safety gate correctly refuses to open a session in that state; reporting it to Sentry made it look like a platform bug and tripped triage.

Change

• Keep the HEAD===published gate in RepoSession.openSession
• Detect the mismatch signature and rethrow as McpCallerError from repo_open_session (covers repo_run_commands too) with guidance to publish/reconcile first
• MCP observability already skips McpCallerError, so these stay on mcp-event logs only

Tests

• source-safety-policy helper coverage for mismatch detection
• repo_open_session maps the DO recovery message to McpCallerError

Not in this PR

Sibling 7642291485 (bundle artifact UNIQUE constraint after publish) is a different source/root cause and is left alone.

System recap — composes existing primitives (low risk)

Mode: recap · Base: main · Head: cursor/sentry-triage-kody-cloudflare-7642635997-fdfc

Classification: composes — keeps the existing source-safety gate; only reclassifies the unpublished-HEAD precondition as McpCallerError so Sentry skips it.

Primitives touched

Primitive	Group	Impact
capability-registry	assistant	composes — repo_open_session wraps HEAD mismatch as caller error
repo-sessions	runtime	composes — helpers to detect/message the mismatch signature

System map

Caller opens a repo session; when Artifacts HEAD is ahead of published_commit, the DO still refuses, but the capability returns McpCallerError so MCP observability does not open a Sentry issue.

Legend: green = composes (wiring only) · amber = extended by this PR · red = new primitive · gray = context (unchanged, included only when an edge crosses it).

flowchart LR
	capabilityRegistry["capability-registry<br/>Capability registry"]:::touched
	repoSessions["repo-sessions<br/>Repo sessions"]:::touched
	capabilityRegistry -->|"openSession RPC"| repoSessions
	repoSessions -->|"HEAD mismatch Error"| capabilityRegistry
	capabilityRegistry -->|"McpCallerError → skip Sentry"| capabilityRegistry
	classDef touched fill:#1a7f37,color:#fff
	classDef extended fill:#9a6700,color:#fff
	classDef added fill:#cf222e,color:#fff
	classDef untouched fill:#57606a,color:#fff

Loading

Change flow

sequenceDiagram
	participant Agent
	participant RepoOpen as repo_open_session
	participant DO as RepoSession DO
	participant Obs as MCP observability
	Agent->>RepoOpen: open package source
	RepoOpen->>DO: openSession
	DO-->>RepoOpen: HEAD ≠ published_commit Error
	RepoOpen-->>Agent: McpCallerError + publish guidance
	Note over Obs: isCallerFailure → no Sentry

Loading

  

Summary by CodeRabbit

• Bug Fixes
  • Improved error handling when the published commit differs from the current Artifacts repository head.
  • Users now receive clearer guidance to publish the current head or wait for reconciliation before retrying.
  • Unrelated session-opening errors continue to be reported unchanged.
• Tests
  • Added coverage for published commit mismatch detection and caller-facing error messages.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: dcf64ccc-8338-4495-b369-72010729189b

📥 Commits

Reviewing files that changed from the base of the PR and between 21ce87f and e2f73a2.

📒 Files selected for processing (4)

• packages/worker/src/mcp/capabilities/repo/repo-open-session.node.test.ts
• packages/worker/src/mcp/capabilities/repo/repo-open-session.ts
• packages/worker/src/repo/source-safety-policy.node.test.ts
• packages/worker/src/repo/source-safety-policy.ts

---

📝 Walkthrough

Walkthrough

The change detects published commit HEAD mismatches during repository session opening and converts them into caller-facing McpCallerError messages. Other errors remain unchanged, with tests covering classification, message construction, and capability behavior.

Changes

Published HEAD mismatch handling

Layer / File(s)	Summary
Mismatch classification and caller message packages/worker/src/repo/source-safety-policy.ts, packages/worker/src/repo/source-safety-policy.node.test.ts	Adds helpers to classify published HEAD mismatches and build retry instructions, with tests for matching and unrelated recovery messages.
Session-opening error translation packages/worker/src/mcp/capabilities/repo/repo-open-session.ts, packages/worker/src/mcp/capabilities/repo/repo-open-session.node.test.ts	Wraps session opening in error handling that maps published HEAD mismatches to McpCallerError while rethrowing other errors unchanged; capability tests verify the mapping and RPC invocation.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: handling unpublished HEAD mismatches in repo_open_session to avoid Sentry noise.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cursor/sentry-triage-kody-cloudflare-7642635997-fdfc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔎 Preview deployed: https://kody-pr-1059.kody-a99.workers.dev

Worker: kody-pr-1059
D1: kody-pr-1059-db
KV: kody-pr-1059-oauth-kv

Mocks:

• cloudflare: https://kody-pr-1059-mock-cloudflare.kody-a99.workers.dev/__mocks (kody-pr-1059-mock-cloudflare)