Decide: keep agent mode for every ecosystem, or limit it to Deno and --global installs

[mikolalysenko]

[agent] Filed by the scheduled architecture audit routine (CLI and core). Register: discussion #560 register.

Kind: decision. Source: review §5 ("Agent mode overall"), §6 owner question 2; register C55.

Question

v5 defaults to hosted mode. Agent mode (in-place patching of installed files: apply, repair, scan/get --mode agent) is now the largest source of open bugs per line of code. What is its scope from here on?

• A. Keep it for every ecosystem (status quo). Keep fixing layout bugs one at a time. Optionally follow review §2.2 and ask the package manager for install layouts (npm query, pnpm list --json, pip show -f, cargo metadata, …) instead of re-implementing them.
• B. Limit it to where nothing else works. Those places are Deno (agent is its only mode) and --global/--global-prefix installs (no project lockfile, so hosted and vendored refuse them). Inside a project that hosted or vendored supports, --mode agent warns for one minor and is then refused with a remedy that names --mode hosted|vendored. The engine stays, but per-ecosystem project-layout discovery stops growing.
• C. Keep it everywhere, but label it. Document agent mode in a project as "fallback" for the ecosystems whose docs already say "prefer vendored / hosted" (Maven, NuGet, Cargo), and close new layout bugs there as won't-fix with the remedy.

Recommendation: B. It keeps the two cases that really need agent mode and stops the open-ended layout work. Most of today's open agent-mode bugs are project-scope layouts that hosted or vendored already cover. The default change (get --save-only → agent) is user-visible, so this is a v5.x/v6 contract decision.

Evidence (main @ 9c43dfc)

Where agent mode is the only option:

