forgedock 1.48.1 → 1.50.0

package/bin/lean/execution.mjs

@@ -32,6 +32,9 @@
  * `openExecutionBudget` enforces the hard caps (`budget_minutes`/`budget_usd` per batch, `day_budget_*` per host UTC day,
  * from the host-day store `execution-budget.json` in the sched dir): pure arithmetic, no LLM.
  *
+ * #5112: `execution.capacity_fallback_after` (positive integer, `capacityFallbackAfter`) is how many `sandbox.capacity` deferrals of one
+ * issue make `fallback_local` run it on the host (orchestrate `CAPACITY_FALLBACK_AFTER` when unset), gated by `hostHeadroom`.
+ *
  * Hybrid (#4256): `placeLane` places each lane from facts (lane kind, validation weight, host headroom, verify.mode);
  * orchestrate runs a remote-placed lane locally when `max_remote` or the execution budget is exhausted.
  *
@@ -113,9 +116,12 @@ export function parseExecution(sec = {}) {
   let endpoint = null;
   try { const u = new URL(str(s.endpoint)); if (u.protocol === "https:" || u.protocol === "http:") endpoint = str(s.endpoint); } catch { endpoint = null; }
   const tokenEnv = ENV_RE.test(str(s.token_env)) ? str(s.token_env) : null;
+  const tokenFile = str(s.token_file) || null; // #5131: explicit pool/remote token file
   const cacheStore = str(s.cache_store) || null;
   const allowActions = str(s.allow_actions).toLowerCase() === "true";
   const fallbackLocal = str(s.fallback_local).toLowerCase() === "true";
+  const cfa = Number(str(s.capacity_fallback_after));
+  const capacityFallbackAfter = Number.isInteger(cfa) && cfa > 0 ? cfa : null; // #5112: unset: orchestrate's CAPACITY_FALLBACK_AFTER
   const heavyRaw = str(s.heavy).toLowerCase();
   const heavy = heavyRaw === "true" ? true : heavyRaw === "false" ? false : null;
   const cap = (v) => { const t = str(v), x = Number(t); return t !== "" && Number.isFinite(x) && x >= 0 ? x : null; };
@@ -133,7 +139,7 @@ export function parseExecution(sec = {}) {
   const uw = Number(str(s.unreachable_window_min));
   const accountRotator = str(s.account_rotator) === "tokenbaton" ? "tokenbaton" : null; // #5094: rotator.mjs reads its per-account quota state
   const unreachableWindowMin = str(s.unreachable_window_min) !== "" && Number.isFinite(uw) && uw >= 0 ? uw : null; // unset: providerLanes defaults to 5
-  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(heavy !== null ? { heavy } : {}), ...(unreachableWindowMin !== null ? { unreachableWindowMin } : {}), ...(Object.keys(relay).length ? { relay } : {}), ...(warmSandboxes ? { warmSandboxes } : {}), ...(accountRotator ? { accountRotator } : {}) };
+  return { mode, maxRemote, provider, image, secrets, budget, ...(hostCapabilities.length ? { hostCapabilities } : {}), ...(hostCapabilityPatterns.length ? { hostCapabilityPatterns } : {}), ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(tokenFile ? { tokenFile } : {}), ...(cacheStore ? { cacheStore } : {}), ...(allowActions ? { allowActions } : {}), ...(fallbackLocal ? { fallbackLocal } : {}), ...(capacityFallbackAfter !== null ? { capacityFallbackAfter } : {}), ...(heavy !== null ? { heavy } : {}), ...(unreachableWindowMin !== null ? { unreachableWindowMin } : {}), ...(Object.keys(relay).length ? { relay } : {}), ...(warmSandboxes ? { warmSandboxes } : {}), ...(accountRotator ? { accountRotator } : {}) };
 }
 
 const round1 = (x) => Math.round(x * 10) / 10;
@@ -480,18 +486,49 @@ export function containerProvider({ batch, repo, image, gitDir, cacheDir = `${ho
 
 const typedError = (code, message) => Object.assign(new Error(message), { code });
 
+/** #5131: an endpoint as `scheme://host:port` (default ports filled, no path or trailing slash); null when unparsable. */
+const endpointKey = (u) => { try { const x = new URL(String(u)); return `${x.protocol}//${x.hostname}:${x.port || (x.protocol === "https:" ? "443" : "80")}`; } catch { return null; } };
+
+/** #5131: the trimmed contents of a token file (`~/` is the home dir); null when unset, unreadable or empty. */
+const readTokenFile = (file) => {
+  if (!file) return null;
+  try { return readFileSync(String(file).startsWith("~/") ? join(homedir(), String(file).slice(2)) : String(file), "utf8").trim() || null; } catch { return null; }
+};
+
+/**
+ * #5131: the one pool/remote credential resolver, shared by both providers, `remoteTransportFor` and `preflight.pool_auth`:
+ * `token_env` from the env, then the keychain; then `execution.token_file`; then the local router's `forgedock_token_file`
+ * (`router`, poolRouterConfig output): always for `pool`, for `remote` only when its endpoint is unset or the router's.
+ * Returns `{token, source}`; `source` names where it came from (env name, `token_file`, `forgedock_token_file`), never the value.
+ */
+export function poolCredential(exec = {}, { env = process.env, router = null, keychain } = {}) {
+  if (exec?.tokenEnv) {
+    const v = resolveCredential(exec.tokenEnv, { env, ...(keychain ? { keychain } : {}) });
+    if (v) return { token: v, source: exec.tokenEnv };
+  }
+  const f = readTokenFile(exec?.tokenFile);
+  if (f) return { token: f, source: "token_file" };
+  const routerOk = Boolean(router?.token) && ((exec?.provider ?? "pool") === "pool" || !exec?.endpoint || endpointKey(exec.endpoint) === endpointKey(router.endpoint));
+  return routerOk ? { token: router.token, source: "forgedock_token_file" } : { token: null, source: null };
+}
+
 /**
  * The remote transport for forge.yaml `execution` settings: `opts.transport` when injected, else `httpTransport` on
- * `exec.endpoint` with the credential `exec.tokenEnv` (env, then keychain). Throws `execution.provider.misconfigured`
+ * `exec.endpoint` with the credential `exec.tokenEnv` from `credentials`, or by default poolCredential (#5131: env,
+ * keychain, `token_file`, the matching local router's token). `fetchFn` is a test seam. Throws `execution.provider.misconfigured`
  * without an endpoint, `execution.provider.actions_refused` for a GitHub Actions endpoint without `allow_actions`.
  */
-export function remoteTransportFor(exec = {}, { transport = null, env = process.env, credentials = (n) => resolveCredential(n, { env }) } = {}) {
+export function remoteTransportFor(exec = {}, { transport = null, env = process.env, credentials = null, router, fetchFn } = {}) {
   if (transport) return transport;
   if (!exec?.endpoint) throw typedError("execution.provider.misconfigured", "execution.provider remote needs execution.endpoint");
   if (isActionsEndpoint(exec.endpoint) && exec.allowActions !== true) {
     throw typedError("execution.provider.actions_refused", "execution.endpoint is a GitHub Actions API; set execution.allow_actions: true to spend Actions minutes");
   }
-  return httpTransport({ endpoint: exec.endpoint, token: exec.tokenEnv ? credentials(exec.tokenEnv) : null });
+  // #5144: a getter, so the bearer is resolved on every request (a token fixed or rotated mid-batch is picked up), not once here.
+  const rt = credentials ? null : (router !== undefined ? router : poolRouterConfig({ env }));
+  const token = credentials ? () => (exec.tokenEnv ? credentials(exec.tokenEnv) : null)
+    : () => poolCredential({ provider: "remote", ...exec }, { env, router: rt }).token;
+  return httpTransport({ endpoint: exec.endpoint, token, ...(fetchFn ? { fetchFn } : {}) });
 }
 
 /**
@@ -510,26 +547,35 @@ export function poolRouterConfig({ env = process.env, path = env.COMPUTESHARE_CO
 export function providerByName(name, opts) {
   if (name === "local") return localProvider(opts);
   if (name === "container") return containerProvider(opts);
-  if (name === "remote") {
-    const exec = opts?.exec ?? {};
-    const env = opts?.env ?? process.env;
-    return remoteProvider({ batch: opts.batch, repo: opts.repo, settings: { ...exec, ...(typeof opts?.prefetch === "function" ? { prefetch: opts.prefetch } : {}) }, env, transport: remoteTransportFor(exec, { transport: opts?.transport, env }), ...(opts?.now ? { now: opts.now } : {}) });
-  }
-  if (name === "pool") {
-    // #4546: `remote` with the endpoint and token defaulted to the local router, and the repo's forge.yaml sent along.
+  if (name === "remote" || name === "pool") {
     const env = opts?.env ?? process.env;
     const exec = opts?.exec ?? {};
-    const router = opts?.transport || exec.endpoint ? null : poolRouterConfig({ env, ...(opts?.poolConfigPath ? { path: opts.poolConfigPath } : {}) });
-    if (!opts?.transport && !exec.endpoint && !router) throw typedError("execution.provider.misconfigured", "execution.provider pool needs a local router config (forgedock pool router) or execution.endpoint");
+    const pool = name === "pool";
+    // #4546: `pool` is `remote` with the endpoint and token defaulted to the local router, and the repo's forge.yaml sent along.
+    // #5131: `remote` reads the router config too, for the token fallback when its endpoint is the local router's.
+    const router = opts?.transport || (pool && exec.endpoint) ? null : poolRouterConfig({ env, ...(opts?.poolConfigPath ? { path: opts.poolConfigPath } : {}) });
+    if (pool && !opts?.transport && !exec.endpoint && !router) throw typedError("execution.provider.misconfigured", "execution.provider pool needs a local router config (forgedock pool router) or execution.endpoint");
     let forgeYaml = null;
-    try { forgeYaml = opts?.cwd ? readFileSync(join(opts.cwd, "forge.yaml"), "utf8") : null; } catch { forgeYaml = null; }
-    // The router's token is resolved under a fixed name so remoteProvider redacts it like any `token_env` credential.
-    const tokenEnv = exec.tokenEnv ?? (router?.token ? "FORGEDOCK_POOL_TOKEN" : undefined);
-    // #4685: an empty env/keychain lookup of a configured token_env falls back to the router's token file.
-    const credentials = (n) => (n === "FORGEDOCK_POOL_TOKEN" && !exec.tokenEnv ? router?.token ?? null : resolveCredential(n, { env }) ?? router?.token ?? null);
-    const settings = { ...exec, ...(exec.endpoint ? {} : router ? { endpoint: router.endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(forgeYaml ? { forgeYaml } : {}),
+    if (pool) { try { forgeYaml = opts?.cwd ? readFileSync(join(opts.cwd, "forge.yaml"), "utf8") : null; } catch { forgeYaml = null; } }
+    const endpoint = exec.endpoint ?? (pool ? router?.endpoint : undefined);
+    // #5144: the router's token file is re-read per call (a rotated or newly written token), its endpoint stays as at construction.
+    const routerEligible = !(opts?.transport || (pool && exec.endpoint));
+    const routerNow = () => {
+      if (!routerEligible) return null;
+      const c = poolRouterConfig({ env, ...(opts?.poolConfigPath ? { path: opts.poolConfigPath } : {}) });
+      return c ? { endpoint: router?.endpoint ?? c.endpoint, token: c.token } : router;
+    };
+    const resolve = () => poolCredential({ ...exec, provider: name, ...(endpoint ? { endpoint } : {}) }, { env, router: routerNow() });
+    // A token read from a file is resolved under a fixed name so remoteProvider redacts it like any `token_env` credential.
+    // #5144: set even when no token exists yet, so one that appears later is still resolved per call (and redacted).
+    const fixed = pool ? "FORGEDOCK_POOL_TOKEN" : "FORGEDOCK_REMOTE_TOKEN";
+    const tokenEnv = exec.tokenEnv ?? fixed;
+    // #4685/#5131: an empty env/keychain lookup of `token_env` falls back to `token_file`, then the (matching) router's token file.
+    const credentials = (n) => (n === tokenEnv ? resolve().token : resolveCredential(n, { env })); // per call, like resolveCredential
+    const settings = { ...exec, ...(endpoint ? { endpoint } : {}), ...(tokenEnv ? { tokenEnv } : {}), ...(forgeYaml ? { forgeYaml } : {}),
       ...(typeof opts?.prefetch === "function" ? { prefetch: opts.prefetch } : {}) }; // #4778: dispatch-time relay pre-fetch
-    return remoteProvider({ batch: opts.batch, repo: opts.repo, settings, name: "pool", env, credentials, transport: remoteTransportFor(settings, { transport: opts?.transport, env, credentials }), ...(opts?.now ? { now: opts.now } : {}) });
+    return remoteProvider({ batch: opts.batch, repo: opts.repo, settings, ...(pool ? { name: "pool" } : {}), env, credentials,
+      transport: remoteTransportFor(settings, { transport: opts?.transport, env, credentials, ...(opts?.fetchFn ? { fetchFn: opts.fetchFn } : {}) }), ...(opts?.now ? { now: opts.now } : {}) });
   }
   const e = new Error(`unknown execution.provider ${JSON.stringify(name)} (known: ${SANDBOX_PROVIDERS.join(", ")})`);
   e.code = "execution.provider.unknown";

package/bin/lean/execution.test.mjs

@@ -7,7 +7,7 @@ import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
 import { renderContract } from "./render.mjs";
-import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, remoteHoldId, usageLimitInTail, isTransportError, isCloneFailure, containerProvider, providerByName, openExecutionBudget } from "./execution.mjs";
+import { parseExecution, SANDBOX_PROVIDERS, detectNeeds, hostCapabilityBlock, placementText, contractHostNeeds, placement, placeLane, validationWeight, hostHeadroom, scopedEnv, providerLanes, remoteHoldId, usageLimitInTail, isTransportError, isCloneFailure, containerProvider, providerByName, openExecutionBudget, poolCredential, remoteTransportFor } from "./execution.mjs";
 import { makeLedger, countLiveLanes } from "./ledger.mjs";
 import { openBatch } from "./batch.mjs";
 import { orchestrate, formatTable, formatSandboxSummary } from "./orchestrate.mjs";
@@ -399,6 +399,27 @@ describe("runBatch wiring (#4253)", () => {
       assert.deepEqual(prov.calls, []);
     }
   });
+
+  it("#5138: a live --set-placement local makes the next lane of a remote batch a detached host lane", async () => {
+    const work = tmpDir("exec-cli-live-");
+    const stub = join(work, "stub.mjs");
+    writeFileSync(stub, `import { writeFileSync } from "node:fs"; const a = process.argv.slice(2); writeFileSync(a[a.indexOf("--result-file") + 1], JSON.stringify({ terminalReason: "merged", pr: 9 }));\n`);
+    const root = join(work, "batches");
+    let recorded = null;
+    const prov = fakeProvider({ finish: (n) => {
+      const b = openBatch(root, "blive");
+      recorded = b.readExecution();
+      if (n === 1) b.setExecution({ mode: "local" }); // the operator's --set-placement before #2 is admitted
+      return { terminalReason: "merged", pr: 100 + n, cost_usd: 0 };
+    } });
+    const res = await quiet(() => orchestrateFromCli(["1", "2", "--repo", "o/r", "--no-prefilter", "--parallel", "1"], base(work, { batchId: "blive", laneScript: stub,
+      execution: parseExecution({ mode: "remote", max_remote: "1" }), sandboxProvider: prov,
+      sandboxLedger: (n) => makeLedger({ root: join(work, "ledger"), batch: "blive", lane: `sandbox-${n}`, owner: "t", issue: n }) })));
+    assert.deepEqual(recorded, { provider: true });
+    assert.deepEqual(res.rows.map((r) => [r.issue, r.outcome, r.pr, r.placement?.where]), [[1, "merged", 101, "remote"], [2, "merged", 9, "local"]]);
+    assert.match(res.rows[1].placement.reason, /live placement/);
+    assert.deepEqual(prov.calls.filter((c) => c[0] === "start").map((c) => c[1]), [1]);
+  });
 });
 
 describe("execution budget and sandbox cost (#4255)", () => {
@@ -716,6 +737,10 @@ describe("#4547: fallback_local and agent liveness", () => {
     assert.equal(parseExecution({ mode: "remote", max_remote: "2", fallback_local: "true" }).fallbackLocal, true);
     assert.equal(parseExecution({ mode: "remote", fallback_local: "yes" }).fallbackLocal, undefined);
   });
+  it("#5112 parseExecution: capacity_fallback_after is a positive integer, absent otherwise", () => {
+    assert.equal(parseExecution({ mode: "remote", fallback_local: "true", capacity_fallback_after: "5" }).capacityFallbackAfter, 5);
+    for (const v of [undefined, "", "0", "-1", "2.5", "x"]) assert.equal("capacityFallbackAfter" in parseExecution({ mode: "remote", capacity_fallback_after: v }), false, String(v));
+  });
   it("transport capacity carries free and liveness; none valid is unknown", async () => {
     const { httpTransport } = await import("./sandbox-remote.mjs");
     const cap = async (data, ok = true) => httpTransport({ endpoint: "http://pool.test", token: "t", fetchFn: async () => ({ ok, status: ok ? 200 : 500, headers: new Headers(), text: async () => JSON.stringify(data) }) }).capacity();
@@ -901,3 +926,110 @@ describe("#5095: launch 5xx and a pool usage limit are deferred, never needs-hum
     assert.equal(plain.terminalReason, "engine-error");
   });
 });
+
+describe("remote/pool credential resolver (#5131)", () => {
+  /** A router config dir: router.json listening on 127.0.0.1:7710 and the sibling forgedock.token. */
+  const routerDir = () => {
+    const d = tmpDir("router-5131-");
+    writeFileSync(join(d, "router.json"), JSON.stringify({ listen: { host: "127.0.0.1", port: 7710 } }));
+    writeFileSync(join(d, "forgedock.token"), "router-tok\n");
+    return d;
+  };
+  const recorder = () => {
+    const seen = [];
+    const fetchFn = async (url, init = {}) => { seen.push({ url: String(url), auth: init.headers?.authorization ?? null }); return new Response("{}", { status: 200 }); };
+    return { seen, fetchFn };
+  };
+  const remoteVia = (exec, { fetchFn, dir }) => providerByName("remote", { batch: { id: "b5131" }, repo: "o/r", exec: parseExecution({ mode: "remote", max_remote: "1", provider: "remote", ...exec }),
+    env: {}, poolConfigPath: join(dir, "router.json"), fetchFn });
+
+  it("5131: providerByName remote with no env/keychain token sends the router token file's bearer only to the router's endpoint", async () => {
+    const dir = routerDir();
+    const hit = recorder();
+    await remoteVia({ endpoint: "http://127.0.0.1:7710/" }, { fetchFn: hit.fetchFn, dir }).capacity();
+    assert.ok(hit.seen.length >= 1);
+    assert.equal(hit.seen[0].auth, "Bearer router-tok");
+    const miss = recorder();
+    await remoteVia({ endpoint: "https://runner.example.com" }, { fetchFn: miss.fetchFn, dir }).capacity();
+    assert.ok(miss.seen.length >= 1);
+    assert.equal(miss.seen[0].auth, null, "the local router token never goes to another endpoint");
+  });
+
+  it("5131: poolCredential order is token_env (env, keychain), token_file, then the matching router token; source never holds the value", () => {
+    const dir = routerDir();
+    const file = join(dir, "explicit.token");
+    writeFileSync(file, "  file-tok \n");
+    const router = { endpoint: "http://127.0.0.1:7710", token: "router-tok" };
+    const keychain = () => null;
+    assert.deepEqual(poolCredential({ provider: "remote", tokenEnv: "COMPUTESHARE_TOKEN", endpoint: "http://127.0.0.1:7710" }, { env: { COMPUTESHARE_TOKEN: "env-tok" }, router, keychain }), { token: "env-tok", source: "COMPUTESHARE_TOKEN" });
+    assert.deepEqual(poolCredential({ provider: "remote", tokenEnv: "COMPUTESHARE_TOKEN", endpoint: "http://127.0.0.1:7710" }, { env: {}, router, keychain: () => "kc-tok" }), { token: "kc-tok", source: "COMPUTESHARE_TOKEN" });
+    assert.deepEqual(poolCredential({ provider: "remote", tokenEnv: "COMPUTESHARE_TOKEN", endpoint: "http://127.0.0.1:7710/" }, { env: {}, router, keychain }), { token: "router-tok", source: "forgedock_token_file" });
+    assert.deepEqual(poolCredential({ provider: "remote", tokenEnv: "COMPUTESHARE_TOKEN", tokenFile: file, endpoint: "https://x.example" }, { env: {}, router, keychain }), { token: "file-tok", source: "token_file" });
+    assert.deepEqual(poolCredential({ provider: "remote", tokenEnv: "COMPUTESHARE_TOKEN", endpoint: "https://x.example" }, { env: {}, router, keychain }), { token: null, source: null });
+    assert.deepEqual(poolCredential({ provider: "pool", endpoint: "https://x.example" }, { env: {}, router, keychain }), { token: "router-tok", source: "forgedock_token_file" });
+    assert.deepEqual(poolCredential({ provider: "remote", tokenFile: join(dir, "missing.token") }, { env: {}, router: null }), { token: null, source: null });
+  });
+
+  it("5131: execution.token_file is parsed and sent as the bearer to any endpoint", async () => {
+    const dir = routerDir();
+    const file = join(dir, "explicit.token");
+    writeFileSync(file, "file-tok\n");
+    assert.equal(parseExecution({ token_file: file }).tokenFile, file);
+    assert.equal(parseExecution({ token_file: "" }).tokenFile, undefined);
+    const hit = recorder();
+    await remoteVia({ endpoint: "https://runner.example.com", token_file: file }, { fetchFn: hit.fetchFn, dir }).capacity();
+    assert.equal(hit.seen[0].auth, "Bearer file-tok");
+  });
+
+  it("5144: a token that appears or rotates after the provider is built is the next request's bearer", async () => {
+    const dir = tmpDir("router-5144-");
+    const tokenFile = join(dir, "forgedock.token");
+    writeFileSync(join(dir, "router.json"), JSON.stringify({ listen: { host: "127.0.0.1", port: 7710 } }));
+    writeFileSync(tokenFile, "\n"); // router config with no token yet
+    const hit = recorder();
+    const env = {};
+    const mk = (name, exec) => providerByName(name, { batch: { id: "b5144" }, repo: "o/r", exec: parseExecution({ mode: "remote", max_remote: "1", provider: name, ...exec }),
+      env, poolConfigPath: join(dir, "router.json"), fetchFn: hit.fetchFn });
+    for (const [name, exec] of [["remote", { endpoint: "http://127.0.0.1:7710" }], ["pool", {}]]) {
+      writeFileSync(tokenFile, "\n");
+      hit.seen.length = 0;
+      const p = mk(name, exec);
+      await p.capacity();
+      assert.equal(hit.seen.at(-1).auth, null, `${name}: no token at construction`);
+      writeFileSync(tokenFile, "router-new\n");
+      await p.capacity();
+      assert.equal(hit.seen.at(-1).auth, "Bearer router-new", `${name}: a token written later is sent`);
+      writeFileSync(tokenFile, "router-rotated\n");
+      await p.capacity();
+      assert.equal(hit.seen.at(-1).auth, "Bearer router-rotated", `${name}: a rotated token is sent`);
+    }
+  });
+
+  it("5144: an env token_env that is set after construction is sent; remoteTransportFor default path resolves per call", async () => {
+    const dir = routerDir();
+    const hit = recorder();
+    const penv = {};
+    const q = providerByName("remote", { batch: { id: "b5144e" }, repo: "o/r", exec: parseExecution({ mode: "remote", max_remote: "1", provider: "remote", endpoint: "https://runner.example.com", token_env: "COMPUTESHARE_TOKEN" }),
+      env: penv, poolConfigPath: join(dir, "router.json"), fetchFn: hit.fetchFn });
+    await q.capacity();
+    assert.equal(hit.seen.at(-1).auth, null);
+    penv.COMPUTESHARE_TOKEN = "env-late";
+    await q.capacity();
+    assert.equal(hit.seen.at(-1).auth, "Bearer env-late");
+    const tenv = {};
+    const t = remoteTransportFor({ endpoint: "https://runner.example.com", tokenEnv: "COMPUTESHARE_TOKEN" }, { env: tenv, router: null, fetchFn: hit.fetchFn });
+    await t.capacity();
+    assert.equal(hit.seen.at(-1).auth, null);
+    tenv.COMPUTESHARE_TOKEN = "env-late-2";
+    await t.capacity();
+    assert.equal(hit.seen.at(-1).auth, "Bearer env-late-2");
+  });
+
+  it("5131: remoteTransportFor's default credentials (gc) fall back to the matching router token", async () => {
+    const hit = recorder();
+    const t = remoteTransportFor({ endpoint: "http://127.0.0.1:7710" }, { env: {}, router: { endpoint: "http://127.0.0.1:7710", token: "router-tok" }, fetchFn: hit.fetchFn });
+    await t.capacity();
+    assert.equal(hit.seen[0].auth, "Bearer router-tok");
+    assert.throws(() => remoteTransportFor({}, { env: {}, router: null }), (e) => e.code === "execution.provider.misconfigured");
+  });
+});

package/bin/lean/heavy.mjs

@@ -266,10 +266,16 @@ export function heavyShimScript(name, real, { node = process.execPath, script =
   return `${SHIM_HEADER}export FORGE_HEAVY_SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"\nexec ${q(node)} ${q(script)} run --name ${q(name)} -- ${q(real)} "$@"\n`;
 }
 
-/** True when `text` is a shell-style script that looks `name` up on PATH itself (a pass-through wrapper, #4680). */
+/**
+ * True when `text` is a shell-style script that looks `name` up on PATH itself (a pass-through wrapper, #4680). The lookup
+ * target may be the literal name, or (#5148) a variable/substitution when the script derives that name from `$0`
+ * (a `${0##…}` strip or `basename "$0"`), the shape of a wrapper symlinked under several command names.
+ */
 export function isPassThroughWrapper(text, name) {
   const t = String(text ?? "");
-  return t.startsWith("#!") && t.includes(name) && /\b(command\s+-v|which|type\s+-p)\b/.test(t);
+  if (!t.startsWith("#!") || !/\b(command\s+-v|which|type\s+-p)\b/.test(t)) return false;
+  if (t.includes(name)) return true;
+  return /(?:command\s+-v|which|type\s+-p)\s+(?:-\s+)?["']?\$/.test(t) && /\$\{0##\*\/\}|basename\s+(?:--\s+)?["']?\$\{?0\b/.test(t);
 }
 const head = (p) => { try { return readFileSync(p, "utf8").slice(0, 4096); } catch { return ""; } };
 
@@ -332,6 +338,8 @@ export function findShimLoops(path, { names = HEAVY_BINS, find = which, read = h
 }
 
 export const SHIM_LOOP_MAX = 4;
+/** #5148: hard bound on shim entries (FORGE_HEAVY_DEPTH) whatever the wrapper shape; far above legitimate `npm run` nesting. */
+export const SHIM_DEPTH_MAX = 32;
 /**
  * Re-entry guard (#4680): FORGE_HEAVY_CHAIN lists `name:cmd` per shim run. A repeat of the same name+cmd where cmd is a
  * pass-through wrapper means it sent the call back to the shim; a repeat of a real binary is a legitimate nested call
@@ -342,15 +350,17 @@ export function guardChain(name, cmd, env, read = head) {
   const chain = String(env.FORGE_HEAVY_CHAIN ?? "").split("|").filter(Boolean);
   const dirs = chain.map((e) => dirname(e.slice(e.indexOf(":") + 1)));
   const loop = (why) => ({ error: `env.shim_loop: ${name} ${why} (PATH dirs: ${[env.FORGE_HEAVY_SHIM_DIR, ...dirs].filter(Boolean).join(", ") || "none"})` });
+  const depth = Math.max(0, Number.parseInt(env.FORGE_HEAVY_DEPTH, 10) || 0);
+  if (depth >= SHIM_DEPTH_MAX) return loop(`re-entered the heavy shim ${depth} levels deep (max ${SHIM_DEPTH_MAX})`);
   const repeat = chain.includes(`${name}:${cmd}`);
-  if (repeat && !isPassThroughWrapper(read(cmd), name)) return { cmd, env };
+  if (repeat && !isPassThroughWrapper(read(cmd), name)) return { cmd, env: { ...env, FORGE_HEAVY_DEPTH: String(depth + 1) } };
   if (chain.length >= SHIM_LOOP_MAX) return loop(`re-entered the heavy shim more than ${SHIM_LOOP_MAX} times`);
   if (repeat) {
     const next = which(name, env.PATH ?? "", [env.FORGE_HEAVY_SHIM_DIR, ...dirs].filter(Boolean));
     if (!next) return loop(`re-entered via ${cmd} and no other ${name} is on PATH`);
     cmd = next;
   }
-  return { cmd, env: { ...env, FORGE_HEAVY_CHAIN: [...chain, `${name}:${cmd}`].join("|") } };
+  return { cmd, env: { ...env, FORGE_HEAVY_DEPTH: String(depth + 1), FORGE_HEAVY_CHAIN: [...chain, `${name}:${cmd}`].join("|") } };
 }
 
 /**

package/bin/lean/heavy.test.mjs

@@ -6,7 +6,7 @@ import { spawnSync } from "node:child_process";
 import { writeFileSync, readFileSync, mkdirSync, chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { tmpDir } from "../tests/_tmp.mjs";
-import { guardChain, isPassThroughWrapper, SHIM_LOOP_MAX, classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS, isHeavyProcess } from "./heavy.mjs";
+import { guardChain, isPassThroughWrapper, SHIM_LOOP_MAX, SHIM_DEPTH_MAX, classifyStep, heavyConfig, openHeavy, acquireHeavy, writeHeavyShims, heavyShimScript, sumWaits, runWrapped, HEAVY_BINS, isHeavyProcess } from "./heavy.mjs";
 import { checkAdmission, ADMISSION_DEFAULTS, localLaneCap } from "./admission.mjs";
 import { formatAlertLines, formatWaitSummary } from "./orchestrate.mjs";
 import { readHeavy, readAdmission, liveLaneCap } from "../engine-cli.mjs";
@@ -347,3 +347,57 @@ describe("validation steps and the local lane cap (#4777)", () => {
     assert.equal(liveLaneCap(null, { cfg: readAdmission(d), host: { cores: () => 16, memAvailableMb: () => 64000 } })(), 2);
   });
 });
+
+describe("#5148 dynamic-name pass-through wrapper", () => {
+  const WRAP = (log) => `#!/bin/bash\nname=\${0##*/}\necho w >> "${log}"\n[ "$(wc -l < "${log}")" -gt 12 ] && exit 99\nself_dir=$(cd "\${0%/*}" && pwd)\nreal=$(PATH=$(printf '%s' "$PATH" | tr ':' '\\n' | grep -vxF "$self_dir" | paste -sd:) command -v "$name")\nexec "$real" "$@"\n`;
+  const fixture = () => {
+    const d = tmpDir("heavy-5148-"), wrap = join(d, "wrap"), real = join(d, "real"), bin = join(d, "bin"), log = join(d, "log");
+    for (const x of [wrap, real, bin]) mkdirSync(x, { recursive: true });
+    writeFileSync(log, "");
+    writeFileSync(join(wrap, "docker"), WRAP(log));
+    writeFileSync(join(real, "docker"), `#!/bin/sh\necho r >> ${log}\necho real-docker\n`);
+    for (const x of [wrap, real]) chmodSync(join(x, "docker"), 0o755);
+    return { d, wrap, real, bin, log };
+  };
+  const lines = (log) => readFileSync(log, "utf8").split("\n").filter(Boolean);
+
+  it("#5148: a ${0##*/} pass-through wrapper on PATH does not recurse through the heavy shim", async () => {
+    const { wrap, real, bin, log } = fixture();
+    assert.ok(isPassThroughWrapper(readFileSync(join(wrap, "docker"), "utf8"), "docker"));
+    assert.ok(isPassThroughWrapper('#!/bin/sh\nexec "$(command -v "$(basename "$0")")" "$@"', "docker"));
+    assert.ok(!isPassThroughWrapper("#!/bin/sh\necho hi\n", "docker"));
+    assert.ok(!isPassThroughWrapper('#!/bin/sh\nx=git\nexec "$(command -v "$x")" "$@"', "docker"), "dynamic lookup without a $0-derived name is not a wrapper");
+    assert.deepEqual(await writeHeavyShims(bin, { path: `${wrap}:${real}`, warn: () => {} }), ["docker"]);
+    assert.match(readFileSync(join(bin, "docker"), "utf8"), new RegExp(`-- '${real}/docker' "\\$@"`));
+    const env = { ...process.env, PATH: `${bin}:${wrap}:${real}:/usr/bin:/bin`, FORGE_HEAVY_DISABLED: "1" };
+    const r = spawnSync(join(bin, "docker"), ["ps"], { env, encoding: "utf8", timeout: 20000 });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /real-docker/);
+    assert.deepEqual(lines(log), ["r"], "the wrapper never ran; the real binary ran once");
+  });
+
+  it("#5148: with the shim baking the wrapper, the call reaches the real binary within SHIM_LOOP_MAX levels", () => {
+    const { wrap, real, bin, log } = fixture();
+    writeFileSync(join(bin, "docker"), heavyShimScript("docker", join(wrap, "docker"))); chmodSync(join(bin, "docker"), 0o755);
+    const env = { ...process.env, PATH: `${bin}:${wrap}:${real}:/usr/bin:/bin`, FORGE_HEAVY_DISABLED: "1" };
+    const r = spawnSync(join(bin, "docker"), ["ps"], { env, encoding: "utf8", timeout: 20000 });
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(lines(log).length <= SHIM_LOOP_MAX + 1, lines(log).join(","));
+    assert.equal(lines(log).at(-1), "r");
+  });
+
+  it("#5148: guardChain stops at SHIM_DEPTH_MAX even for a repeat it judges legitimate, and counts each entry", () => {
+    const env = { PATH: "/s:/r", FORGE_HEAVY_SHIM_DIR: "/s", FORGE_HEAVY_CHAIN: "npm:/r/npm", FORGE_HEAVY_DEPTH: String(SHIM_DEPTH_MAX) };
+    assert.match(guardChain("npm", "/r/npm", env, () => "").error, /^env\.shim_loop: npm .*levels deep/);
+    const ok = guardChain("npm", "/r/npm", { ...env, FORGE_HEAVY_DEPTH: String(SHIM_DEPTH_MAX - 1) }, () => "");
+    assert.equal(ok.error, undefined); assert.equal(ok.env.FORGE_HEAVY_DEPTH, String(SHIM_DEPTH_MAX));
+  });
+
+  it("#5148: under systemd-run TasksMax the shimmed call finishes without hitting the limit", { skip: spawnSync("systemd-run", ["--user", "--scope", "-q", "true"], { timeout: 10000 }).status !== 0 && "no systemd --user manager" }, () => {
+    const { wrap, real, bin, log } = fixture();
+    writeFileSync(join(bin, "docker"), heavyShimScript("docker", join(wrap, "docker"))); chmodSync(join(bin, "docker"), 0o755);
+    const r = spawnSync("systemd-run", ["--user", "--scope", "-q", "-p", "TasksMax=64", "env", `PATH=${bin}:${wrap}:${real}:/usr/bin:/bin`, "FORGE_HEAVY_DISABLED=1", join(bin, "docker"), "ps"], { encoding: "utf8", timeout: 30000 });
+    assert.equal(r.status, 0, r.stderr);
+    assert.ok(lines(log).length < 13);
+  });
+});

