run402 4.93.1 → 4.94.0

package/README.md

@@ -4,7 +4,7 @@
 
 Command-line interface for [Run402](https://run402.com) — provision Postgres databases, deploy static sites, run Node 22 serverless functions, host content-addressed CDN assets, send email, sign on-chain. Paid autonomously with x402 (USDC on Base) or MPP (pathUSD on Tempo, or sats over Bitcoin Lightning). **Prototype tier is free on testnet.**
 
-The CLI lets an agent act as its own first-class Run402 principal rather than borrowing a human account. Identity records who invoked an action; organization roles, grants, delegates, freshness, and spend policy determine what that principal may do. People remain first-class owners and collaborators without becoming routine CLI operators.
+The CLI lets an agent act as its own first-class Run402 principal rather than borrowing a human account. Identity records who invoked an action; organization roles, grants, delegates, freshness, and spend policy determine what that principal may do. People remain first-class owners and members without having to run the CLI themselves.
 
 For the full CLI reference (every flag, every subcommand) start at **<https://docs.run402.com/llms-cli.txt>** — the index holds the first-deploy contract and links one fetchable `/llms-cli-<slice>.txt` per topic (deploy, commands, repos, orgs, functions, assets, ops, errors, frontend, platform); <https://docs.run402.com/llms-cli-full.txt> is the whole reference as one document.
 
@@ -25,8 +25,8 @@ npx -y run402@latest <command>
 ## 30-second start
 
 ```bash
-run402 up --name my-app -y                 # bootstrap allowance/tier/project/link, then deploy
-run402 subdomains claim my-app             # → https://my-app.run402.com
+run402 up --name my-app -y                 # bootstrap wallet/tier/project/link, then deploy
+run402 subdomains add my-app             # → https://my-app.run402.com
 ```
 
 That's a real Postgres database + a deployed static site, paid for autonomously with testnet USDC.
@@ -51,13 +51,13 @@ run402 up verify --project prj_...
 run402 up --nested -y                         # app root inside another repo: its own nested repo + run402 remote
 ```
 
-`up` is a thin CLI shim over the Node SDK action runner. It discovers `run402.json`, `run402.deploy.json`, then `app.json`. A `run402.json` carrying the app schema/app markers uses the app-install graph; a release-shaped `run402.json` is normalized through the same ReleaseSpec path as `deploy apply` for compatibility. It validates the deploy input before any mutation, resolves the project as `--project` → `.run402/project.json` → manifest `project_id` → approved creation from `--name` → approved active-project fallback, then applies the manifest. `--name` is creation/link metadata only; it is not a manifest field and never renames an existing project. When everything is already configured, plain `run402 up` deploys. Non-interactive recursive prerequisites/local writes require `-y/--yes`.
+`up` is a thin CLI shim over the Node SDK action runner. It discovers `run402.json`, `run402.deploy.json`, then `app.json`. A `run402.json` carrying the app schema/app markers uses the app-install graph; a release-shaped `run402.json` is normalized through the same ReleaseSpec path as `run402 deploy` for compatibility. It validates the deploy input before any mutation, resolves the project as `--project` → `.run402/project.json` → manifest `project_id` → approved creation from `--name` → approved active-project fallback, then applies the manifest. `--name` is creation/link metadata only; it is not a manifest field and never renames an existing project. When everything is already configured, plain `run402 up` deploys. Non-interactive recursive prerequisites/local writes require `-y/--yes`.
 
 For app manifests with `verify.http[]`, `up` runs HTTP checks after deploy. Fresh Run402 edge sentinel misses (`x-run402-edge` or sentinel JSON bodies) become `propagation_pending` with diagnostics instead of hard failure while the host binding is still converging. Use `--propagation-budget-s <seconds>` to tune the default 120 second wait, `--no-propagation-wait` to return immediately, and `run402 up verify` to rerun the same checks without upload, deploy, project creation, or resource mutation.
 
-For typed `run402.deploy.ts` configs, pass `--manifest` explicitly because TypeScript/JavaScript configs execute local code. Use `--check` for local-only import/normalize/file validation, `--print-spec` to inspect the normalized `ReleaseSpec`, `--plan` for a gateway-reviewed non-deploying plan, and `--require-plan <plan_id>` to apply only that reviewed intent. Warning flags are not used with `--require-plan`; the reviewed plan binds the exact warning/destructive set. Run402 Core skips Cloud allowance/tier prerequisites and fails closed when no Core project is selected.
+For typed `run402.deploy.ts` configs, pass `--manifest` explicitly because TypeScript/JavaScript configs execute local code. Use `--check` for local-only import/normalize/file validation, `--print-spec` to inspect the normalized `ReleaseSpec`, `--plan` for a gateway-reviewed non-deploying plan, and `--require-plan <plan_id>` to apply only that reviewed intent. Warning flags are not used with `--require-plan`; the reviewed plan binds the exact warning/destructive set. Run402 Core skips Cloud wallet/tier prerequisites and fails closed when no Core project is selected.
 
-Every mode (and `deploy apply`) verifies the files the manifest references before any gateway call: migration `sql_path`/`sql_file`, function `source`/`files`, site `{ path }` entries and `dir()` targets, `assets.put` sources. A missing one is `MANIFEST_FILE_MISSING` (`details.missing[]` = `{ field_path, path, kind }`, one `create_file` next action per file). With no manifest in the working directory, `UP_MANIFEST_REQUIRED` looks one directory down (`details.nearby_manifests[]`, a leading `run_in_directory` next action such as `run402 up --check --dir <dir>`); `--manifest <path>` to a missing file is a typed `MANIFEST_NOT_FOUND` with a `create_manifest` next action. An app root that lies inside another repository is never scaffolded into it: the skip carries a `create_nested_repo` next action, and `--nested` gives the app its own nested repository (`git init -b main`, the `run402` remote, the first push) plus exactly one line in the enclosing repository's local `.git/info/exclude`, nothing else touched. `up` also sets this principal's display name when it has none: `RUN402_AGENT_NAME` (overrides an existing name), else the detected client (`claude-code`, `codex`, `cursor`, `grok`, or `RUN402_CLIENT=<name>` for one with no marker), and `result.identity` reports `detected` plus `detection: { applied, reason }` either way.
+Every mode (and `run402 deploy`) verifies the files the manifest references before any gateway call: migration `sql_path`/`sql_file`, function `source`/`files`, site `{ path }` entries and `dir()` targets, `assets.put` sources. A missing one is `MANIFEST_FILE_MISSING` (`details.missing[]` = `{ field_path, path, kind }`, one `create_file` next action per file). With no manifest in the working directory, `UP_MANIFEST_REQUIRED` looks one directory down (`details.nearby_manifests[]`, a leading `run_in_directory` next action such as `run402 up --check --dir <dir>`); `--manifest <path>` to a missing file is a typed `MANIFEST_NOT_FOUND` with a `create_manifest` next action. An app root that lies inside another repository is never scaffolded into it: the skip carries a `create_nested_repo` next action, and `--nested` gives the app its own nested repository (`git init -b main`, the `run402` remote, the first push) plus exactly one line in the enclosing repository's local `.git/info/exclude`, nothing else touched. `up` also sets this principal's display name when it has none: `RUN402_AGENT_NAME` (overrides an existing name), else the detected client (`claude-code`, `codex`, `cursor`, `grok`, or `RUN402_CLIENT=<name>` for one with no marker), and `result.identity` reports `detected` plus `detection: { applied, reason }` either way.
 
 ### repos — host-blind encrypted git repos (zero deploy ceremony)
 
@@ -78,19 +78,19 @@ run402 repos delete --project prj_xyz --force # refuses without --force while th
 
 A hosted git remote, encrypted before it leaves the machine — no deploy, no manifest, no app. `origin` is claimed additively — an existing `origin` is never touched, the run402 remote falls back to `run402` instead. A directory inside another repository is never scaffolded into that repository: the skip carries a `create_nested_repo` next action, `--nested` makes it its own nested repository (one line appended to the enclosing repository's local `.git/info/exclude`, nothing else touched), and `create` prints a `git push` next action only for a remote it actually added. Every mutating `repos` verb (`create`, `rename`, `delete`, `snapshot`, `policy`, `mirror`, `gc`, `handoff`, `resume`, `invite`, `join`) is CLI/OpenClaw-only by design — no MCP tool exists or will exist for them (one-shot recovery receipts, immutable generations, irreversible delete, single-use bearer keys). Three READ-ONLY tools do exist — `repos_view`, `repos_list_heads`, `repos_fsck` — teaching only `repos` spellings. See `run402 repos --help` for the full tiered surface (common: `create`/`view`/`list`; occasional: `snapshot`/`mirror`/`recover`/`handoff`/`resume`/`invite`/`join`; lifecycle: `rename`/`delete`; maintenance: `fsck`/`gc`/`access`/`policy`), and the CLI reference's `repos` section for the terminal-loss statement and the progressive backup warning.
 
-**Handoff / resume.** `run402 repos handoff [--note-file <path>]` captures the actual working tree (staged/unstaged/untracked, like `git stash push -u`) into the vault and mints a single-use bearer key (`kgh1_…`, printed to stdout exactly once); `run402 repos resume <kgh1_…>` claims it on another machine, clones fresh, and reapplies the exact dirty state with `git stash apply --index`. No shared keystore, no shared allowance — the key is the whole handoff. On a wallet with no active tier, `resume` first folds the same cold-start chain `create` does (allowance → faucet → one x402 prototype payment); `--no-init` opts out, and the claim itself never waits on it. Sensitive untracked files (`.env`, `*.pem`, SSH/AWS/GPG dirs, …) are excluded from capture by default (`--include-sensitive <glob>` re-admits one). See the reference `run402.com/llms-cli.txt` for the full note-schema and flag reference.
+**Handoff / resume.** `run402 repos handoff [--note-file <path>]` captures the actual working tree (staged/unstaged/untracked, like `git stash push -u`) into the vault and mints a single-use bearer key (`kgh1_…`, printed to stdout exactly once); `run402 repos resume <kgh1_…>` claims it on another machine, clones fresh, and reapplies the exact dirty state with `git stash apply --index`. No shared keystore, no shared wallet — the key is the whole handoff. On a wallet with no active tier, `resume` first folds the same cold-start chain `create` does (wallet → faucet → one x402 prototype payment); `--no-init` opts out, and the claim itself never waits on it. Sensitive untracked files (`.env`, `*.pem`, SSH/AWS/GPG dirs, …) are excluded from capture by default (`--include-sensitive <glob>` re-admits one). See the reference `run402.com/llms-cli.txt` for the full note-schema and flag reference.
 
 **Invite / join.** The second claim kind beside handoff/resume: a Handoff passes the work on and the sender stops; an Invite grows the team while the sender keeps working. `run402 repos invite [--room <key>] [--note-file <path>]` captures the checkpoint exactly like `handoff` — the inviter's own worktree, index, branch, refs, and access are all untouched — registers the inviter's presence in a coordination room (the project's default room, or `--room <key>` for a named org room), mints a single-use bearer key (`kgi1_…`, printed to stdout exactly once), and posts ONE room message naming the checkpoint (never the key). `run402 repos join <kgi1_…>` folds the SAME cold-start chain `resume` does before the claim, clones fresh, restores the exact dirty state, pins the invite's room locally, registers its own presence, posts ONE arrival message, and reports the inviter (name, labels, liveness), the room's other live presences, and the last few messages. `run402 messages wait` is the room's blocking read from there — the agent's ear, never an error on silence. Neither `invite` nor `join` has an MCP tool, same reasoning as `handoff`/`resume`.
 
-**Named addressing.** `run402 org slug <slug>` (owner-only, small one-time fee) claims an org's globally-unique, address-form slug, after which `run402::<slug>/<name>` addresses any repo under it — `git push` to a name that doesn't exist yet push-to-creates it. `run402 repos rename <name> [--project <id>]` claims the per-org-unique `<name>` half explicitly (no fee); `repos create` claims one automatically, best-effort, when the org already has a slug. Also CLI/SDK-only — no MCP tool.
+**Named addressing.** `run402 org slug <slug>` (owner-only, small one-time fee) sets an org's globally-unique, address-form slug, after which `run402::<slug>/<name>` addresses any repo under it — `git push` to a name that doesn't exist yet push-to-creates it. `run402 repos rename <name> [--project <id>]` claims the per-org-unique `<name>` half explicitly (no fee); `repos create` claims one automatically, best-effort, when the org already has a slug. Also CLI/SDK-only — no MCP tool.
 
-### Allowance
+### Wallet
 
 ```bash
-run402 allowance create    # generate the local allowance
-run402 allowance fund      # request testnet USDC from the faucet
-run402 allowance balance   # mainnet + testnet + billing balance
-run402 allowance export    # print {"address":"0x..."} for funding
+run402 wallets new default # generate the local wallet without funding it
+run402 wallets fund        # request testnet USDC from the faucet
+run402 wallets balance     # mainnet + testnet USDC, plus the organization's allowance
+run402 wallets current     # the active wallet's address (for funding), rail, and file path
 ```
 
 ### Promo codes
@@ -100,9 +100,9 @@ run402 redeem R402-K8F3-Q2W9          # any time, before or after `run402 init`
 run402 init --voucher R402-K8F3-Q2W9  # same redemption, folded into setup
 ```
 
-A promo code credits the organization with prepaid credit that settles tiers and
+A promo code adds to the organization's allowance, which settles tiers and
 priced calls with no on-chain payment. Case-insensitive, hyphens optional.
-Retrying is safe — a repeat returns the original result and never credits twice.
+Retrying is safe — a repeat returns the original result and never adds twice.
 A bad code never blocks `init`; it warns and records `voucher_error` in the JSON
 summary.
 
@@ -155,14 +155,14 @@ run402 projects schema <id>                              # introspect tables + R
 
 ```bash
 run402 sites deploy-dir ./dist                # incremental upload (plan/commit transport)
-run402 deploy apply --manifest app.json       # one-call full stack deploy
-run402 apply --manifest app.json --rehearse --json
+run402 deploy --manifest app.json             # deploy only (`run402 up` does missing setup first, then this)
+run402 deploy status op_... --project prj_...
 run402 deploy verify op_... --project prj_... --wait
-run402 deploy release active                  # inspect current-live release inventory
-run402 deploy release diff --from empty --to active
-run402 deploy diagnose --project prj_123 https://example.com/events --method GET
-run402 deploy resolve --project prj_123 --url https://example.com/events?utm=x#hero --method GET
-run402 subdomains claim my-app                # → my-app.run402.com (auto-reassigns on next deploy)
+run402 deploy releases active                 # inspect current-live release inventory
+run402 deploy releases diff --from empty --to active
+run402 deploy resolve https://example.com/events --project prj_123 --method GET
+run402 deploy resolve --url https://example.com/events?utm=x#hero --project prj_123 --method GET
+run402 subdomains add my-app                # → my-app.run402.com (auto-reassigns on next deploy)
 ```
 
 For pointer-swap recovery, verify the returned operation before declaring the public rollback complete:
@@ -175,13 +175,13 @@ run402 deploy verify --operation OPERATION_ID --wait
 Promote success means the origin pointer is active; mutable public URLs may still be converging. The result's `edge.state` reports convergence, and `edge.verify_url` is the direct operation-scoped HTTP verification endpoint.
 
 `deploy-dir` hashes each file client-side and only uploads bytes the gateway doesn't already have. Re-deploying an unchanged tree returns immediately with `bytes_uploaded: 0`. Progress events stream to stderr.
-Release inspection commands print `{ release: ... }` or `{ diff: ... }` (raw payload, no envelope — see the "Output Contract" section in [llms-cli.txt](llms-cli.txt)); use them after deploys to compare release inventory without starting another mutation. `deploy verify` prints the canonical edge-coherence report and exits 2 when the report is valid but not yet coherent. Inventories include `release_generation`, `static_manifest_sha256`, and nullable `static_manifest_metadata`; diffs include `static_assets` counters such as unchanged/changed/added/removed and CAS byte reuse. `deploy diagnose` / `deploy resolve --url` print URL-first diagnostics with `would_serve`, `diagnostic_status`, `match`, warnings, `edge_propagation`, and next steps; host misses are successful diagnostic calls with `would_serve: false`. Stable-host resolve fields can include `authorization_result`, `cas_object`, `response_variant`, `allow`, `route_pattern`, `target_type`, `target_name`, `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`).
+Release inspection commands print `{ release: ... }` or `{ diff: ... }` (raw payload, no envelope — see the "Output Contract" section in [llms-cli.txt](llms-cli.txt)); use them after deploys to compare release inventory without starting another mutation. `deploy verify` prints the canonical edge-coherence report and exits 2 when the report is valid but not yet coherent. Inventories include `release_generation`, `static_manifest_sha256`, and nullable `static_manifest_metadata`; diffs include `static_assets` counters such as unchanged/changed/added/removed and CAS byte reuse. `deploy resolve <url>` (or `--url` / `--host` + `--path`) prints URL diagnostics with `would_serve`, `diagnostic_status`, `match`, warnings, `edge_propagation`, and next steps; host misses are successful diagnostic calls with `would_serve: false`. Stable-host resolve fields can include `authorization_result`, `cas_object`, `response_variant`, `allow`, `route_pattern`, `target_type`, `target_name`, `target_file`, and `edge_propagation` (`settled`, `propagating`, or `sync_pending`).
 
