Fix: verify against the pinned artifact, not HEAD -- ModelRuntime does not exist in 0.80.7

CI caught this on the first container run and it is the most important mistake of the
project so far, because it is methodological rather than local.

Every upstream claim in this repo was verified by reading source at
earendil-works/pi@5e336cf. That is HEAD. The image pins npm 0.80.7. Those are different
artifacts and nothing here ever checked they agreed.

ModelRuntime is a value export at that sha and does not exist in 0.80.7 at all: no
model-runtime module in dist/, not exported from dist/index.js. pi's changelog files the
migration under [Unreleased] -- which was exactly correct -- and OQ-005 had "corrected"
the changelog for being out of date, concluding "the changelog is not a reliable signal".
The changelog was right. The methodology was wrong. The runner imported the phantom API,
the image built cleanly, and every job would have died on a missing export.

The real 0.80.7 wiring, read from the tarball:
  AuthStorage.create(authPath)                       // sync
  ModelRegistry.create(authStorage, modelsPath)      // sync
  modelRegistry.find(provider, modelId)              // NOT getModel
  modelRegistry.hasConfiguredAuth(model)
  createAgentSession({ authStorage, modelRegistry, model, ... })

Everything else survives the pin, which is why the loader assertions passed: noContextFiles,
noSkills, noExtensions, additionalSkillPaths, additionalExtensionPaths,
appendSystemPromptOverride and SettingsManager.inMemory are all present at 0.80.7. The
instruction model was never affected -- only the model/auth wiring.

Fixes:
- run-job.mjs uses AuthStorage + ModelRegistry, and checks hasConfiguredAuth before the
  container spends anything.
- constitution.md's evidence convention now says a sha is not a version. A sha citation
  establishes where behaviour lives and nothing about whether the pinned release contains
  it: necessary, not sufficient. Claims the code depends on must hold in the published
  artifact -- npm pack it, or assert it in a test that imports what the lockfile resolves.
- interfaces.md separates "Evidence (pinned artifact -- authoritative)" from "Evidence
  (HEAD -- explains behaviour, does NOT establish the pin contains it)".
- OQ-005 retracted and re-corrected, with the wrong entry kept struck through rather than
  deleted: a spec that hides having been wrong teaches the next reader to trust it more
  than it deserves.
- pinned-api.test.mjs asserts every symbol run-job.mjs imports exists in the resolved
  package, and asserts ModelRuntime is ABSENT -- so the day the migration ships, a test
  fails with a message instead of a container failing with a stack trace.

Also fixed: the CI in-image assertions all ran `docker run img <cmd>` while ENTRYPOINT is
the runner and ignores CMD, so they silently tested the runner instead of what they named.
Every one now overrides --entrypoint.

Author: edgehero

.github/workflows/pi-upgrade-check.yml

@@ -96,22 +96,24 @@ jobs:
       # `pi --mode print` does not exist: --mode accepts text|json|rpc, and --print/-p is a separate
       # boolean. --help rather than a real prompt, because a real prompt needs a paid API key and a
       # contract test that costs money is a contract test that gets disabled.
+      # --entrypoint is required: ENTRYPOINT is the runner and ignores CMD, so `docker run img pi ...`
+      # would silently run the runner instead of pi and the assertion would test nothing.
       - name: pi -p is still a flag
-        run: docker run --rm pi-job:ci pi -p --help >/dev/null
+        run: docker run --rm --entrypoint pi pi-job:ci -p --help >/dev/null
 
       # --- CONST-ISOLATION-CONTAINER-PER-JOB ---
       # --cap-drop=ALL is the enforcement surface. Read the effective capability set directly rather
       # than install libcap just to ask.
       - name: No capabilities under --cap-drop=ALL
         run: |
