run402 2.27.0 → 2.29.0

package/README.md

@@ -118,8 +118,12 @@ run402 functions deploy <id> my-fn --file fn.ts \
   --deps "stripe,zod@^3"
 run402 functions logs <id> my-fn --tail 100 --request-id req_abc123 --follow
 run402 functions invoke <id> my-fn --body '{"hello":"world"}'
+run402 functions rebuild <id> my-fn      # refresh ONE function onto the current runtime
+run402 functions rebuild <id> --all      # refresh every function in the project
 ```
 
+`functions rebuild` is opt-in and never changes your source: it re-bundles the stored source against the platform's current runtime/entry-wrapper (deps pinned to the exact versions recorded at deploy), so a gateway-side wrapper fix (e.g. an SSR `auth.*` fix) reaches an already-deployed function — a plain redeploy with unchanged source does not. The source `code_hash` is unchanged and no new release is created. Functions deployed before dependency locking return `CANNOT_REBUILD_UNLOCKED_DEPS`; redeploy those from source instead. `run402 doctor` flags functions on a stale runtime.
+
 Functions run on Node 22 with `@run402/functions` auto-bundled. Inside the handler:
 
 ```ts
@@ -193,8 +197,18 @@ Local state lives at:
 
 - `~/.config/run402/projects.json` (`0600`) — project credentials (`anon_key`, `service_key`, `tier`, `lease_expires_at`)
 - `~/.config/run402/allowance.json` (`0600`) — wallet for x402 signing
+- `~/.config/run402/config.json` (`0600`) — global default wallet pointer (`active_wallet`)
+- `~/.config/run402/profiles/<name>/` (`0700`) — named wallets, each with its own `allowance.json` + `projects.json` + non-secret `meta.json`
+
+Override the base directory with `RUN402_CONFIG_DIR` or the allowance file with `RUN402_ALLOWANCE_PATH`. Override the API base with `RUN402_API_BASE`.
+
+### Named wallets (profiles)
+
+Hold several wallets on one machine and select between them:
 
-Override with `RUN402_CONFIG_DIR` or `RUN402_ALLOWANCE_PATH`. Override the API base with `RUN402_API_BASE`.
+- `run402 wallets list | new <name> | use <name> | rename <old> <new> | bind [<name>] | unbind | import <name> --key <path|-> | rm <name> --yes`
+- Select per-command with `--wallet <name>` (alias `--profile`), the `RUN402_WALLET` env var, or a per-directory `.run402.json` (commit-safe — holds only a name) resolved by walking up the tree. Precedence: flag > env > binding > `wallets use` default > `default`. A conflicting env + binding is a hard error.
+- The active wallet name shows in `run402 status` and `run402 wallets current`.
 
 The CLI handles all x402 payment signing automatically — never ask the human for a private key or set up payment libraries by hand.
 

package/cli.mjs

@@ -6,7 +6,7 @@
 
 import { readFileSync } from "node:fs";
 