-For database-bearing changes, use `run402 apply --manifest app.json --rehearse --json` before commit. It creates a contained branch, applies the candidate plan there, runs checks, and exits nonzero on a failed rehearsal. The automatic rehearsal inside `up` / `apply` reports `rehearsal: { status: "skipped", reason }` when there is nothing to protect: `no_live_release` on a first deploy, `no_migrations`, or `migrations_unchanged` when every migration is already applied with an identical checksum (a page-only redeploy that still carries its migrations ships in seconds). `PUBLIC_ROUTED_FUNCTION` is informational (`requires_confirmation: false`) and needs no `--allow-warning`; only warnings with `requires_confirmation: true` do. Manual restore points live under `run402 snapshots create|list|get|restore|delete`; temporary data branches live under `run402 branches create|list|renew|delete`.
+For database-bearing changes, rehearsal happens before commit without a flag: `run402 deploy --manifest app.json --json` (or `run402 up`) creates a contained branch, applies the candidate plan there, runs checks, and stops on a failed rehearsal; `--no-rehearse` skips it and `run402 deploy rehearse <plan_id>` rehearses a persisted plan by hand. The automatic rehearsal inside `up` / `deploy` reports `rehearsal: { status: "skipped", reason }` when there is nothing to protect: `no_live_release` on a first deploy, `no_migrations`, or `migrations_unchanged` when every migration is already applied with an identical checksum (a page-only redeploy that still carries its migrations ships in seconds). `PUBLIC_ROUTED_FUNCTION` is informational (`requires_confirmation: false`) and needs no `--allow-warning`; only warnings with `requires_confirmation: true` do. Manual restore points live under `run402 snapshots create|list|get|restore|delete`; temporary data branches live under `run402 branches create|list|renew|delete`.
 
 ### GitHub Actions OIDC deploys
 