-          caps=$(docker run --rm --cap-drop=ALL --security-opt no-new-privileges pi-job:ci \
-                   sh -c 'grep ^CapEff /proc/self/status' | awk '{print $2}')
+          caps=$(docker run --rm --cap-drop=ALL --security-opt no-new-privileges \
+                   --entrypoint sh pi-job:ci -c 'grep ^CapEff /proc/self/status' | awk '{print $2}')
           [ "$caps" = "0000000000000000" ] || { echo "::error::Container retains capabilities: $caps"; exit 1; }
           echo "OK: CapEff=$caps"
 
       - name: Runs as a non-root user
         run: |
-          uid=$(docker run --rm pi-job:ci id -u)
+          uid=$(docker run --rm --entrypoint id pi-job:ci -u)
           [ "$uid" != "0" ] || { echo "::error::Job container runs as root."; exit 1; }
 
       # --- INT-CONTAINER-JOB-INPUTS ---
@@ -121,8 +123,8 @@ jobs:
         run: |
           mkdir -p fixture/pi
           echo "x" > fixture/pi/APPEND_SYSTEM.md
-          if docker run --rm --cap-drop=ALL -v "$PWD/fixture:/job:ro" pi-job:ci \
-               sh -c 'echo pwned > /job/pi/APPEND_SYSTEM.md' 2>/dev/null; then
+          if docker run --rm --cap-drop=ALL -v "$PWD/fixture:/job:ro" --entrypoint sh pi-job:ci \
+               -c 'echo pwned > /job/pi/APPEND_SYSTEM.md' 2>/dev/null; then
             echo "::error::/job is writable. The agent can rewrite its own instructions."
             exit 1
           fi
@@ -133,11 +135,11 @@ jobs:
       # dir is root-owned the job dies EACCES at runtime, on a path nothing in the Dockerfile hints
       # at. COPY --chown does not fix it (it skips auto-created parents), so assert the real thing.
       - name: The agent dir is writable by the runtime user
-        run: docker run --rm pi-job:ci sh -c 'touch "$HOME/.pi/agent/auth.json" && rm "$HOME/.pi/agent/auth.json"'
+        run: docker run --rm --entrypoint sh pi-job:ci -c 'touch "$HOME/.pi/agent/auth.json" && rm "$HOME/.pi/agent/auth.json"'
 
       - name: The guardrails are baked where the runner reads them
         run: |
-          docker run --rm pi-job:ci grep -q "pi-dispatch-guardrails-v1" /opt/pi-dispatch/HARD_RULES.md \
+          docker run --rm --entrypoint grep pi-job:ci -q "pi-dispatch-guardrails-v1" /opt/pi-dispatch/HARD_RULES.md \
             || { echo "::error::Guardrails sentinel missing from /opt/pi-dispatch/HARD_RULES.md"; exit 1; }
 
       # --- DES-PLAYWRIGHT-CLI-NOT-CHROME-DEVTOOLS / REQ-FRONTEND-VISUAL-VERIFY ---
@@ -149,14 +151,14 @@ jobs:
         run: |
           echo '<html><body><h1>pi-dispatch</h1></body></html>' > fixture/page.html
           docker run --rm --init --cap-drop=ALL --security-opt no-new-privileges --shm-size=1g \
-            -v "$PWD/fixture:/fixture:ro" pi-job:ci \
-            sh -c 'playwright-cli screenshot --browser-arg=--no-sandbox file:///fixture/page.html /tmp/x.png && test -s /tmp/x.png' \
+            -v "$PWD/fixture:/fixture:ro" --entrypoint sh pi-job:ci \
+            -c 'playwright-cli screenshot --browser-arg=--no-sandbox file:///fixture/page.html /tmp/x.png && test -s /tmp/x.png' \
             || { echo "::error::Chromium unusable as non-root — check PLAYWRIGHT_BROWSERS_PATH at build AND run"; exit 1; }
 
       # Fonts absent => tofu boxes => screenshots that look fine and contain no legible text. That
       # silently guts the requirement full Chromium is in this image for.
       - name: Fonts are installed (or screenshots are tofu)
         run: |
-          n=$(docker run --rm pi-job:ci sh -c 'fc-list | wc -l')
+          n=$(docker run --rm --entrypoint sh pi-job:ci -c 'fc-list | wc -l')
           [ "$n" -gt 0 ] || { echo "::error::No fonts. Chromium will render boxes and REQ-FRONTEND-VISUAL-VERIFY is a lie."; exit 1; }
           echo "OK: $n fonts"

