@run402/sdk 4.93.2 → 4.95.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 orgs 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` |
@@ -535,7 +537,7 @@ if (result.hasErrors) console.log(result.errors);
 
 `migrationSql` is reference context only; it is not executed as a PostgreSQL dry run. This method validates authorization manifests, not deploy manifests.
 
-### Unified apply — `r.project(spec.project).apply`
+### Unified apply — `r.project(spec.project_id).apply`
 
 The canonical primitive for any deploy (database + migrations + manifest + value-free secret declarations + functions + site + subdomain). Three layers:
 
@@ -544,7 +546,7 @@ import { run402, summarizeDeployResult, type ReleaseSpec } from "@run402/sdk/nod
 
 const r = run402();
 const spec: ReleaseSpec = {
-  project: "prj_...",
+  project_id: "prj_...",
   site: {
     patch: {
       put: {
@@ -560,12 +562,12 @@ const spec: ReleaseSpec = {
 };
 
 // One-shot — most agents use this.
-const result = await (await r.project(spec.project)).apply(spec);
+const result = await (await r.project(spec.project_id)).apply(spec);
 const summary = summarizeDeployResult(result);
 console.log(summary.headline);
 
 // Long-running with progress events. Events are a discriminated union on `type`.
-const op = await (await r.project(spec.project)).apply.start(spec);
+const op = await (await r.project(spec.project_id)).apply.start(spec);
 for await (const ev of op.events()) console.log(ev.type);
 const final = await op.result();
 
@@ -581,11 +583,11 @@ const resumed = await (await r.project(projectId)).apply.resume("op_...");
 - **Warnings are structured.** `DeployResult.warnings` contains `WarningEntry[]` (`code`, `severity`, `requires_confirmation`, `message`, optional `affected`/`details`/`confidence`); the type preserves legacy low/medium/high plan warnings and modern deploy-observability info/warn/high warnings. `apply()` emits `plan.warnings` and stops before upload/commit on confirmation-required warnings unless broad `allowWarnings` is set or every blocking code is listed in `allowWarningCodes`. For `MISSING_REQUIRED_SECRET`, set the affected keys with `r.secrets.set`, then retry.
 - **Deploy summaries are SDK-owned convenience.** `summarizeDeployResult(result)` returns `DeploySummary` (`schema_version: "deploy-summary.v1"`) with a headline plus reliable current buckets for site path counts, CAS new/reused bytes, functions, migrations, routes, secrets, subdomains, and warning counts. It is derived from `DeployResult.diff` / `DeployResult.warnings`; it makes no extra gateway calls, omits sections the gateway did not return, and intentionally excludes timings, client-side duration estimates, and function old/new code hashes.
 - **Safe release-race retries are SDK-owned.** `apply()` automatically re-plans and retries omitted/current-base specs when the gateway returns `BASE_RELEASE_CONFLICT` with `safe_to_retry: true`. Static activation/config failures reported from `activation_pending` throw immediately with gateway metadata preserved. The default retry budget is two retries after the initial attempt; pass `{ maxRetries: 0 }` to opt out.
-- **Planning has two explicit non-deploying modes.** `(await r.project(spec.project)).apply.plan(spec, { mode: "reviewedPlan" })` calls the gateway reviewed-plan route and returns `plan_id`, `plan_fingerprint`, `plan_expires_at`, diff, warnings, and `next_actions[]` without uploading bytes or committing. Exact apply passes `{ requiredPlan: { planId, planFingerprint? } }` to `apply()` / `start()` / `commit()`; the SDK verifies before upload and commit. Legacy `{ dryRun: true }` still calls the no-row debug route and returns `plan_id: null`, but it is not require-able.
+- **Planning has two explicit non-deploying modes.** `(await r.project(spec.project_id)).apply.plan(spec, { mode: "reviewedPlan" })` calls the gateway reviewed-plan route and returns `plan_id`, `plan_fingerprint`, `plan_expires_at`, diff, warnings, and `next_actions[]` without uploading bytes or committing. Exact apply passes `{ requiredPlan: { planId, planFingerprint? } }` to `apply()` / `start()` / `commit()`; the SDK verifies before upload and commit. Legacy `{ dryRun: true }` still calls the no-row debug route and returns `plan_id: null`, but it is not require-able.
 - **Rehearsals run candidate plans on contained branches.** Use the lower-level sequence when you want an explicit gate before commit:
 
   ```ts