-Link once from a local shell that has your Run402 allowance, then commit the generated workflow and manifest:
+Link once from a local shell that has your Run402 wallet, then commit the generated workflow and manifest:
 
 ```bash
 run402 ci link github --project prj_... --manifest run402.deploy.json
@@ -203,10 +203,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Deploy to run402
-        run: npx --yes run402@3.7.5 deploy apply --manifest 'run402.deploy.json' --project 'prj_...'
+        run: npx --yes run402@3.7.5 deploy --manifest 'run402.deploy.json' --project 'prj_...'
 ```
 
-CI deploys can ship `site`, `functions`, `database`, and absent/current `base` changes. Route declarations are allowed only when the binding was linked with covering `--route-scope` patterns (`/admin` exact, `/api/*` final wildcard); no scopes means no CI route authority. Keep secrets, domains, subdomains, checks, non-current base changes, and out-of-scope routes in a local `run402 deploy apply` where the full allowance-backed authority is present.
+CI deploys can ship `site`, `functions`, `database`, and absent/current `base` changes. Route declarations are allowed only when the binding was linked with covering `--route-scope` patterns (`/admin` exact, `/api/*` final wildcard); no scopes means no CI route authority. Keep secrets, domains, subdomains, checks, non-current base changes, and out-of-scope routes in a local `run402 deploy` where the full wallet-backed authority is present.
 
 ### Storage (paste-and-go CDN assets)
 
