@event4u/agent-config 17.2.1 → 17.4.0

package/src/config/hook-bundle-budget.json

@@ -4,7 +4,7 @@
     "registered_at": "2026-10-01",
     "owner": "maintainer",
     "review_by": "2027-10-01",
-    "max_bytes": 1550500,
+    "max_bytes": 1554000,
     "max_bytes_derivation": "Measured 1,514,715 bytes on origin/main at 213d87055 (the gate's own reading, APFS-cloned node_modules so no worktree path artefacts). The ceiling is that reading plus ~2.3 % of headroom, rounded to 1,550,000, on the same doctrine as the 2026-10-01 registration: a bundle is rebuilt from source on every run, so an esbuild minor that renames symbols moves the figure by hundreds of bytes with no change to this tree, and a ceiling one byte above the reading would red on that. Composition is healthy at this reading and was checked rather than assumed: one YAML package (258,833 bytes) and 1,238,525 bytes of own source, so the growth is own code, not a re-entered dependency. The 1,564,211-byte pre-swap regression this roadmap closed still cannot reappear under it. RAISED to 1,550,500 on 2026-10-23 for the InstructionsLoaded binding (237 bytes against 51 of headroom); the reasoning and the measured alternative are the last `raise_log` entry, so this paragraph describes the 1,550,000 registration and the raise is recorded there rather than restated.",
     "shrink_only": true,
     "shrink_only_note": "A RAISE needs a recorded reason in `raise_log` below naming what was added and why it could not be avoided. Enforced since road-to-a-ratification-fence-that-follows-its-imports 3.2: the gate reads `max_bytes` at the base revision, and a working value above it fails unless `raise_log` gained an entry whose `to` equals the new value. A lowering needs no entry. This file is also on the ratification gate's watched set, so a raise carries a record as well as a log entry.",
@@ -14,8 +14,8 @@
             "from": 1500000,
             "to": 1550000,
             "by": "agent, during the inbox-2026-10 drain",
