feat(sdk,cli,mcp): v1.57 lifecycle-state-on-billing-account client cascade (#402)

Gateway v1.57 moved the lifecycle state machine from `internal.projects` to
`internal.billing_accounts` and dropped the per-project pin endpoints. This is
the client-side cascade — runs as a breaking minor.

SDK (`@run402/sdk`):
- `ProjectSummary` / `UsageReport`: drop `status` (and `pinned` on list), gain
  `effective_status`, `account_lifecycle_state`, `lease_perpetual`,
  `deleted_at`, `archived_at`. New `EffectiveProjectStatus` /
  `BillingAccountLifecycleState` union types.
- `TierStatusResult`: optional top-level `account_lifecycle_state` +
  `lease_perpetual`.
- `r.admin`: new `setLeasePerpetual(ba, bool)`, `archiveProject(id, {reason?})`,
  `reactivateProject(id)` with typed result envelopes (including no-op
  `note: "already archived" | "not archived"` variants).
- Remove `r.projects.pin()` and the scoped wrapper; remove `PinResult`.

CLI (`run402`):
- New `run402 admin` group: `lease-perpetual`, `archive`, `reactivate`.
- `run402 projects pin` returns a `REMOVED_COMMAND` envelope pointing at
  `admin lease-perpetual` (no network call).
- `run402 status` exposes top-level `account_lifecycle_state` +
  `lease_perpetual`.

MCP (`run402-mcp`):
- New tools: `admin_set_lease_perpetual`, `admin_archive_project`,
  `admin_reactivate_project`. Drop `pin_project`.
- `list_projects` / `get_usage` render the new lifecycle fields.

Docs + drift: SKILL.md, openclaw/SKILL.md, llms-mcp.txt, cli/llms-cli.txt,
sdk/llms-sdk.txt rewritten; SURFACE + SDK_BY_CAPABILITY updated; banned-
regression patterns added for `pin_project` (SKILL) and `run402 projects pin`
(openclaw SKILL).

Closes #402.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MajorTal

SKILL.md

@@ -564,8 +564,9 @@ For agents that need to sign Ethereum transactions. Private keys never leave AWS
 - **`allowance_status`** / **`allowance_create`** / **`allowance_export`** — local allowance management.
 - **`request_faucet`** — testnet USDC.
 - **`check_balance`** — USDC for an allowance address.
-- **`list_projects`** — active projects for a wallet.
-- **`pin_project`** — pin a project (admin only — uses the configured admin allowance wallet).
+- **`list_projects`** — active projects for a wallet. Each row carries v1.57 lifecycle fields: `effective_status`, `account_lifecycle_state` (same value across every project on the billing account), `lease_perpetual`, `deleted_at`, `archived_at`.
+- **`admin_set_lease_perpetual`** — operator escape hatch (v1.57+). Toggles the billing account's `lease_perpetual` flag so the account never advances past `active` regardless of lease expiry. Replaces the v1.56 per-project pin tool (gateway endpoint was removed). Enabling on a grace-state account reactivates inline.
+- **`admin_archive_project`** / **`admin_reactivate_project`** — operator moderation actions on a single project (`projects.archived_at`). Independent of account-level lifecycle.
 - **`project_info`** / **`project_keys`** / **`project_use`** — inspect / set the active project.
 - **`send_message`** — send feedback to the Run402 team.
 - **`set_agent_contact`** / **`get_agent_contact_status`** / **`verify_agent_contact_email`** — register agent contact info, read assurance status, and start the operator email reply challenge.
@@ -618,17 +619,23 @@ Project rate limit: **100 req/sec**. Exceeding returns 429 with `retry_after`. E
 
 ## Project lifecycle (~104-day soft delete)
 
-After lease expires, projects go through a state machine. The live data plane keeps serving the whole time — only the owner's control plane gets gated:
+Gateway v1.57 moved the lifecycle state machine from `internal.projects` to `internal.billing_accounts`. The grace clock now ticks per **billing account** — every project on the same account inherits the same `account_lifecycle_state`. The live data plane keeps serving the whole time; only the owner's control plane gets gated:
 
 | State | When | What happens |
 |-------|------|--------------|
 | `active` | — | Full read/write |
 | `past_due` | day 0 | Site, REST, email keep serving. Owner gets first email. |
 | `frozen` | +14d | Control plane (deploys, secrets, subdomain claims, function upload) returns 402 with `lifecycle_state` / `entered_state_at` / `next_transition_at`. Site still serves. Subdomain reserved so the brand can't be claimed by another wallet. |
 | `dormant` | +44d | Scheduled functions pause. |
-| `purged` | +104d | Cascade: schema dropped, Lambdas deleted, mailbox tombstoned. Subdomain becomes claimable 14 days later. |
+| `purged` | +104d | Cascade: schemas dropped, Lambdas deleted, mailboxes tombstoned. Subdomains become claimable 14 days later. |
 
-Calling **`set_tier`** during grace reactivates the project and clears all timers in one transaction. Pinned projects bypass the state machine entirely.
+Calling **`set_tier`** during grace reactivates the **account** inline and clears every project's timers in one transaction. Per-project fields on each `list_projects` row:
+
+- `effective_status` — derived for serving / UX. Equals `account_lifecycle_state` unless the project is individually archived (`archived_at` set → `archived`) or deleted (`deleted_at` set → `deleted`).
+- `account_lifecycle_state` — the raw per-account state. Identical across every project on the same account.
+- `lease_perpetual` — operator escape hatch flag on the owning account. When `true`, the account never advances past `active`. Replaces the v1.56 per-project `pinned`. Toggle via **`admin_set_lease_perpetual`** (platform-admin only).
+
+Operator moderation actions (independent of lifecycle, scoped to a single project): **`admin_archive_project`** and **`admin_reactivate_project`**.
 
 ## Standard Workflow
 
@@ -693,7 +700,7 @@ Other allowance options:
 |---|---|
 | `402 payment_required` on `set_tier` | Allowance is empty. Call `request_faucet` (testnet) or fund with real USDC. |
 | `402` with `lifecycle_state: frozen` | Project past lease + 14 days. `set_tier` reactivates instantly. |
-| `403 admin_required` | Tool is admin-only (e.g., `pin_project`). Use a platform admin allowance wallet; project owners can't pin their own projects. |
+| `403 admin_required` | Tool is platform-admin only (e.g., `admin_set_lease_perpetual`, `admin_archive_project`, `admin_reactivate_project`). Use a platform admin allowance wallet; project owners can't toggle these on their own. |
 | Empty `[]` from `rest_query` for anon | Table not in manifest with `expose: true`. Call `apply_expose`. |
 | `403 forbidden_function` calling an RPC | Function not in the manifest's `rpcs[]`. Add `{ name, signature, grant_to: ["authenticated"] }` and re-apply. |
 | `409 reserved` from `claim_subdomain` | Original owner's grace period — subdomain held until +118 days from lease expiry. |

SKILL.test.ts

@@ -111,6 +111,7 @@ describe("SKILL.md (root, MCP-based)", () => {
       { pattern: /\bvalue_hash\b/, reason: "secret value hashes are no longer public; list only keys/timestamps" },
       { pattern: /"secrets"\s*:\s*\{\s*"set"\s*:/, reason: "deploy specs must not carry secret values; use secrets.require" },
       { pattern: /\breplace_all\b/, reason: "secrets.replace_all is not representable in value-free deploy specs" },
+      { pattern: /\bpin_project\b/, reason: "pin_project was removed in v1.57; use admin_set_lease_perpetual" },
     ];
     for (const { pattern, reason } of banned) {
       it(`does not contain: ${pattern.source}`, () => {
@@ -222,6 +223,7 @@ describe("openclaw/SKILL.md (CLI-based)", () => {
       { pattern: /"secrets"\s*:\s*\[/, reason: "CLI deploy manifests must not carry legacy secret value arrays" },
       { pattern: /"secrets"\s*:\s*\{\s*"set"\s*:/, reason: "deploy specs must not carry secret values; use secrets.require" },
       { pattern: /\breplace_all\b/, reason: "secrets.replace_all is not representable in value-free deploy specs" },
+      { pattern: /\brun402 projects pin\b/, reason: "`run402 projects pin` was removed in v1.57; use `run402 admin lease-perpetual`" },
     ];
     for (const { pattern, reason } of banned) {
       it(`does not contain: ${pattern.source}`, () => {

cli-e2e.test.mjs

@@ -190,9 +190,28 @@ async function mockFetch(input, init) {
   if (path.match(/^\/projects\/v1\/[^/]+$/) && method === "DELETE") {
     return Promise.resolve(noContent());
   }
-  if (path.match(/^\/projects\/v1\/admin\/[^/]+\/pin$/) && method === "POST") {
+  if (path.match(/^\/billing-accounts\/v1\/admin\/[^/]+\/lease-perpetual$/) && method === "POST") {
+    const accountId = path.split("/").at(-2);
+    const desired = Boolean(body?.lease_perpetual);
+    return Promise.resolve(json({
+      status: "ok",
+      billing_account_id: accountId,
+      lease_perpetual: desired,
+      reactivated: desired,
+    }));
+  }
+  if (path.match(/^\/projects\/v1\/admin\/[^/]+\/archive$/) && method === "POST") {
+    const projectId = path.split("/").at(-2);
+    return Promise.resolve(json({
+      status: "ok",
+      project_id: projectId,
+      archived_at: "2026-05-06T12:00:00.000Z",
+      reason: body?.reason ?? "(no reason given)",
+    }));
+  }
+  if (path.match(/^\/projects\/v1\/admin\/[^/]+\/reactivate$/) && method === "POST") {
     const projectId = path.split("/").at(-2);
-    return Promise.resolve(json({ status: "pinned", project_id: projectId }));
+    return Promise.resolve(json({ status: "ok", project_id: projectId, reactivated: true }));
   }
   if (
     (path === "/projects/v1/expose/validate" ||
@@ -1838,8 +1857,13 @@ describe("CLI e2e happy path", () => {
     assert.equal(seenCookie, "run402_admin=test-session");
   });
 
-  it("projects pin uses allowance admin auth, not project service key auth", async () => {
-    const { run } = await import("./cli/lib/projects.mjs");
+  // v1.57: projects pin was removed in favor of admin lease-perpetual.
+  // Same auth shape — allowance SIWX, X-Admin-Mode: 1, no Bearer service_key.
+  // The mockFetch lease-perpetual route echoes the request body back as the
+  // `lease_perpetual` field of the response, so verifying the response shape
+  // is equivalent to verifying the body went out correctly.
+  it("admin lease-perpetual uses allowance admin auth, not project service key auth", async () => {
+    const { run } = await import("./cli/lib/admin.mjs");
     const { saveAllowance } = await import("./cli/lib/config.mjs");
     saveAllowance({
       address: "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
@@ -1849,19 +1873,22 @@ describe("CLI e2e happy path", () => {
       rail: "x402",
     });
     let seenUrl = null;
+    let seenMethod = null;
     let seenSiwx = null;
     let seenAdminMode = null;
     let seenAuthorization = null;
     const prevFetch = globalThis.fetch;
     globalThis.fetch = (input, init) => {
       const url = typeof input === "string" ? input : (input instanceof Request ? input.url : String(input));
-      if (url.includes("/projects/v1/admin/prj_external/pin")) {
+      if (url.includes("/billing-accounts/v1/admin/ba_external/lease-perpetual")) {
         seenUrl = url;
         if (input instanceof Request) {
+          seenMethod = input.method;
           seenSiwx = input.headers.get("sign-in-with-x");
           seenAdminMode = input.headers.get("x-admin-mode");
           seenAuthorization = input.headers.get("authorization");
         } else {
+          seenMethod = init?.method ?? "GET";
           const headers = init?.headers ?? {};
           seenSiwx = headers["SIGN-IN-WITH-X"] ?? headers["sign-in-with-x"] ?? null;
           seenAdminMode = headers["X-Admin-Mode"] ?? headers["x-admin-mode"] ?? null;
@@ -1872,19 +1899,23 @@ describe("CLI e2e happy path", () => {
     };
     captureStart();
     try {
-      await run("pin", ["prj_external"]);
+      await run("lease-perpetual", ["ba_external", "--enable"]);
     } finally {
       captureStop();
       globalThis.fetch = prevFetch;
     }
-    assert.ok(seenUrl && seenUrl.includes("/projects/v1/admin/prj_external/pin"),
-      `pin should hit the admin pin endpoint; got: ${seenUrl}`);
-    assert.equal(typeof seenSiwx, "string", "pin should send allowance SIWX admin-wallet auth");
-    assert.equal(seenAdminMode, "1", "pin should explicitly request admin mode");
-    assert.equal(seenAuthorization, null, "pin must not use the project's service_key as Bearer auth");
+    assert.ok(
+      seenUrl && seenUrl.includes("/billing-accounts/v1/admin/ba_external/lease-perpetual"),
+      `lease-perpetual should hit the admin endpoint; got: ${seenUrl}`,
+    );
+    assert.equal(seenMethod, "POST");
+    assert.equal(typeof seenSiwx, "string", "lease-perpetual should send allowance SIWX admin-wallet auth");
+    assert.equal(seenAdminMode, "1", "lease-perpetual should explicitly request admin mode");
+    assert.equal(seenAuthorization, null, "lease-perpetual must not use a service_key as Bearer auth");
     const parsed = JSON.parse(capturedStdout());
-    assert.equal(parsed.status, "pinned");
-    assert.equal(parsed.project_id, "prj_external");
+    assert.equal(parsed.billing_account_id, "ba_external");
+    assert.equal(parsed.lease_perpetual, true,
+      "mockFetch echoes the request body; if this is false, the body didn't carry lease_perpetual:true");
   });
 
   it("projects schema defaults to active project (GH-102)", async () => {
@@ -4281,35 +4312,57 @@ describe("CLI e2e happy path", () => {
     bannerRegex: /^run402 projects/,
   });
 
-  // GH-103: `projects pin` must be clearly marked as admin-only in help text.
-  // The server-side /projects/v1/admin/:id/pin endpoint rejects project-owner
-  // auth (service_key / SIWX) with 403 admin_required. Help text that omits
-  // the admin caveat leads owners into an error they cannot resolve.
-  it("projects pin --help marks pin as admin-only (GH-103)", async () => {
+  // v1.57: `projects pin` was removed. The CLI now surfaces a structured
+  // REMOVED_COMMAND error pointing users at `admin lease-perpetual` — without
+  // making a network call — so owners who follow stale docs get redirected
+  // instead of hitting a 404. The replacement help (lease-perpetual / archive
+  // / reactivate) must clearly mark itself as admin-only.
+  it("projects pin returns REMOVED_COMMAND with a hint at admin lease-perpetual (v1.57)", async () => {
     const { run } = await import("./cli/lib/projects.mjs");
     let fetchCalled = false;
     const prevFetch = globalThis.fetch;
     globalThis.fetch = (...args) => { fetchCalled = true; return prevFetch(...args); };
     let threw = null;
     captureStart();
     try {
-      await run("pin", ["--help"]);
+      await run("pin", ["prj_anything"]);
     } catch (e) {
       threw = e;
     } finally {
       captureStop();
       globalThis.fetch = prevFetch;
     }
-    assert.equal(threw?.message, "process.exit(0)", "pin --help should exit 0");
-    assert.equal(fetchCalled, false, "pin --help must not make any fetch/API call");
+    assert.equal(threw?.message, "process.exit(1)", "projects pin should exit non-zero");
+    assert.equal(fetchCalled, false, "removed command must not make any fetch/API call");
+    const stderr = capturedStderr();
+    const envelope = JSON.parse(stderr.trim());
+    assert.equal(envelope.code, "REMOVED_COMMAND");
+    assert.match(envelope.hint, /admin lease-perpetual/i,
+      `hint should point at admin lease-perpetual; got: ${envelope.hint}`);
+  });
+
+  it("admin --help marks subcommands as admin-only (v1.57 replacements)", async () => {
+    const { run } = await import("./cli/lib/admin.mjs");
+    let fetchCalled = false;
+    const prevFetch = globalThis.fetch;
+    globalThis.fetch = (...args) => { fetchCalled = true; return prevFetch(...args); };
+    let threw = null;
+    captureStart();
+    try {
+      await run("--help", []);
+    } catch (e) {
+      threw = e;
+    } finally {
+      captureStop();
+      globalThis.fetch = prevFetch;
+    }
+    assert.equal(threw?.message, "process.exit(0)", "admin --help should exit 0");
+    assert.equal(fetchCalled, false, "admin --help must not make any fetch/API call");
     const stdout = capturedStdout();
-    // Find the pin line in the subcommand list and assert it mentions admin.
-    const pinLine = stdout.split("\n").find(l => /^\s*pin\s/.test(l)) ?? "";
-    assert.match(
-      pinLine,
-      /admin/i,
-      `pin subcommand line should mention admin-only; got: ${pinLine}`,
-    );
+    assert.match(stdout, /admin/i, "admin help should mention admin gating");
+    assert.match(stdout, /lease-perpetual/);
+    assert.match(stdout, /archive/);
+    assert.match(stdout, /reactivate/);
   });
 
   // Also spot-check the short flag alias -h works.

cli-help.test.mjs

@@ -57,10 +57,14 @@ const MATRIX = {
   projects: {
     shared: [
       "quote", "use", "list", "info", "keys", "rest",
-      "usage", "schema", "rls", "delete", "pin", "promote-user", "demote-user",
+      "usage", "schema", "rls", "delete", "promote-user", "demote-user",
     ],
     specific: ["provision", "sql", "costs", "validate-expose"],
   },
+  admin: {
+    shared: [],
+    specific: ["lease-perpetual", "archive", "reactivate"],
+  },
   deploy: { shared: [], specific: ["apply", "resume", "list", "events", "diagnose", "resolve", "release"] },
   ci: { shared: [], specific: ["link", "list", "revoke"] },
   functions: {

cli/cli.mjs

@@ -25,6 +25,7 @@ Commands:
   allowance   Manage your agent allowance (create, fund, balance, status)
   tier        Manage tier subscription (status, set)
   projects    Manage projects (provision, list, query, inspect, delete)
+  admin       Platform-admin operations (lease-perpetual, archive, reactivate)
   deploy      Unified deploy operations (requires active tier)
   ci          Link GitHub Actions OIDC deploy bindings
   jobs        Submit and inspect fixed platform-managed jobs
@@ -125,6 +126,11 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
+  case "admin": {
+    const { run } = await import("./lib/admin.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "deploy": {
     const { run } = await import("./lib/deploy.mjs");
     await run([sub, ...rest].filter(Boolean));