@@ -253,7 +253,7 @@ import { db, adminDb, auth, email, ai } from "@run402/functions";
 
 ### Same-origin web routes
 
-`run402 deploy apply` accepts `site.public_paths` for clean static browser URLs and `routes.replace` for function ingress or exact method-aware static aliases. Release asset paths such as `events.html` are distinct from public paths such as `/events`: prefer `{ "site": { "replace": { "events.html": { "data": "<h1>Events</h1>" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html" } } } } }` for ordinary clean static URLs. In explicit mode `/events.html` is not public unless separately declared; `mode: "implicit"` restores filename-derived reachability and can widen access. `site.embedding.frame_ancestors` (catalog keys, e.g. `["localhost"]`, never raw origins) lets the named embedders put the site in an iframe: the gateway sends `Content-Security-Policy: frame-ancestors http://localhost:* http://127.0.0.1:*` and drops `X-Frame-Options` on every response of the host; omitted on a later apply carries the previous declaration forward, `null` returns to deny, unknown keys fail `INVALID_SPEC` naming the valid ones, and `/_run402/config.json` discloses the effective policy cross-origin so an embedder can check before framing. `routes.replace` is an array of route entries, not a path-keyed map. Use exact `/admin` plus final-wildcard `/admin/*` for a routed section root, narrow `/api/*` methods such as `["GET","POST","OPTIONS"]`, POST-only `/login` function routes, and exact static route targets like `{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } }` only for route-table alias behavior. Static route `file` is a release asset path, not a public path, URL, CAS hash, rewrite, or redirect. Recipe — static home page + SPA shell: a root alias `{ "pattern": "/", "target": { "type": "static", "file": "home.html" } }` (with `home.html` at the site root) serves real static bytes at `GET /` (`route_static_alias`) while unmatched app routes keep the `index.html` shell (`spa_fallback`); expect non-blocking `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn) / `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info) plan lints and verify with `run402 deploy resolve --url https://<your-site>/ --method GET`. Routed functions use Node 22 Fetch Request -> Response; `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Direct `/functions/v1/:name` remains API-key protected. Known resolve literals include `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. Release inventories may include `static_public_paths` with `public_path`, `asset_path`, `reachability_authority`, and `direct`; resolve may return the same reachability fields plus `authorization_result`, `cas_object`, `response_variant`, and route/static fields like `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Static route target warnings include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and the backing `asset_path`. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED`, `ROUTED_INVOKE_WORKER_SECRET_MISSING`, `ROUTED_INVOKE_AUTH_FAILED`, `ROUTED_ROUTE_STALE`, `ROUTE_METHOD_NOT_ALLOWED`, and `ROUTED_RESPONSE_TOO_LARGE`.
+`run402 deploy` accepts `site.public_paths` for clean static browser URLs and `routes.replace` for function ingress or exact method-aware static aliases. Release asset paths such as `events.html` are distinct from public paths such as `/events`: prefer `{ "site": { "replace": { "events.html": { "data": "<h1>Events</h1>" } }, "public_paths": { "mode": "explicit", "replace": { "/events": { "asset": "events.html" } } } } }` for ordinary clean static URLs. In explicit mode `/events.html` is not public unless separately declared; `mode: "implicit"` restores filename-derived reachability and can widen access. `site.embedding.frame_ancestors` (catalog keys, e.g. `["localhost"]`, never raw origins) lets the named embedders put the site in an iframe: the gateway sends `Content-Security-Policy: frame-ancestors http://localhost:* http://127.0.0.1:*` and drops `X-Frame-Options` on every response of the host; omitted on a later apply carries the previous declaration forward, `null` returns to deny, unknown keys fail `INVALID_SPEC` naming the valid ones, and `/_run402/config.json` discloses the effective policy cross-origin so an embedder can check before framing. `routes.replace` is an array of route entries, not a path-keyed map. Use exact `/admin` plus final-wildcard `/admin/*` for a routed section root, narrow `/api/*` methods such as `["GET","POST","OPTIONS"]`, POST-only `/login` function routes, and exact static route targets like `{ "pattern": "/events", "methods": ["GET","HEAD"], "target": { "type": "static", "file": "events.html" } }` only for route-table alias behavior. Static route `file` is a release asset path, not a public path, URL, CAS hash, rewrite, or redirect. Recipe — static home page + SPA shell: a root alias `{ "pattern": "/", "target": { "type": "static", "file": "home.html" } }` (with `home.html` at the site root) serves real static bytes at `GET /` (`route_static_alias`) while unmatched app routes keep the `index.html` shell (`spa_fallback`); expect non-blocking `STATIC_ALIAS_SHADOWS_STATIC_PATH` (warn) / `STATIC_ALIAS_DUPLICATE_CANONICAL_URL` (info) plan lints and verify with `run402 deploy resolve --url https://<your-site>/ --method GET`. Routed functions use Node 22 Fetch Request -> Response; `req.url` is the full public URL on managed subdomains, deployment hosts, and verified custom domains. Direct `/functions/v1/:name` remains API-key protected. Known resolve literals include `host_missing`, `manifest_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `none`, `static_exact`, `static_index`, `spa_fallback`, `spa_fallback_missing`, `route_function`, `route_static_alias`, and `route_method_miss`; known `authorization_result` values include `authorized`, `not_public`, `not_applicable`, `manifest_missing`, `target_missing`, `active_release_missing`, `unsupported_manifest_version`, `path_error`, `missing_cas_object`, `unfinalized_or_deleting_cas_object`, `size_mismatch`, and `unauthorized_cas_object`. Known `fallback_state` values include `active_release_missing`, `unsupported_manifest_version`, and `negative_cache_hit`; preserve unknown future strings. Release inventories may include `static_public_paths` with `public_path`, `asset_path`, `reachability_authority`, and `direct`; resolve may return the same reachability fields plus `authorization_result`, `cas_object`, `response_variant`, and route/static fields like `allow`, `route_pattern`, `target_type`, `target_name`, and `target_file`. Static route target warnings include `STATIC_ALIAS_SHADOWS_STATIC_PATH`, `STATIC_ALIAS_RELATIVE_ASSET_RISK`, `STATIC_ALIAS_DUPLICATE_CANONICAL_URL`, `STATIC_ALIAS_EXTENSIONLESS_NON_HTML`, and `STATIC_ALIAS_TABLE_NEAR_LIMIT`; inspect active routes, `static_public_paths`, and the backing `asset_path`. Runtime route failure codes to branch on: `ROUTE_MANIFEST_LOAD_FAILED`, `ROUTED_INVOKE_WORKER_SECRET_MISSING`, `ROUTED_INVOKE_AUTH_FAILED`, `ROUTED_ROUTE_STALE`, `ROUTE_METHOD_NOT_ALLOWED`, and `ROUTED_RESPONSE_TOO_LARGE`.
 
 ### Secrets
 
@@ -261,7 +261,7 @@ import { db, adminDb, auth, email, ai } from "@run402/functions";
 run402 secrets set <id> OPENAI_API_KEY --file ./.secrets/openai-key
 printf %s "$OPENAI_API_KEY" | run402 secrets set <id> OPENAI_API_KEY --stdin
 run402 secrets list <id>
-run402 deploy apply --manifest run402.deploy.json   # manifest uses secrets.require, not values
+run402 deploy --manifest run402.deploy.json   # manifest uses secrets.require, not values
 ```
 
 Secret values are write-only. `list` returns keys and timestamps only; deploy manifests should declare dependencies with `secrets.require` and never contain values.
