@run402/sdk 4.93.2 → 4.94.0

package/README.md

@@ -14,7 +14,7 @@ Deployment summaries share the SDK workflow view. CLI writes redacted detail und
 
 | Import | Use when |
 |---|---|
-| `@run402/sdk/node` | Running in Node 22 with the local profile state, project-key credential cache, and allowance. Auto-loads the configured API base, profile `credentials/project-keys.v1.json`, and signs x402 payments from the selected allowance or opaque signer. Includes `r.actions.run(...)`, `r.up(...)`, `r.sites.deployDir(dir)`, `fileSetFromDir(dir)`, `loadDeployManifest(path)`, `normalizeDeployManifest(input)`, and `resolveRun402TargetProfile()`. |
+| `@run402/sdk/node` | Running in Node 22 with the local profile state, project-key credential cache, and wallet. Auto-loads the configured API base, profile `credentials/project-keys.v1.json`, and signs x402 payments from the selected wallet or opaque signer. Includes `r.actions.run(...)`, `r.up(...)`, `r.sites.deployDir(dir)`, `fileSetFromDir(dir)`, `loadDeployManifest(path)`, `normalizeDeployManifest(input)`, and `resolveRun402TargetProfile()`. |
 | `@run402/sdk` | Isomorphic — works in Node, Deno, Bun, V8 isolates. No filesystem access. Bring your own `CredentialsProvider` (a session-token shim, a remote vault, anything that resolves project keys + auth headers). |
 
 The Node entry sends bounded client-version metadata on gateway requests using the unprefixed `Run402-Client` header, for example `surface="sdk", version="3.7.14", sdk="3.7.14"`. The CLI passes `surface: "cli"`, so gateway compatibility hints can distinguish CLI-created SDK traffic from direct SDK callers. Metadata never includes local paths, package manager details, wallet/org/project ids, secrets, or install confidence. The isomorphic entry does not send this header by default; pass `clientMetadata` explicitly only in runtimes where custom headers are expected.
@@ -78,14 +78,14 @@ provider controls API authentication; the x402 payer is resolved exactly once
 in this order:
 
 1. `paymentSigner` — an explicit async EVM signer provider (KMS/HSM friendly).
-2. `allowancePath` — an explicit local allowance file.
-3. `credentials.readAllowance()` — when a supplied provider implements it.
-4. The Node default provider's active-profile allowance — only when the caller
+2. `walletPath` — an explicit local wallet file.
+3. `credentials.readWallet()` — when a supplied provider implements it.
+4. The Node default provider's active-profile wallet — only when the caller
    did not supply a custom credentials provider.
 
 Once a source is selected, the SDK never falls back to the ambient/global
-wallet. `paymentSigner` and `allowancePath` together throw
-`PAYMENT_SOURCE_CONFLICT`. Passing both `credentials` and `allowancePath` is
+wallet. `paymentSigner` and `walletPath` together throw
+`PAYMENT_SOURCE_CONFLICT`. Passing both `credentials` and `walletPath` is
 valid: auth uses `credentials`, while payment intentionally uses that file.
 `fetch` still takes precedence over built-in paid fetch, and
 `disablePaidFetch: true` disables automatic payment entirely.
@@ -123,7 +123,7 @@ const payer = await r.paymentPayer();
 
 The provider may return `null` for an unsupported Base network. Paid-fetch
 initialization is lazy and retries after missing/recoverable local state, so a
-long-lived client can start paying after its selected allowance/provider
+long-lived client can start paying after its selected wallet/provider
 becomes available without being reconstructed. `r.paymentPayer()` initializes
 the selected source if necessary and returns only its source, rail, public
 address(es), and network(s); it never returns a key, signed authorization, or
@@ -211,7 +211,7 @@ await r.actions.run({
 });
 ```
 
-Action identifiers are exported constants plus a string-literal union, so inputs narrow by `type`. `up` validates `run402.deploy.json` / `app.json` before any mutation, resolves the project as explicit `projectId` → `.run402/project.json` → manifest `project_id` → approved creation from `name`; global active state never selects a deployment target, then delegates to `r.project(id).apply(...)`. `name` is only project creation/link metadata; it is not a manifest field and never renames an existing project. If allowance/tier/project/link are already configured, `r.up()` can run the requested deploy with the default approval policy; pass `{ approval: "yes" }` only when you want recursive prerequisites/local writes to proceed unattended.
+Action identifiers are exported constants plus a string-literal union, so inputs narrow by `type`. `up` validates `run402.deploy.json` / `app.json` before any mutation, resolves the project as explicit `projectId` → `.run402/project.json` → manifest `project_id` → approved creation from `name`; global active state never selects a deployment target, then delegates to `r.project(id).apply(...)`. `name` is only project creation/link metadata; it is not a manifest field and never renames an existing project. If wallet/tier/project/link are already configured, `r.up()` can run the requested deploy with the default approval policy; pass `{ approval: "yes" }` only when you want recursive prerequisites/local writes to proceed unattended.
 
 Before any gateway call, in every mode, `up` verifies every local file the manifest references (migration `sql_path`/`sql_file`, function `source`/`files`, site `{ path }` entries and `dir()` targets, `assets.put[].source`) and throws `MANIFEST_FILE_MISSING` (`details.missing[]` of `{ field_path, path, kind }`, one `create_file` next action per file); `manifest` pointing at a missing path is `MANIFEST_NOT_FOUND`, and with no manifest in the directory `UP_MANIFEST_REQUIRED` lists `details.nearby_manifests[]` one level down with a read-only `run_in_directory` action for a single candidate, or one unranked `select_application` action for multiple apps. The same check is exported standalone from `@run402/sdk/node`: `collectLocalFileReferences(spec)`, `findMissingLocalFileReferences(spec)`, `assertLocalFileReferencesExist(spec, { manifestPath? })`, plus the `manifestFileMissingError` / `manifestNotFoundError` builders.
 
@@ -303,14 +303,14 @@ const r = new Run402({
 });
 ```
 