-const [,, cmd, sub, ...rest] = process.argv;
+const rawArgv = process.argv.slice(2);
 
 const { version } = JSON.parse(
   readFileSync(new URL("./package.json", import.meta.url), "utf8")
@@ -22,6 +22,7 @@ Commands:
   init        Set up allowance, funding, and check tier status (x402 default)
   init mpp    Set up with MPP payment rail (Tempo Moderato testnet)
   status      Show full account state (allowance, balance, tier, projects)
+  wallets     Manage multiple named wallets (list, new, use, rename, bind, import)
   allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
@@ -53,6 +54,10 @@ Commands:
   dev         Run Astro dev with Run402 env + credentials in scope
   logs        Fetch function logs by request id (--request-id req_...)
 
+Global options (any command):
+  --wallet <name>   Select a named wallet for this command (see 'run402 wallets')
+                    Also: RUN402_WALLET env, or a ./.run402.json directory binding.
+
 Run 'run402 <command> --help' for detailed usage of each command.
 
 Examples:
@@ -74,22 +79,39 @@ Getting started:
   run402 ci link github --project prj_... --manifest run402.deploy.json
 `;
 
-if (cmd === '--version' || cmd === '-v') {
+const first = rawArgv[0];
+
+if (first === '--version' || first === '-v') {
   console.log(version);
   process.exit(0);
 }
 
-if (!cmd || cmd === '--help' || cmd === '-h') {
+if (first === undefined || first === '--help' || first === '-h') {
   console.log(HELP);
   process.exit(0);
 }
 
+// Resolve the active wallet/profile from the global --wallet/--profile flag,
+// env, and any per-directory .run402.json binding BEFORE dispatch loads a
+// subcommand (whose config.mjs snapshots credential paths). splitWalletFlag
+// also strips the global flag so subcommands never see it.
+const { splitWalletFlag, applyWalletSelection } = await import("./lib/wallet-context.mjs");
+const { argv, walletFlag } = splitWalletFlag(rawArgv);
+const [cmd, sub, ...rest] = argv;
+
 try {
+  applyWalletSelection({
+    walletFlag,
+    cmd,
+    cwd: process.cwd(),
+    env: process.env,
+    quiet: rawArgv.includes("--quiet"),
+  });
   await dispatch();
 } catch (err) {
-  // Surface env/config errors (e.g. invalid RUN402_API_BASE) as a clean
-  // JSON envelope on stderr instead of a raw stack trace. We import the
-  // helper lazily so a broken env doesn't fail this catch handler too.
+  // Surface env/config errors (e.g. invalid RUN402_API_BASE, bad RUN402_WALLET)
+  // as a clean JSON envelope on stderr instead of a raw stack trace. We import
+  // the helper lazily so a broken env doesn't fail this catch handler too.
   const { fail } = await import("./lib/sdk-errors.mjs");
   fail({
     code: "BAD_ENV",
@@ -112,6 +134,11 @@ switch (cmd) {
     await run([sub, ...rest].filter(Boolean));
     break;
   }
+  case "wallets": {
+    const { run } = await import("./lib/wallets.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "allowance": {
     const { run } = await import("./lib/allowance.mjs");
     await run(sub, rest);

package/core-dist/allowance.js

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync, renameSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getAllowancePath } from "./config.js";
@@ -26,10 +26,33 @@ const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
  * `src/tools/{status,init}.ts` callers translate the throw into their own
  * structured envelopes (`code: BAD_ALLOWANCE_FILE`).
  */
+/**
+ * If an allowance file is readable by group or other (any of the low 0o077
+ * bits set), tighten it to 0600 and warn once on stderr. This self-heals the
+ * historical case where a legacy world-readable `wallet.json` (mode 0644) was
+ * migrated to `allowance.json` via a mode-preserving rename, leaving the
+ * private key exposed on a shared machine. Best-effort: POSIX-only and silent
+ * on platforms without meaningful Unix modes (e.g. Windows).
+ */
+function selfHealPermissions(p) {
+    if (process.platform === "win32")
+        return;
+    try {
+        const mode = statSync(p).mode & 0o777;
+        if ((mode & 0o077) !== 0) {
+            chmodSync(p, 0o600);
+            process.stderr.write(`warning: tightened permissions on ${p} from ${mode.toString(8)} to 600 (was readable by other users).\n`);
+        }
+    }
+    catch {
+        // Best-effort; never block a read on a chmod/stat failure.
+    }
+}
 export function readAllowance(path) {
     const p = path ?? getAllowancePath();
     if (!existsSync(p))
         return null;
+    selfHealPermissions(p);
     let raw;
     try {
         raw = readFileSync(p, "utf-8");

package/core-dist/config.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { existsSync, renameSync, mkdirSync } from "node:fs";
+import { existsSync, renameSync, mkdirSync, chmodSync } from "node:fs";
 const DEFAULT_API_BASE = "https://api.run402.com";
 /**
  * Validate a user-supplied API base URL. Throws a clear error message that
@@ -47,9 +47,71 @@ export function getDeployApiBase() {
     const validated = validateApiBase("RUN402_DEPLOY_API_BASE", process.env.RUN402_DEPLOY_API_BASE, fallback);
     return validated ?? fallback;
 }
-export function getConfigDir() {
+/**
+ * The base credential directory — the root under which the `default` wallet
+ * lives directly and named wallets live under `profiles/<name>/`. This is the
+ * value `RUN402_CONFIG_DIR` overrides; profiles nest *within* it.
+ */
+export function getConfigBaseDir() {
     return process.env.RUN402_CONFIG_DIR || join(homedir(), ".config", "run402");
 }
+export const DEFAULT_PROFILE = "default";
+// Filesystem-safe wallet/profile name. Lowercase only (avoids collisions on
+// case-insensitive filesystems like macOS), starts alphanumeric, then
+// alphanumeric/underscore/hyphen, max 64 chars. The CLI edge enforces this for
+// nice UX; core re-checks it as a defense-in-depth guard so a hostile
+// `RUN402_WALLET`/`RUN402_PROFILE` cannot traverse outside the profiles dir.
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export function isValidProfileName(name) {
+    return PROFILE_NAME_RE.test(name);
+}
+/**
+ * Guard against path traversal from the profile env vars. The reserved
+ * `default` profile is always allowed (it maps to the base dir). Any other
+ * name must pass the filesystem-safe pattern; otherwise we throw rather than
+ * silently resolve a surprising path.
+ */
+function assertSafeProfileName(name) {
+    if (name === DEFAULT_PROFILE)
+        return;
+    if (!isValidProfileName(name)) {
+        throw new Error(`Invalid wallet/profile name ${JSON.stringify(name)}. ` +
+            "Names must match /^[a-z0-9][a-z0-9_-]{0,63}$/ (lowercase letters, digits, '_' and '-'). " +
+            "Check the RUN402_WALLET / RUN402_PROFILE env var.");
+    }
+}
+/**
+ * The active wallet/profile name from the environment. `RUN402_WALLET` is
+ * canonical; `RUN402_PROFILE` is accepted as an alias. Empty/unset → the
+ * reserved `default`. The CLI edge resolves the `--wallet` flag and any
+ * per-directory `.run402.json` binding into `RUN402_WALLET` *before* dispatch,
+ * so core stays env-only and never reads argv or cwd.
+ */
+export function getActiveProfile() {
+    const raw = process.env.RUN402_WALLET ?? process.env.RUN402_PROFILE;
+    const name = raw == null ? "" : raw.trim();
+    if (!name)
+        return DEFAULT_PROFILE;
+    assertSafeProfileName(name);
+    return name;
+}
+/** Directory holding all named wallets: `{base}/profiles`. */
+export function getProfilesDir() {
+    return join(getConfigBaseDir(), "profiles");
+}
+/**
+ * The effective config directory for the *active* wallet. The `default` wallet
+ * resolves to the base dir (zero migration for existing single-wallet
+ * installs); any named wallet resolves to `{base}/profiles/<name>`. Because
+ * keystore, allowance, and meta paths all derive from this, switching the
+ * profile env var moves the whole wallet bundle atomically — and the SDK/MCP
+ * inherit profile selection for free.
+ */
+export function getConfigDir() {
+    const base = getConfigBaseDir();
+    const profile = getActiveProfile();
+    return profile === DEFAULT_PROFILE ? base : join(base, "profiles", profile);
+}
 export function getKeystorePath() {
     return join(getConfigDir(), "projects.json");
 }
@@ -59,10 +121,20 @@ export function getAllowancePath() {
     const dir = getConfigDir();
     const newPath = join(dir, "allowance.json");
     const oldPath = join(dir, "wallet.json");
-    // Auto-migrate from wallet.json → allowance.json
+    // Auto-migrate from wallet.json → allowance.json. renameSync preserves the
+    // source file's mode, so a legacy world-readable wallet.json (mode 0644)
+    // would otherwise carry that mode forward and leave the private key
+    // world-readable on a shared machine. Tighten to 0600 after the rename.
     if (!existsSync(newPath) && existsSync(oldPath)) {
         mkdirSync(dir, { recursive: true });
         renameSync(oldPath, newPath);
+        try {
+            chmodSync(newPath, 0o600);
+        }
+        catch {
+            // Best-effort (e.g. Windows / exotic filesystems). Read-time self-heal
+            // in readAllowance() is the backstop.
+        }
     }
     return newPath;
 }

package/core-dist/profiles.js

@@ -0,0 +1,196 @@
+/**
+ * Named-wallet profile storage.
+ *
+ * A "wallet" is a whole config directory. The reserved `default` wallet lives
+ * at the base config dir (zero migration for existing installs); every named
+ * wallet lives under `{base}/profiles/<name>/` with its own `allowance.json`,
+ * `projects.json`, and this module's non-secret `meta.json`.
+ *
+ * Two levels of active state, mirroring the wallet → project model:
+ *   - base `{base}/config.json` `active_wallet`  — which wallet is the default
+ *   - per-wallet `projects.json` `active_project_id` — which project within it
+ *
+ * All writes are atomic (temp-file + rename) and owner-only (0600 files,
+ * 0700 dirs). `meta.json` holds only public/display data (no private key), so
+ * listing and name display never need to load key material.
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync, chmodSync, existsSync, readdirSync, rmSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, } from "./config.js";
+function atomicWrite(p, content, mode) {
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    const tmp = join(dir, `.${randomBytes(4).toString("hex")}.tmp`);
+    writeFileSync(tmp, content, { mode });
+    renameSync(tmp, p);
+    try {
+        chmodSync(p, mode);
+    }
+    catch {
+        /* best-effort on non-POSIX */
+    }
+}
+// --- base config.json (global default wallet pointer) ---
+function baseConfigPath() {
+    return join(getConfigBaseDir(), "config.json");
+}
+export function readBaseConfig() {
+    try {
+        const parsed = JSON.parse(readFileSync(baseConfigPath(), "utf-8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* missing / unreadable / malformed → empty */
+    }
+    return {};
+}
+export function writeBaseConfig(cfg) {
+    atomicWrite(baseConfigPath(), JSON.stringify(cfg, null, 2), 0o600);
+}
+/**
+ * The globally-selected default wallet (set via `wallets use`), or the
+ * reserved `default` when unset/invalid. This is precedence rung 4 — below the
+ * flag, env var, and per-directory binding.
+ */
+export function getDefaultWallet() {
+    const w = readBaseConfig().active_wallet;
+    return w && (w === DEFAULT_PROFILE || isValidProfileName(w)) ? w : DEFAULT_PROFILE;
+}
+export function setDefaultWallet(name) {
+    const cfg = readBaseConfig();
+    cfg.active_wallet = name;
+    writeBaseConfig(cfg);
+}
+// --- per-profile directory + meta.json ---
+/** Absolute directory for a wallet. `default` → base dir; named → profiles/<name>. */
+export function profileDir(name) {
+    return name === DEFAULT_PROFILE ? getConfigBaseDir() : join(getProfilesDir(), name);
+}
+/** Create (if needed) a wallet's directory with owner-only (0700) perms. */
+export function ensureProfileDir(name) {
+    const dir = profileDir(name);
+    if (name === DEFAULT_PROFILE) {
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    }
+    const profilesRoot = getProfilesDir();
+    mkdirSync(profilesRoot, { recursive: true });
+    try {
+        chmodSync(profilesRoot, 0o700);
+    }
+    catch {
+        /* best-effort */
+    }
+    mkdirSync(dir, { recursive: true });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best-effort */
+    }
+    return dir;
+}
+function metaPath(name) {
+    return join(profileDir(name), "meta.json");
+}
+export function readMeta(name) {
+    try {
+        const parsed = JSON.parse(readFileSync(metaPath(name), "utf-8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        /* missing / unreadable / malformed → null */
+    }
+    return null;
+}
+export function writeMeta(name, meta) {
+    ensureProfileDir(name);
+    atomicWrite(metaPath(name), JSON.stringify(meta, null, 2), 0o600);
+}
+// --- enumeration + lifecycle ---
+/** True when a wallet's `allowance.json` exists on disk. */
+export function profileExists(name) {
+    return existsSync(join(profileDir(name), "allowance.json"));
+}
+/**
+ * All wallet names on disk: `default` (only if a root allowance.json exists)
+ * plus every valid directory under `profiles/`.
+ */
+export function listProfileNames() {
+    const names = [];
+    if (existsSync(join(getConfigBaseDir(), "allowance.json"))) {
+        names.push(DEFAULT_PROFILE);
+    }
+    try {
+        for (const entry of readdirSync(getProfilesDir(), { withFileTypes: true })) {
+            if (entry.isDirectory() && isValidProfileName(entry.name))
+                names.push(entry.name);
+        }
+    }
+    catch {
+        /* no profiles dir yet */
+    }
+    return names;
+}
+/** Delete a named wallet's directory. Refuses to remove the reserved default. */
+export function removeProfile(name) {
+    if (name === DEFAULT_PROFILE) {
+        throw new Error("Refusing to remove the reserved 'default' wallet");
+    }
+    rmSync(profileDir(name), { recursive: true, force: true });
+}
+/**
+ * Move a wallet to a new name. Renaming `default` migrates the root-level
+ * credential files into `profiles/<newName>/` (so a named wallet is always a
+ * directory). Does NOT update the `active_wallet` pointer — the caller owns
+ * that orchestration. Throws if the destination already exists or the source
+ * is missing.
+ */
+export function renameProfile(oldName, newName) {
+    if (!isValidProfileName(newName)) {
+        throw new Error(`Invalid wallet name ${JSON.stringify(newName)}.`);
+    }
+    if (newName === oldName)
+        return;
+    const dest = join(getProfilesDir(), newName);
+    if (existsSync(dest)) {
+        throw new Error(`A wallet named '${newName}' already exists.`);
+    }
+    mkdirSync(getProfilesDir(), { recursive: true });
+    try {
+        chmodSync(getProfilesDir(), 0o700);
+    }
+    catch {
+        /* best-effort */
+    }
+    if (oldName === DEFAULT_PROFILE) {
+        if (!profileExists(DEFAULT_PROFILE)) {
+            throw new Error("No 'default' wallet to rename.");
+        }
+        mkdirSync(dest, { recursive: true });
+        try {
+            chmodSync(dest, 0o700);
+        }
+        catch {
+            /* best-effort */
+        }
+        const base = getConfigBaseDir();
+        for (const f of ["allowance.json", "projects.json", "meta.json"]) {
+            const src = join(base, f);
+            if (existsSync(src))
+                renameSync(src, join(dest, f));
+        }
+        return;
+    }
+    const src = join(getProfilesDir(), oldName);
+    if (!existsSync(src)) {
+        throw new Error(`Wallet '${oldName}' not found.`);
+    }
+    renameSync(src, dest);
+}
+//# sourceMappingURL=profiles.js.map

package/lib/allowance.mjs

@@ -1,4 +1,4 @@
-import { readAllowance, saveAllowance, ALLOWANCE_FILE } from "./config.mjs";
+import { readAllowance, saveAllowance, allowanceFile } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { assertKnownFlags, flagValue, normalizeArgv, parseIntegerFlag, positionalArgs } from "./argparse.mjs";
@@ -98,7 +98,7 @@ async function status() {
         // now" check, use `run402 allowance balance`.
         faucet_used: !!data.faucet_used,
         rail: w?.rail || "x402",
-        path: data.path ?? ALLOWANCE_FILE,
+        path: data.path ?? allowanceFile(),
       },
     }));
   } catch (err) {
@@ -111,7 +111,7 @@ async function create() {
     const result = await getSdk().allowance.create();
     console.log(JSON.stringify({
       address: result.address,
-      path: result.path ?? ALLOWANCE_FILE,
+      path: result.path ?? allowanceFile(),
       created: true,
     }));
   } catch (err) {

package/lib/config.mjs

@@ -9,9 +9,24 @@ import { loadKeyStore, getProject, saveProject, updateProject, removeProject, sa
 import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
 import { fail } from "./sdk-errors.mjs";
 
+// Wallet-dependent paths are exposed as getters (preferred — they always
+// reflect the active profile, even if some future code path imports this module
+// before wallet resolution). Production code (init/doctor/allowance) uses these.
+export function configDir() { return getConfigDir(); }
+export function allowanceFile() { return getAllowancePath(); }
+export function projectsFile() { return getKeystorePath(); }
+
+// Snapshot constants, retained for backward compatibility (tests, the OpenClaw
+// config re-export). These are evaluated when this module is first imported.
+// That is safe in every real flow because the CLI resolves the active wallet
+// (publishing RUN402_WALLET) in cli.mjs BEFORE any subcommand imports this
+// module, and tests set RUN402_CONFIG_DIR before importing. New code should
+// prefer the getters above.
 export const CONFIG_DIR = getConfigDir();
 export const ALLOWANCE_FILE = getAllowancePath();
 export const PROJECTS_FILE = getKeystorePath();
+
+// API base is independent of the active wallet, so a module-load snapshot is safe.
 export const API = getApiBase();
 
 /**
@@ -32,7 +47,7 @@ export function readAllowance() {
       code: "BAD_ALLOWANCE_FILE",
       message: err?.message ?? "allowance.json is malformed",
       hint: "Back up ~/.config/run402/allowance.json and run 'run402 init' to recreate it.",
-      details: { path: ALLOWANCE_FILE },
+      details: { path: allowanceFile() },
     });
   }
 }

package/lib/doctor.mjs

@@ -12,7 +12,7 @@
  */
 
 import { existsSync, statSync } from "node:fs";
-import { CONFIG_DIR, readAllowance, loadKeyStore } from "./config.mjs";
+import { configDir, readAllowance, loadKeyStore } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import {
   resolveScanRoot,
@@ -39,6 +39,9 @@ Checks performed:
   - Keystore has at least one wallet
   - API_BASE is reachable (network check via /health)
   - Active tier resolves and is not 'past_due' / 'frozen'
+  - Function runtime staleness: deployed functions running an older platform
+    runtime than the current gateway build (refresh with 'run402 functions
+    rebuild --all'; re-bundles from your stored source, no source change)
   - Source scan: hallucinated SDK auth names (R402_AUTH_UNKNOWN_EXPORT),
     state-changing GET handlers (R402_AUTH_STATE_CHANGING_GET),
     auth.* calls in prerendered pages (R402_AUTH_PRERENDERED),
@@ -62,6 +65,7 @@ export async function run(sub, args = []) {
   const scanDirOverride = scanDirArgIdx >= 0 ? all[scanDirArgIdx + 1] : null;
 
   const checks = [];
+  const CONFIG_DIR = configDir();
 
   // 1. Config directory.
   try {
@@ -226,16 +230,57 @@ export async function run(sub, args = []) {
     } else {
       checks.push({ name: "operator_health", status: "ok" });
     }
+
+    // 6b. Function runtime staleness (v1.69, capability
+    // function-runtime-rebuild). A deployed function is stale when its Lambda
+    // zip carries an older platform entry wrapper / bundled runtime than the
+    // gateway's current build — a plain redeploy with unchanged source does
+    // NOT refresh it (apply's release diff keys on the source code_hash, not
+    // the wrapper). Read-only signal; refreshing is strictly opt-in. Reuses
+    // the operator status fetched above to avoid a second round-trip.
+    const runtime = status.runtime;
+    if (runtime && typeof runtime.stale_function_count === "number") {
+      if (runtime.stale_function_count > 0) {
+        checks.push({
+          name: "runtime_staleness",
+          status: "warning",
+          value: {
+            stale_function_count: runtime.stale_function_count,
+            stale_functions: runtime.stale_functions ?? [],
+          },
+          hint: `${runtime.stale_function_count} function(s) are running an older platform runtime. Run 'run402 functions rebuild --all' to refresh (re-bundles from your stored source; no source change).`,
+        });
+      } else {
+        checks.push({
+          name: "runtime_staleness",
+          status: "ok",
+          value: { stale_function_count: 0 },
+        });
+      }
+    } else {
+      // Gateway older than v1.69 doesn't surface the runtime block.
+      checks.push({
+        name: "runtime_staleness",
+        status: "skipped",
+        ...(verbose && { hint: "operator status has no 'runtime' block; requires v1.69+ gateway." }),
+      });
+    }
   } catch (err) {
     // Operator status endpoint may not be reachable if the operator-binding
     // substrate isn't deployed yet on the target API. Don't fail the whole
-    // doctor over it — emit as a soft warning.
+    // doctor over it — emit as a soft warning. The runtime-staleness check
+    // rides on the same fetch, so skip it for the same reason.
     checks.push({
       name: "operator_health",
       status: "skipped",
       message: err instanceof Error ? err.message : String(err),
       ...(verbose && { hint: "GET /agent/v1/operator/status not reachable; requires v1.55+ gateway." }),
     });
+    checks.push({
+      name: "runtime_staleness",
+      status: "skipped",
+      message: err instanceof Error ? err.message : String(err),
+    });
   }
 
   // 7. Source-tree scan (auth-aware-ssr Section 9). Detects hallucinated