-            "what_was_added": "Nothing in this commit. The 1,500,000 ceiling was red on the very commit that registered it: measured 1,511,489 bytes at 22b19e520, which is the merge of the PR that introduced the budget. Its derivation read 1,469,738 bytes on the PR branch, whose base predated three PRs that had merged meanwhile \u2014 the failure-event binding of #2160 (sixteen concerns on a new slot), the touched-file quality pass of #2152, and the evidence classification of #2153 \u2014 and #2162 landed after it. The gate ran on each PR's pre-merge tree and never on the merge result, so every one of those PRs was green alone and the trunk was red the moment they were together.",
-            "why_it_could_not_be_avoided": "The bytes are deliberately merged capability, not an accident to trim: the composition check above shows one parser and no duplicate dependency, so there is nothing to remove that would not remove a feature. The alternative \u2014 reverting a merged lane to fit a ceiling derived against a base that no longer exists \u2014 would discard working code to satisfy a number that never described this tree.",
+            "what_was_added": "Nothing in this commit. The 1,500,000 ceiling was red on the very commit that registered it: measured 1,511,489 bytes at 22b19e520, which is the merge of the PR that introduced the budget. Its derivation read 1,469,738 bytes on the PR branch, whose base predated three PRs that had merged meanwhile — the failure-event binding of #2160 (sixteen concerns on a new slot), the touched-file quality pass of #2152, and the evidence classification of #2153 — and #2162 landed after it. The gate ran on each PR's pre-merge tree and never on the merge result, so every one of those PRs was green alone and the trunk was red the moment they were together.",
+            "why_it_could_not_be_avoided": "The bytes are deliberately merged capability, not an accident to trim: the composition check above shows one parser and no duplicate dependency, so there is nothing to remove that would not remove a feature. The alternative — reverting a merged lane to fit a ceiling derived against a base that no longer exists — would discard working code to satisfy a number that never described this tree.",
             "what_would_have_caught_it": "Measuring the ceiling against the merge result rather than the PR branch. A ceiling derived on a branch is a statement about that branch; the trunk is what the gate defends, and the two diverge exactly when several lanes land in one day."
         },
         {
@@ -36,6 +36,34 @@
             "what_was_added": "The `InstructionsLoaded` binding: one `LAZY_CONCERNS` row for the observer (its 11,097-byte body ships in its own chunk, never in this bundle) and the event name in the three vocabularies the bundle carries (dispatcher, collector, journal). Measured 1,550,186 bytes with the binding by the gate; the same esbuild invocation on the base and on this branch differs by 237 bytes, so the base sat at 1,549,949 — 51 bytes of headroom.",
             "why_it_could_not_be_avoided": "D8 (council, 2026-10-18) asked for room before a raise. Room was tried and measured: moving `session-eol` (27,708 B in-bundle, `stop` alone) into a chunk freed 29,948 B (same esbuild invocation, with and without the move) but produced a 259,330-byte chunk (`yaml` external) required on every `stop` — about 8.5 times the bytes that event parses today, to buy 186. The observer itself was already moved out. What remains in the bundle is the row and three event-name strings, which no chunk can carry.",
             "what_would_have_caught_it": "Nothing earlier: the base sat 51 bytes under the ceiling, so any new event in the vocabulary would have tripped it. Sized to this binding plus about 300 bytes; step 3.3's promotion is sized when it is built."
+        },
+        {
+            "date": "2026-10-24",
+            "from": 1550500,
+            "to": 1551000,
+            "by": "agent, feat/code-graph-auto-refresh (PR #2604) merged onto docs/inbox-2026-10-ac-roadmap (PR #2603) on the owner's instruction to target #2603",
+            "what_was_added": "One `LAZY_CONCERNS` row for the `code-graph-refresh` session concern (its 12,726-byte body ships in its own chunk). Each branch fit alone: #2603 measured 1,550,498 B, #2604 added 153 B to a base that sat 356 B under. Merged, the gate measured 1,550,617 B — 117 over. With the `provider_id` type check restored in validate.ts (the one #2603 had dropped for its last 2 bytes, asked for by both ratification seats of round 12) the final combined measurement is 1,550,751 B, 249 under the new ceiling.",
+            "why_it_could_not_be_avoided": "Room was tried and measured, as D8 asks: moving `handoff-context` (10,433 B in-bundle, `session_start` alone) into a chunk would free about 10 KB but produces a 581,613-byte chunk inlined, 319,233 bytes with `yaml` external — required on every `session_start` to buy 117 bytes, the same trade the 2026-10-23 entry refused for `session-eol`. Shortening the row's strings saves under 20 bytes. What remains is the row, which no chunk can carry. Sized to the merged measurement plus about 380 bytes.",
+            "what_would_have_caught_it": "Measuring the two branches together before the merge: two lanes that each fit a ceiling with a few hundred bytes to spare do not fit it together, and #2603 had already spent its last 2 bytes by dropping a provider_id type check in validate.ts."
+        },
+        {
+            "date": "2026-10-24",
+            "from": 1551000,
+            "to": 1554000,
+            "by": "agent, drain/update-installs-itself-20261024 (road-to-an-update-that-installs-itself-only-when-it-is-safe 3.1)",
+            "what_was_added": "A user-addressed channel in the dispatcher: a `notification` concern may reply `user_notice`, and on claude the dispatcher emits it as `systemMessage`, the field the host documents as shown to the user and not added to model context (hooks/user_notice.ts: collectUserNotice; host_semantics: withUserNotice, which merges context, the native emission and the notice as structures and falls back to the old output whenever a field it would extend has the wrong type, and writeStdout, which writes the output and only then a small user-global receipt naming the session and the notice id for each notice actually in the output, so a concern counts a notice as shown only on that receipt). Plus one LAZY_CONCERNS row for `update-notice`, whose body ships in its own chunk. Measured with one esbuild invocation over origin/main and over this branch after merging it: +2,945 bytes of own source (host_semantics +1,582, user_notice +1,095, dispatch_hook +116, lazy_concern +152; identifier renames elsewhere net 0), so 1,553,708 B against 1,551,000, the base reading 1,550,763. The logic sits in the two helper modules rather than in dispatch_hook.ts because that file is at the 1,500-line source cap. The first measurement, +1,391 B, predated the structural merge, the type guards and the delivery receipt that council rounds asked for.",
+            "why_it_could_not_be_avoided": "The channel is what step 3.1 was reopened for: every host runs the dispatcher on pipes, so a notice on stderr reached nobody, and a council round refused the registration for exactly that. The bytes are dispatcher code on the emission path of every event, so a chunk cannot carry them; the concern body is already in one. Room was not re-tried: the 2026-10-23 and 2026-10-24 entries measured the two narrow-event chunk candidates (`session-eol`, `handoff-context`) as buying a few hundred bytes for a quarter-megabyte require on every event, and nothing in this tree has changed that trade. Own code was compacted first (1,545 -> 1,391 B).",
+            "what_would_have_caught_it": "Nothing earlier: the base sat about 240 bytes under the ceiling. Sized to this change plus 292 bytes."
+        },
+        {
+            "date": "2026-10-24",
+            "chunk": "src/scripts/_lib/egress_engine.ts",
+            "from": 32000,
+            "to": 33000,
+            "by": "agent, drain/one-detector-20261024 (road-to-one-detector-and-the-senders-we-own 2.5)",
+            "what_was_added": "The invisible-character normalisation of one-detector 2.5 wired into the engine: `replaceValues` and `tallyText` now detect through `egress_normalize.ts` (`detectWithExtent`), and a rule's extent reader (`through`) runs on the normalised text with its end mapped back, so a key block whose BEGIN and END markers both carry a zero-width character is removed whole instead of refused or left behind. Measured 30,511 bytes on origin/main, 31,907 with the wiring alone, 32,305 with the extent fix.",
+            "why_it_could_not_be_avoided": "The 2026-10-18 derivation queued this rescan inside the 32,000 ceiling and the 2026-10-22 raise recorded it as not yet in the chunk. Room was taken first: `LATIN_TWIN` moved out of confusables.ts as a hex-encoded string pair so the chunk no longer carries that module's four script regexes, and the normaliser keeps one origin array instead of two (32,670 down to 31,907). The extent fix that a council seat found in round 1 of the ratification review adds about 400 bytes of mapping code no smaller form carries. The chunk loads only when a caller needs detection; the dispatch bundle is unchanged.",
+            "what_would_have_caught_it": "Measuring the wired engine when 2.5 was first built rather than the unwired module, and a disguised-marker key block in the extent tests from the start."
         }
     ],
     "chunks": [
@@ -47,7 +75,7 @@
         },
         {
             "entry": "src/scripts/_lib/egress_engine.ts",
-            "max_bytes": 32000,
+            "max_bytes": 33000,
             "registered_at": "2026-10-18",
             "derivation": "Measured 18,478 bytes on 2026-10-18 (the rule table, the token grammar and the commit scanner, with the per-rule linearity prose moved to a test-only module). The ceiling is that reading plus the queued engine work of road-to-one-detector-and-the-senders-we-own (validated identifier rules about 4.3 KB, known values, the invisible-character rescan and the variant suffix about 1-2 KB each), rounded up. An AI council of two providers chose on 2026-10-18 to move the engine out of the dispatch bundle into this conditional chunk rather than raise the dispatch ceiling, and asked that the chunk carry a measured budget of its own so the move does not just relocate uncontrolled growth. A raise follows the same rule as max_bytes: a raise_log entry naming the chunk (`chunk`: this entry) and what was added."
         },
@@ -55,17 +83,29 @@
             "entry": "src/scripts/chat_history.ts",
             "max_bytes": 232000,
             "registered_at": "2026-10-20",
