kandev/docs/plans/managed-runtime-pin-docs/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-09-11	complete	REQ-AGENTS-RUNTIME-UPDATES-001	../../specs/agents/system-design/runtime-updates-01.md

Implementation Plan: Remove duplicated runtime defaults

Overview

Replace current-version claims in three documents with links to the runtime catalogue. Preserve exact versions that identify historical experiments. One sequential work order completes this documentation repair.

Evidence and root cause

PR 3606 changes only apps/backend/internal/agent/agents/managed_npm_runtime_versions.json. Its review comment identifies stale defaults in three documents.

The updater writes the JSON catalogue. The workflow stages only that file. Separate prose and a table duplicate the current defaults without an update mechanism. Each version change can therefore leave those claims stale.

The read-only reproduction compares the PR catalogue with these claims:

• ACP_BRIDGE_VERSIONS.md lists six default versions and a concrete Claude launch example as current.
• ADR 0034 calls Codex 1.10.0 the current default.
• The timeout design calls Claude 0.75.1 the default at this commit. That same version also identifies the binary used in historical experiments.

Requirement conformance

The agents system owns the managed runtime catalogue and update lifecycle. REQ-AGENTS-RUNTIME-UPDATES-001 already defines exact defaults (AC-AGENTS-RUNTIME-UPDATES-001.5) and the grouped maintenance PR (AC-AGENTS-RUNTIME-UPDATES-001.9). The implementation follows those criteria. This repair corrects descriptions of that implementation.

No new product requirement or ADR is necessary. The existing system design continues to describe the updater. The token decision continues to govern workflow authorization.

The related packages are managed-runtime-version-awareness and managed-runtime-pin-workflow-auth. This package does not reopen their runtime or workflow work orders or replace their recorded results.

Scope

In scope

• Link current defaults directly to the JSON catalogue in all three documents.
• Preserve the agent names, package names, ACP arguments, and effective-version semantics.
• Identify the timeout experiments as historical evidence for their exact tested binary.

Out of scope

• Version bumps, runtime code, updater code, or workflow changes.
• Generated documentation tables or a general documentation scanner.
• New timeout experiments or changes to their recorded results.
• UI changes, browser tests, and public website documentation.
• Pushing, merging, rerunning PR 3606, or replying to its review thread during implementation.

Technical approach

In apps/backend/internal/agent/agents/ACP_BRIDGE_VERSIONS.md, remove the default-version column. Link to the adjacent JSON catalogue for current defaults. Use @<effective-version> in the Claude command example and explain that the placeholder represents the resolved exact version.

In docs/decisions/0034-agentclientprotocol-codex-acp.md, replace the numeric current-default claim with a relative catalogue link. Preserve the decision, package identity, and operator-selection semantics.

In docs/specs/agents/system-design/mcp-timeout-budgets.md, keep 0.75.1, 0.3.257, the binary path, and the experiment results. Remove the claim that the experiment version is the current default. Link current defaults to the catalogue and state that the evidence concerns the tested version.

The workflow requires no change. After this repair reaches main, its next run starts from documentation that does not duplicate current version values. A fix applied only to the automation branch can disappear because the workflow recreates that branch from origin/main.

Tests

The regression check is the current-default documentation audit in Task 01. Before the correction, it finds the three current-version claims. After the correction, those claims are absent and all three catalogue links resolve. This documentation-only repair uses direct inspection instead of permanent tests that assert prose wording.

Existing updater fixtures cover changed and unchanged catalogues for AC-AGENTS-RUNTIME-UPDATES-001.9. The existing workflow contract suite covers the grouped PR and validation sequence. These checks supplement the document audit without changing their test files.

No E2E test is necessary because runtime and rendered UI behavior do not change.

Work orders

• Task 01: Remove duplicated runtime defaults

Verification results

Package and implementation validation on 2026-09-11:

• python3 scripts/lint-spec-files.py --all: passed.
• node --test scripts/update-agent-runtime-pins.test.mjs: 7 tests passed.
• python3 .github/scripts/update-agent-runtime-pins-workflow-contract_test.py: 9 tests passed.
• The current-default documentation audit passed after the three corrections.
• All three catalogue links resolve to apps/backend/internal/agent/agents/managed_npm_runtime_versions.json.
• make -C apps/backend build: passed. The build reported non-fatal missing codesign/rcodesign warnings for Darwin artifacts.
• git diff --check: passed.
• git status --short: contains only the three target documents and this plan package.
• Requirement IDs, acceptance IDs, and the system-design path exist.

Risks

• A broad version replacement can falsely imply that newer runtimes passed old experiments.
• Relative links must resolve from each document, including the deeply nested timeout design.
• This repair removes the known recurring cause. It cannot guarantee that future reviews contain no other findings.