@event4u/agent-config 17.3.0 → 17.4.0

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_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.

package/src/scripts/_cli/upgrade_unattended.ts

@@ -22,17 +22,14 @@
  * registry, a live session) · `1` a step failed and the previous version was
  * restored · `4` a step failed and the restore did not reach the previous version.
  */
+import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 
-import {
-    EXPECTED_WORKFLOW_REF,
-    attestation_workflow_ref,
-    provenance_matches_publish,
-    verify_attestation_signature,
-} from '../_lib/provenance_verify.js';
+import { type ReleaseToVerify, verify_release_provenance } from '../_lib/sigstore_provenance.js';
 import { read_candidate, unattended_decision, type RegistryCandidate } from '../_lib/unattended_gates.js';
 import type { InstallOrigin } from '../_lib/classify_update.js';
 import * as installed_lock from '../_lib/installed_lock.js';
@@ -97,10 +94,13 @@ export interface StepResult {
 
 export type Packument = { readonly ok: true; readonly doc: unknown } | { readonly ok: false; readonly reason: string };
 
+/** A verified tarball on disk, the only thing the install step may install — or why there is none. */
+export type Provenance = { readonly ok: true; readonly tarball: string } | { readonly ok: false; readonly reason: string };
+
 export interface UnattendedDeps {
     readonly fetchPackument: () => Promise<Packument>;
-    /** Refusal reason when the attestation does not tie to this package's publish workflow, else `null`. */
-    readonly verifyProvenance: (candidate: RegistryCandidate) => Promise<string | null>;
+    /** Download the candidate, verify its attestations against it, and hand back the verified file. */
+    readonly verifyProvenance: (candidate: RegistryCandidate) => Promise<Provenance>;
     readonly run: (cmd: string[]) => StepResult;
     /** The version recorded in `installed.lock`; `''` when unknown. */
     readonly readInstalled: () => string;
@@ -243,9 +243,10 @@ function release_lock(deps: Pick<UnattendedDeps, 'lockPath' | 'pid'>): void {
 
 // --- the run -----------------------------------------------------------------
 
-function install_steps(version: string, deps: UnattendedDeps): string[][] {
+/** `spec` is the verified tarball for an upgrade, and `<package>@<version>` only for a restore. */
+function install_steps(spec: string, deps: UnattendedDeps): string[][] {
     return [
-        ['npm', 'install', '-g', `${PACKAGE_NAME}@${version}`],
+        ['npm', 'install', '-g', spec],
         [deps.agentConfigBin, 'global', '--no-ui'],
         ...deps.globalSettings.map((target) => [deps.agentConfigBin, 'settings:sync', '--path', target]),
     ];
@@ -263,7 +264,7 @@ function run_steps(steps: string[][], deps: UnattendedDeps, honourSignal = true)
 
 /** Restored means both the binary and `installed.lock` read the previous version again. */
 function restore(previous: string, deps: UnattendedDeps): number {
-    const back = run_steps(install_steps(previous, deps).slice(0, 2), deps, false);
+    const back = run_steps(install_steps(`${PACKAGE_NAME}@${previous}`, deps).slice(0, 2), deps, false);
     const lock = deps.readInstalled();
     const binary = deps.readBinary();
     if (back.ok && lock === previous && binary === previous) {
@@ -279,7 +280,10 @@ function restore(previous: string, deps: UnattendedDeps): number {
     return EXIT_RESTORE_FAILED;
 }
 
-async function decide(installed: string, deps: UnattendedDeps): Promise<{ candidate: RegistryCandidate } | { refused: string[] }> {
+async function decide(
+    installed: string,
+    deps: UnattendedDeps,
+): Promise<{ candidate: RegistryCandidate; tarball: string } | { refused: string[] }> {
     const fetched = await deps.fetchPackument();
     if (!fetched.ok) return { refused: [`registry unavailable: ${fetched.reason}`] };
     const candidate = read_candidate(fetched.doc);
@@ -292,85 +296,89 @@ async function decide(installed: string, deps: UnattendedDeps): Promise<{ candid
         env: { ...deps.env, now: deps.now().toISOString() },
     });
     if (!decision.install) return { refused: [...decision.reasons] };
-    // 2.1's open half. `decision` accepted an attestation that EXISTS and
-    // carries an SLSA predicate; that document is producible by any workflow
-    // in any repository with `id-token: write`, so it is checked here against
-    // the one workflow this package publishes from before anything installs.
+    // `decision` accepted an attestation that EXISTS and carries an SLSA
+    // predicate, which any workflow with `id-token: write` can produce; the
+    // tarball is verified here against pinned roots before anything installs.
     const provenance = await deps.verifyProvenance(candidate);
-    if (provenance !== null) return { refused: [provenance] };
-    return { candidate };
+    if (!provenance.ok) return { refused: [provenance.reason] };
+    return { candidate, tarball: provenance.tarball };
 }
 
+/** Largest tarball the unattended path downloads; a release is about 16 MB. */
+export const MAX_TARBALL_BYTES = 64 * 1024 * 1024;
+
 /**
- * Fetch the attestation bundle, require it to name this package's publish
- * workflow, and require its DSSE signature to verify. Returns a refusal
- * reason, or `null` when both hold.
+ * Download the candidate's tarball, check it against the packument's integrity
+ * and against both attestations, and write exactly those bytes to a private
+ * temp file — the file the install step installs. Returns that file, or why
+ * there is none.
  *
- * **This used to say the signature half was `npm audit signatures` "in the
- * install step". It was not, and never had been** — `install_steps` runs
- * `npm install -g`, `agent-config global` and `settings:sync`, and no audit.
- * The sentence described a composition nobody wrote, which is the worst shape
- * a security note can have, so it is replaced by what the code does rather
- * than corrected in place.
+ * The bytes verified and the bytes installed are one buffer: installing by
+ * `<package>@<version>` would let the registry serve different bytes to the
+ * second request than to the first.
  *
- * What runs now: the payload is tied to the workflow, the envelope's signature
- * is verified against the certificate the bundle carries, and that
- * certificate's SAN is required to name the same workflow. What does NOT run:
- * any check of who ISSUED that certificate. The residue is the
- * `dsse-trust-root` blocker on the roadmap, and
- * `verify_attestation_signature`'s header states it in full.
- *
- * A bundle that cannot be fetched REFUSES rather than passing. Unlike the live
- * session register, there is no second independent gate behind this one: an
- * unreachable attestation is exactly what an attacker serving a tarball
- * without one produces, so failing open here would hand back the property the
- * check exists to establish.
+ * Every URL comes from the packument, so each must be on the registry's own
+ * origin; a hostile answer would otherwise choose both the host fetched and the
+ * document verified. A fetch that fails REFUSES rather than passing: an
+ * unreachable attestation is exactly what an attacker serving a tarball without
+ * one produces.
  */
 export async function verify_provenance_default(
     candidate: RegistryCandidate,
     fetch_impl: typeof fetch = fetch,
-    timeoutMs = 10_000,
-): Promise<string | null> {
-    if (candidate.attestationsUrl === null) {
-        return `${candidate.version} carries no attestation bundle to verify`;
+    timeoutMs = 60_000,
+    verify: (release: ReleaseToVerify) => Promise<string | null> = (r) => verify_release_provenance(r),
+): Promise<Provenance> {
+    const v = candidate.version;
+    const registry = new URL(PACKUMENT_URL).origin;
+    const refuse = (reason: string): Provenance => ({ ok: false, reason: `${v}: ${reason}` });
+    for (const [what, url] of [
+        ['attestation bundle', candidate.attestationsUrl],
+        ['tarball', candidate.tarballUrl],
+    ] as const) {
+        if (url === null) return refuse(`the registry names no ${what} to verify`);
+        let origin = '';
+        try {
+            origin = new URL(url).origin;
+        } catch {
+            // an unparsable URL is refused below like a foreign one
+        }
+        if (origin !== registry) return refuse(`the ${what} url is not on ${registry}`);
     }
-    // The URL comes from the packument, so a hostile registry answer would
-    // otherwise choose both the host fetched and the document verified.
-    let origin: string;
+    const integrity = /^sha512-([A-Za-z0-9+/=]+)$/.exec(candidate.integrity ?? '');
+    if (integrity === null) return refuse('the registry records no sha512 integrity for the tarball');
+
+    const get = async (url: string): Promise<Response> => {
+        const resp = await fetch_impl(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
+        if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+        return resp;
+    };
+    let attestations: unknown;
+    let bytes: Buffer;
     try {
-        origin = new URL(candidate.attestationsUrl).origin;
-    } catch {
-        origin = '';
+        attestations = await (await get(candidate.attestationsUrl as string)).json();
+        const resp = await get(candidate.tarballUrl as string);
+        if (Number(resp.headers.get('content-length') ?? 0) > MAX_TARBALL_BYTES) return refuse('the tarball is larger than allowed');
+        bytes = Buffer.from(await resp.arrayBuffer());
+    } catch (err) {
+        return refuse(`download failed: ${err instanceof Error ? err.message : String(err)}`);
     }
-    if (origin !== new URL(PACKUMENT_URL).origin) {
-        return `${candidate.version}: attestation url is not on ${new URL(PACKUMENT_URL).origin}`;
+    if (bytes.length > MAX_TARBALL_BYTES) return refuse('the tarball is larger than allowed');
+    const digest = crypto.createHash('sha512').update(bytes).digest();
+    if (!digest.equals(Buffer.from(integrity[1] as string, 'base64'))) {
+        return refuse('the downloaded tarball does not match the integrity the registry records');
     }
-    let doc: unknown;
+    const reason = await verify({ version: v, tarballSha512Hex: digest.toString('hex'), attestations });
+    if (reason !== null) return refuse(reason);
+
     try {
-        const resp = await fetch_impl(candidate.attestationsUrl, {
-            signal: AbortSignal.timeout(timeoutMs),
-            headers: { accept: 'application/json' },
-            redirect: 'error',
-        });
-        if (!resp.ok) return `attestation fetch failed: HTTP ${resp.status}`;
-        doc = await resp.json();
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-config-upgrade-'));
+        const tarball = path.join(dir, `agent-config-${v}.tgz`);
+        fs.writeFileSync(tarball, bytes, { mode: 0o600, flag: 'wx' });
+        return { ok: true, tarball };
     } catch (err) {
-        return `attestation fetch failed: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    if (!provenance_matches_publish(doc)) {
-        const named = attestation_workflow_ref(doc);
-        return named === null
-            ? `${candidate.version} has no readable provenance workflow in its attestation`
-            : `${candidate.version} was built by ${named}, not ${EXPECTED_WORKFLOW_REF}`;
+        return refuse(`cannot write the verified tarball: ${err instanceof Error ? err.message : String(err)}`);
     }
-    // The payload says the right thing; this asks whether the payload is the
-    // one that was signed, and whether the certificate that signed it carries
-    // the same identity. It does NOT establish who issued that certificate —
-    // see `verify_attestation_signature`'s own note and the `dsse-trust-root`
-    // blocker, which is where the trust root is decided.
-    const signature = await verify_attestation_signature(doc);
-    if (signature !== null) return `${candidate.version}: ${signature}`;
-    return null;
 }
 
 /** Contexts where even the registry fetch and the lock file are side effects nobody asked for. */
@@ -397,14 +405,16 @@ export async function run_unattended(deps: UnattendedDeps): Promise<number> {
         say(deps.err, `${PREFIX}: not installing — ${locked}.`);
         return EXIT_REFUSED;
     }
+    let verified: string | null = null;
     try {
         const verdict = await decide(previous, deps);
         if ('refused' in verdict) {
             say(deps.out, `ℹ️  ${PREFIX}: not installing (installed: ${previous}) — ${verdict.refused.join('; ')}.`);
             return EXIT_REFUSED;
         }
+        verified = verdict.tarball;
         const target = verdict.candidate.version;
-        const steps = install_steps(target, deps);
+        const steps = install_steps(verified, deps);
         if (deps.activationBlocked !== null) {
             const how = deps.dryRun ? 'dry run: a real run would not install' : 'not installing';
             say(deps.out, `ℹ️  ${PREFIX}: every gate passed for ${target}, but ${how} — ${deps.activationBlocked}.`);
@@ -422,10 +432,13 @@ export async function run_unattended(deps: UnattendedDeps): Promise<number> {
         }
         const what = `${ran.cmd.join(' ')} (exit ${ran.result.rc})`;
         if (/\bEACCES\b/.test(ran.result.stderr)) {
+            // The verified file is removed when this run ends, so the command a
+            // person can still run names the version instead.
+            const manual = ran.cmd === steps[0] ? ['npm', 'install', '-g', `${PACKAGE_NAME}@${target}`] : ran.cmd;
             say(
                 deps.err,
                 `❌  ${PREFIX}: permission denied on ${what}. agent-config never runs sudo; ` +
-                    `run this yourself with the right permissions: ${ran.cmd.join(' ')}`,
+                    `run this yourself with the right permissions: ${manual.join(' ')}`,
             );
             // Denied on the very first write, npm changed nothing; any later step leaves a mixed install.
             const untouched = ran.cmd === steps[0] && deps.readInstalled() === previous && deps.readBinary() === previous;
@@ -435,6 +448,7 @@ export async function run_unattended(deps: UnattendedDeps): Promise<number> {
         say(deps.err, `❌  ${PREFIX}: step failed: ${what} — restoring ${previous}.`);
         return restore(previous, deps);
     } finally {
+        if (verified !== null) fs.rmSync(path.dirname(verified), { recursive: true, force: true });
         release_lock(deps);
     }
 }

package/src/scripts/_dispatch.bash

@@ -104,7 +104,8 @@ EOF
     cat <<'EOF'
 
 Tier 1 — power-user (release shape, audit, migration):
-  update                     Update the agent_config_version pin in .agent-settings.yml
+  update                     Pin agent_config_version in .agent-settings.yml; installs that
+                             version globally first when the global install is older
                              Flags: --check (read-only) | --to <version> (explicit pin)
   upgrade                    Install the latest @event4u/agent-config globally
                              (npm i -g) and refresh the global install + plugin.
@@ -1400,7 +1401,7 @@ cmd_use() {
 }
 
 # `agent-config update` — flip the agent_config_version pin in
-# .agent-settings.yml. See scripts/_cli/cmd_update.ts (P3.1 of
+# .agent-settings.yml, upgrading the global install first when it is older. See scripts/_cli/cmd_update.ts (P3.1 of
 # road-to-portable-runtime-and-update-check.md).
 cmd_update() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_update.ts" "$@"