-  const p = await r.project(spec.project);
+  const p = await r.project(spec.project_id);
   const { plan, byteReaders } = await p.apply.plan(spec);
   await p.apply.upload(plan, { byteReaders });
   if (!plan.plan_id) throw new Error("Preview plans cannot be rehearsed");
@@ -627,7 +629,7 @@ const resumed = await (await r.project(projectId)).apply.resume("op_...");
     { pattern: "/login", methods: ["POST"], target: { type: "function", name: "auth" } },
   ];
   const spec: ReleaseSpec = {
-    project: projectId,
+    project_id: projectId,
     functions: {
       replace: {
         api: { source: "export default async function handler(req) { const url = new URL(req.url); return Response.json({ ok: true, path: url.pathname }); }" },
@@ -643,7 +645,7 @@ const resumed = await (await r.project(projectId)).apply.resume("op_...");
     routes: { replace: routes },
   };
 
-  await (await r.project(spec.project)).apply(spec);
+  await (await r.project(spec.project_id)).apply(spec);
   ```
 
   Matching is exact or final `/*` prefix only. `/admin/*` does not match `/admin`; deploy both `/admin` and `/admin/*` when the section root is dynamic. Release static asset paths and public browser paths are distinct. In the example, `events.html` is a release asset and `/events` is the public static URL declared by `site.public_paths`; `/events.html` is not public in explicit mode unless separately declared. A route-only static alias looks like `{ pattern: "/events", methods: ["GET", "HEAD"], target: { type: "static", file: "events.html" } }`; prefer `site.public_paths` for ordinary clean URLs and reserve static route targets for exact method-aware route-table behavior. Avoid routing every static file, wildcard static targets, leading-slash files, directory shorthand, broad method lists by default, and one-static-route-target-per-page route-table exhaustion. Query strings are ignored for matching and preserved in the handler's full public `req.url`. Exact beats prefix, longest prefix wins, and method-compatible dynamic routes beat static files. A method-specific `POST /login` route lets static `GET /login` serve HTML. Unsafe method mismatch returns `405`; matched dynamic route failures do not fall back to static assets.
@@ -705,11 +707,11 @@ const resumed = await (await r.project(projectId)).apply.resume("op_...");
 
   const r = run402();
   const { spec, idempotencyKey } = await loadDeployManifest("./run402.deploy.json");
-  await (await r.project(spec.project)).apply(spec, { idempotencyKey });
+  await (await r.project(spec.project_id)).apply(spec, { idempotencyKey });
   ```
 
-  `loadDeployManifest(path)` parses JSON relative to the manifest file, maps
-  agent-friendly `project_id` into `ReleaseSpec.project`, decodes base64 file
+  `loadDeployManifest(path)` parses JSON relative to the manifest file, carries
+  `project_id` into `ReleaseSpec.project_id`, decodes base64 file
   entries, turns `{ path }` entries into lazy `FsFileSource` values, and reads
   migration `sql_path` / `sql_file`. It also loads explicit executable
   `.ts/.mts/.cts/.js/.mjs/.cjs` configs and rejects executable auto-discovery
@@ -727,7 +729,7 @@ const resumed = await (await r.project(projectId)).apply.resume("op_...");
   import { defineConfig, dir, nodeFunction, sqlFile } from "@run402/sdk/config";
 
   export default defineConfig(({ env }) => ({
-    project: env.required("RUN402_PROJECT_ID"),
+    project_id: env.required("RUN402_PROJECT_ID"),
     database: { migrations: [sqlFile("db/001_init.sql")] },
     site: { replace: dir("dist"), public_paths: { mode: "implicit" } },
     functions: { replace: { api: nodeFunction("dist/functions/api.js") } },
@@ -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
@@ -857,7 +859,7 @@ console.log(heard.settled, heard.messages, heard.live_presences);
 
 ### GitHub Actions OIDC — CI credentials drive deploy
 
-The v1 CI path keeps the deploy primitive simple: link a GitHub repository once, then call the existing `r.project(spec.project).apply` with CI-marked credentials. There is no separate `r.ci.deployApply` method and no public `ci: true` deploy option.
+The v1 CI path keeps the deploy primitive simple: link a GitHub repository once, then call the existing `r.project(spec.project_id).apply` with CI-marked credentials. There is no separate `r.ci.deployApply` method and no public `ci: true` deploy option.
 
 The CLI is the easiest setup path (`run402 ci link github`), but the SDK exposes the building blocks:
 
@@ -903,15 +905,15 @@ const r = run402({
 });
 
 const ciSpec: ReleaseSpec = {
-  project: projectId,
+  project_id: projectId,
   base: { release: "current" },
   site: { patch: { put: { "index.html": "<h1>ship</h1>" } } },
 };
 
-await (await r.project(ciSpec.project)).apply(ciSpec);
+await (await r.project(ciSpec.project_id)).apply(ciSpec);
 ```
 
-CI deploys intentionally allow only `project`, `database`, `functions`, `site`, absent/current `base`, and `routes` authorized by the binding's `route_scopes`. Omitted or empty `route_scopes` preserves the original no-routes CI posture. The SDK normalizes scopes, sends `route_scopes` only when non-empty, and still rejects `secrets`, `subdomains`, `checks`, unknown future top-level fields, non-current `base`, and specs large enough to require `manifest_ref` before upload/plan. Gateway planning enforces route diffs and can return `CI_ROUTE_SCOPE_DENIED`; re-link with covering exact scopes like `/admin` or final-wildcard scopes like `/api/*`, or deploy locally. Use the canonical builders (`buildCiDelegationStatement`, `buildCiDelegationResourceUri`) instead of hand-rolling SIWX text; gateway tests pin those strings as golden vectors.
+CI deploys intentionally allow only `project_id`, `database`, `functions`, `site`, absent/current `base`, and `routes` authorized by the binding's `route_scopes`. Omitted or empty `route_scopes` preserves the original no-routes CI posture. The SDK normalizes scopes, sends `route_scopes` only when non-empty, and still rejects `secrets`, `subdomains`, `checks`, unknown future top-level fields, non-current `base`, and specs large enough to require `manifest_ref` before upload/plan. Gateway planning enforces route diffs and can return `CI_ROUTE_SCOPE_DENIED`; re-link with covering exact scopes like `/admin` or final-wildcard scopes like `/api/*`, or deploy locally. Use the canonical builders (`buildCiDelegationStatement`, `buildCiDelegationResourceUri`) instead of hand-rolling SIWX text; gateway tests pin those strings as golden vectors.
 
 ### Timestamp Convention
 
@@ -962,7 +964,7 @@ declare const spec: ReleaseSpec;
 const r = run402();
 
 try {
-  await (await r.project(spec.project)).apply(spec);
+  await (await r.project(spec.project_id)).apply(spec);
 } catch (e) {
   if (isPaymentRequired(e)) {
     // e is narrowed to PaymentRequired
@@ -990,7 +992,7 @@ should not duplicate or corrupt state, not that lifecycle/payment/auth gates
 will become allowed without an action. Pair retries with the SDK method's own
 `idempotencyKey` so retried mutations dedup server-side:
 
-For `r.project(spec.project).apply()`, safe `BASE_RELEASE_CONFLICT` release races are already
+For `r.project(spec.project_id).apply()`, safe `BASE_RELEASE_CONFLICT` release races are already
 handled by the apply hero with a fresh plan and visible `deploy.retry`
 events. Use `withRetry` for caller-owned retry policies around other operations,
 or pass `maxRetries: 0` to `apply` when you want to handle deploy races
@@ -1010,7 +1012,7 @@ const r = run402();
 
 try {
   const release = await withRetry(
-    async () => (await r.project(spec.project)).apply(spec, { idempotencyKey: "deploy-2026-05-01" }),
+    async () => (await r.project(spec.project_id)).apply(spec, { idempotencyKey: "deploy-2026-05-01" }),
     {
       attempts: 3,
       onRetry: (e, attempt, delayMs) =>

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;