run402 4.79.2 → 4.80.1

package/README.md

@@ -4,7 +4,7 @@ Command-line interface for [Run402](https://run402.com) — provision Postgres d
 
 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.
 
-For the full CLI reference (every flag, every subcommand) see **<https://docs.run402.com/llms-cli.txt>**.
+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.
 
 ## Install
 
@@ -44,6 +44,7 @@ run402 up --manifest run402.deploy.ts --plan
 run402 up --manifest run402.deploy.ts --require-plan plan_...
 run402 up --manifest run402.deploy.json --project prj_...
 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`.
@@ -52,6 +53,8 @@ For app manifests with `verify.http[]`, `up` runs HTTP checks after deploy. Fres
 
 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.
 
+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.
+
 ### repos — host-blind encrypted git repos (zero deploy ceremony)
 
 One noun, fourteen verbs (`repo` singular resolves identically). `run402 gitvault <verb>` answers `COMMAND_MOVED`/`COMMAND_REMOVED`.
@@ -63,12 +66,13 @@ git push -u origin main                       # allocates the vault on first pus
 
 # or, one call: provision + allocate + scaffold, nothing deployed
 run402 repos create my-notes
+run402 repos create --nested --project prj_xyz # app inside another repo: its own nested repo + remote
 run402 repos view --human
 run402 repos list --org org_1a2b3c
 run402 repos delete --project prj_xyz --force # refuses without --force while the vault holds generations
 ```
 
-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. 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.
+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.
 
@@ -169,7 +173,7 @@ Promote success means the origin pointer is active; mutable public URLs may stil
 `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`).
 
-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. 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, 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`.
 
 ### GitHub Actions OIDC deploys
 
@@ -220,12 +224,17 @@ run402 functions deploy <id> my-fn --file fn.ts \
   --schedule "*/15 * * * *" \
   --deps "stripe,zod@^3"
 run402 functions logs <id> my-fn --tail 100 --request-id req_abc123 --follow
+run402 functions logs --request-id req_abc123 --project <id>   # <name> optional with --request-id: every function is searched
+run402 functions logs my-fn --project <id> --all               # include the Lambda INIT_START / REPORT lines
+run402 logs --request-id req_abc123 --project <id>             # the x-run402-request-id response header, no function name needed
 run402 functions invoke my-fn --project <id> --body-file request.json
 run402 functions invoke paid-fn --project <id> --body-file request.json --idempotency-key paid:call:123 --wait
 run402 functions rebuild <id> my-fn      # refresh ONE function onto the current runtime
 run402 functions rebuild <id> --all      # refresh every function in the project
 ```
 
+Log reads are app-first: every entry carries `origin: "app" | "platform"`, the Lambda runtime lines (INIT_START, START/END/REPORT RequestId, billed duration) are hidden by default (`--app`), `--platform` shows only them and `--all` the raw stream; `hidden` counts what was dropped and a `hint` explains an empty result. `--request-id` accepts `req_`, `fnrun_`, and `fnatt_` ids, `--since` takes an ISO timestamp or epoch ms, and `run402 logs` rejects unknown flags.
+
 Inline `--body <json>` is validated before any request. Prefer `--body-file <path>` for agents and Windows `cmd.exe`; the file path avoids shell quoting entirely. Invalid or empty JSON fails locally instead of invoking the function with corrupted input.
 
 `functions rebuild` is opt-in and never changes your source: it re-bundles the stored source against the platform's current runtime/entry-wrapper (deps pinned to the exact versions recorded at deploy), so a gateway-side wrapper fix (e.g. an SSR `auth.*` fix) reaches an already-deployed function — a plain redeploy with unchanged source does not. The source `code_hash` is unchanged and no new release is created. Functions deployed before dependency locking return `CANNOT_REBUILD_UNLOCKED_DEPS`; redeploy those from source instead. `run402 doctor` flags functions on a stale runtime.