• docs/ecosystems.md#L15-L25: every ecosystem except Deno has hosted ✅ and vendored ✅. Deno: "in place (the only mode for Deno)"; vendored refused; hosted not supported.
• Global installs: hosted and vendored act on a project's lockfiles, vendor under global scope is a usage error (global_scope_unsupported), and apply/scan --mode agent patch the global copies (CLI_CONTRACT.md#L129). The review didn't list this case.
• Go: agent mode is not in-place. It writes a replace to .socket/go-patches/, the same shape as vendored, so Go doesn't need it. The review's "Go local replace" case is covered by vendored. Paid hosted Go is refused with a vendored remedy.
• Agent mode is still a default in two places: get --save-only and get --global (CLI_CONTRACT.md#L23).

Footprint (production lines, split at #[cfg(test)]):

• CLI: commands/apply.rs 2,963 (2,237 at the review), fetch_stage.rs 437, repair.rs 785, plus the agent arms in scan, get, rollback and remove.
• Core, agent-only: patch/rollback.rs 751, patch/sidecars/ 1,107 (708 at the review; the Maven .sha1/.md5 rewriter arrived with Full Gradle support in agent, hosted and vendored modes #646), store_copies.rs 332, shared_store.rs 332, api/blob_fetcher.rs 603, patch/diff.rs 99.
• Core, shared with vendored: patch/apply.rs (1,230), patch/package.rs and manifest/, which vendored staging also uses. These stay under every option.

Bug load: about 29 of the 246 open bug issues are agent-mode-specific by title, roughly double the review's ~15. Almost all are project-scope install layouts that the crawlers re-implement:

• npm family: Agent mode misses an npm-aliased copy under install-strategy=linked (node_modules/.store/lp@…), so apply exits 0 with it unpatched and VEX attests not_affected #852, Agent mode misses transitive packages in Yarn's pnpm-linker store when pnpmStoreFolder moves it out of node_modules: skipped as package_not_installed, or refused as "first-party source" #859, Agent-mode scan packages/<member> finds nothing in a pnpm workspace (exit 0), while rollback packages/<member> selects the same packages #778, Agent-mode apply in a pnpm workspace reports each member-linked package twice, inflating the --json skipped count with duplicate already_patched events #633, With Bun's globalStore (Bun ≥ 1.3.14), agent mode patches and rolls back every other project sharing the store, and vex attests unpatched transitive copies as not_affected #635, Global agent mode on pnpm 12 (and 11 without the global virtual store) patches only one of the per-install copies of a package, reports success, and VEX attests not_affected #435, Agent-mode rollback and remove delete empty directories the package shipped when a patch added a file under them (regression from #846) #862, Agent-mode scan ignores socket.yml includePaths / ignorePaths (and the built-in tests/ default) for nested npm projects, patching every nested project's node_modules #554, A report-only scan -g tells you to run socket-patch scan --mode agent [PATHS] without -g, so following the hint scans the cwd project instead of the global install #464, With Bun's isolated linker, vex refuses every hosted patch as not_applied after the usual in-place bun install, because it checks orphaned node_modules/.bun registry entries that Bun never removes (regression from #496) #599;
• PyPI: With {data-dir} in Poetry's virtualenvs.path, agent mode also patches an unrelated activated VIRTUAL_ENV / conda env, even though poetry env use pins the project's env, and hosted VEX then refuses a correctly installed patch #866, Agent mode honours the Pipfile's [pipenv] venv_in_project = true for every Pipenv, but only 2026.2+ read it, so on Pipenv 2018–2026.1 the WORKON_HOME venv stays unpatched, the system Python is patched instead, and VEX attests not_affected #842, Agent-mode apply of a same-size PyPI patch in the same second as pip install leaves pip's __pycache__ bytecode valid, so Python keeps running the unpatched code while apply reports it patched #819, With Poetry virtualenvs.create = false, agent mode patches a stray ./venv (or ./.venv under in-project = false) instead of the system env Poetry installed into, and VEX attests not_affected #671, Agent-mode scan in a Pipenv project without a Pipenv venv patches the system Python's site-packages in place instead of the project's venv/ (regression from #388) #504, Agent-mode rollback in the other scope (rollback -g after a project apply, or rollback after a -g apply) deletes the manifest entry and blobs while the patched copy stays patched, and exits 0 #450;
• Cargo: Agent-mode cargo patches the unused registry copy of a crate the user overrides with [patch.crates-io], and VEX attests not_affected while the build links the user's unpatched fork #506, Agent-mode cargo rollback leaves a committed cargo vendor tree dirty: .cargo-checksum.json comes back pretty-printed instead of cargo's compact bytes #416, Agent-mode cargo apply/rollback has no effect on an already-built project: cargo reuses the cached rlib from target/, while apply reports success and VEX attests not_affected #387, Agent-mode cargo apply patches only the first of several registry/src index dirs (cargo 1.84 vs 1.85+ hashes), so one cargo keeps building the unpatched crate while apply and VEX report success #339, Agent-mode cargo apply patches the wrong copy when cargo vendor uses a custom directory (or apply runs from a workspace member), yet reports success and VEX attests not_affected #338;
• Go: Agent-mode Go rollback and remove after go mod tidy drop the replace but not restore the module's go.sum lines, so the next default go build fails with "missing go.sum entry" while rollback exits 0 with no warning #549, Agent-mode Go vex omits an applied patch for a +incompatible module (not_applied, exit 1) because it looks up the manifest with a literal "+" while the API key spells it %2B #484, Agent-mode Go apply writes a go-patches replace for a module version the build graph doesn't select, reports it applied, and on a go 1.16 go.mod apply --check and vex also report it as patched #392, Agent-mode Go vex attests not_affected after go get upgrades the patched module, although the go-patches replace no longer applies and the build links the unpatched code #391;
• NuGet: Since #446, scan -g --mode agent then rollback -g from a vendored NuGet project reverts the project's patched package in the shared global packages folder; the locked restore stays "up-to-date" and VEX keeps attesting #489, Agent-mode NuGet apply ignores nuget.config repositoryPath for packages.config projects and patches ~/.nuget/packages instead, reporting success #398, Agent-mode NuGet apply patches ~/.nuget/packages instead of the project's configured globalPackagesFolder / RestorePackagesPath, reports success, and VEX attests not_affected #397;
• Maven: scan/get --json drop the agent-mode apply failure: exit 1 with failed: 0, the patch shown as "added", and no error anywhere (e.g. a read-only global ~/.m2) #424.

Under B, the project-scope ones close with a "use --mode hosted|vendored" remedy. Under A, each needs its own fix.

What each option deletes

• A: nothing. §2.2's "ask the package manager" work adds a per-ecosystem probe layer (Crawler probes spawn gem, python and npm with no timeout, so a hung shim hangs scan forever #845's spawn deadline is its prerequisite).
• B: no engine code at first. The project-scope agent paths in apply/scan/get become a refusal, and later majors can delete the project-layout discovery that only agent mode uses: the pnpm/bun/vlt store fan-out, the venv-name hashing and the Cargo/NuGet cache-path resolution. Rough estimate: 3–5K production lines over time.
• C: none. Docs and triage policy only.

Constraints

• The contract makes --mode agent and get --save-only agent defaults v5.0 behavior, so B is a MAJOR (or a deprecation window in a minor).
• C24/Tracking: one agent-mode patch engine for apply and rollback #771 (one apply/rollback engine), Agent-mode apply and rollback reject a manifest hash in uppercase hex that blob download accepts as valid #707, Hash agent-mode jar members through the shared streaming zip comparator instead of buffering each member #914 and repair and scan --prune delete the beforeHash blobs of active patches, so a later offline rollback fails and tells the user to run repair #893 apply under every option.
• The C34 command-model decision (fix/undo/sync) assumes agent mode survives as sync. Under B, sync shrinks to global and Deno.

Acceptance

An owner picks A, B or C, and for B the deprecation window. The audit then files the mechanical follow-ups.

[mikolalysenko]

[agent] Triaged as priority:p3 (a cross-cutting contract decision). This needs an owner's call between A, B and C, so it stays agent:needs-human and the maintainer agent won't claim it.

---

Generated by Claude Code

[mikolalysenko]

We need to continue supporting agent mode for at least the time being. Don't get rid of it yet.

[mikolalysenko]

[agent] Decision: option A, keep agent mode for every ecosystem. This follows the maintainer's comment above.

What this means:

• --mode agent, apply, repair and agent-mode scan/get stay supported in projects and for --global/--global-prefix installs. No deprecation warning, no refusal and no removal window.
• get --save-only and get --global keep agent mode as their default.
• Open agent-mode layout bugs (npm family, PyPI, Cargo, Go, NuGet, Maven, listed in the issue body) stay open as normal bugs and get fixed one by one. None will be closed as won't-fix with a "use hosted/vendored" remedy.
• This decision does not adopt the §2.2 idea of asking the package manager for install layouts (npm query, pip show -f, cargo metadata, …). If it's wanted, it should be proposed separately.
• C34 (the command-model decision) can keep assuming agent mode survives in full as sync.
• This holds "for the time being". A later change of scope would be a new decision issue.

Docs check on main @ db83f014: nothing says agent mode is going away. The only "deprecated" wording in crates/socket-patch-cli/CLI_CONTRACT.md:97 is about the scan --apply spelling, not the mode. The "prefer hosted or vendored" notes in docs/ecosystems.md (NuGet at line 24, Gradle at line 502) are technical caveats about shared caches, and they stay. docs/migrating-to-v5.md:11 and :50 already describe --mode agent as the supported way to keep in-place patching.

No code or docs PR is needed. The register row C55 on discussion #560 will be marked decided (A). Closing as decided.

---

Generated by Claude Code