[lucasbraum]

What happened

UpgradeBench v1, guardian/support-dotcom-components, fix typescript 5.9.3 → 6, Uptide 0.18.1. The PR also moved @guardian/ophan-tracker-js 2.8.3 → 3.1.0 and widened src/dotcom's peer range. Its stated reason was "@guardian/libs 33.0.0 pins @guardian/ophan-tracker-js 3.1.0".

The engine did this, not the agent. The bump is in Uptide's mechanical commit (chore: upgrade typescript to 6.0.3 with @guardian/ophan-tracker-js 3.1.0). The agent's commit touches only cdk/tsconfig.json. The reason text comes from check/companions.ts (agreeing()), built from registry manifests; no model output reaches report.companions (fix/run.ts:555 → :1416, fixed before any agent session).

Why the reason was misleading. The pin is real: @guardian/libs@33.0.0 lists @guardian/ophan-tracker-js: 3.1.0 under dependencies. The same manifest also lists it under peerDependencies as ^2.2.10, which 2.8.3 satisfies, and the lockfile already resolved libs' ophan to 2.8.3 through that peer. libs did not move: it stayed at 33.0.0. The planner still applied the pin of a package that wasn't changing.

Changes

1. A package that does not move drags nothing (check/companions.ts, commit 1)

• A group member decided at its installed version requires nothing new of the others: its pins are what the install already has.
• A pin that the same manifest also declares as a peer, satisfied by the installed version, moves nothing.
• A pin reason names the manifest field and the installed version: ai 7.0.9 pins @ai-sdk/provider 4.0.1 in its dependencies; installed 3.0.3.

2. A new major that a third package asks for is a blocker (check/companions.ts, commit 3)

A release-group member that would move to a new major with no migration pack moves only when the upgraded package itself asks for it:

• the upgraded package's manifest at the target pins the member;
• the member's manifest declares the upgraded package;
• the upgraded package's pack names it (companions).

If another moving member asks for it instead, it is listed under Blocked. The blocker names that package, the manifest field and the range: @guardian/libs 33.0.0 declares @guardian/ophan-tracker-js 3.1.0 in dependencies.

Where "asked for by the upgraded package" comes from: the move must come from agreeing() with the lead as host. Every path of agreeing() checks registry manifests:

Path	Manifest evidence
Pin	The lead's manifest at the target, dependencies[member], exact version
Release pair (react-dom)	The member's manifest at the lead's target version declares the lead, in dependencies or peerDependencies, at a range that accepts the target
Peer or range search	The member's manifest at the chosen version declares the lead at a range that accepts the target
Shared pin (@ai-sdk/openai)	The lead's manifest at the target pins @ai-sdk/provider 4.0.1, and the member's manifest pins the same exact version

The shared-pin path is the one indirect case: neither package declares the other. Two non-manifest paths are also exempt:

• @types/* follows the package it types: the @types/<pkg> name and the DefinitelyTyped major (check/types-release.ts). This is not manifest data; say if it should be refused too.
• The pack's releaseGroup is pack metadata.

react-dom with react, @ai-sdk/* with ai and @sentry/profiling-node with @sentry/node still move; their tests now also assert that nothing is blocked.

3. The agent cannot change dependencies (fix/dependency-edits.ts, guard and editRules in fix/sdk-agent.ts, commits 2 and 4)

The agent could edit a package.json whenever it was a task file (the sentry pack reports sites on package.json script lines), and editRules only checked which files changed. It could also Write a new package.json, lockfile or .pnpmfile.cjs.

• editRules diffs every changed package.json against the commit before the session. These are refused:

  • a version or range change, or a removal, of any existing dependency in dependencies, devDependencies, peerDependencies or optionalDependencies, including the upgraded package and its planned companions (the engine wrote those);
  • any edit to overrides, resolutions or pnpm.

  A rewrite to the same value is allowed. Engine-written pins and overrides, including UPT-125's peer overrides, are committed before the session, so they are never flagged.

• A refused task resets, as with the test-edit gate. The refusal names each package and goes into the next feedback round's prompt, including a refusal from the first pass. The existing 3-round limit bounds an agent that keeps retrying.

• Refused edits are recorded in report.json as llm.tasks[].outOfScopeDependencyEdits (file, field, name, before, after, reverted: true).

• A new dependency is kept. It is recorded as agentAddedDependencies and listed in the PR body under Added by the agent. It never blocks publication.

• guard refuses lockfiles (npm, pnpm, Yarn classic and Berry, Bun), .npmrc, .yarnrc, .yarnrc.yml, .pnpmfile.cjs, pnpm-workspace.yaml and new package.json files, before the edit happens.

Tests

• Guardian, every layer:
  • libs staying (with the peer, and with the pin alone): no companion;
  • libs moving: a blocker naming libs, dependencies and 3.1.0; the same plan with ophan named by the lead's pack moves it;
  • the agent's bump and the nested peer widening: refused, reverted and recorded, whatever reason the agent gives.
• Release pairs still move: react → react-dom, ai → @ai-sdk/*, @sentry/node → @sentry/profiling-node, with no blocker.
• Upgraded package's range:
  • changed by the agent → refused;
  • rewritten identically → allowed.
• Added dependency: kept, recorded and listed. Removals and override edits are refused. Engine overrides, kept or reformatted, are not flagged.
• End to end through fix():
  • an agent that re-bumps every round is refused in all 3 rounds, and rounds 2 and 3 are told why;
  • a refusal in the first pass reaches round 1.
• Package-manager files: guard and editRules refuse each one.
• Mutation checks: each new branch was disabled in turn and its test failed: 4 for commit 1, 3 for the blocker rule, 11 for the gate, 2 for the corrected exemption.

Local, on main with UPT-125: core 2453 passed, CLI 538 passed, typecheck 3/3. Lint shows the same 2 warnings and 1 info as on main.

Known limitations

• Additions in feedback rounds (UPT-129): in verification feedback rounds no package.json is a task file, so an agent's new dependency is refused there. Additions are possible only in the first pass, when a manifest holds a site.
• run_tests (follow-up ticket): it runs repository test files related to the task, including ones the agent creates. A test file can run arbitrary code, so it could run the package manager.
• Naming a blocked companion on the command line: fix typescript @guardian/ophan-tracker-js does not lift the blocker yet. peer-preflight.ts plans without the command-line names and rejects a named package that is not a peer blocker. It was left untouched, as asked. The blocker's next step says to upgrade the package on its own first.

🤖 Generated with Claude Code

[tenki-reviewer]

Review complete. No blocking issues — approved ✅; 2 nitpicks below.

🧹 Nitpicks (2) — 🟢 2 low

• 🟢 Unescaped agent dependency fields in PR body (report.ts:1291) — The new "Added by the agent" section interpolates agent-controlled strings raw into PR markdown: d.after, d.file, and d.field are unquoted and a backtick inside d.name terminates the code span (packages/core/src/fix/report.ts:1291).
• 🟢 Package-manager gate misses Yarn PnP loader files (dependency-edits.ts:16) — packageManagerFile covers lockfiles, .npmrc/.yarnrc*, .pnpmfile.cjs and pnpm-workspace.yaml, but not Yarn Berry's .pnp.cjs/.pnp.js loaders or .yarn/ state such as .yarn/config.yml and .yarn/plugins/*.cjs (packages/core/src/fix/dependency-edits.ts:16).

---

This PR teaches the autonomous fix agent to propose dependency edits safely: package-manager manifests are gated, refused edits are reverted, and accepted edits are summarized for reviewers. Feedback rounds now seed the agent's prompt with the previous attempt when a task was both edited and rejected. Companion pinning gets a short-circuit when a same-manifest peer already satisfies the requested pin.

Files	Change
packages/core/src/fix/dependency-edits.ts (+tests)	New gate identifying package-manager files and classifying dependency edits as in/out of scope.
packages/core/src/fix/sdk-agent.ts	Wires the gate into editRules, reverting refused writes and recording them for reporting.
packages/core/src/fix/run.ts, fix/feedback.test.ts	Adds feedback rounds: previousAttempt propagation and refusal handling across rounds.
packages/core/src/fix/report.ts, fix/types.ts	New "Added by the agent" section listing accepted dependency edits in the PR body.
packages/core/src/check/companions.ts (+tests)	Suppresses EXACT pins when the same manifest declares a satisfied peer dependency.
.changeset/*	Changesets for the dependency-edit gate and companion-pin behavior.

_{Reviewed commit: 4a7f201}