@@ -303,6 +312,15 @@ run402 tier set hobby                                        # $5 / 30 days
 run402 billing checkout <org_id> --product tier --tier hobby  # Stripe alternative
 ```
 
+### Doctor
+
+```bash
+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`).
+
 ## State
 
 Local state lives at:
@@ -357,7 +375,7 @@ The canonical, comprehensive CLI reference — every flag, every subcommand, edg
 
 **<https://docs.run402.com/llms-cli.txt>**
 
-Same content also at [`cli/llms-cli.txt`](./llms-cli.txt) in the repo. Treat that file as authoritative; this README is a quick-orientation landing page.
+Same content also at [`cli/llms-cli.txt`](./llms-cli.txt) (index), [`cli/llms-cli-<slice>.txt`](./) (topic slices) and [`cli/llms-cli-full.txt`](./llms-cli-full.txt) (everything) in the repo. Treat those files as authoritative; this README is a quick-orientation landing page.
 
 ## Other interfaces
 

package/gitvault-surface.json

@@ -1,5 +1,5 @@
 {
-  "surface_version": "4.79.2",
+  "surface_version": "4.80.1",
   "verbs": [
     "repos create",
     "repos list",

package/lib/command-manifest.mjs

@@ -485,7 +485,10 @@ export const COMMAND_MANIFEST = [
   // without rejecting it," which this satisfies.
   { path: ["doctor"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--no-scan"], runStyle: "merged" },
   { path: ["webhook-secret", "rotate"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: [] },
-  { path: ["logs"], positionals: [], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--request-id", "req_gate123"], runStyle: "merged" },
+  // `run402 logs [<function>] --request-id <id>`: the optional positional is
+  // the function name (`run402 errors` samples print it that way); it is
+  // never a project id.
+  { path: ["logs"], positionals: [p("function", { required: false })], projectScoped: true, legacyPositionalProject: false, minimalArgs: ["--request-id", "req_gate123"], runStyle: "merged" },
 ];
 
 // Families deliberately absent from the manifest, consumed by the gate's

package/lib/deploy-v2.mjs

@@ -26,6 +26,7 @@ import { existsSync, fstatSync, readFileSync } from "node:fs";
 import { resolve, dirname, extname, isAbsolute } from "node:path";
 import {
   applyWithGitvault,
+  assertLocalFileReferencesExist,
   buildDeployResolveSummary,
   githubActionsCredentials,
   loadDeployManifest,
@@ -1182,6 +1183,18 @@ async function applyCmd(args) {
   const releaseSpec = normalizedManifest.spec;
   const idempotencyKey = normalizedManifest.idempotencyKey;
 
+  // Filesystem-reference check: every function source, site file / dir and
+  // asset path the normalized spec still points at must exist. One `stat`
+  // per reference, so it runs in every mode — `--check` / `--print-spec`
+  // included — before any gateway call (MANIFEST_FILE_MISSING).
+  try {
+    await assertLocalFileReferencesExist(releaseSpec, {
+      ...(manifestPath ? { manifestPath } : {}),
+    });
+  } catch (err) {
+    reportSdkError(err);
+  }
+
   if (opts.mode === "check") {
     console.log(JSON.stringify({
       ok: true,
@@ -1531,12 +1544,15 @@ function enhanceDeployWarningError(err) {
 
 const ROUTE_WARNING_GUIDANCE = {
   PUBLIC_ROUTED_FUNCTION: {
-    hint: "A deploy route makes a function public same-origin browser ingress; direct /functions/v1/:name remains API-key protected.",
+    // Informational on the gateway (requires_confirmation: false): it never
+    // blocks a deploy by itself, so the guidance must not teach an
+    // acknowledgement flag the warning does not need.
+    hint: "A deploy route makes a function public same-origin browser ingress; direct /functions/v1/:name remains API-key protected. This warning is informational and needs no --allow-warning; another warning with requires_confirmation: true is what blocked this plan.",
     next_actions: [
       nextAction("edit_request", { why: "Review application auth and authorization in the routed function." }),
       nextAction("edit_request", { why: "Add CSRF protection for cookie-authenticated POST/PUT/PATCH/DELETE routes." }),
       nextAction("edit_request", { why: "Implement CORS and OPTIONS explicitly when cross-origin callers are intended." }),
-      retryAction("run402 deploy apply --allow-warnings", "Retry only after the public ingress review is intentional."),
+      retryAction("run402 deploy apply --allow-warning <code>", "Acknowledge only the warning that has requires_confirmation: true, after review."),
     ],
   },
   ROUTE_TARGET_CARRIED_FORWARD: {

package/lib/doctor.mjs

@@ -79,7 +79,25 @@ Usage:
   run402 --wallet <profile> doctor --buzz --buzz-agent <npub-or-hex>
 
 Output:
-  Stdout is a JSON report { ok, checks: [{ name, status, value?, hint?, message? }] }.
+  Stdout is a JSON report:
+    { ok,
+      blocking: [{ check, status, message, hint? }],
+      warnings: [{ check, code?, message, hint? }],
+      checks:   [{ name, status, severity, value?, hint?, message? }] }
+  \`ok\` answers ONE question — can this agent ship from here — and is true
+  exactly when \`blocking[]\` is empty. Every check carries a \`severity\`:
+    blocking  would stop a deploy: config_dir / allowance missing or error,
+              api_reachable error, tier inactive / frozen / past_due /
+              dormant / missing / error, error-severity source_scan findings
+    advisory  a warning that never stops a deploy: operator_health,
+              recovery_posture, gitvault, runtime_staleness, cli_update gaps
+    info      ok / skipped / unknown
+  Agents: branch on \`ok\`; read \`warnings[]\` (one entry per gap) for the
+  non-blocking gaps and \`blocking[]\` for what to fix when \`ok\` is false.
+  \`--only\` and \`--refresh\` runs have the same shape. The tier check's
+  status is a fixed vocabulary — ok | inactive | frozen | past_due | dormant
+  | purged | missing | unknown | error — never a tier name; the tier name
+  and raw lifecycle ride in value.tier / value.lifecycle.
   Buzz mode adds { mode: "buzz", contract_id, generated_at, mutation_state,
   binding, telemetry } and uses check status ok|warning|blocked.
 
@@ -130,7 +148,10 @@ Checks performed:
   - Allowance is configured and on a valid rail (x402 / mpp)
   - Keystore has at least one wallet
   - API_BASE is reachable (network check via /health)
-  - Active tier resolves and is not 'past_due' / 'frozen'
+  - Active tier resolves and is not 'past_due' / 'frozen' / 'dormant'. A wallet
+    whose OWN organization holds no tier but that can reach projects owned by
+    another organization (membership or grant) reports status 'missing' as an
+    advisory, not a blocker — deploys to those projects are unaffected.
   - Function runtime staleness: deployed functions running an older platform
     runtime than the current gateway build (refresh with 'run402 functions
     rebuild --all'; re-bundles from your stored source, no source change)
@@ -157,10 +178,89 @@ Buzz mode checks (in order):
   operator, runtime-staleness, and source-tree checks.
 
 Exit codes:
-  0  — all checks pass
-  1  — one or more checks failed (details in output)
+  0  — ok: true (advisory warnings never change the exit code)
+  1  — ok: false (one or more blocking checks; see blocking[])
 `;
 