-The `CredentialsProvider` interface has two required methods (`getAuth`, `getProject`) plus optional ones (`saveProject`, `removeProject`, `setActiveProject`, `readAllowance`, `saveAllowance`, …) for hosts that want full sticky-default behavior.
+The `CredentialsProvider` interface has two required methods (`getAuth`, `getProject`) plus optional ones (`saveProject`, `removeProject`, `setActiveProject`, `readWallet`, `saveWallet`, …) for hosts that want full sticky-default behavior.
 
 ## Namespaces
 
 | Namespace | Highlights |
 |---|---|
 | `actions` | Node entry only (`@run402/sdk/node`). Generic recursive action runner: `actions.run({ type: Run402Action.Up | ProjectsProvision | TierSet, ... })`; `r.up(input, opts)` is the convenience for repo-level manifest deploys. Recursive mutations are approval-gated; `mode: "check" | "printSpec" | "printManifest" | "plan" | { kind: "applyReviewed" }` distinguishes local validation, gateway review, and exact reviewed apply. Child gateway mutations derive idempotency keys from the root action. |
-| `pay` | `fetch(url, init?, { maxUsdMicros?, idempotencyKey?, requireReceipt? })` — bounded arbitrary-URL x402 buyer; Node uses the selected allowance/signer and returns the response plus settlement and independently verified merchant evidence. |
+| `pay` | `fetch(url, init?, { maxUsdMicros?, idempotencyKey?, requireReceipt? })` — bounded arbitrary-URL x402 buyer; Node uses the selected wallet/signer and returns the response plus settlement and independently verified merchant evidence. |
 | `projects` | `provision`, `delete`, `list`, `get`, `use`, `active`, `sql`, `rest`, `validateExpose`, `applyExpose`, `getExpose`, `getUsage`, `getSchema`, `info`, `keys`, `pin`, `getQuote`. `list`/`get`/`use` are server-authoritative; local key reads are moving to `credentials.projectKeys`. |
 | `snapshots` | Internal project restore points: `create`, `list`, `get`, `restorePlan`, `restore`, `delete`. Restore is a two-step plan/confirm handshake. |
 | `branches` | Contained project data branches: `create`, `list`, `renew`, `delete`. Branches default to expiring, noindex, sandboxed-email copies. |