-            "derivation": "Measured 209,890 bytes on 2026-10-20, with `yaml` external (inlined it is 472,201 \u2014 a second copy of the parser the dispatch bundle already carries). The ceiling is that reading plus about 10 %, rounded, because this chunk carries a 2,300-line concern plus the memory lookup and FTS index it reads, all of which still grow.\n\nWHY IT WAS MOVED \u2014 AND THE REASON FIRST GIVEN WAS FALSE, which is recorded here rather than corrected silently. This entry said `chat-history` is bound on `session_start` and on no other event, and called it the largest narrow-event module the metafile ranks. An independent provider review of 2026-10-20 checked the manifest and refused the change on it: `chat-history` is bound on FIVE events \u2014 `session_start`, `session_end`, `stop`, `post_tool_use` and `user_prompt_submit` \u2014 across seven hosts. It is close to the widest-bound concern in the tree, not the narrowest. The claim came from reading the `session_start:` rows of the manifest and never the others.\n\nWHAT SURVIVES THE CORRECTION, stated as narrowly as the evidence allows: the move takes 120,586 bytes out of a bundle every hook event parses (1,549,961 -> 1,429,414 B) and pays for them with one `require` of a 209,890-byte CJS file on the events that actually need the concern. Whether that is a latency WIN is UNMEASURED, and the 2026-10-18 council that chose this mechanism asked for exactly that proof inside `src/config/hook-latency-budget.json`. Until it exists this chunk is a byte-budget move with an unproven wall-clock effect, and the honest narrow-event candidates the same metafile ranks are recorded for whoever re-does it: `turn-end-gate` 71,928 B on `stop` alone, `injection-scan` 46,660 B on `post_tool_use` alone, `skill-route` 31,183 B and `git-authorization` 30,761 B on `user_prompt_submit` alone, `session-eol` 27,708 B on `stop` alone, `handoff-context` 25,220 B on `session_start` alone.\n\nUNLIKE THE OTHER TWO CHUNKS this one carries a CONCERN, so there is a correct path behind the fast one: `_run_concern` tries the static registry, then `loadLazyConcern`, then the historical spawn-per-concern path. A missing or mis-digested chunk costs latency, never the concern's effect \u2014 which the same review confirmed, noting it holds because `src/scripts/` ships in the package."
+            "derivation": "Measured 209,890 bytes on 2026-10-20, with `yaml` external (inlined it is 472,201 — a second copy of the parser the dispatch bundle already carries). The ceiling is that reading plus about 10 %, rounded, because this chunk carries a 2,300-line concern plus the memory lookup and FTS index it reads, all of which still grow.\n\nWHY IT WAS MOVED — AND THE REASON FIRST GIVEN WAS FALSE, which is recorded here rather than corrected silently. This entry said `chat-history` is bound on `session_start` and on no other event, and called it the largest narrow-event module the metafile ranks. An independent provider review of 2026-10-20 checked the manifest and refused the change on it: `chat-history` is bound on FIVE events — `session_start`, `session_end`, `stop`, `post_tool_use` and `user_prompt_submit` — across seven hosts. It is close to the widest-bound concern in the tree, not the narrowest. The claim came from reading the `session_start:` rows of the manifest and never the others.\n\nWHAT SURVIVES THE CORRECTION, stated as narrowly as the evidence allows: the move takes 120,586 bytes out of a bundle every hook event parses (1,549,961 -> 1,429,414 B) and pays for them with one `require` of a 209,890-byte CJS file on the events that actually need the concern. Whether that is a latency WIN is UNMEASURED, and the 2026-10-18 council that chose this mechanism asked for exactly that proof inside `src/config/hook-latency-budget.json`. Until it exists this chunk is a byte-budget move with an unproven wall-clock effect, and the honest narrow-event candidates the same metafile ranks are recorded for whoever re-does it: `turn-end-gate` 71,928 B on `stop` alone, `injection-scan` 46,660 B on `post_tool_use` alone, `skill-route` 31,183 B and `git-authorization` 30,761 B on `user_prompt_submit` alone, `session-eol` 27,708 B on `stop` alone, `handoff-context` 25,220 B on `session_start` alone.\n\nUNLIKE THE OTHER TWO CHUNKS this one carries a CONCERN, so there is a correct path behind the fast one: `_run_concern` tries the static registry, then `loadLazyConcern`, then the historical spawn-per-concern path. A missing or mis-digested chunk costs latency, never the concern's effect — which the same review confirmed, noting it holds because `src/scripts/` ships in the package."
         },
         {
             "entry": "src/scripts/hooks/instructions_observer_hook.ts",
             "max_bytes": 12000,
             "registered_at": "2026-10-23",
             "derivation": "Measured 11,097 bytes on 2026-10-23 (the observe-only `InstructionsLoaded` capture, its classifier, and the CLI entry the spawn fallback needs). The ceiling is that reading plus about 10 %, rounded, with no growth queued. Bound on `instructions_loaded` alone, so a chunk keeps it off every other dispatch's parse; the observer body ships here, never in the dispatch bundle. The binding that reaches it (one registry row and the event name in three vocabularies, 237 bytes) does sit in the bundle and is the 2026-10-23 raise of `max_bytes` recorded in `raise_log`. Like `chat_history` it carries a concern, so a missing chunk falls back to the spawn path and costs latency, never the capture."
+        },
+        {
+            "entry": "src/scripts/hooks/code_graph_refresh_hook.ts",
+            "max_bytes": 15400,
+            "registered_at": "2026-10-23",
+            "derivation": "Measured 14,284 bytes on 2026-10-24 (the session-start code-graph refresh concern with its opt-in, tracked-file and PATH-trust checks, the CLI capability probe and outcome record of the PR #2604 review follow-up, the refresh-lock staleness check it shares with `code-graph refresh --single-flight`, and the hardened spawn environment). The ceiling is that reading plus about 8 %, rounded, with no growth queued; it was registered at 14,000 against 12,726 B and re-derived in the same PR, before any release carried it. Bound on `session_start` alone; a chunk keeps it off every other dispatch's parse, and the dispatch bundle carries only its `LAZY_CONCERNS` row. Like `chat_history` it carries a concern, so a missing chunk falls back to the spawn path and costs latency, never the refresh."
+        },
+        {
+            "entry": "src/scripts/update_notice_hook.ts",
+            "max_bytes": 35500,
+            "registered_at": "2026-10-24",
+            "derivation": "Measured 32,812 bytes on 2026-10-24 (the concern, its decision library and the delivery-receipt reader) with `yaml` external (the concern reads one user-global settings file with it; inlined it would be a second copy of the parser the dispatch bundle already carries). The ceiling is that reading plus about 10 %, rounded, with no growth queued. Bound on claude `session_start` alone, so a chunk keeps its body off every other dispatch parse; the bundle carries only its LAZY_CONCERNS row. Like `chat_history` it carries a concern, so a missing chunk falls back to the spawn path and costs latency, never the notice."
         }
     ],
     "chunks_note": "A chunk is loaded only when a caller needs it, so its bytes are not paid by every dispatch; its ceiling exists so that the move out of dispatch.js stays a measured place rather than an unmeasured one. The gate builds each chunk with the exact esbuild segment `build:hook-chunks` uses for its entry.",
     "max_yaml_packages": 1,