@@ -289,7 +289,7 @@ run402 email send --to user@example.com --subject "Welcome" --html "<h1>Hi</h1>"
 run402 email send --to user@example.com --template notification --var project_name="My App"
 ```
 
-For Run402 Core, use the same commands after `run402 init --api-base=http://my-core:4020`. The Core gateway operator must configure an outbound provider such as SES first; `run402 email mailboxes` surfaces `provider_readiness`, `can_send`, `send_blocked_reason`, and `next_actions` when setup is missing. Core's first email slice supports raw outbound mail with attachments; managed templates, inbound reply handling, sender-domain automation, and delivery operations may remain Cloud-only until the Core gateway adds those capabilities.
+For Run402 Core, use the same commands after `run402 init --api-base=http://my-core:4020`. Whoever runs the Core gateway must configure an outbound provider such as SES first; `run402 email mailboxes` surfaces `provider_readiness`, `can_send`, `send_blocked_reason`, and `next_actions` when setup is missing. Core's first email slice supports raw outbound mail with attachments; managed templates, inbound reply handling, sender-domain automation, and delivery operations may remain Cloud-only until the Core gateway adds those capabilities.
 
 ### Image generation
 
@@ -323,18 +323,18 @@ run402 doctor                    # { ok, blocking[], warnings[], checks[] }
 run402 doctor --refresh          # live npm check for a newer run402
 ```
 
-`ok` is structural: `true` exactly when `blocking[]` is empty. Every check carries `severity: "blocking" | "advisory" | "info"`; advisory findings (an unbound operator passkey, a degraded recovery posture on another org, a stale CLI, gitvault gaps) land in `warnings[]` without changing `ok` or the exit code. The `tier` check's `status` is a fixed vocabulary (`ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error`, never a tier name; see `value.tier` / `value.lifecycle`), and a wallet whose own org holds no tier but can reach another org's projects reports `missing` as advisory (`TIER_MISSING_ON_OWN_ORG`).
+`ok` is structural: `true` exactly when `blocking[]` is empty. Every check carries `severity: "blocking" | "advisory" | "info"`; advisory findings (an unbound contact passkey, a degraded recovery posture on another org, a stale CLI, gitvault gaps) land in `warnings[]` without changing `ok` or the exit code. The `tier` check's `status` is a fixed vocabulary (`ok | inactive | frozen | past_due | dormant | purged | missing | unknown | error`, never a tier name; see `value.tier` / `value.lifecycle`), and a wallet whose own org holds no tier but can reach another org's projects reports `missing` as advisory (`TIER_MISSING_ON_OWN_ORG`).
 
 ## State
 
 Local state lives at:
 
 - `~/.config/run402/projects.json` (`0600`) — project credentials (`anon_key`, `service_key`, `tier`, `lease_expires_at`)
-- `~/.config/run402/allowance.json` (`0600`) — wallet for x402 signing
+- `~/.config/run402/wallet.json` (`0600`) — wallet for x402 signing
 - `~/.config/run402/config.json` (`0600`) — global default wallet pointer (`active_wallet`)
-- `~/.config/run402/profiles/<name>/` (`0700`) — named wallets, each with its own `allowance.json` + `projects.json` + non-secret `meta.json`
+- `~/.config/run402/profiles/<name>/` (`0700`) — named wallets, each with its own `wallet.json` + `projects.json` + non-secret `meta.json`
 
-Override the base directory with `RUN402_CONFIG_DIR` or the allowance file with `RUN402_ALLOWANCE_PATH`. Override the API base with `RUN402_API_BASE`.
+Override the base directory with `RUN402_CONFIG_DIR` or the wallet file with `RUN402_WALLET_PATH`. Override the API base with `RUN402_API_BASE`.
 
 ### Named wallets (profiles)
 
@@ -346,16 +346,18 @@ Hold several wallets on one machine and select between them:
 
 The CLI handles all x402 / MPP payment signing automatically — never ask the human for a private key or set up payment libraries by hand.
 
-### Operator (human / email session)
+### Sign-in session (a person)
 
-The **operator** is YOU, the human, identified by email — distinct from the agent (your wallet). One browser login spans every wallet that verified your email, so the overview is a cross-wallet union. For a single wallet's account state, use `run402 status`.
+A person signs in; the agent is your wallet (`run402 status` shows the wallet's own organization state). There is one sign-in session, graded by how it was minted.
 
-- `run402 operator login` — browser-delegated sign-in (device-authorization, RFC 8628, like `aws sso login`): magic-link or passkey in the browser, no WebAuthn in the CLI. Caches an email-scoped session at the base config dir (shared across named wallets).
-- `run402 operator overview` — account view across ALL wallets controlling your email (requires login; never falls back to a single wallet).
-- `run402 operator whoami` — show the cached session (email, wallets, expiry); local, no network.
-- `run402 operator logout` — revoke the session server-side and clear the local cache.
+- `run402 login` — browser passkey sign-in over loopback PKCE (RFC 8252, like `aws sso login`): the CLI listens on `127.0.0.1`, the browser runs the ceremony, and the session (grade `loopback`: full, step-up-able) is cached at the base config dir (shared across named wallets). Signing in again is the step-up.
+- `run402 login --device` — RFC 8628 device code for a terminal with no browser; approve it in the console. The session is grade `device`: read-only.
+- `run402 whoami` — principal, memberships, `session.grade`, and the write approvals cached on this machine.
+- `run402 approve --action <capability> (--org <org_id> | --project <project_id>)` — passkey-signed write approval for one action on one target; a person without a wallet needs it to provision, deploy, or write secrets (an interactive `provision`/`deploy` opens it for you).
+- `run402 logout` — revoke the session server-side and clear it and every write approval locally.
+- `run402 org list` — your orgs joined with the account overview (tier, lifecycle, quotas, allowance, advisories).
 
-Not exposed as MCP tools by design — MCP authenticates as the agent (wallet), and the human session must not be handed to it.
+Not exposed as MCP tools by design — MCP authenticates as the agent (wallet), and a person's session must not become its ambient authority.
 
 ## Active project (sticky default)
 

package/cli.mjs

@@ -31,20 +31,18 @@ Usage:
 Commands, grouped by when you reach for them:
 
 SET UP — get an agent funded and entitled
-  init        Set up allowance, funding, and check tier status (x402 default)
+  init        Set up the local wallet, funding, and check tier status (x402 default)
   init mpp    Set up with MPP payment rail (Tempo Moderato testnet)
-  wallets     Manage multiple named wallets (list, new, use, rename, bind, import)
-  allowance   Manage your agent allowance (create, fund, balance, status)
-  tier        Manage tier subscription (status, set)
-  redeem      Redeem a promo code for run402 credit
+  wallets     Manage local wallets (list, current, new, use, fund, balance, import)
+  tier        Manage your tier and its lease (status, set)
+  redeem      Redeem a promo code into your organization's allowance
   pay         Call an arbitrary x402-priced URL with a bounded payment
 
 BUILD & SHIP — the app and everything it serves
   up          Provision/link/deploy the current app with SDK orchestration
   projects    Manage projects (provision, list, get, sql, delete)
   repos       Host-blind encrypted git repos: create/view/list, snapshot/mirror/recover, fsck/gc/access/policy (repo aliases repos)
-  deploy      Unified deploy operations (requires active tier)
-  apply       Alias for deploy apply; supports --rehearse for migration rehearsal
+  deploy      Deploy a release; subcommands inspect and steer deploys (requires active tier)
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
   secrets     Manage project secrets (set, list, delete)
   sites       Deploy static sites
@@ -57,7 +55,7 @@ OPERATE — what happened, and is it healthy
   live        Change hints for live tables as NDJSON (SSE; --once for one held read)
   errors      Grouped error fingerprints + a promote/revert verdict (release-baselined)
   logs        Fetch function logs by request id (--request-id req_...)
-  status      Show full account state (allowance, balance, tier, projects)
+  status      Show full account state (wallet, allowance, tier, projects)
   doctor      Health and config diagnostics (JSON by default; includes --buzz preflight)
   service     Run402 service health and availability (status, health)
   snapshots   Create/list/restore/delete project data snapshots
@@ -78,13 +76,16 @@ AUTHORITY — who may act, and with what credential
   identity    Public proof-backed external agent identity links
   auth        Manage project user authentication (magic link, passwords, settings)
   ci          Link GitHub Actions OIDC deploy bindings
-  operator    Operator (human/email) session — login, then overview across your wallets
+  login       Sign in as a person (browser passkey; --device for a read-only session)
+  logout      End your sign-in session and clear it from this machine
+  whoami      Who this CLI acts as: principal, memberships, session grade
+  approve     Write approval for one action on one target (provision, deploy, secrets)
 
 DELIVER — reach a human when something happens
   deliveries     Did a notification actually land (list, get)
   contacts       Where a human is reachable — paging ladder + Telegram (list, add, connect, rm, preferences)
   subscriptions  Which events go where (add, list, rm)
-  webhook-secret Rotate the operator webhook signing secret
+  webhook-secret Rotate your webhook signing secret
   email          Send template-based emails from your project
 
 PLATFORM — everything else, and the things still finding a home
@@ -92,7 +93,7 @@ PLATFORM — everything else, and the things still finding a home
   billing     Email organizations, Stripe tier checkout, email packs
   contracts   KMS signers ($0.04/day rental + $0.000005/sign)
   jobs        Submit and inspect platform-managed jobs
-  transfer    Two-party project transfer (init, preview, list, accept, cancel)
+  transfer    Project transfer to a wallet, an email, or an owned org (init, preview, list, accept, cancel)
   cloud       Cloud portability archive export (archives create/download/status)
   archives    Inspect and verify portable project archives locally
   gitvault    RETIRED — moved to repos (repo-surface-consolidation); every spelling answers COMMAND_MOVED/COMMAND_REMOVED
@@ -115,11 +116,10 @@ Run 'run402 <command> --help' for detailed usage of each command.
 
 Examples:
   run402 up --name my-app -y
-  run402 allowance create
-  run402 allowance fund
+  run402 init
+  run402 wallets fund
   run402 pay https://seller.example/resource --max-usd 0.05
-  run402 deploy apply --manifest app.json
-  run402 apply --manifest app.json --rehearse --json
+  run402 deploy --manifest app.json
   run402 snapshots list --project prj_...
   run402 branches create --project prj_... --ttl-days 7 --json
   run402 cloud archives create --project prj_... --wait --output ./project.r402ar --json
@@ -134,7 +134,7 @@ Examples:
 Getting started:
   run402 init               Set up with x402 (Base Sepolia)
   run402 init mpp           Set up with MPP (Tempo Moderato)
-  run402 tier set prototype  Subscribe to a tier
+  run402 tier set prototype  Set a tier (prototype is free)
   run402 up --name my-app -y  Create and deploy this app (explicit destination)
   run402 ci link github --project prj_... --manifest run402.deploy.json
 `;