@@ -323,23 +323,25 @@ The `CredentialsProvider` interface has two required methods (`getAuth`, `getPro
 | `functions` | `deploy`, `invoke`, `logs` (`{ tail?, since?, requestId?, origin? }`; every entry carries `origin: "app" \| "platform"`, computed by the exported `classifyFunctionLogLine`, and `origin` filters client-side with `hidden: { platform, app }` counts), `logsByRequestId(projectId, requestId, { tail?, since?, origin?, functionName? })` (project-wide search for a `req_`/`fnrun_`/`fnatt_` id, the `x-run402-request-id` response header: reads every function, merges oldest-first, tags each entry with its `function`; also `r.project(id).functions.logsByRequestId`), `update`, `list`, `delete`, `rebuild`, `rebuildAll`, `runs.*` durable function requests |
 | `jobs` | `submit`, `get`, `logs`, `cancel`, `purge` for platform-managed jobs |
 | `secrets` | `set`, `list`, `delete` |
-| `subdomains` | `claim`, `list`, `delete` (most agents declare subdomains in `r.project(id).apply({ subdomains: { set: [...] } })` instead) |
+| `subdomains` | `add`, `list`, `delete` (most agents declare subdomains in `r.project(id).apply({ subdomains: { set: [...] } })` instead) |
 | `domains` | The ProjectDomain lifecycle — the one surface for custom domains (web + email): `ensure` (connect / update desired state), `get`, `list`, `check` (refresh observations), `apply` (records Run402 has authority over), `repair`, `wait`, `testReceive`, `activate`, `disconnect`. `desired` carries `web`, `email`, and an optional `authority` — `"hosted_dns_zone"` is the root-domain path (one nameserver change at the registrar; Run402 applies every in-zone record and issues TLS). Every response carries `next_actions[]`. |
 | `email` | `createMailbox`, `listMailboxes`, `setMailboxDefaults`, `updateMailbox`, `getMailbox`, `deleteMailbox`, `send`, `list`, `get`, `getRaw`, `webhooks.*` |
 | `auth` | `requestMagicLink` (link/code/both), `verifyMagicLink`, `verifyEmailCode`, `createUser`, `inviteUser`, `setUserPassword`, `settings`, passkey registration/login/list/delete helpers, typed `providers`, `promote`, `demote` |
 | `apps` | `browse`, `getApp`, `fork`, `publish`, `listVersions`, `updateVersion`, `deleteVersion` |
 | `tier` | `set`, `status` (tier pricing lives on `r.projects.getQuote()`) |
 | `billing` | `createEmailOrganization`, `linkWallet`, `createCheckout`, `setAutoRecharge`, `checkBalance`, `getOrganization`, `lookupOrganization`, `getHistory`, `balance`, `history` |
-| `vouchers` | `redeem` (promo code → prepaid credit; safe to retry) |
+| `vouchers` | `redeem` (promo code → the organization's allowance; safe to retry) |
 | `contracts` | `provisionSigner`, `getSigner`, `listSigners`, `setRecovery`, `setLowBalanceAlert`, `call`, `read`, `callStatus`, `drain`, `deleteSigner` |
 | `ai` | `translate`, `moderate`, `usage`, `generateImage` |
-| `allowance` | `status`, `create`, `export`, `faucet` |
 | `service` | `status`, `health` (no auth, no setup — works on a fresh install) |
-| `admin` | Operator/admin endpoints: messages/contact, per-project finance (`getProjectFinance`) |
-| `operator` | **The human / email principal** — distinct from the agent's per-wallet SIWX identity (and from platform-`admin`). Read session: `deviceStart`, `devicePoll`, `overview({ token })`, `revoke({ token })` — browser-delegated device-authorization (RFC 8628, the `aws sso login` model); `overview` returns the email-union across every wallet that verified the email. Write session (v1.78): `buildCliAuthorizeUrl`/`exchangeCliToken` (loopback-PKCE CLI login) + the hosted `operator.session.*` surface (email magic-link / passkey / OAuth login, `whoami`/`refresh`/`revoke`, step-up, authenticators, recovery) — carry a minted session SDK-wide with `controlPlaneSessionCredentials({ token })`. Drives `run402 operator login[/--loopback]/overview/whoami/logout`. No MCP tool by design — MCP authenticates as the agent, not the human. |
+| `admin` | Admin endpoints: messages/contact, notifications, staff-only per-project finance (`getProjectFinance`) |
+| `session` | **A person's sign-in session** — distinct from the agent's per-wallet SIWX identity. One session class, graded by provenance (`grade`: `browser`, `loopback`, `device` — read-only). CLI seams: `buildCliAuthorizeUrl`/`exchangeCliToken` (loopback PKCE, `run402 login`) and `deviceStart`/`devicePoll` (RFC 8628, `run402 login --device`). Browser surface: email magic link / passkey / OAuth sign-in, `whoami`/`refresh`/`revoke`, step-up, authenticators, recovery. Carry a minted session SDK-wide with `controlPlaneSessionCredentials({ token })`. No MCP tool by design. |
+| `writeApproval` | `requestChallenge`, `exchangeClaimCode` — the passkey-signed, `(action, target)`-scoped write approval a person without a wallet needs to provision, deploy, or write secrets (`run402 approve`); a gated write without one throws `WriteApprovalRequiredError`. |
+| `me` | `overview()` (`GET /agent/v1/me/overview`, joined into `run402 org list`), `status()` (`GET /agent/v1/me/status`, read by `run402 doctor` and MCP `whoami`) |
 | `identityLinks` | Public human/agent external identity attribution with a discriminated proof protocol. Agent `nostr.begin`/`complete` uses EOA + kind 1; human creation/revocation is browser-canonical. `list`, `getProof`, and `revoke` preserve multiple active and revoked records. Never accepts a Nostr secret and never grants authority. |
 | `buzz` | Capability-detecting Buzz control plane. `offerAdoption` plus `humanAdoptionOffers` creates/reads/cancels durable HTTPS handoffs and creates human-bound attempts; direct `humanAdoptions` is advanced compatibility. `install/enroll` and typed community/enrollment methods preserve separate principals, bounded named-project grants, drift, and scoped revocation. `notifications` routes project events into a Buzz channel (`createRoute`/`list`/`get`/`update`/`pause`/`resume`/`rotate`/`revoke`/`test`/`deliveries`/`testAndWait` — configure → authorize → test → live; the signing secret never leaves the gateway). Buzz signing stays outside the SDK. |
-| `wallet(address)` | `getLabel()`, `setLabel(label)` — the signed server-side wallet label (gateway `/wallets/v1/:address/label`) surfaced in the operator console; pushed on `wallets use` unless `RUN402_WALLET_LABEL_SYNC=0`. Use the `r.wallet(address)` handle; `r.wallets.getLabel(address)` remains a bare read |
+| `wallets` | The local wallet: `status`, `create`, `export`, `faucet`; plus `getLabel(address)` |
+| `wallet(address)` | `getLabel()`, `setLabel(label)` — the signed server-side wallet label (gateway `/wallets/v1/:address/label`) surfaced in the console; pushed on `wallets use` unless `RUN402_WALLET_LABEL_SYNC=0`. Use the `r.wallet(address)` handle; `r.wallets.getLabel(address)` remains a bare read |
 | `orgs` | **Org-owned control plane** (first-class orgs). `create`, `list`, `whoami` (the gateway-resolved control-plane identity) on the collection; the scoped `r.org(id)` sub-client (org analog of `r.project(id)`) adds `get`, `rename`, `setPayoutWallet`, `members.*` (`list`/`add`/`setRole`/`revoke`), `invites.*` (`list`/`create`/`revoke`), `audit`. Org create/read/rename summaries include `tier`, `lease_started_at`, and `lease_expires_at`. |
 | `grants` | `create`, `revoke` — per-project capability grants (e.g. `"deploy"`, `"functions:write"`) for agent/CI principals; owner-gated, also reachable project-scoped as `r.project(id).grants` |
 | `events` | `list`, `listForOrg` — the cursored project events feed ("what happened since I last looked"): deploy activations, suspensions, transfers, lifecycle cliffs, each with platform-suggested `next_actions`, plus app-emitted business facts (`source: "app"`) alongside the platform's own (`source: "platform"`) — filter with `{ source?, eventType? }`. Opaque store-and-echo cursor; `reset: true` + `earliest_cursor` instead of errors on expiry. Also reachable project-scoped as `r.project(id).events` |
@@ -823,12 +825,12 @@ const minted = await r.gitvault.handoff({
 });
 console.log(minted.handoff_key); // kgh1_… — print it ALONE, this is the only copy
 
-// on another machine, with no shared keystore or allowance:
+// on another machine, with no shared keystore or wallet:
 const resumed = await r.gitvault.resume({ key: "kgh1_…" });
 console.log(resumed.restored.dir); // the fresh checkout, dirty state reapplied
 ```
 
-**Invite / join — a second agent into the SAME work, dirty tree included (kygit-invite).** The second claim kind beside handoff/resume, sharing the same crypto/keystore/restore machinery, kind-parameterized: a Handoff passes the work on and the sender stops; an Invite grows the team while the sender keeps working. `r.gitvault.invite({ project_id, note, roomKey?, role?, ttlSeconds?, includeSensitive?, program?, model?, sessionKey? })` captures the checkpoint exactly like `handoff` — the inviter's own worktree, index, branch, refs, and access are all untouched — registers the inviter's OWN presence in the invite's room (the project's default room, or `roomKey` for a named org room) BEFORE minting, mints a single-use bearer `kgi1_<base64url(invite_id[16] ‖ master_secret[32])>` key (returned in `invite_key`, the ONLY copy), and posts ONE room message naming the checkpoint and invite id (never the key) — a presence or fact-post failure is reported in `inviter_presence`/`room_fact` and never voids the mint. `r.gitvault.join({ key, to?, program?, model?, sessionKey? })` claims it (a same-principal replay dedups safely), clones a fresh checkout, reapplies the checkpoint with `git stash apply --index`, pins the invite's OWN room locally (`r402.room`), registers this session's presence, posts ONE arrival message, and returns the inviter (name, labels, liveness), `live_presences`, the catch-up `cursor`, and the last few `recent_messages` — the joiner's first message needs no lookup. `r.gitvault.listInvites`/`revokeInvite` manage outstanding keys. A `kgh1_…` key handed to `join()`, or a `kgi1_…` key handed to `resume()`, is refused BY NAME (`INVITE_KEY_WRONG_KIND`/`HANDOFF_KEY_WRONG_KIND`) before any network call.
+**Invite / join — a second agent into the SAME work, dirty tree included (kygit-invite).** The second claim kind beside handoff/resume, sharing the same crypto/keystore/restore machinery, kind-parameterized: a Handoff passes the work on and the sender stops; an Invite grows the team while the sender keeps working. `r.gitvault.invite({ project_id, note, roomKey?, role?, ttlSeconds?, includeSensitive?, program?, model?, sessionKey? })` captures the checkpoint exactly like `handoff` — the inviter's own worktree, index, branch, refs, and access are all untouched — registers the inviter's OWN presence in the invite's room (the project's default room, or `roomKey` for a named org room) BEFORE minting, mints a single-use bearer `kgi1_<base64url(invite_id[16] ‖ master_secret[32])>` key (returned in `invite_key`, the ONLY copy), and posts ONE room message naming the checkpoint and invite id (never the key) — a presence or fact-post failure is reported in `inviter_presence`/`room_message` and never voids the mint. `r.gitvault.join({ key, to?, program?, model?, sessionKey? })` claims it (a same-principal replay dedups safely), clones a fresh checkout, reapplies the checkpoint with `git stash apply --index`, pins the invite's OWN room locally (`r402.room`), registers this session's presence, posts ONE arrival message, and returns the inviter (name, labels, liveness), `live_presences`, the catch-up `cursor`, and the last few `recent_messages` — the joiner's first message needs no lookup. `r.gitvault.listInvites`/`revokeInvite` manage outstanding keys. A `kgh1_…` key handed to `join()`, or a `kgi1_…` key handed to `resume()`, is refused BY NAME (`INVITE_KEY_WRONG_KIND`/`HANDOFF_KEY_WRONG_KIND`) before any network call.
 
 ```ts
 const minted = await r.gitvault.invite({
@@ -837,7 +839,7 @@ const minted = await r.gitvault.invite({
 });
 console.log(minted.invite_key); // kgi1_… — print it ALONE, this is the only copy
 
-// on another machine, with no shared keystore or allowance:
+// on another machine, with no shared keystore or wallet:
 const joined = await r.gitvault.join({ key: "kgi1_…" });
 console.log(joined.restored.dir); // the fresh checkout, dirty state reapplied
 console.log(joined.inviter?.name); // who invited you, and whether they're still live

package/core-dist/config.d.ts

@@ -39,7 +39,7 @@ export declare function getProfilesDir(): string;
  * 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
+ * keystore, wallet, 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.
  */
@@ -57,5 +57,19 @@ export declare function configureApiBase(apiBase: string, options?: Omit<ApiTarg
 export declare function getConfiguredApiBase(): string | null;
 export declare function getApiTargetKind(): ApiTargetKind;
 export declare function isCoreApiTarget(): boolean;
-export declare function getAllowancePath(): string;
+/**
+ * The file that holds a wallet's key, in the base config dir (the `default`
+ * wallet) and in each `profiles/<name>/` directory.
+ */
+export declare const WALLET_FILE_NAME = "wallet.json";
+/**
+ * One-time local move of the wallet key file to its current name: in the base
+ * config dir and every `profiles/<name>/` directory, `allowance.json` is
+ * renamed to `wallet.json` (an atomic same-directory rename) when
+ * `wallet.json` is absent, then tightened to 0600. A directory that already
+ * holds `wallet.json` is left untouched. Runs once per base dir per process;
+ * nothing reads the previous name afterwards.
+ */
+export declare function moveWalletFiles(): void;
+export declare function getWalletPath(): string;
 //# sourceMappingURL=config.d.ts.map

package/core-dist/config.js

@@ -1,6 +1,6 @@
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { existsSync, renameSync, mkdirSync, chmodSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, renameSync, mkdirSync, chmodSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { describeRejectedValue } from "./redact.js";
 export const DEFAULT_API_BASE = "https://api.run402.com";
@@ -118,7 +118,7 @@ export function getProfilesDir() {
  * 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
+ * keystore, wallet, 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.
  */
@@ -232,27 +232,61 @@ export function isCoreApiTarget() {
         return true;
     return false;
 }
-export function getAllowancePath() {
-    if (process.env.RUN402_ALLOWANCE_PATH)
-        return process.env.RUN402_ALLOWANCE_PATH;
-    const dir = getConfigDir();
-    const newPath = join(dir, "allowance.json");
-    const oldPath = join(dir, "wallet.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);
+/**
+ * The file that holds a wallet's key, in the base config dir (the `default`
+ * wallet) and in each `profiles/<name>/` directory.
+ */
+export const WALLET_FILE_NAME = "wallet.json";
+/** The name the wallet key file had before it was `wallet.json`. */
+const PREVIOUS_WALLET_FILE_NAME = "allowance.json";
+const walletFilesMovedFor = new Set();
+/**
+ * One-time local move of the wallet key file to its current name: in the base
+ * config dir and every `profiles/<name>/` directory, `allowance.json` is
+ * renamed to `wallet.json` (an atomic same-directory rename) when
+ * `wallet.json` is absent, then tightened to 0600. A directory that already
+ * holds `wallet.json` is left untouched. Runs once per base dir per process;
+ * nothing reads the previous name afterwards.
+ */
+export function moveWalletFiles() {
+    const base = getConfigBaseDir();
+    if (walletFilesMovedFor.has(base))
+        return;
+    walletFilesMovedFor.add(base);
+    const dirs = [base];
+    try {
+        for (const entry of readdirSync(join(base, "profiles"), { withFileTypes: true })) {
+            if (entry.isDirectory())
+                dirs.push(join(base, "profiles", entry.name));
+        }
+    }
+    catch {
+        // No profiles directory yet.
+    }
+    for (const dir of dirs) {
+        const from = join(dir, PREVIOUS_WALLET_FILE_NAME);
+        const to = join(dir, WALLET_FILE_NAME);
+        if (existsSync(to) || !existsSync(from))
+            continue;
+        try {
+            renameSync(from, to);
+        }
+        catch {
+            continue;
+        }
         try {
-            chmodSync(newPath, 0o600);
+            chmodSync(to, 0o600);
         }
         catch {
             // Best-effort (e.g. Windows / exotic filesystems). Read-time self-heal
-            // in readAllowance() is the backstop.
+            // in readWallet() is the backstop.
         }
     }
-    return newPath;
+}
+export function getWalletPath() {
+    if (process.env.RUN402_WALLET_PATH)
+        return process.env.RUN402_WALLET_PATH;
+    moveWalletFiles();
+    return join(getConfigDir(), WALLET_FILE_NAME);
 }
 //# sourceMappingURL=config.js.map

package/core-dist/control-plane-session.d.ts

@@ -1,33 +1,40 @@
 /**
- * A cached **control-plane session** — the human principal's bearer, minted by
- * the loopback-PKCE flow (`run402 operator login --loopback`). Distinct from the
- * device-flow {@link OperatorSession} (read-only): this one carries `provenance`
- * (`loopback_pkce`) and `amr`. It authorizes most control-plane operations, but
- * since gateway v1.85/v1.87 it is NOT sufficient on its own for the high-stakes
- * writes `provision` / `deploy` / secrets — those additionally require a
- * passkey-fresh **operator approval** (`X-Run402-Write-Auth`, minted by
- * `run402 operator approve`; see {@link WriteAuthApproval}). Cached at the BASE
- * config dir (email/principal-scoped, shared across local named wallets), mode
- * 0600 — the token is as sensitive as the allowance key.
+ * The cached **sign-in session** — a person's one Run402 session, bound to
+ * their principal and graded by how it was minted: `loopback` (`run402 login`,
+ * the loopback-PKCE browser ceremony; full, step-up-able) or `device`
+ * (`run402 login --device`, RFC 8628; read-only — the gateway refuses every
+ * mutation with `SESSION_READ_ONLY`). The wire token class is
+ * `control_plane_session`. The session authorizes most control-plane writes,
+ * but provisioning, deploying, and writing secrets additionally need a
+ * passkey-signed **write approval** (`X-Run402-Write-Approval`, minted by
+ * `run402 approve`; see `write-approvals.ts`). Cached at the BASE config dir
+ * (principal-scoped, shared across local named wallets), mode 0600 — the token
+ * is as sensitive as the wallet key.
  *
  * Stored shape vs the gateway payload: the gateway returns a relative
  * `expires_in` (seconds); we persist the absolute `expires_at` (epoch ms) so a
  * cached session can be expiry-checked without knowing when it was written.
  */
+/** How a sign-in session was minted, as the gateway reports it. */
+export type SessionGrade = "browser" | "loopback" | "device";
 export interface ControlPlaneSessionCache {
     control_plane_session_token: string;
     token_type: string;
-    provenance: string;
+    grade: SessionGrade;
     principal_id: string;
     amr: string[];
     /** Epoch ms when the session expires (issued_at + expires_in). */
     expires_at: number;
 }
-/** The token payload returned by `POST /agent/v1/control-plane/cli/token`. */
+/**
+ * The token payload returned by `POST /agent/v1/control-plane/cli/token`
+ * (grade `loopback`) and `POST /agent/v1/control-plane/cli/device/token`
+ * (grade `device`).
+ */
 export interface ControlPlaneSessionTokenResponse {
     control_plane_session_token: string;
     token_type?: string;
-    provenance?: string;
+    grade?: string;
     principal_id?: string;
     amr?: string[];
     expires_in?: number;
@@ -45,7 +52,7 @@ export declare function getControlPlaneSessionPath(): string;
 export declare function readControlPlaneSession(path?: string): ControlPlaneSessionCache | null;
 /** Persist a control-plane session atomically (temp-file + rename), mode 0600. */
 export declare function saveControlPlaneSession(data: ControlPlaneSessionCache, path?: string): void;
-/** Delete the cached control-plane session — local half of `operator logout`. Idempotent. */
+/** Delete the cached sign-in session — local half of `run402 logout`. Idempotent. */
 export declare function clearControlPlaneSession(path?: string): void;
 /** Whether a cached session is past its usable life (with a small skew buffer). */
 export declare function isControlPlaneSessionExpired(session: ControlPlaneSessionCache, nowMs?: number, skewMs?: number): boolean;
@@ -53,4 +60,12 @@ export declare function isControlPlaneSessionExpired(session: ControlPlaneSessio
 export declare function loadLiveControlPlaneSession(path?: string, nowMs?: number): ControlPlaneSessionCache | null;
 /** Map a gateway token payload (relative `expires_in`) into the cached shape (absolute `expires_at`). */
 export declare function controlPlaneSessionFromTokenResponse(resp: ControlPlaneSessionTokenResponse, nowMs?: number): ControlPlaneSessionCache;
+/**
+ * Delete the session caches of the retired email-scoped session
+ * (`{base}/operator-session.json`) and the retired approval cache file
+ * (`{base}/write-auth-session.json`). Neither is read any more; `run402 login`
+ * and `run402 logout` call this so a stale token does not linger on disk.
+ * Best-effort and idempotent.
+ */
+export declare function clearRetiredSessionCaches(): void;
 //# sourceMappingURL=control-plane-session.d.ts.map

package/core-dist/control-plane-session.js

@@ -10,6 +10,14 @@ export function getControlPlaneSessionPath() {
     return (process.env.RUN402_CONTROL_PLANE_SESSION_PATH ||
         join(getConfigBaseDir(), "control-plane-session.json"));
 }
+/**
+ * Read a wire grade. An unknown or absent value is treated as `device` (the
+ * read-only grade) so a cache the client cannot classify never claims more
+ * authority than the gateway will grant.
+ */
+function toGrade(raw) {
+    return raw === "browser" || raw === "loopback" || raw === "device" ? raw : "device";
+}
 /** Tighten 0600 if group/other-readable, warning once. Best-effort, POSIX-only. */
 function selfHealPermissions(p) {
     if (process.platform === "win32")
@@ -50,20 +58,20 @@ export function readControlPlaneSession(path) {
         return null;
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("control-plane-session.json must contain a JSON object. Delete it and run 'run402 operator login --loopback' to recreate it.");
+        throw new Error("control-plane-session.json must contain a JSON object. Delete it and run 'run402 login' to recreate it.");
     }
     const data = parsed;
     if (typeof data.control_plane_session_token !== "string" ||
         data.control_plane_session_token.length === 0) {
-        throw new Error("control-plane-session.json missing valid 'control_plane_session_token'. Run 'run402 operator login --loopback' to refresh it.");
+        throw new Error("control-plane-session.json missing valid 'control_plane_session_token'. Run 'run402 login' to refresh it.");
     }
     if (typeof data.expires_at !== "number" || !Number.isFinite(data.expires_at)) {
-        throw new Error("control-plane-session.json missing valid 'expires_at'. Run 'run402 operator login --loopback' to refresh it.");
+        throw new Error("control-plane-session.json missing valid 'expires_at'. Run 'run402 login' to refresh it.");
     }
     return {
         control_plane_session_token: data.control_plane_session_token,
         token_type: typeof data.token_type === "string" ? data.token_type : "Bearer",
-        provenance: typeof data.provenance === "string" ? data.provenance : "loopback_pkce",
+        grade: toGrade(data.grade),
         principal_id: typeof data.principal_id === "string" ? data.principal_id : "",
         amr: Array.isArray(data.amr) ? data.amr.filter((a) => typeof a === "string") : [],
         expires_at: data.expires_at,
@@ -79,7 +87,7 @@ export function saveControlPlaneSession(data, path) {
     renameSync(tmp, p);
     chmodSync(p, 0o600);
 }
-/** Delete the cached control-plane session — local half of `operator logout`. Idempotent. */
+/** Delete the cached sign-in session — local half of `run402 logout`. Idempotent. */
 export function clearControlPlaneSession(path) {
     const p = path ?? getControlPlaneSessionPath();
     try {
@@ -105,10 +113,27 @@ export function controlPlaneSessionFromTokenResponse(resp, nowMs = Date.now()) {
     return {
         control_plane_session_token: resp.control_plane_session_token,
         token_type: resp.token_type ?? "Bearer",
-        provenance: resp.provenance ?? "loopback_pkce",
+        grade: toGrade(resp.grade),
         principal_id: resp.principal_id ?? "",
         amr: Array.isArray(resp.amr) ? resp.amr.filter((a) => typeof a === "string") : [],
         expires_at: nowMs + (typeof resp.expires_in === "number" ? resp.expires_in : 0) * 1000,
     };
 }
+/**
+ * Delete the session caches of the retired email-scoped session
+ * (`{base}/operator-session.json`) and the retired approval cache file
+ * (`{base}/write-auth-session.json`). Neither is read any more; `run402 login`
+ * and `run402 logout` call this so a stale token does not linger on disk.
+ * Best-effort and idempotent.
+ */
+export function clearRetiredSessionCaches() {
+    for (const name of ["operator-session.json", "write-auth-session.json"]) {
+        try {
+            rmSync(join(getConfigBaseDir(), name), { force: true });
+        }
+        catch {
+            // Best-effort: a failed unlink never blocks login or logout.
+        }
+    }
+}
 //# sourceMappingURL=control-plane-session.js.map

package/core-dist/keystore.js

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { getLegacyProjectsPath, getProjectCredentialsPath } from "./config.js";
 import { clearActiveProjectId as clearProfileActiveProjectId, getActiveProjectId as getProfileActiveProjectId, recordMigration, setActiveProjectId as setProfileActiveProjectId, } from "./profile-state.js";
-import { readAllowance } from "./allowance.js";
+import { readWallet } from "./wallet.js";
 function withFileLock(path, fn, { retries = 200, delayMs = 20 } = {}) {
     const lockDir = path + ".lock";
     mkdirSync(dirname(path), { recursive: true });
@@ -99,7 +99,7 @@ function migrateLegacyProjectsJson(targetPath) {
         // Scoped the same way every other write in this module now is (see
         // `currentPrincipal`'s doc comment) — an unscoped write here is exactly
         // what poisons the "unknown"-principal bucket for good on a machine that
-        // migrates before its wallet allowance exists yet.
+        // migrates before its wallet exists yet.
         setProfileActiveProjectId(legacy.active_project_id, undefined, { principal: currentPrincipal() });
     }
     recordMigration("projects_json_import", {
@@ -174,7 +174,7 @@ export function removeProject(projectId, path) {
 }
 /**
  * The active-project scope's `principal`, derived from the CURRENT wallet's
- * allowance — matching exactly what `NodeCredentialsProvider.setActiveProject`
+ * wallet — matching exactly what `NodeCredentialsProvider.setActiveProject`
  * (sdk/src/node/credentials.ts) writes after `projects.provision` /
  * `projects.use`. Without this, every reader here used the profile-state
  * module's own default (empty) scope, which resolves to a FIXED
@@ -185,7 +185,7 @@ export function removeProject(projectId, path) {
  * `profile-state.ts#getActiveProjectId` happens to agree), but once the
  * "unknown" bucket is EVER populated by any principal-less write — the
  * one-time legacy `projects.json` migration below, or any provision/`use`