-    "max_yaml_packages_note": "The dispatch path reads YAML for the hook manifest, the host-lowering table and the settings contract. One reader covers all three. Two cost 95,846 bytes for a single call site and were invisible until an external rescore counted them \u2014 which is why this is a cap rather than prose. The package set the cap counts over is YAML_PACKAGES in the gate.",
+    "max_yaml_packages_note": "The dispatch path reads YAML for the hook manifest, the host-lowering table and the settings contract. One reader covers all three. Two cost 95,846 bytes for a single call site and were invisible until an external rescore counted them — which is why this is a cap rather than prose. The package set the cap counts over is YAML_PACKAGES in the gate.",
     "what_this_does_not_bound": "Latency. A smaller bundle is not a measured speed-up; src/config/hook-latency-budget.json owns the wall-clock axis and is not derived from this file. Nor does it bound dist/install/install.mjs or dist/mcp/server.mjs, which carry their own module graphs."
 }

package/src/config/pack-size-budget.json

@@ -123,5 +123,16 @@
         "measured_at": "2026-10-17",
         "measured_on": "One machine, one clean checkout of origin/main at 8c90aad26, plus the earlier readings taken in a separate worktree of the same content. Node and npm as resolved by the repo's engines field (node >=20.11.0). From this change onward the required Consistency job also produces a CI reading of the built surface, which the 2026-09-10 record said was impossible."
     },
-    "built_surface_enforcement_2026_08_30": "How the two surfaces this file records are now ENFORCED, which until 2026-08-30 they were not. `check_pack_size` compared every payload against `budgets.packed_size_mb.max`, and that cap was measured on the UNBUILT tree — this file has said so since 2026-08-24 in `measurement_conditions` and in `built_surface_measurement_2026_08_24`, and the gate did not read it. Measured on the day this note was written: main packed 8.985 MB over 2715 entries with `--ignore-scripts` and passed; a branch adding six source files packed 9.922 over 2827 and failed `max: 9.1`. The 112-entry difference is `dist/cli` plus `dist/cli-delegate` — the build, not the diff. The gate now reads the payload it is judging (`payloadIsBuilt`, keyed on `dist/cli/**`, already used by the content classes for the same reason) and routes: an UNBUILT payload against `max` and the `last_measured` creep line, unchanged; a BUILT payload against `built_surface_measurement_*.built.packed_mb` with the same `regression_pct`. A built payload with no recorded built figure is a FINDING, not a pass — otherwise removing the record would silently disable the built path. What this does NOT do: it does not raise `max`, and it does not gate the built surface against an absolute cap. The built surface gets a regression line only, because no absolute figure for it was ever set by a maintainer and inventing one here would be exactly the invented number the `_comment` warns about. Revisit-if: a maintainer sets an absolute built cap, or the built figure is re-measured (add a new `built_surface_measurement_<date>` key — the newest is read, so no code changes)."
+    "built_surface_enforcement_2026_08_30": "How the two surfaces this file records are now ENFORCED, which until 2026-08-30 they were not. `check_pack_size` compared every payload against `budgets.packed_size_mb.max`, and that cap was measured on the UNBUILT tree — this file has said so since 2026-08-24 in `measurement_conditions` and in `built_surface_measurement_2026_08_24`, and the gate did not read it. Measured on the day this note was written: main packed 8.985 MB over 2715 entries with `--ignore-scripts` and passed; a branch adding six source files packed 9.922 over 2827 and failed `max: 9.1`. The 112-entry difference is `dist/cli` plus `dist/cli-delegate` — the build, not the diff. The gate now reads the payload it is judging (`payloadIsBuilt`, keyed on `dist/cli/**`, already used by the content classes for the same reason) and routes: an UNBUILT payload against `max` and the `last_measured` creep line, unchanged; a BUILT payload against `built_surface_measurement_*.built.packed_mb` with the same `regression_pct`. A built payload with no recorded built figure is a FINDING, not a pass — otherwise removing the record would silently disable the built path. What this does NOT do: it does not raise `max`, and it does not gate the built surface against an absolute cap. The built surface gets a regression line only, because no absolute figure for it was ever set by a maintainer and inventing one here would be exactly the invented number the `_comment` warns about. Revisit-if: a maintainer sets an absolute built cap, or the built figure is re-measured (add a new `built_surface_measurement_<date>` key — the newest is read, so no code changes).",
+    "built_surface_measurement_2026_10_23": {
+        "purpose": "Re-measure of the BUILT surface for PR #2603 (road-to-graph-providers-for-every-stack). It vendors one itemised addition: the C# tree-sitter grammar (src/vendor/grammars/tree-sitter-c_sharp.wasm, 3,978,594 B uncompressed, about 0.25 MB packed), which brings C# extraction and the ASP.NET Core provider. CI measured the built tarball at 16.036 MB against the 15.949 line derived from built_surface_measurement_2026_10_17. AI council 2026-10-23, round 2, two seats convergent: record a dated built measurement for the C# grammar and carry Ruby + Rails to road-to-graph-providers-for-every-stack-carried. The re-anchor is OWNER-RESERVED under the 2026-10-17 precedent (the agent proposing a reset is the one it unblocks); the owner chose it on 2026-10-24.",
+        "built": {
+            "packed_mb": 16.036,
+            "command": "CI: Sync + Generate Tools Consistency job, check_pack_size on the BUILT surface (the same callers built_surface_measurement_2026_10_17 aligned)",
+            "note": "The derived ceiling becomes 17.640 at regression_pct 10. Local pristine builds read about 0.1 MB lower (base 15.683, with the C# grammar 15.937); the CI figure is recorded because CI is the caller that gates."
+        },
+        "policy_clarification": "REQUIRED BY BOTH SEATS. This re-anchor admits the itemised C# grammar only. It does NOT authorise the roughly 1.6 MB of headroom the 10 % rule now derives for unrelated growth: the next built re-anchor must itemise every payload addition since this record, and a grammar (Ruby, blocker built-pack-budget-for-grammars in the carried roadmap) is decided on its own. Revisit-if: an addition lands under this line without being itemised here or in a later record, or a maintainer sets an absolute built cap.",
+        "measured_at": "2026-10-23",
+        "measured_on": "GitHub Actions, PR #2603 head 2c06e7881, required job Sync + Generate Tools Consistency."
+    }
 }