package/bin/lean/lanecheck.mjs

@@ -31,20 +31,49 @@ const C = PREFLIGHT_CODES;
 /** A remote or hybrid execution is configured (the only case the pool checks apply to). */
 export const usesPool = (exec) => Boolean(exec) && (exec.mode === "remote" || exec.mode === "hybrid") && ["pool", "remote"].includes(exec.provider ?? "pool");
 
-/** The pool token resolves (env/keychain `token_env`, else the router's `forgedock_token_file`) and the router does not answer 401/403 to an authenticated ping. */
-export async function checkPoolAuth({ exec, router = null, credential = () => null, ping = null }) {
+/** #5131: `a` and `b` name the same `scheme://host:port` (default ports filled, path and trailing slash ignored). */
+const sameEndpoint = (a, b) => {
+  const key = (u) => { try { const x = new URL(String(u)); return `${x.protocol}//${x.hostname}:${x.port || (x.protocol === "https:" ? "443" : "80")}`; } catch { return null; } };
+  return key(a) !== null && key(a) === key(b);
+};
+
+/**
+ * The injectable stand-in for execution.mjs `poolCredential` when no `poolToken` is given (tests, older callers): `credential`
+ * on `token_env` (default COMPUTESHARE_TOKEN), then the router token, for `remote` only when its endpoint is unset or the router's.
+ */
+export const legacyPoolToken = (credential = () => null) => (exec, router) => {
+  const name = exec?.tokenEnv ?? "COMPUTESHARE_TOKEN";
+  const v = credential(name);
+  if (v) return { token: v, source: name };
+  const ok = Boolean(router?.token) && ((exec?.provider ?? "pool") === "pool" || !exec?.endpoint || sameEndpoint(exec.endpoint, router.endpoint));
+  return ok ? { token: router.token, source: "forgedock_token_file" } : { token: null, source: null };
+};
+
+/** The sources a resolver tries for `exec` (names only, never values), for a FAIL detail. */
+const sourcesTried = (exec, router) => [
+  `env/keychain ${exec.tokenEnv ?? (exec.provider === "remote" ? "(no token_env)" : "COMPUTESHARE_TOKEN")}`,
+  ...(exec.tokenFile ? [`token_file ${exec.tokenFile}`] : []),
+  !router ? "no router config (COMPUTESHARE_CONFIG / ~/.config/computeshare/router.json)"
+    : (exec.provider ?? "pool") === "remote" && exec.endpoint && !sameEndpoint(exec.endpoint, router.endpoint) ? `the router's forgedock_token_file (not used: endpoint ${exec.endpoint} is not the local router ${router.endpoint})`
+      : "the router's forgedock_token_file",
+].join(", ");
+
+/**
+ * The pool token resolves through `poolToken(exec, router) -> {token, source}` (#5131: hostLaneIo wires execution.mjs
+ * poolCredential with the dispatch env, so preflight and lane dispatch resolve the same token), else `credential`/`router`
+ * (legacyPoolToken), and the router does not answer 401/403 to an authenticated ping. Details name sources, never values.
+ */
+export async function checkPoolAuth({ exec, router = null, credential = () => null, ping = null, poolToken = null }) {
   const code = C.PREFLIGHT_POOL_AUTH;
   if (!usesPool(exec)) return pass(code, "skipped: no remote or hybrid execution", "remote");
-  const name = exec.tokenEnv ?? "COMPUTESHARE_TOKEN";
-  const fromEnv = credential(name);
-  const token = fromEnv || router?.token || null;
-  if (!token) return fail(code, `pool token does not resolve: tried env/keychain ${name}, ${router ? "the router's forgedock_token_file" : "no router config (COMPUTESHARE_CONFIG / ~/.config/computeshare/router.json)"}`, "remote");
+  const { token, source } = (poolToken ?? legacyPoolToken(credential))(exec, router) ?? {};
+  if (!token) return fail(code, `pool token does not resolve: tried ${sourcesTried(exec, router)}`, "remote");
   const endpoint = exec.endpoint ?? router?.endpoint ?? null;
-  if (!endpoint || typeof ping !== "function") return pass(code, `token resolved from ${fromEnv ? name : "forgedock_token_file"}`, "remote");
+  if (!endpoint || typeof ping !== "function") return pass(code, `token resolved from ${source}`, "remote");
   let r = null;
   try { r = await ping(endpoint, token); } catch { r = null; }
-  if ([401, 403].includes(r?.status)) return fail(code, `router ${endpoint} answered HTTP ${r.status} to the token from ${fromEnv ? name : "forgedock_token_file"}`, "remote");
-  return pass(code, `token resolved from ${fromEnv ? name : "forgedock_token_file"}${r ? "" : "; router unreachable (not an auth failure)"}`, "remote");
+  if ([401, 403].includes(r?.status)) return fail(code, `router ${endpoint} answered HTTP ${r.status} to the token from ${source}`, "remote");
+  return pass(code, `token resolved from ${source}${r ? "" : "; router unreachable (not an auth failure)"}`, "remote");
 }
 
 /** Every online pool agent runs the CLI's version. `agents` is the router's `GET /agents` list (each spreads versionOf: version, image). */
@@ -99,9 +128,11 @@ export async function runLaneChecks({ exec = null, env = process.env, cliVersion
   let router = null;
   try { router = io.router?.() ?? null; } catch { router = null; }
   const ping = io.ping ?? null;
-  const agentsOf = async () => { try { return (await io.agents?.(exec?.endpoint ?? router?.endpoint, exec?.tokenEnv ? (io.credential?.(exec.tokenEnv) ?? router?.token) : router?.token)) ?? null; } catch { return null; } };
+  // #5131: one resolver for the auth check and the agents read: io.poolToken (poolCredential), else the injected credential/router.
+  const poolToken = io.poolToken ?? legacyPoolToken(io.credential ?? (() => null));
+  const agentsOf = async () => { try { return (await io.agents?.(exec?.endpoint ?? router?.endpoint, poolToken(exec, router)?.token ?? null)) ?? null; } catch { return null; } };
   return Promise.all([
-    safe(C.PREFLIGHT_POOL_AUTH, "remote", () => checkPoolAuth({ exec, router, credential: io.credential, ping })),
+    safe(C.PREFLIGHT_POOL_AUTH, "remote", () => checkPoolAuth({ exec, router, poolToken, ping })),
     safe(C.PREFLIGHT_POOL_VERSION, "remote", async () => checkPoolVersion({ exec, agents: usesPool(exec) ? await agentsOf() : null, cliVersion: cliV })),
     safe(C.PREFLIGHT_PATH_LOOP, "all", () => checkPathLoop({ env: { ...env, PATH: env.PATH ?? "" }, ...(io.loops ? { loops: io.loops } : {}) })),
     safe(C.PREFLIGHT_GH_FIELDS, "all", () => (io.ghExec ? checkGhFields({ exec: io.ghExec }) : pass(C.PREFLIGHT_GH_FIELDS, "skipped: no gh", "all"))),
@@ -113,7 +144,7 @@ export const formatLaneChecks = (checks) => checks.map((c) => `${c.ok ? "PASS" :
 
 /** Real-host io for the daemon, the batch and `doctor --lanes`. gh output is cached per process (it cannot change under a running engine). */
 export async function hostLaneIo({ env = process.env } = {}) {
-  const { poolRouterConfig } = await import("./execution.mjs");
+  const { poolCredential, poolRouterConfig } = await import("./execution.mjs");
   const { resolveCredential } = await import("./credentials.mjs");
   const { execFile } = await import("node:child_process");
   const call = (url, token, timeoutMs = 5000) => fetch(url, { headers: token ? { authorization: `Bearer ${token}` } : {}, signal: AbortSignal.timeout(timeoutMs) });
@@ -122,6 +153,7 @@ export async function hostLaneIo({ env = process.env } = {}) {
   return {
     router: () => poolRouterConfig({ env }),
     credential: (n) => resolveCredential(n, { env }),
+    poolToken: (exec, router) => poolCredential(exec, { env, router }), // #5131: the dispatch resolver on the dispatch env
     ping: async (endpoint, token) => ({ status: (await call(`${endpoint}/status`, token)).status }),
     agents: async (endpoint, token) => { const r = await call(`${endpoint}/agents`, token); return r.ok ? (await r.json())?.agents ?? null : null; },
     ghExec: (args) => { const k = args.join(" "); if (!memo.has(k)) memo.set(k, run(args)); return memo.get(k); },

package/bin/lean/lanecheck.test.mjs

@@ -31,6 +31,29 @@ describe("pool_auth", () => {
   });
 });
 
+describe("pool_auth shared resolver (#5131)", () => {
+  const remote = { mode: "remote", provider: "remote", endpoint: "https://runner.example.com", tokenEnv: "COMPUTESHARE_TOKEN" };
+  const router = { endpoint: "http://127.0.0.1:7710", token: "router-tok" };
+  it("5131: FAILs remote on a non-matching endpoint although a router token exists, naming sources never the value", async () => {
+    const a = await checkPoolAuth({ exec: remote, router, credential: () => null });
+    assert.equal(a.ok, false); assert.equal(a.code, "preflight.pool_auth"); assert.equal(a.scope, "remote");
+    assert.match(a.detail, /COMPUTESHARE_TOKEN/); assert.match(a.detail, /not the local router/); assert.doesNotMatch(a.detail, /router-tok/);
+    const viaIo = await checkPoolAuth({ exec: remote, router, poolToken: () => ({ token: null, source: null }) });
+    assert.equal(viaIo.ok, false);
+    assert.equal((await checkPoolAuth({ exec: { ...remote, endpoint: "http://127.0.0.1:7710/" }, router, credential: () => null })).ok, true, "matching endpoint: router token applies");
+  });
+  it("5131: runLaneChecks uses io.poolToken for the auth check and the agents read, and FAILs a rejected token", async () => {
+    const calls = [];
+    const io = { router: () => router, poolToken: (exec, r) => { calls.push([exec.provider, r?.endpoint]); return { token: "tok", source: "token_file" }; },
+      ping: async (_e, t) => ({ status: t === "tok" ? 401 : 200 }), agents: async (_e, t) => { calls.push(["agents", t]); return []; } };
+    const checks = await runLaneChecks({ exec: remote, env: { PATH: "" }, io: { ...io, loops: () => [] } });
+    const auth = checks.find((c) => c.code === "preflight.pool_auth");
+    assert.equal(auth.ok, false); assert.match(auth.detail, /HTTP 401/); assert.match(auth.detail, /token_file/); assert.doesNotMatch(auth.detail, /\btok\b/);
+    assert.ok(calls.some((c) => c[0] === "agents" && c[1] === "tok"));
+    assert.ok(calls.some((c) => c[0] === "remote" && c[1] === router.endpoint));
+  });
+});
+
 describe("pool_version", () => {
   it("reports the agent, image version, CLI version and upgrade command", () => {
     const c = checkPoolVersion({ exec: pool, cliVersion: "1.39.0", agents: [{ name: "a1", ok: true, version: "1.37.0" }, { name: "a2", ok: true, version: "1.39.0" }] });