- * call made before this machine had a wallet allowance — it never gets
+ * call made before this machine had a wallet — it never gets
  * updated again (real wallet operations write to the principal-keyed
  * bucket, not "unknown") and PERMANENTLY shadows every later wallet-scoped
  * activation for every caller that reads through this module: `resolveProjectId`
@@ -197,13 +197,13 @@ export function removeProject(projectId, path) {
  * stale "unknown"-bucket entry first and never falls through to the
  * freshly-updated flat value.
  *
- * Best-effort: an unreadable/malformed allowance degrades to `null` (the
+ * Best-effort: an unreadable/malformed wallet degrades to `null` (the
  * "unknown" bucket callers tolerate), never a
- * throw — this is a read-scoping concern, not an allowance-validity one.
+ * throw — this is a read-scoping concern, not a wallet-validity one.
  */
 function currentPrincipal() {
     try {
-        return readAllowance()?.address ?? null;
+        return readWallet()?.address ?? null;
     }
     catch {
         return null;

package/core-dist/profiles.d.ts

@@ -3,7 +3,7 @@
  *
  * 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`,
+ * wallet lives under `{base}/profiles/<name>/` with its own `wallet.json`,
  * `projects.json`, and this module's non-secret `meta.json`.
  *
  * Two levels of active state, mirroring the wallet → project model:
@@ -40,10 +40,10 @@ export declare function profileDir(name: string): string;
 export declare function ensureProfileDir(name: string): string;
 export declare function readMeta(name: string): ProfileMeta | null;
 export declare function writeMeta(name: string, meta: ProfileMeta): void;
-/** True when a wallet's `allowance.json` exists on disk. */
+/** True when a wallet's `wallet.json` exists on disk. */
 export declare function profileExists(name: string): boolean;
 /**
- * All wallet names on disk: `default` (only if a root allowance.json exists)
+ * All wallet names on disk: `default` (only if a root wallet.json exists)
  * plus every valid directory under `profiles/`.
  */
 export declare function listProfileNames(): string[];

package/core-dist/profiles.js

@@ -3,7 +3,7 @@
  *
  * 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`,
+ * wallet lives under `{base}/profiles/<name>/` with its own `wallet.json`,
  * `projects.json`, and this module's non-secret `meta.json`.
  *
  * Two levels of active state, mirroring the wallet → project model:
@@ -17,7 +17,7 @@
 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";
+import { getConfigBaseDir, getProfilesDir, DEFAULT_PROFILE, isValidProfileName, moveWalletFiles, WALLET_FILE_NAME, } from "./config.js";
 import { describeRejectedValue } from "./redact.js";
 function atomicWrite(p, content, mode) {
     const dir = dirname(p);
@@ -114,17 +114,19 @@ export function writeMeta(name, meta) {
     atomicWrite(metaPath(name), JSON.stringify(meta, null, 2), 0o600);
 }
 // --- enumeration + lifecycle ---
-/** True when a wallet's `allowance.json` exists on disk. */
+/** True when a wallet's `wallet.json` exists on disk. */
 export function profileExists(name) {
-    return existsSync(join(profileDir(name), "allowance.json"));
+    moveWalletFiles();
+    return existsSync(join(profileDir(name), WALLET_FILE_NAME));
 }
 /**
- * All wallet names on disk: `default` (only if a root allowance.json exists)
+ * All wallet names on disk: `default` (only if a root wallet.json exists)
  * plus every valid directory under `profiles/`.
  */
 export function listProfileNames() {
+    moveWalletFiles();
     const names = [];
-    if (existsSync(join(getConfigBaseDir(), "allowance.json"))) {
+    if (existsSync(join(getConfigBaseDir(), WALLET_FILE_NAME))) {
         names.push(DEFAULT_PROFILE);
     }
     try {
@@ -184,7 +186,7 @@ export function renameProfile(oldName, newName) {
             /* best-effort */
         }
         const base = getConfigBaseDir();
-        for (const f of ["allowance.json", "projects.json", "meta.json"]) {
+        for (const f of [WALLET_FILE_NAME, "projects.json", "meta.json"]) {
             const src = join(base, f);
             if (existsSync(src))
                 renameSync(src, join(dest, f));

package/core-dist/{allowance-auth.d.ts → wallet-auth.d.ts}

@@ -1,8 +1,8 @@
 /**
- * Allowance auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
+ * SIWX auth helper — generates SIWX (Sign-In With X / EIP-4361) headers for Run402 API.
  * Uses @noble/curves (lighter than viem) for signing.
  */
-import type { AllowanceData } from "./allowance.js";
+import type { WalletData } from "./wallet.js";
 export interface SIWxAuthHeaders {
     "SIGN-IN-WITH-X": string;
 }
@@ -22,7 +22,7 @@ interface SIWEMessageOpts {
     resources?: string[];
 }
 export interface SIWxAuthOptions extends SIWEMessageOpts {
-    allowance: Pick<AllowanceData, "address" | "privateKey">;
+    wallet: Pick<WalletData, "address" | "privateKey">;
     type?: "eip191";
 }
 /**
@@ -33,10 +33,10 @@ export declare function formatSIWEMessage(opts: SIWEMessageOpts, address: string
 export declare function buildSIWxAuthHeaders(opts: SIWxAuthOptions): SIWxAuthHeaders;
 /**
  * Get SIWX auth headers for the Run402 API.
- * Returns null if no allowance is configured.
+ * Returns null if no local wallet is configured.
  *
  * @param path - API path (e.g. "/projects/v1") used to build the SIWE uri field.
  */
-export declare function getAllowanceAuthHeaders(path: string, allowancePath?: string): SIWxAuthHeaders | null;
+export declare function getWalletAuthHeaders(path: string, walletPath?: string): SIWxAuthHeaders | null;
 export {};
-//# sourceMappingURL=allowance-auth.d.ts.map
+//# sourceMappingURL=wallet-auth.d.ts.map