package/src/config/packed-binary-manifest.json

@@ -55,6 +55,24 @@
       "grammar_id": "java",
       "abi": 14,
       "why": "The Java grammar (road-to-a-map-that-draws-itself 6.1). Same reason as the php entry: the engine indexes .java files in a consumer install with no manual parser step."
+    },
+    {
+      "path": "src/vendor/grammars/tree-sitter-c_sharp.wasm",
+      "sha256": "6266a7e32d68a3459104d994dc848df15d5672b0ea8e86d327274b694f8e6991",
+      "size": 3978594,
+      "kind": "tree-sitter-wasm-grammar",
+      "grammar_id": "c_sharp",
+      "abi": 13,
+      "why": "The C# grammar (road-to-graph-providers-for-every-stack 5.2). Same reason as the php entry: the engine indexes .cs files in a consumer install with no manual parser step. ABI 13, not 14: tree-sitter-wasms@0.1.13 compiles this one grammar at ABI 13, which the pinned web-tree-sitter loads, so the loader pins it per language."
+    },
+    {
+      "path": "src/vendor/grammars/tree-sitter-ruby.wasm",
+      "sha256": "93a5022855314cdb45458c7bb026a24a0ebc3a5ff6439e542e881f14dfa13a39",
+      "size": 2106447,
+      "kind": "tree-sitter-wasm-grammar",
+      "grammar_id": "ruby",
+      "abi": 14,
+      "why": "The Ruby grammar (road-to-graph-providers-for-every-stack-carried 1.1). Same reason as the php entry: the engine indexes .rb files in a consumer install with no manual parser step."
     }
   ]
 }

package/src/config/sigstore/npm_keys.json

@@ -0,0 +1,50 @@
+{
+    "keys": [
+        {
+            "keyId": "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA",
+            "keyUsage": "npm:signatures",
+            "publicKey": {
+                "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg==",
+                "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+                "validFor": {
+                    "start": "1999-01-01T00:00:00.000Z",
+                    "end": "2025-01-29T00:00:00.000Z"
+                }
+            }
+        },
+        {
+            "keyId": "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA",
+            "keyUsage": "npm:attestations",
+            "publicKey": {
+                "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE1Olb3zMAFFxXKHiIkQO5cJ3Yhl5i6UPp+IhuteBJbuHcA5UogKo0EWtlWwW6KSaKoTNEYL7JlCQiVnkhBktUgg==",
+                "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+                "validFor": {
+                    "start": "2022-12-01T00:00:00.000Z",
+                    "end": "2025-01-29T00:00:00.000Z"
+                }
+            }
+        },
+        {
+            "keyId": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U",
+            "keyUsage": "npm:signatures",
+            "publicKey": {
+                "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==",
+                "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+                "validFor": {
+                    "start": "2025-01-13T00:00:00.000Z"
+                }
+            }
+        },
+        {
+            "keyId": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U",
+            "keyUsage": "npm:attestations",
+            "publicKey": {
+                "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEY6Ya7W++7aUPzvMTrezH6Ycx3c+HOKYCcNGybJZSCJq/fd7Qa8uuAKtdIkUQtQiEKERhAmE5lMMJhP8OkDOa2g==",
+                "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+                "validFor": {
+                    "start": "2025-01-13T00:00:00.000Z"
+                }
+            }
+        }
+    ]
+}

package/src/config/sigstore/trust-material.json

@@ -0,0 +1,9 @@
+{
+    "_comment": "Trust material the unattended upgrade verifies release provenance against (road-to-an-update-that-installs-itself-only-when-it-is-safe D15). Pinned, never refreshed at run time: a candidate release can never choose the roots it is checked against. Read by src/scripts/_lib/sigstore_provenance.ts, which refuses when a file's sha256 differs from the one recorded here. Refresh by re-extracting both targets from a newer @sigstore/tuf seeds.json and updating source and digests together; until a release carries new material, an unattended run refuses anything signed under a rotated root and `agent-config upgrade` by hand still works.",
+    "source": "@sigstore/tuf@5.0.0 seeds.json, mirror https://tuf-repo-cdn.sigstore.dev, extracted 2026-10-24",
+    "files": {
+        "trusted_root.json": "6494e21ea73fa7ee769f85f57d5a3e6a08725eae1e38c755fc3517c9e6bc0b66",
+        "npm_keys.json": "160677eb6e1c7083c89b166b20f8fe4e837fb71181506aff1991b80b89184f7d"
+    },
+    "npm_keys_live_check": "Equal on 2026-10-24 to https://registry.npmjs.org/-/npm/v1/keys: SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA (expired 2025-01-29) and SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U (no expiry)."
+}

package/src/config/sigstore/trusted_root.json