+/**
+ * Check statuses that carry no finding at all. Everything else is either the
+ * one advisory status (`warning`) or a blocking status — so a NEW status
+ * string that slips into a check (a lifecycle name, a tier name, a typo)
+ * fails closed as blocking instead of silently passing.
+ */
+const INFO_STATUSES = new Set(["ok", "skipped", "unknown"]);
+
+/** Non-active organization lifecycle states the gateway can report (`organization-lifecycle` spec); each is its own blocking tier status. */
+const TIER_LIFECYCLE_STATUSES = new Set(["past_due", "frozen", "dormant", "purged"]);
+
+/**
+ * The severity contract, in one place: `blocking` = would stop this agent
+ * from shipping; `advisory` = a gap worth surfacing that never stops a
+ * deploy; `info` = nothing to act on. A check may pin its own `severity`
+ * explicitly (the tier check does, for the missing-but-can-reach-projects
+ * shape); otherwise it is derived from `status`.
+ */
+function severityOf(check) {
+  if (check.severity === "blocking" || check.severity === "advisory" || check.severity === "info") return check.severity;
+  if (INFO_STATUSES.has(check.status)) return "info";
+  if (check.status === "warning") return "advisory";
+  return "blocking";
+}
+
+/** Stable codes for advisory checks that report ONE finding (no `value.gaps`), keyed by check name. */
+const ADVISORY_CODES = {
+  cli_update: "CLI_UPDATE_AVAILABLE",
+  runtime_staleness: "FUNCTION_RUNTIME_STALE",
+  source_scan: "SOURCE_SCAN_WARNINGS",
+  tier: "TIER_MISSING_ON_OWN_ORG",
+};
+
+/**
+ * Fold the per-check report into the agent-facing envelope:
+ * `{ ok, blocking[], warnings[], checks[] }`. `warnings[]` carries one entry
+ * per gap string of every advisory check (plus one for an advisory check
+ * with no gaps); `blocking[]` carries one entry per blocking check and is
+ * empty exactly when `ok` is true. Pure — the same fold serves a full run,
+ * `--only`, and `--refresh`.
+ */
+export function buildDoctorReport(rawChecks) {
+  const checks = rawChecks.map((check) => {
+    const { name, status, severity: _pinned, ...rest } = check;
+    return { name, status, severity: severityOf(check), ...rest };
+  });
+  const blocking = [];
+  const warnings = [];
+  for (const check of checks) {
+    if (check.severity === "blocking") {
+      blocking.push({
+        check: check.name,
+        status: check.status,
+        message: check.message ?? `${check.name}: ${check.status}`,
+        ...(check.hint && { hint: check.hint }),
+      });
+      continue;
+    }
+    if (check.severity !== "advisory") continue;
+    const gaps = Array.isArray(check.value?.gaps) ? check.value.gaps.filter((g) => typeof g === "string" && g.length > 0) : [];
+    if (gaps.length > 0) {
+      for (const gap of gaps) {
+        warnings.push({ check: check.name, message: gap, ...(check.hint && { hint: check.hint }) });
+      }
+    } else {
+      const code = check.code ?? ADVISORY_CODES[check.name];
+      const message = check.message ?? check.hint ?? `${check.name}: ${check.status}`;
+      warnings.push({
+        check: check.name,
+        ...(code && { code }),
+        message,
+        // Only carry `hint` when it adds something the message does not.
+        ...(check.hint && check.hint !== message && { hint: check.hint }),
+      });
+    }
+  }
+  return { ok: blocking.length === 0, blocking, warnings, checks };
+}
+
 function redactAllowanceForDiagnostics(allowance) {
   if (!allowance || typeof allowance !== "object") return allowance;
   const safe = { ...allowance };
@@ -368,36 +468,71 @@ export async function run(sub, args = []) {
   }
 
   // 5. Active tier.
+  //
+  // `status` is a FIXED vocabulary — ok | inactive | frozen | past_due |
+  // dormant | purged | missing | unknown | error — never the tier name and
+  // never a raw gateway string: the old derivation fell through to
+  // `tierName ?? "missing"`, which could put a tier NAME ("team") in the
+  // status slot, and any status outside the ok-allowlist silently flipped
+  // the whole report to ok:false while looking benign. The tier name and the
+  // raw lifecycle ride in value.tier / value.lifecycle instead.
   if (wanted("tier")) try {
     const sdk = getSdk();
     const tier = await sdk.tier.status();
-    const tierName = tier?.tier ?? null;
-    const lifecycle = tier?.organization_lifecycle_state ?? null;
+    const tierName = typeof tier?.tier === "string" && tier.tier.length > 0 ? tier.tier : null;
+    const lifecycle = typeof tier?.organization_lifecycle_state === "string" && tier.organization_lifecycle_state.length > 0
+      ? tier.organization_lifecycle_state
+      : null;
     const active = tier?.active === true;
-    if (tierName && active && lifecycle === "active") {
+    // Projects this wallet can reach through org membership or a grant —
+    // the tier read already carries them. A wallet whose OWN org-of-one
+    // never bought a tier can still ship into another org's projects, so
+    // "missing" is only a blocker when there is nowhere to ship.
+    const reachableProjects = Array.isArray(tier?.projects) ? tier.projects.length : 0;
+    let status;
+    if (lifecycle !== null && lifecycle !== "active") {
+      status = TIER_LIFECYCLE_STATUSES.has(lifecycle) ? lifecycle : "inactive";
+    } else if (tierName === null) {
+      status = "missing";
+    } else if (!active) {
+      status = "inactive";
+    } else if (lifecycle === null) {
+      status = "unknown";
+    } else {
+      status = "ok";
+    }
+    const value = {
+      tier: tierName,
+      lifecycle,
+      active,
+      organization_lifecycle_state: lifecycle,
+      lease_expires_at: tier?.lease_expires_at ?? null,
+      reachable_projects: reachableProjects,
+    };
+    if (status === "ok") {
+      checks.push({ name: "tier", status, value });
+    } else if (status === "missing" && reachableProjects > 0) {
       checks.push({
         name: "tier",
-        status: "ok",
-        value: { tier: tierName, active, organization_lifecycle_state: lifecycle },
+        status,
+        severity: "advisory",
+        value,
+        message: `this wallet's own organization holds no tier, but it can reach ${reachableProjects} project(s) owned by another organization (membership or grant) — deploys to those are unaffected`,
+        hint: "Run 'run402 tier set prototype' only if you want to provision projects under this wallet's own organization.",
       });
     } else {
-      const status = lifecycle && lifecycle !== "active"
-        ? lifecycle
-        : tierName && !active
-          ? "inactive"
-          : tierName && lifecycle === null
-            ? "unknown"
-            : tierName ?? "missing";
       checks.push({
         name: "tier",
         status,
-        value: {
-          tier: tierName,
-          active,
-          organization_lifecycle_state: lifecycle,
-          lease_expires_at: tier?.lease_expires_at ?? null,
-        },
-        hint: lifecycle === null && tierName
+        value,
+        message: status === "unknown"
+          ? "tier resolved, but the organization lifecycle could not be determined"
+          : status === "missing"
+            ? "no tier on this wallet's organization and no reachable project — nothing can be provisioned or deployed from here"
+            : status === "inactive"
+              ? `tier '${tierName ?? "(none)"}' is not active${lifecycle && lifecycle !== "active" ? ` (organization lifecycle '${lifecycle}')` : ""}`
+              : `organization lifecycle is '${lifecycle}' — the control plane is gated until the tier is reactivated`,
+        hint: status === "unknown"
           ? "Tier resolved, but organization lifecycle could not be determined. Check `run402 tier status` before assuming the account is healthy."
           : "Run 'run402 tier set prototype' to subscribe, renew, or reactivate the tier.",
       });
@@ -838,11 +973,10 @@ export async function run(sub, args = []) {
     }
   }
 
-  // 'warning' counts as ok for exit-code purposes — gaps are surfaced in
-  // output but don't fail the doctor. Only hard 'error' / 'missing' /
-  // 'empty' fail.
-  const allOk = checks.every((c) => c.status === "ok" || c.status === "warning" || c.status === "skipped" || c.status === "unknown");
-
-  console.log(JSON.stringify({ ok: allOk, checks }, null, 2));
-  process.exit(allOk ? 0 : 1);
+  // `ok` is structural — "no check is blocking" — never an allowlist of
+  // status strings. Advisory warnings ride in `warnings[]` and never change
+  // the exit code; `blocking[]` is what to fix when `ok` is false.
+  const report = buildDoctorReport(checks);
+  console.log(JSON.stringify(report, null, 2));
+  process.exit(report.ok ? 0 : 1);
 }

package/lib/errors.mjs

@@ -108,9 +108,11 @@ Exit codes (the promote gate — only when --fail-on-new is set):
                 from 1. Without --fail-on-new, failures are the usual exit 1.
 
 Auth:
-  The addressed project's own anon_key or service_key. A key for project A
-  requesting project B's errors gets 403 (never a 404 that leaks existence).
-  Read-only; never lifecycle-gated.
+  The addressed project's own service_key when it is cached locally; otherwise
+  your wallet / session / delegate, which the gateway authorizes with
+  project.read — an org member or teammate agent needs no project key. A key
+  for project A requesting project B's errors gets 403 (never a 404 that
+  leaks existence). Read-only; never lifecycle-gated.
 
 The golden path — gate a promote:
   run402 deploy promote --project <id> --release <rel>