@@ -219,11 +219,6 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
-  case "allowance": {
-    const { run } = await import("./lib/allowance.mjs");
-    await run(sub, rest);
-    break;
-  }
   case "tier": {
     const { run } = await import("./lib/tier.mjs");
     await run(sub, rest);
@@ -247,11 +242,6 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
-  case "apply": {
-    const { runDeployV2 } = await import("./lib/deploy-v2.mjs");
-    await runDeployV2("apply", [sub, ...rest].filter(Boolean));
-    break;
-  }
   case "snapshots": {
     const { run } = await import("./lib/snapshots.mjs");
     await run(sub, rest);
@@ -450,9 +440,24 @@ switch (cmd) {
     await run(sub, rest);
     break;
   }
-  case "operator": {
-    const { run } = await import("./lib/operator.mjs");
-    await run(sub, rest);
+  case "login": {
+    const { run } = await import("./lib/login.mjs");
+    await run([sub, ...rest].filter(Boolean));
+    break;
+  }
+  case "logout": {
+    const { run } = await import("./lib/logout.mjs");
+    await run([sub, ...rest].filter(Boolean));
+    break;
+  }
+  case "whoami": {
+    const { run } = await import("./lib/whoami.mjs");
+    await run([sub, ...rest].filter(Boolean));
+    break;
+  }
+  case "approve": {
+    const { run } = await import("./lib/approve.mjs");
+    await run([sub, ...rest].filter(Boolean));
     break;
   }
   case "source-access": {

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.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;