@@ -0,0 +1,126 @@
+{
+  "mediaType": "application/vnd.dev.sigstore.trustedroot+json;version=0.1",
+  "tlogs": [
+    {
+      "baseUrl": "https://rekor.sigstore.dev",
+      "hashAlgorithm": "SHA2_256",
+      "publicKey": {
+        "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE2G2Y+2tabdTV5BcGiBIx0a9fAFwrkBbmLSGtks4L3qX6yYY0zufBnhC8Ur/iy55GhWP/9A/bY2LhC30M9+RYtw==",
+        "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+        "validFor": {
+          "start": "2021-01-12T11:53:27Z"
+        }
+      },
+      "logId": {
+        "keyId": "wNI9atQGlz+VWfO6LRygH4QUfY/8W4RFwiT5i5WRgB0="
+      }
+    },
+    {
+      "baseUrl": "https://log2025-1.rekor.sigstore.dev",
+      "hashAlgorithm": "SHA2_256",
+      "publicKey": {
+        "rawBytes": "MCowBQYDK2VwAyEAt8rlp1knGwjfbcXAYPYAkn0XiLz1x8O4t0YkEhie244=",
+        "keyDetails": "PKIX_ED25519",
+        "validFor": {
+          "start": "2025-09-23T00:00:00Z"
+        }
+      },
+      "logId": {
+        "keyId": "zxGZFVvd0FEmjR8WrFwMdcAJ9vtaY/QXf44Y1wUeP6A="
+      }
+    }
+  ],
+  "certificateAuthorities": [
+    {
+      "subject": {
+        "organization": "sigstore.dev",
+        "commonName": "sigstore"
+      },
+      "uri": "https://fulcio.sigstore.dev",
+      "certChain": {
+        "certificates": [
+          {
+            "rawBytes": "MIIB+DCCAX6gAwIBAgITNVkDZoCiofPDsy7dfm6geLbuhzAKBggqhkjOPQQDAzAqMRUwEwYDVQQKEwxzaWdzdG9yZS5kZXYxETAPBgNVBAMTCHNpZ3N0b3JlMB4XDTIxMDMwNzAzMjAyOVoXDTMxMDIyMzAzMjAyOVowKjEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MREwDwYDVQQDEwhzaWdzdG9yZTB2MBAGByqGSM49AgEGBSuBBAAiA2IABLSyA7Ii5k+pNO8ZEWY0ylemWDowOkNa3kL+GZE5Z5GWehL9/A9bRNA3RbrsZ5i0JcastaRL7Sp5fp/jD5dxqc/UdTVnlvS16an+2Yfswe/QuLolRUCrcOE2+2iA5+tzd6NmMGQwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQEwHQYDVR0OBBYEFMjFHQBBmiQpMlEk6w2uSu1KBtPsMB8GA1UdIwQYMBaAFMjFHQBBmiQpMlEk6w2uSu1KBtPsMAoGCCqGSM49BAMDA2gAMGUCMH8liWJfMui6vXXBhjDgY4MwslmN/TJxVe/83WrFomwmNf056y1X48F9c4m3a3ozXAIxAKjRay5/aj/jsKKGIkmQatjI8uupHr/+CxFvaJWmpYqNkLDGRU+9orzh5hI2RrcuaQ=="
+          }
+        ]
+      },
+      "validFor": {
+        "start": "2021-03-07T03:20:29Z",
+        "end": "2022-12-31T23:59:59.999Z"
+      }
+    },
+    {
+      "subject": {
+        "organization": "sigstore.dev",
+        "commonName": "sigstore"
+      },
+      "uri": "https://fulcio.sigstore.dev",
+      "certChain": {
+        "certificates": [
+          {
+            "rawBytes": "MIICGjCCAaGgAwIBAgIUALnViVfnU0brJasmRkHrn/UnfaQwCgYIKoZIzj0EAwMwKjEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MREwDwYDVQQDEwhzaWdzdG9yZTAeFw0yMjA0MTMyMDA2MTVaFw0zMTEwMDUxMzU2NThaMDcxFTATBgNVBAoTDHNpZ3N0b3JlLmRldjEeMBwGA1UEAxMVc2lnc3RvcmUtaW50ZXJtZWRpYXRlMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE8RVS/ysH+NOvuDZyPIZtilgUF9NlarYpAd9HP1vBBH1U5CV77LSS7s0ZiH4nE7Hv7ptS6LvvR/STk798LVgMzLlJ4HeIfF3tHSaexLcYpSASr1kS0N/RgBJz/9jWCiXno3sweTAOBgNVHQ8BAf8EBAMCAQYwEwYDVR0lBAwwCgYIKwYBBQUHAwMwEgYDVR0TAQH/BAgwBgEB/wIBADAdBgNVHQ4EFgQU39Ppz1YkEZb5qNjpKFWixi4YZD8wHwYDVR0jBBgwFoAUWMAeX5FFpWapesyQoZMi0CrFxfowCgYIKoZIzj0EAwMDZwAwZAIwPCsQK4DYiZYDPIaDi5HFKnfxXx6ASSVmERfsynYBiX2X6SJRnZU84/9DZdnFvvxmAjBOt6QpBlc4J/0DxvkTCqpclvziL6BCCPnjdlIB3Pu3BxsPmygUY7Ii2zbdCdliiow="
+          },
+          {
+            "rawBytes": "MIIB9zCCAXygAwIBAgIUALZNAPFdxHPwjeDloDwyYChAO/4wCgYIKoZIzj0EAwMwKjEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MREwDwYDVQQDEwhzaWdzdG9yZTAeFw0yMTEwMDcxMzU2NTlaFw0zMTEwMDUxMzU2NThaMCoxFTATBgNVBAoTDHNpZ3N0b3JlLmRldjERMA8GA1UEAxMIc2lnc3RvcmUwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAT7XeFT4rb3PQGwS4IajtLk3/OlnpgangaBclYpsYBr5i+4ynB07ceb3LP0OIOZdxexX69c5iVuyJRQ+Hz05yi+UF3uBWAlHpiS5sh0+H2GHE7SXrk1EC5m1Tr19L9gg92jYzBhMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBRYwB5fkUWlZql6zJChkyLQKsXF+jAfBgNVHSMEGDAWgBRYwB5fkUWlZql6zJChkyLQKsXF+jAKBggqhkjOPQQDAwNpADBmAjEAj1nHeXZp+13NWBNa+EDsDP8G1WWg1tCMWP/WHPqpaVo0jhsweNFZgSs0eE7wYI4qAjEA2WB9ot98sIkoF3vZYdd3/VtWB5b9TNMea7Ix/stJ5TfcLLeABLE4BNJOsQ4vnBHJ"
+          }
+        ]
+      },
+      "validFor": {
+        "start": "2022-04-13T20:06:15Z"
+      }
+    }
+  ],
+  "ctlogs": [
+    {
+      "baseUrl": "https://ctfe.sigstore.dev/test",
+      "hashAlgorithm": "SHA2_256",
+      "publicKey": {
+        "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEbfwR+RJudXscgRBRpKX1XFDy3PyudDxz/SfnRi1fT8ekpfBd2O1uoz7jr3Z8nKzxA69EUQ+eFCFI3zeubPWU7w==",
+        "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+        "validFor": {
+          "start": "2021-03-14T00:00:00Z",
+          "end": "2022-10-31T23:59:59.999Z"
+        }
+      },
+      "logId": {
+        "keyId": "CGCS8ChS/2hF0dFrJ4ScRWcYrBY9wzjSbea8IgY2b3I="
+      }
+    },
+    {
+      "baseUrl": "https://ctfe.sigstore.dev/2022",
+      "hashAlgorithm": "SHA2_256",
+      "publicKey": {
+        "rawBytes": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiPSlFi0CmFTfEjCUqF9HuCEcYXNKAaYalIJmBZ8yyezPjTqhxrKBpMnaocVtLJBI1eM3uXnQzQGAJdJ4gs9Fyw==",
+        "keyDetails": "PKIX_ECDSA_P256_SHA_256",
+        "validFor": {
+          "start": "2022-10-20T00:00:00Z"
+        }
+      },
+      "logId": {
+        "keyId": "3T0wasbHETJjGR4cmWc3AqJKXrjePK3/h4pygC8p7o4="
+      }
+    }
+  ],
+  "timestampAuthorities": [
+    {
+      "subject": {
+        "organization": "sigstore.dev",
+        "commonName": "sigstore-tsa-selfsigned"
+      },
+      "uri": "https://timestamp.sigstore.dev/api/v1/timestamp",
+      "certChain": {
+        "certificates": [
+          {
+            "rawBytes": "MIICEDCCAZagAwIBAgIUOhNULwyQYe68wUMvy4qOiyojiwwwCgYIKoZIzj0EAwMwOTEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MSAwHgYDVQQDExdzaWdzdG9yZS10c2Etc2VsZnNpZ25lZDAeFw0yNTA0MDgwNjU5NDNaFw0zNTA0MDYwNjU5NDNaMC4xFTATBgNVBAoTDHNpZ3N0b3JlLmRldjEVMBMGA1UEAxMMc2lnc3RvcmUtdHNhMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAE4ra2Z8hKNig2T9kFjCAToGG30jky+WQv3BzL+mKvh1SKNR/UwuwsfNCg4sryoYAd8E6isovVA3M4aoNdm9QDi50Z8nTEyvqgfDPtTIwXItfiW/AFf1V7uwkbkAoj0xxco2owaDAOBgNVHQ8BAf8EBAMCB4AwHQYDVR0OBBYEFIn9eUOHz9BlRsMCRscsc1t9tOsDMB8GA1UdIwQYMBaAFJjsAe9/u1H/1JUeb4qImFMHic6/MBYGA1UdJQEB/wQMMAoGCCsGAQUFBwMIMAoGCCqGSM49BAMDA2gAMGUCMDtpsV/6KaO0qyF/UMsX2aSUXKQFdoGTptQGc0ftq1csulHPGG6dsmyMNd3JB+G3EQIxAOajvBcjpJmKb4Nv+2Taoj8Uc5+b6ih6FXCCKraSqupe07zqswMcXJTe1cExvHvvlw=="
+          },
+          {
+            "rawBytes": "MIIB9zCCAXygAwIBAgIUV7f0GLDOoEzIh8LXSW80OJiUp14wCgYIKoZIzj0EAwMwOTEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MSAwHgYDVQQDExdzaWdzdG9yZS10c2Etc2VsZnNpZ25lZDAeFw0yNTA0MDgwNjU5NDNaFw0zNTA0MDYwNjU5NDNaMDkxFTATBgNVBAoTDHNpZ3N0b3JlLmRldjEgMB4GA1UEAxMXc2lnc3RvcmUtdHNhLXNlbGZzaWduZWQwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAAQUQNtfRT/ou3YATa6wB/kKTe70cfJwyRIBovMnt8RcJph/COE82uyS6FmppLLL1VBPGcPfpQPYJNXzWwi8icwhKQ6W/Qe2h3oebBb2FHpwNJDqo+TMaC/tdfkv/ElJB72jRTBDMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEAMB0GA1UdDgQWBBSY7AHvf7tR/9SVHm+KiJhTB4nOvzAKBggqhkjOPQQDAwNpADBmAjEAwGEGrfGZR1cen1R8/DTVMI943LssZmJRtDp/i7SfGHmGRP6gRbuj9vOK3b67Z0QQAjEAuT2H673LQEaHTcyQSZrkp4mX7WwkmF+sVbkYY5mXN+RMH13KUEHHOqASaemYWK/E"
+          }
+        ]
+      },
+      "validFor": {
+        "start": "2025-07-04T00:00:00Z"
+      }
+    }
+  ]
+}