image/runner/run-job.mjs

@@ -1,8 +1,9 @@
 import { readFileSync } from "node:fs";
 import {
+	AuthStorage,
 	createAgentSession,
 	getAgentDir,
-	ModelRuntime,
+	ModelRegistry,
 	SessionManager,
 	SettingsManager,
 } from "@earendil-works/pi-coding-agent";
@@ -29,20 +30,32 @@ async function main() {
 	const maxTurns = Number.parseInt(requireEnv("PI_MAX_TURNS"), 10);
 
 	const agentDir = getAgentDir();
-	const modelRuntime = await ModelRuntime.create({
-		authPath: `${agentDir}/auth.json`,
-		modelsPath: `${agentDir}/models.json`,
-	});
 
-	// Pin the model explicitly. With `model` omitted, findInitialModel picks from settings
-	// and provider defaults -- nondeterministic across images, and it silently changes cost
-	// per job. A missing model yields modelFallbackMessage on the RESULT rather than a
-	// throw, so validate here and fail loudly instead of discovering it in a bill.
-	const model = modelRuntime.getModel(provider, modelId);
+	// AuthStorage + ModelRegistry, NOT ModelRuntime.
+	//
+	// pi's [Unreleased] changelog says these two are replaced by an async `modelRuntime`.
+	// That is true of its main branch and NOT of 0.80.7, which is what we pin -- the source
+	// at HEAD and the artifact on npm are different things, and conflating them cost a build.
+	// When the migration ships, REQ-UPSTREAM-CONTRACT-TESTS fires on the pin bump and this
+	// is the code that changes. See OQ-005.
+	const authStorage = AuthStorage.create(`${agentDir}/auth.json`);
+	const modelRegistry = ModelRegistry.create(authStorage, `${agentDir}/models.json`);
+
+	// Pin the model explicitly. With `model` omitted, pi picks from settings and provider
+	// defaults -- nondeterministic across images, and it silently changes cost per job. A
+	// missing model surfaces as a fallback message on the RESULT rather than a throw, so
+	// validate here and fail loudly instead of discovering it on a bill.
+	const model = modelRegistry.find(provider, modelId);
 	if (!model) {
 		log("model_unknown", { provider, modelId });
 		return EXIT_POLICY; // config error: retrying cannot fix it
 	}
+	if (!modelRegistry.hasConfiguredAuth(model)) {
+		// Catch this before the container spends anything. Preflight would throw on it
+		// anyway, but a clear signal beats parsing a message out of an exception.
+		log("model_no_auth", { provider, modelId });
+		return EXIT_POLICY;
+	}
 
 	// Pin pi's own retry settings rather than inherit `maxRetries ?? 3`. An upstream default
 	// change would silently move our spend -- CONST-PI-VERSION-PINNED's reasoning, applied to
@@ -62,7 +75,8 @@ async function main() {
 	const { session } = await createAgentSession({
 		cwd: WORKSPACE,
 		agentDir,
-		modelRuntime,
+		authStorage,
+		modelRegistry,
 		model,
 		settingsManager,
 		sessionManager: SessionManager.inMemory(WORKSPACE),

image/runner/test/pinned-api.test.mjs

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+
+/**
+ * REQ-UPSTREAM-CONTRACT-TESTS -- assert against the PINNED ARTIFACT, not against HEAD.
+ *
+ * This exists because of a real and expensive mistake. Every claim about pi in this
+ * project was verified by reading source at `earendil-works/pi @ 5e336cf` -- which is
+ * HEAD, not the 0.80.7 release we pin. `ModelRuntime` is a value export in that source
+ * and DOES NOT EXIST in 0.80.7 at all: pi's changelog files it under [Unreleased] and
+ * the changelog was exactly right. The runner imported it, the image built cleanly, and
+ * every job would have died on a missing export.
+ *
+ * Reading a moving branch to verify a fixed version is not verification. These tests
+ * import the package the lockfile actually resolves and assert the symbols exist there,
+ * so the next time HEAD and the pin disagree, a test says so instead of a container.
+ */
+const pkg = "@earendil-works/pi-coding-agent";
+
+let mod;
+let importError;
+try {
+	mod = await import(pkg);
+} catch (error) {
+	importError = error;
+}
+
+const required = process.env.PI_DISPATCH_REQUIRE_LOADER_TESTS === "1";
+if (!mod && required) {
+	throw new Error(`${pkg} must be importable here; a skip would hide a pin/HEAD mismatch.\n${importError}`);
+}
+const skip = mod ? false : `pi not installed (node ${process.version} < 22.19.0); CI runs these`;
+
+/** Every value the runner imports at runtime. If pi drops one, the job dies on module load. */
+const REQUIRED_VALUE_EXPORTS = [
+	"createAgentSession",
+	"getAgentDir",
+	"AuthStorage",
+	"ModelRegistry",
+	"SessionManager",
+	"SettingsManager",
+	"DefaultResourceLoader",
+];
+
+test("the pinned package exports everything the runner imports", { skip }, () => {
+	const missing = REQUIRED_VALUE_EXPORTS.filter((name) => typeof mod[name] === "undefined");
+	assert.deepEqual(missing, [], `pinned ${pkg} is missing value exports the runner needs: ${missing}`);
+});
+
+test("model/auth wiring is the 0.80.7 shape, not HEAD's", { skip }, () => {
+	// The [Unreleased] migration replaces these two with an async ModelRuntime. When the pin
+	// moves past it, THIS fails -- which is the signal to rewrite run-job.mjs's wiring,
+	// rather than discovering it when every queued job becomes a no-op.
+	assert.equal(typeof mod.AuthStorage?.create, "function", "AuthStorage.create missing");
+	assert.equal(typeof mod.ModelRegistry?.create, "function", "ModelRegistry.create missing");
+	assert.equal(
+		typeof mod.ModelRuntime,
+		"undefined",
+		"ModelRuntime now EXISTS at the pin -- the [Unreleased] migration shipped. " +
+			"Rewrite run-job.mjs to modelRuntime and re-verify sdk.d.ts before bumping.",
+	);
+});
+
+test("the resource-loader options the instruction model depends on still exist", { skip }, () => {
+	// These are asserted behaviourally in loader.test.mjs, but a rename would fail there with
+	// a confusing symptom (an empty prompt) rather than a clear one. This names them.
+	const loader = Object.getOwnPropertyNames(mod.DefaultResourceLoader?.prototype ?? {});
+	for (const method of ["reload", "getAppendSystemPrompt", "getAgentsFiles", "getSkills"]) {
+		assert.ok(loader.includes(method), `DefaultResourceLoader.${method} missing at the pin`);
+	}
+});
+
+test("the runner imports nothing the pinned package does not export", { skip }, () => {
+	// Catches a new import added to run-job.mjs that only exists at HEAD -- the exact
+	// mistake this file was written for, generalised so it cannot recur silently.
+	const source = readFileSync(fileURLToPath(new URL("../run-job.mjs", import.meta.url)), "utf8");
+	const block = source.match(/import\s*\{([^}]+)\}\s*from\s*["']@earendil-works\/pi-coding-agent["']/);
+	assert.ok(block, "could not find the runner's pi import block");
+
+	const imported = block[1]
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean);
+	const missing = imported.filter((name) => typeof mod[name] === "undefined");
+	assert.deepEqual(missing, [], `run-job.mjs imports symbols absent from the pinned package: ${missing}`);
+});

specs/constitution.md

@@ -19,6 +19,29 @@ was verified against pi's docs across two adversarial passes, recorded 48/50 cla
 wrong on roughly seven points within twenty-four hours — every one of them found by reading source. For
 a dependency that moves this fast, docs are a hint.
 
+**Verify against the PINNED ARTIFACT, not against HEAD. A sha is not a version.** This rule is written
+in blood: every upstream claim in this repository was originally verified by reading source at
+`earendil-works/pi @ 5e336cf`, while the image pins **npm `0.80.7`**. Those are different artifacts.
+`ModelRuntime` is a value export at that sha and **does not exist in 0.80.7 at all** — pi's changelog
+files it under `[Unreleased]`, which was exactly correct, and a spec entry here "corrected" the
+changelog for being out of date. The changelog was right; the methodology was wrong. The runner imported
+it, the image built cleanly, and every job would have died on a missing export.
+
+Reading a moving branch to verify a fixed version is not verification — it is verification of something
+else. So:
+
+- A sha citation establishes *where the behaviour lives and why*, and nothing about whether the pinned
+  release contains it. It is necessary and **not sufficient**.
+- Any claim the code depends on must additionally hold in the **published artifact**: `npm pack` it and
+  read `dist/`, or assert it in a test that imports what the lockfile resolves.
+- Prefer the release tag over `main`. Where a sha is cited, state its relationship to the pin.
+- `REQ-UPSTREAM-CONTRACT-TESTS` is the enforcement: `image/runner/test/pinned-api.test.mjs` asserts the
+  runner's imports exist in the resolved package, so the next pin/HEAD divergence fails a test rather
+  than a container.
+
+The failure this guards is the familiar one: it is **silent**. HEAD and the pin agree often enough that
+the habit forms, and the day they disagree the build still passes.
+
 **Two evidence classes, deliberately.** `Evidence (upstream)` and `Code evidence` have different drift
 semantics and must not share a field: upstream facts are pinned to *pi's* sha and must never be
 drift-checked against *our* HEAD. `detect_drift.py` keys only on the literal `- **Code evidence**:`, so

specs/interfaces.md

@@ -21,10 +21,17 @@ Evidence convention as in `constitution.md`.
 *invisibly*.
 
 - **Contract**:
+  **Verified against the published `0.80.7` tarball, not against HEAD** — see the evidence convention
+  in `constitution.md`. At this pin the model/auth wiring is `AuthStorage` + `ModelRegistry`. There is
+  **no `ModelRuntime`**: that is HEAD-only, `[Unreleased]`, and importing it makes every job die on a
+  missing export while the image builds cleanly.
+
   ```typescript
-  const modelRuntime = await ModelRuntime.create({ authPath, modelsPath });
-  const model = modelRuntime.getModel(process.env.PI_PROVIDER, process.env.PI_MODEL);
+  const authStorage   = AuthStorage.create(`${agentDir}/auth.json`);
+  const modelRegistry = ModelRegistry.create(authStorage, `${agentDir}/models.json`);
+  const model = modelRegistry.find(process.env.PI_PROVIDER, process.env.PI_MODEL);  // NOT getModel
   if (!model) throw new InfraError(`unknown model`);   // exit 2 — config, not retryable
+  if (!modelRegistry.hasConfiguredAuth(model)) throw new InfraError(`no auth`);      // exit 2
 
   // Guardrails read EXPLICITLY from a path we own — never via discovery. See (e).
   const guardrails    = readFileSync("/opt/pi-dispatch/HARD_RULES.md", "utf8");
@@ -46,7 +53,8 @@ Evidence convention as in `constitution.md`.
   const { session } = await createAgentSession({
     cwd: "/workspace",
     agentDir: getAgentDir(),
-    modelRuntime,
+    authStorage,
+    modelRegistry,
     model,
     sessionManager: SessionManager.inMemory("/workspace"),
     settingsManager: SettingsManager.inMemory({ retry: { maxRetries, baseDelayMs } }),
@@ -108,24 +116,34 @@ Evidence convention as in `constitution.md`.
   `noSkills: true` + `additionalSkillPaths` loads *exactly* what we hand it and nothing from the tree.
   Explicit beats gated: the same principle as `noContextFiles` + an explicit read.
 
-  `modelRuntime.getModel(provider, modelId)` is a **method**, not a free function; there is no exported
-  `getModel`. Pin the model explicitly: with `model` omitted, `findInitialModel` picks from settings and
-  provider defaults, which is nondeterministic across images and silently changes cost per job. A missing
-  model yields a `modelFallbackMessage` on the *result*, not a throw — validate and fail loudly.
+  `modelRegistry.find(provider, modelId)` is a **method**, not a free function; there is no exported
+  `getModel`. Pin the model explicitly: with `model` omitted, pi picks from settings and provider
+  defaults, which is nondeterministic across images and silently changes cost per job. A missing model
+  yields a fallback message on the *result*, not a throw — validate and fail loudly.
   `SessionManager.inMemory()` because the container is ephemeral: session storage would write to a
   filesystem that is about to cease existing.
   `SettingsManager.inMemory()` is load-bearing beyond the retry pin: it writes our settings to the
   **global** scope of a storage with **no project file**, so a serviced project's `.pi/settings.json` is
   never read and **cannot override our spend controls**. `SettingsManager.create(cwd, agentDir)` would
   read it and `deepMergeSettings(global, project)` lets project win. Use `inMemory`. Deliberately.
 
-  The complete option set is `cwd`, `agentDir`, `modelRuntime`, `model`, `thinkingLevel`, `scopedModels`,
-  `noTools`, `tools`, `excludeTools`, `customTools`, `resourceLoader`, `sessionManager`,
-  `settingsManager`, `sessionStartEvent`. Note `modelRuntime` is **already present at the pin** — part of
-  `OQ-005`'s migration has landed.
-- **Evidence (upstream)**: `earendil-works/pi @ 5e336cf → packages/coding-agent/src/core/sdk.ts:33-80`
+  The complete option set **at 0.80.7** is `cwd`, `agentDir`, `authStorage`, `modelRegistry`, `model`,
+  `thinkingLevel`, `scopedModels`, `noTools`, `tools`, `excludeTools`, `customTools`, `resourceLoader`,
+  `sessionManager`, `settingsManager`, `sessionStartEvent`. `OQ-005`'s migration replaces the first two
+  with an async `modelRuntime` and **has not shipped** — it exists only on `main`.
+- **Evidence (pinned artifact — authoritative)**: `npm @earendil-works/pi-coding-agent@0.80.7 →
+  dist/core/sdk.d.ts → CreateAgentSessionOptions` — `authStorage?: AuthStorage` ("Default:
+  AuthStorage.create(agentDir/auth.json)"), `modelRegistry?: ModelRegistry` ("Default:
+  ModelRegistry.create(authStorage, agentDir/models.json)"); **no `modelRuntime` field, and no
+  `model-runtime` module in `dist/` at all** · `→ dist/core/model-registry.d.ts → find(provider, modelId)`,
+  `hasConfiguredAuth(model)`, `getAvailable()`, `getAll()`, `static create(authStorage, modelsJsonPath?)`
+  · `→ dist/index.js` — `AuthStorage` and `ModelRegistry` are value exports; `ModelRuntime` is absent ·
+  `→ dist/core/resource-loader.d.ts` — `noContextFiles`, `noSkills`, `noExtensions`,
+  `additionalSkillPaths`, `additionalExtensionPaths`, `appendSystemPromptOverride` all present at the pin
+- **Evidence (HEAD — explains behaviour, does NOT establish the pin contains it)**:
+  `earendil-works/pi @ 5e336cf → packages/coding-agent/src/core/sdk.ts:33-80`
   (option set; no append fields, `resourceLoader?: ResourceLoader`) · `→ sdk.ts:164` (`createAgentSession`
-  is async) · `→ sdk.ts:171` (`ModelRuntime.create`, async) · `→ sdk.ts:176-180` (default loader is built
+  is async) · `→ sdk.ts:176-180` (default loader is built
   **and `reload()`ed** only when none is passed) · `→ sdk.ts:187-217` (`findInitialModel` fallback;
   `modelFallbackMessage` returned, not thrown) · `→ resource-loader.ts:122-157`
   (`DefaultResourceLoaderOptions`; `cwd`/`agentDir` **required**) · `→ resource-loader.ts:156`