package/src/config/skill-body-budget.json

@@ -38,7 +38,7 @@
     "character-consistency": 8555,
     "check-refs": 4188,
     "churn-prevention": 8014,
-    "code-intelligence": 16998,
+    "code-intelligence": 17182,
     "code-refactoring": 13717,
     "code-review": 16261,
     "command-routing": 6040,
@@ -687,6 +687,12 @@
       "old": 16492,
       "new": 16998,
       "reason": "road-to-a-map-that-draws-itself (ADR-297): step 0 sends an orientation question to agents/map/MAP.md before any graph query, and the MCP table gains rows for graph_map_status and graph_area. Both are the skill's routing surface for the new map; trimming them would hide the tools the roadmap added."
+    },
+    {
+      "skill": "code-intelligence",
+      "old": 16998,
+      "new": 17182,
+      "reason": "road-to-a-graph-that-follows-you (ADR-299): the MCP table gains a row for graph_estate and one line naming the new project parameter on every other graph tool. The ceiling sat 3 bytes above the body, so documenting the tool at all needs a raise; the wording was compressed first, from 262 to 184 bytes."
     }
   ]
 }

package/src/scripts/_cli/cmd_settings_set.ts

@@ -44,7 +44,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
 
-import { z } from 'zod';
+import * as z from 'zod';
 
 import { mergeIntoTemplate } from '../../server/io/yamlIO.js';
 import { settingsSchema } from '../../server/schemas/settings.js';
@@ -269,10 +269,11 @@ function _unwrap(schema: z.ZodTypeAny): z.ZodTypeAny {
     let current: z.ZodTypeAny = schema;
     while (
         current instanceof z.ZodDefault ||
+        current instanceof z.ZodPrefault ||
         current instanceof z.ZodOptional ||
         current instanceof z.ZodNullable
     ) {
-        current = (current._def as { innerType: z.ZodTypeAny }).innerType;
+        current = (current._def as unknown as { innerType: z.ZodTypeAny }).innerType;
     }
     return current;
 }

package/src/scripts/_cli/cmd_update.ts

@@ -21,6 +21,12 @@
  *   Downgrades are allowed; the pin is a project decision.
  * - (no flag) — pin to the registry's `latest` tag.
  *
+ * The global install moves first. Only the CLI follows the pin (`pin_resolver`
+ * re-execs through npx); hooks, rules and skills run from the global install. So
+ * when `installed.lock` records an older version than the target, this runs
+ * `agent-config upgrade` to exactly that version and writes the pin only once it
+ * succeeded — offline, where it cannot, the pin is refused instead.
+ *
  * Write target: the **deepest** `.agent-settings.yml` in the project cascade
  * that already carries the `agent_config_version` key. When no file carries
  * it, the repo-root file is created/edited. Comments and key ordering are
@@ -405,6 +411,10 @@ interface MainOptions {
     state_path?: string | null;
     out?: OutSink;
     err?: OutSink;
+    /** The version the global install recorded in `installed.lock`, or `null` when there is none. */
+    global_version?: () => string | null;
+    /** Install exactly this version globally; returns the exit code. */
+    upgrader?: (version: string, out: OutSink, err: OutSink) => Promise<number>;
 }
 
 interface Args {
@@ -526,6 +536,29 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         return 0;
     }
 
+    // The pin only steers the CLI (`pin_resolver` re-execs through npx); hooks,
+    // rules and skills run from the global install. A pin ahead of it would
+    // leave the project naming one version while every session runs another,
+    // so the global install moves first, and the pin only once it has.
+    const global = (options.global_version ?? _global_install_version)();
+    if (global !== null && update_check._is_newer(latest, global)) {
+        if (offline) {
+            _print(
+                err,
+                `❌  agent-config: the global install is ${global} and cannot be upgraded to ${latest} offline; ` +
+                    'the pin is unchanged. Run `agent-config update` again with registry access.',
+            );
+            return 1;
+        }
+        _print(out, `→ The global install is ${global}; installing ${latest} first so the pin matches what runs.`);
+        const upgrader = options.upgrader ?? _upgrade_global;
+        const rc = await upgrader(latest, out, err);
+        if (rc !== 0) {
+            _print(err, `❌  agent-config: the global upgrade to ${latest} failed (exit ${rc}); the pin is unchanged.`);
+            return 1;
+        }
+    }
+
     const pin_file = _find_pin_file(cwd);
     const changed = _write_pin(pin_file, latest);
     const rel = _relativeToOr(pin_file, cwd);
@@ -542,7 +575,6 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         cache_warmer(latest);
     }
     _refresh_state(latest, latest, state_path);
-    _report_global_install(latest, out);
     return 0;
 }
 
@@ -556,28 +588,24 @@ function _relativeToOr(target: string, base: string): string {
 }
 
 /**
- * Name `agent-config upgrade` when the global install is older than the pin.
+ * The version the global install recorded, or `null` when there is no global
+ * install to keep in step with.
  *
- * Read-only by design: `installed.lock` records what the global install
- * deployed, and `upgrade` (plus its `--check` and unattended paths) reads it as
- * the installed version. This command used to rewrite it to the pin, so after
- * `update` the lock claimed a version no `npm install -g` had installed and
- * `upgrade --check` reported "up to date" over the old binary.
+ * Read-only by design: `installed.lock` is written by the global install itself.
+ * This command once rewrote it to the pin, so the lock claimed a version no
+ * `npm install -g` had installed and `upgrade --check` reported "up to date"
+ * over the old binary.
  */
-function _report_global_install(version: string, out: OutSink): void {
+function _global_install_version(): string | null {
     const existing = installed_lock.read_lockfile(installed_lock.lockfile_path());
-    if (existing === null) {
-        return;
-    }
-    const recorded = (existing as unknown as Record<string, unknown>)['agent_config_version'];
-    if (typeof recorded !== 'string' || !update_check._is_newer(version, _normalize(recorded))) {
-        return;
-    }
-    _print(
-        out,
-        `ℹ️  The global install is ${_normalize(recorded)}; this pin does not change it. ` +
-            `Run \`agent-config upgrade\` to install ${version} globally.`,
-    );
+    const recorded = (existing as unknown as Record<string, unknown> | null)?.['agent_config_version'];
+    return typeof recorded === 'string' && recorded.trim() !== '' ? _normalize(recorded) : null;
+}
+
+/** `agent-config upgrade`, in process, to exactly `version`. */
+async function _upgrade_global(version: string, out: OutSink, err: OutSink): Promise<number> {
+    const upgrade = await import('./cmd_upgrade.js');
+    return upgrade.main([], { version, out, err });
 }
 
 /** Read `version` from the package's own `package.json`. */

package/src/scripts/_cli/cmd_upgrade.ts

@@ -505,6 +505,12 @@ interface MainOptions {
     project_root?: string | null;
     out?: OutSink;
     err?: OutSink;
+    /**
+     * Install this exact version instead of `latest`. Programmatic only — set by
+     * `agent-config update`, which must install the version it is about to pin;
+     * the command line keeps `update --to` as the one way to name a version.
+     */
+    version?: string;
 }
 
 export async function main(argv: string[] | null = null, options: MainOptions = {}): Promise<number> {
@@ -549,7 +555,7 @@ export async function main(argv: string[] | null = null, options: MainOptions =
         return 0;
     }
 
-    const target = `${PACKAGE_NAME}@latest`;
+    const target = `${PACKAGE_NAME}@${options.version ?? 'latest'}`;
     const npm_cmd: string[] = ['npm', 'install', '-g', target];
     // --no-ui: the setup wizard is an onboarding surface, not an upgrade
     // step — its foreground server used to block the upgrade until Ctrl-C.