ai-saas-guard 0.38.0 → 0.40.0

package/README.md

@@ -170,7 +170,9 @@ For a concise comparison with Semgrep, zizmor, OpenSSF Scorecard, Snyk, and GitH
 | --- | --- | --- |
 | Local CLI | Private code, first local launch review, founder or reviewer workflow | Published on npm; local-first, read-only, no code upload, no LLM calls |
 | GitHub Action | CI review queue, SARIF upload, PR summary artifacts, controlled fail thresholds | Available through `zr9959/ai-saas-guard@v0` and fixed version tags |
-| Hosted GitHub App | Future hosted Check Run experience for selected repositories | Limited trial gate with staging ingress, public install-info, compact Check Runs, and cleanup handling; not the complete hosted SaaS, not a public hosted scanner |
+| Hosted GitHub App | Selected-repository Check Run for AI-heavy SaaS PRs | Limited trial gate with [install/privacy notes](docs/hosted-install-privacy.md), public install-info, compact Check Runs, and cleanup handling; not the complete hosted SaaS, not a public hosted scanner |
+
+Choose the path by trust boundary: use the **Local CLI** when code must stay on your machine, the **GitHub Action** when you want repeatable CI evidence, and the **Hosted GitHub App** when reviewers need an automatic Check Run that groups auth, billing, tenant-data, deploy, and test-risk areas before merge.
 
 ## Quick Start
 
@@ -233,16 +235,16 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.38.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.38.0` |
+| npm CLI | `ai-saas-guard@0.40.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.40.0` |
 | Outputs | Launch decision queue, short summary, terminal, JSON, SARIF, and PR-focused markdown |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, suppressions, and fail thresholds |
 | Privacy model | Local-first, read-only scan commands, no LLM calls, no code upload |
-| Versioned Action tags | `v0.38.0`, `v0` |
-| Current release | `0.38.0` closes more of the hosted GitHub App staging loop with public install guidance, selected-repository Check Run wording, signed installation cleanup, and updated hosted docs/tests |
+| Versioned Action tags | `v0.40.0`, `v0` |
+| Current release | `0.40.0` groups hosted Check Run output by launch-risk area, adds machine-readable hosted smoke evidence, clarifies CLI/Action/Hosted path selection, and documents the next source-checkout boundary |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
-| Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
+| Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; public install/privacy notes are in [docs/hosted-install-privacy.md](docs/hosted-install-privacy.md); signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
 | Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`; hosted operations evidence is in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
 | OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
 | Previous roadmap | v0.36.0 plan is tracked in [docs/v0.36-roadmap.md](docs/v0.36-roadmap.md) |
@@ -365,6 +367,10 @@ Deployed worker staging evidence is documented in [docs/hosted-deployed-worker-s
 
 The first live hosted ingress is deployed on Cloudflare Workers at `https://ai-saas-guard-hosted.zr9959.workers.dev` and documented in [hosted/cloudflare-worker/README.md](hosted/cloudflare-worker/README.md). It exposes `/healthz`, `/github/app/install-info`, `/github/app/manifest-callback`, and signed `/github/webhook` intake backed by Cloudflare KV. A private staging GitHub App, `ai-saas-guard-hosted`, is installed on `zr9959/ai-saas-guard` with selected-repository access and the first-slice permission contract. The Worker verifies signatures, stores compact pull request identity records, exchanges a scoped installation token, fetches PR file metadata from GitHub, classifies PR-risk hotspots, and publishes a bounded selected-repository hosted check with a review queue and manual proof prompt. Signed installation deletion and repository removal events delete matching compact records. Current deployed evidence is tracked in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md): health, signed webhook delivery, compact KV records, cleanup, and Check Run publication pass in staging. The Cloudflare Worker still does not run a full source checkout scan worker or store raw webhook payloads, PR title/body text, raw diffs, source, secrets, checkout paths, or installation tokens.
 
+The next hosted source-checkout step is intentionally narrow: deploy the existing read-only checkout worker behind the same selected-repository identity, keep the fixed `pr-risk --json` command, write only compact findings to the Check Run, and require deployed cleanup/log-boundary/rollback evidence before broader trial use.
+
+Hosted install and privacy details are summarized in [docs/hosted-install-privacy.md](docs/hosted-install-privacy.md): selected-repository permissions, supported events, Check Run data boundaries, uninstall cleanup, and why the local CLI remains the private/offline path.
+
 The hosted operational release gate is documented in [docs/hosted-operational-release-gate.md](docs/hosted-operational-release-gate.md). It defines the hosted-specific CI, replay, queue, worker cleanup, privacy, monitoring, rollback, and incident-response evidence required before any hosted environment is exposed to users. The pure gate evaluator exported from `ai-saas-guard/hosted/contracts` blocks hosted exposure unless every P0 evidence item is fresh, a container digest is recorded, and release notes avoid pentest, certification, and full-audit claims.
 
 Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninstall-data-deletion.md](docs/hosted-uninstall-data-deletion.md). It defines repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup, and user-facing deletion wording.
@@ -417,7 +423,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.38.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.40.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/hosted/contracts.js

@@ -485,7 +485,12 @@ export function createHostedCheckRunSummary(input) {
         conclusion,
         output: {
             title: formatCheckRunTitle(totalFindings, conclusion, input.failOnSeverity),
-            summary: `Launch-risk gate: ${launchGate}. Launch gate: ${launchGate}. Review first: What changed at the launch boundary? Manual proof required before release. This is not an AI reviewer and not a full security audit, pentest, or certification.`,
+            summary: [
+                `Launch-risk gate: ${launchGate}. Launch gate: ${launchGate}.`,
+                "Review task: inspect the files below before merge.",
+                "Manual proof: prove changed auth, billing, data, deploy, or tests fail closed.",
+                "Boundary: selected repository only; not an AI reviewer, pentest, full audit, or certification."
+            ].join(" "),
             text: truncateMarkdown(formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate), input.maxMarkdownChars)
         },
         annotations: report.evidence.slice(0, MAX_CHECK_RUN_ANNOTATIONS).map((finding) => {
@@ -1137,6 +1142,7 @@ function formatCheckRunTitle(totalFindings, conclusion, failOnSeverity) {
 }
 function formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate) {
     const categories = getHostedCheckRunCategories(report);
+    const riskAreas = getHostedCheckRunRiskAreas(report);
     const filesToReview = getHostedCheckRunFiles(report);
     const findingLines = report.evidence.length === 0
         ? ["No findings in the compact hosted report."]
@@ -1148,7 +1154,9 @@ function formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate)
     return [
         "### AI SaaS Guard Launch-risk gate",
         "",
-        "Review first: verify findings locally before launch or merge. Not an AI reviewer or full security audit.",
+        "Review task: inspect the files below before merge.",
+        "Manual proof: prove changed auth, billing, data, deploy, or tests fail closed.",
+        "Boundary: selected repository only; not an AI reviewer, pentest, full audit, or certification.",
         "",
         `Launch gate: ${launchGate}`,
         `Conclusion: ${conclusion}`,
@@ -1159,9 +1167,14 @@ function formatCheckRunMarkdown(report, conclusion, localCliCommand, launchGate)
         ...(categories.length === 0 ? ["- None"] : categories.map((category) => `- ${category}`)),
         "",
         "Verification steps:",
-        "- Review listed files before release or merge.",
+        "- Inspect the listed files locally before release or merge.",
         "- Reproduce locally with the CLI command above.",
-        "- Confirm behavior with app-specific tests.",
+        "- Prove changed auth, billing, data, deploy, or tests fail closed.",
+        "",
+        "Risk areas:",
+        ...(riskAreas.length === 0
+            ? ["- None"]
+            : riskAreas.map((area) => `- ${area.name}: ${area.count} finding(s). Proof: ${area.proof}`)),
         "",
         "Launch decision queue:",
         "- Can a real user get access they should not have?",
@@ -1219,6 +1232,69 @@ function getHostedCheckRunCategories(report) {
     const categories = report.evidence.map((finding) => categoryForRuleId(finding.ruleId));
     return [...new Set(categories)];
 }
+function getHostedCheckRunRiskAreas(report) {
+    const counts = new Map();
+    for (const finding of report.evidence) {
+        const area = riskAreaForRuleId(finding.ruleId);
+        counts.set(area.key, {
+            ...area,
+            count: (counts.get(area.key)?.count ?? 0) + 1
+        });
+    }
+    return [...counts.values()].sort((a, b) => {
+        if (b.weight !== a.weight)
+            return b.weight - a.weight;
+        return b.count - a.count;
+    });
+}
+function riskAreaForRuleId(ruleId) {
+    if (/^(auth|api)\./.test(ruleId)) {
+        return {
+            key: "auth",
+            name: "Auth and session",
+            proof: "use two accounts and confirm access, session, and ownership checks fail closed",
+            weight: 50
+        };
+    }
+    if (/^stripe\./.test(ruleId)) {
+        return {
+            key: "billing",
+            name: "Billing and entitlement",
+            proof: "force unsigned, duplicate, failed, and canceled billing events before granting access",
+            weight: 50
+        };
+    }
+    if (/^(supabase|data)\./.test(ruleId)) {
+        return {
+            key: "data",
+            name: "Tenant data access",
+            proof: "run cross-tenant SELECT, INSERT, UPDATE, and DELETE checks with user A and user B",
+            weight: 45
+        };
+    }
+    if (/^(deploy|secrets|mcp|actions)\./.test(ruleId)) {
+        return {
+            key: "deploy",
+            name: "Deploy, secrets, tools, and permissions",
+            proof: "confirm production env, workflow permissions, and tool scopes are least privilege",
+            weight: 35
+        };
+    }
+    if (/^silent-success\.|weakened-test|test/i.test(ruleId)) {
+        return {
+            key: "tests",
+            name: "Tests and silent success",
+            proof: "make the upstream path fail and confirm tests catch an error instead of fake success",
+            weight: 40
+        };
+    }
+    return {
+        key: "pr",
+        name: "PR trust boundary",
+        proof: "explain the trust-boundary decision and prove the changed path fails closed",
+        weight: 30
+    };
+}
 function categoryForRuleId(ruleId) {
     const prefix = ruleId.split(".")[0] ?? "review";
     const categoryNames = {

package/docs/README.zh-CN.md

@@ -165,7 +165,9 @@ Next steps
 | --- | --- | --- |
 | 本地 CLI | 私有代码、本机首次上线 review、founder 或 reviewer 自查 | 已发布到 npm；本地优先、只读、不上传代码、不调用 LLM |
 | GitHub Action | CI 里的 review queue、SARIF、PR summary artifact、可控 fail threshold | 可通过 `zr9959/ai-saas-guard@v0` 或固定版本标签使用 |
-| Hosted GitHub App | 未来面向 selected repositories 的 hosted Check Run 体验 | 当前是 staging ingress，已有公开 install-info、compact Check Run 和 cleanup handling；不是完整 hosted SaaS，也不是公开 hosted scanner |
+| Hosted GitHub App | 面向 AI 大 PR 的 selected-repository Check Run | 当前是 staging ingress，已有[安装和隐私说明](hosted-install-privacy.md)、公开 install-info、compact Check Run 和 cleanup handling；不是完整 hosted SaaS，也不是公开 hosted scanner |
+
+按信任边界选择：代码必须留在本机时用 **Local CLI**；需要 CI 里的可重复证据时用 **GitHub Action**；reviewer 需要自动 Check Run 时用 **Hosted GitHub App**，它会把 auth、billing、tenant data、deploy 和 test-risk areas 分组后放到 PR 里。
 
 ## 快速开始
 
@@ -211,21 +213,21 @@ node dist/cli.js scan --root /path/to/your-saas
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.38.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.38.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.40.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.40.0`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.38.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.38.0` |
+| npm CLI | `ai-saas-guard@0.40.0` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.40.0` |
 | 输出格式 | 上线决策队列、短 summary、Terminal、JSON、SARIF 和 PR markdown |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
 | 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.38.0` 补齐更多 hosted GitHub App staging 闭环：公开 install-info、selected-repository Check Run 文案、签名 installation cleanup，以及对应 hosted 文档和测试 |
-| Action 标签 | `v0.38.0`、`v0` |
+| 当前版本 | `0.40.0` 按上线风险区域分组 hosted Check Run 输出，增加机器可读 hosted smoke evidence，讲清 CLI/Action/Hosted 三条路径选择，并记录下一步 source-checkout 边界 |
+| Action 标签 | `v0.40.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
-| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；提供 `/github/app/install-info`，签名 GitHub App webhook delivery、compact Check Run 和 installation cleanup staging smoke 已通过 |
+| Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；安装和隐私说明见 [hosted-install-privacy.md](hosted-install-privacy.md)；提供 `/github/app/install-info`，签名 GitHub App webhook delivery、compact Check Run 和 installation cleanup staging smoke 已通过 |
 | Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`；hosted operations evidence 见 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md) |
 | OpenSSF Best Practices | 已获得 passing badge，项目 `12955`；`.bestpractices.json` 继续作为保守证据记录 |
 | 上一版路线 | v0.36.0 计划见 [v0.36-roadmap.md](v0.36-roadmap.md) |
@@ -381,6 +383,10 @@ GitHub Marketplace wrapper 决策见 [docs/github-marketplace-wrapper-decision.m
 
 当前仓库已经包含未来 Hosted GitHub App 的设计文档、纯契约测试、第一个真实 Cloudflare hosted ingress，以及 Node/container read-only checkout scan runner。私有 staging GitHub App `ai-saas-guard-hosted` 已安装到 `zr9959/ai-saas-guard`，Cloudflare 已配置所需的云端凭据绑定。Worker 代码已经能接收签名 webhook、写入 KV 队列、换取 scoped installation token、读取 GitHub PR file metadata、做 compact PR-risk classification，并发布有长度上限的 selected-repository Check Run summary；`/github/app/install-info` 会返回公开安全的安装说明、权限、事件、隐私边界和卸载说明。签名 installation deletion 和 repository removal 事件会删除匹配的 compact records。当前端到端 GitHub App webhook delivery smoke 已通过，证据记录在 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md)。Cloudflare ingress 本身仍不是完整 source checkout scan worker。
 
+下一步 hosted source checkout 仍然要保持窄边界：把现有 read-only checkout worker 放到同一个 selected-repository identity 后面，继续固定 `pr-risk --json` 命令，只把 compact findings 写入 Check Run，并在扩大 trial 前要求 deployed cleanup、log-boundary 和 rollback evidence。
+
+Hosted 安装、权限和隐私边界见 [hosted-install-privacy.md](hosted-install-privacy.md)：selected-repository 权限、支持的 GitHub 事件、Check Run 数据边界、卸载清理，以及为什么本地 CLI 仍然是私有/离线路径。
+
 相关文档：
 
 - [docs/github-app-design.md](github-app-design.md)
@@ -394,6 +400,7 @@ GitHub Marketplace wrapper 决策见 [docs/github-marketplace-wrapper-decision.m
 - [docs/hosted-staging-harness.md](hosted-staging-harness.md)
 - [docs/hosted-deployed-worker-staging.md](hosted-deployed-worker-staging.md)
 - [docs/hosted-operational-release-gate.md](hosted-operational-release-gate.md)
+- [docs/hosted-install-privacy.md](hosted-install-privacy.md)
 - [docs/hosted-uninstall-data-deletion.md](hosted-uninstall-data-deletion.md)
 - [docs/hosted-pricing-packaging.md](hosted-pricing-packaging.md)
 - [docs/hosted-preimplementation-contracts.md](hosted-preimplementation-contracts.md)

package/docs/hosted-install-privacy.md

@@ -0,0 +1,68 @@
+# Hosted Install And Privacy
+
+`ai-saas-guard-hosted` is the limited hosted GitHub App path for teams that want a selected-repository Check Run instead of running only the local CLI.
+
+Use the local CLI first when you need private, offline, no-account review:
+
+```bash
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main
+```
+
+Install information for the hosted App is available from the deployed Worker:
+
+- public install info: `https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info`
+- GitHub App install URL: `https://github.com/apps/ai-saas-guard-hosted/installations/new`
+- staging App ID: `3834787`
+
+## What It Solves
+
+AI-built SaaS pull requests often change auth, billing, tenant data, deploy settings, or tests inside a large diff. The hosted App turns those trust-boundary changes into a compact GitHub Check Run so reviewers know what files to inspect before merge.
+
+It is not an AI reviewer, pentest, full audit, or certification. It is a launch-risk review queue.
+
+## Permissions
+
+The first hosted slice uses selected-repository access only:
+
+| Permission | Access | Why |
+| --- | --- | --- |
+| `checks` | write | Publish the bounded launch-risk Check Run |
+| `contents` | read | Read PR file metadata for the selected repository |
+| `pull_requests` | read | Identify the PR, base SHA, and head SHA |
+| `metadata` | read | Required by GitHub Apps |
+
+It does not request administration, Actions write, repository secrets, deployments, issues, or organization-wide access.
+
+## Events
+
+The hosted App listens for:
+
+- `pull_request` for opened, reopened, synchronize, and ready-for-review events
+- `installation` for full uninstall cleanup
+- `installation_repositories` for selected repository removal cleanup
+
+Unsupported, draft, unsigned, oversized, or malformed events are ignored or rejected before scan side effects.
+
+## Privacy Boundary
+
+The hosted Check Run and compact records are designed to avoid sensitive payloads:
+
+- no raw source files
+- no raw diffs
+- no webhook payload bodies
+- no PR title or body text
+- no secrets
+- no customer payloads
+- no private checkout paths
+- no installation tokens
+- no model training and no LLM calls
+
+The hosted Worker stores compact identity, file path, category, severity, and rule signals needed to publish a review queue. Local CLI use remains available without any hosted processing.
+
+## Uninstall And Deletion
+
+Repository removal and full App uninstall trigger cleanup for matching compact records and queued work. GitHub-owned Check Runs may remain in GitHub history, but hosted compact records are deleted according to the cleanup path described in [hosted-uninstall-data-deletion.md](hosted-uninstall-data-deletion.md).
+
+## Current Trial Boundary
+
+The deployed Cloudflare Worker currently handles signed webhook intake, scoped installation token exchange, PR file metadata classification, compact Check Run publication, and installation cleanup for staging. It is not yet the complete source checkout scan worker or public hosted SaaS.

package/docs/hosted-operational-release-gate.md

@@ -21,6 +21,8 @@ Every hosted release must record:
 - privacy and retention evidence
 - monitoring and alerting checks
 - manual rollback result
+- real hosted PR smoke result, when a live GitHub App ingress is deployed
+- staging KV cleanup result for `delivery:` and `scan:` smoke records
 - incident response owner and escalation path
 
 ## P0 Gate Summary
@@ -35,6 +37,7 @@ Every hosted release must record:
 8. Retention checks prove compact reports expire according to policy.
 9. Monitoring and alerting checks cover ingress, queue depth, worker failures, check run failures, and cleanup failures.
 10. Manual rollback is tested against the release candidate.
+11. Any deployed GitHub App ingress passes a real temporary PR smoke with Check Run evidence and post-smoke branch, PR, and KV cleanup.
 
 ## Current Source Candidate Evidence Notes
 
@@ -58,6 +61,7 @@ Source-level evidence notes for this release candidate:
 | `container_scan` | Container image scan has no unresolved high or critical runtime-layer findings | No hosted container image exists in the public package release | Not applicable to current non-hosted release; required before hosted exposure |
 | `queue_worker_cleanup` | Queue dedupe, running cancellation, terminal cleanup, worker checkout deletion, and no long-running processes | Pure queue, worker, checkout, retention cleanup planner tests, staging harness success/failure cleanup probes, and deployed worker staging cleanup evidence helper | Passed for source candidate; deployed helper can record success/failure cleanup before exposure |
 | `privacy_retention` | No raw source, raw diffs, secrets, customer payloads, private URLs, or full file contents; retention and uninstall cleanup are proven | Compact report, Check Run publication, retention/deletion cleanup, docs tests, `validateHostedLogBoundary` source-candidate log checks, and deployed log-boundary staging evidence | Passed for source candidate; deployed log sampling still required before exposure |
+| `hosted_pr_smoke` | Deployed GitHub App ingress creates a temporary PR, publishes `ai-saas-guard PR risk`, closes the PR, deletes the branch, and clears staging `delivery:` / `scan:` KV records | `node scripts/hosted-pr-smoke.mjs --plan` plus `node scripts/hosted-pr-smoke.mjs` after deployment | Required for any release that changes the live hosted Worker or GitHub App wiring |
 | `monitoring_alerting` | Ingress, queue depth, worker failures, Check Run failures, cleanup failures, retention failures, and credential rotation alerts | Required alert list remains in this document | Documented; must attach provider evidence before exposure |
 | `manual_rollback` | Worker pause, previous artifact redeploy, queue resume, controlled ingress failure, and affected Check Run identification | Manual rollback procedure remains in this document | Documented; must execute against deployed artifact before exposure |
 | `incident_response` | Owner, backup, credential rotation, queue pause, customer communication, status path, and privacy-safe evidence collection | Incident response checklist remains in this document | Documented; must name live owners before exposure |
@@ -79,6 +83,7 @@ node dist/cli.js scan --root . --sarif
 node dist/cli.js pr-risk --root . --json
 npm audit --audit-level=high --registry=https://registry.npmjs.org
 npm pack --dry-run --json
+node scripts/hosted-pr-smoke.mjs --plan
 ```
 
 CI must also run GitHub Actions static checks:
@@ -90,6 +95,14 @@ uvx zizmor --offline .github/workflows
 
 For a hosted release candidate, CI must additionally verify the built container image or deployment artifact rather than only source files.
 
+For any release that changes the deployed Cloudflare GitHub App ingress, run the real smoke after deployment:
+
+```bash
+node scripts/hosted-pr-smoke.mjs --evidence-file /tmp/ai-saas-guard-hosted-smoke.json
+```
+
+The script must refuse a dirty working tree, target only `zr9959/ai-saas-guard`, create a `codex/hosted-smoke-*` branch, query Check Runs with a GET request on the trusted head SHA, write a public-safe machine-readable evidence record, close the temporary PR, delete the remote and local branch, and bulk-delete staging KV `delivery:` / `scan:` records.
+
 ## Hosted Security Tests
 
 The release blocks when any of these tests fail:
@@ -241,9 +254,11 @@ Each hosted release run must clean:
 
 - temporary files
 - package tarballs that are not release assets
+- temporary smoke PRs and `codex/hosted-smoke-*` branches
 - worker checkouts
 - generated SARIF and JSON scratch files
 - dead test queues or local stores
+- staging KV `delivery:` and `scan:` smoke records
 - long-running processes started during verification
 
 After cleanup, `git status --short --branch` should be clean, and process checks should show no test, build, watch, queue, worker, or dev-server processes left behind.

package/docs/hosted-operations-evidence.md

@@ -10,6 +10,14 @@ Recorded on 2026-05-25 from the deployed Cloudflare Worker plus the earlier temp
 
 | Check | Evidence | Result |
 | --- | --- | --- |
+| Cloudflare Worker health, v0.40.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, routes including `/github/app/install-info`, `checkRunPublisher: "configured"`, `scannerVersion: "0.40.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
+| Public install guidance, v0.40.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info` returned the `ai-saas-guard-hosted` install URL, selected-repository boundary wording, first-slice permissions `checks: write`, `contents: read`, `metadata: read`, `pull_requests: read`, subscribed events `pull_request`, `installation`, and `installation_repositories`, uninstall cleanup wording, `scannerVersion: "0.40.0"`, and no private keys, webhook secrets, installation tokens, source, diffs, or customer payloads | Passed |
+| Deployed Worker version, v0.40.0 | `wrangler deploy` uploaded 38.99 KiB / gzip 10.01 KiB and deployed version `47e90d1c-0d7b-455f-b1a4-1ec7ee10d58b` at `2026-05-25T12:47:28Z` verification time | Passed |
+| Real hosted PR smoke, v0.40.0 | `node scripts/hosted-pr-smoke.mjs --evidence-file /tmp/ai-saas-guard-hosted-smoke-v0.40.json` opened temporary PR `#85`, waited for Check Run `77714061842` on head SHA `e312073d12dffdca3358edfce17869adac48d7f4`, received conclusion `success`, closed the PR, restored the original branch, deleted the local branch, and deleted 4 staging KV records with `remainingSmokeKeys: 0`; `gh pr view 85` returned `state: "CLOSED"`, `git ls-remote --heads origin codex/hosted-smoke-20260525124817` returned no remote branch, and `wrangler kv key list --namespace-id fa5344fbd7944de6a776bf8731d58460 --remote` returned `[]` after cleanup | Passed |
+| Cloudflare Worker health, v0.39.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, routes including `/github/app/install-info`, `checkRunPublisher: "configured"`, `scannerVersion: "0.39.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
+| Public install guidance, v0.39.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info` returned the `ai-saas-guard-hosted` install URL, selected-repository boundary wording, first-slice permissions `checks: write`, `contents: read`, `metadata: read`, `pull_requests: read`, subscribed events `pull_request`, `installation`, and `installation_repositories`, uninstall cleanup wording, `scannerVersion: "0.39.0"`, and no private keys, webhook secrets, installation tokens, source, diffs, or customer payloads | Passed |
+| Deployed Worker version, v0.39.0 | `wrangler deploy` uploaded 36.25 KiB / gzip 9.26 KiB and deployed version `91aebf30-4c25-4639-bf5c-6f8be4e85690` at `2026-05-25T12:26:24Z` verification time | Passed |
+| Real hosted PR smoke, v0.39.0 | `node scripts/hosted-pr-smoke.mjs` opened temporary PR `#82`, waited for Check Run `77711358510` on head SHA `64fa25f631a78131b19ee33094c9469736f151dc`, received conclusion `success`, closed the PR, deleted branch `codex/hosted-smoke-20260525122732`, and `wrangler kv key list --namespace-id fa5344fbd7944de6a776bf8731d58460 --remote` returned `[]` after cleanup | Passed |
 | Cloudflare Worker health, v0.38.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/healthz` returned `ok: true`, routes including `/github/app/install-info`, `checkRunPublisher: "configured"`, `scannerVersion: "0.38.0"`, and all privacy flags set to false for raw payloads, PR text, source, diffs, secrets, customer payloads, checkout paths, and installation tokens | Passed |
 | Public install guidance, v0.38.0 | `GET https://ai-saas-guard-hosted.zr9959.workers.dev/github/app/install-info` returned the `ai-saas-guard-hosted` install URL, selected-repository boundary wording, first-slice permissions `checks: write`, `contents: read`, `metadata: read`, `pull_requests: read`, subscribed events `pull_request`, `installation`, and `installation_repositories`, uninstall cleanup wording, `scannerVersion: "0.38.0"`, and no private keys, webhook secrets, installation tokens, source, diffs, or customer payloads | Passed |
 | Deployed Worker version, v0.38.0 | `wrangler deploy` uploaded 36.35 KiB / gzip 9.30 KiB and deployed version `5999ccce-c64d-4f3f-96c9-b46cff5a2aed` at `2026-05-25T10:51:30Z` verification time | Passed |
@@ -66,3 +74,14 @@ npx wrangler kv key list --namespace-id fa5344fbd7944de6a776bf8731d58460 --remot
 Then open a temporary no-file-change PR, wait for an `ai-saas-guard PR risk` Check Run on the smoke commit, and close the PR plus delete the branch. After the smoke run, verify no temporary KV records remain unless a retained compact report is intentionally part of that test.
 
 Do not leave smoke PRs, scratch branches, package tarballs, SARIF files, or test KV records behind.
+
+The executable path for this procedure is:
+
+```bash
+node scripts/hosted-pr-smoke.mjs --plan
+node scripts/hosted-pr-smoke.mjs --evidence-file /tmp/ai-saas-guard-hosted-smoke.json
+```
+
+The script is the preferred release-gate evidence path for the current Cloudflare hosted ingress. It creates a temporary `codex/hosted-smoke-*` branch and PR, waits for the hosted `ai-saas-guard PR risk` Check Run, records only public-safe Check Run metadata plus cleanup status, closes the PR, deletes the branch, restores the local branch, and bulk-deletes staging KV `delivery:` and `scan:` records. It refuses to target repositories outside `zr9959/ai-saas-guard` and does not print source, diffs, secrets, installation tokens, customer payloads, or checkout paths.
+
+The script also refuses to run against a dirty working tree, queries the trusted head SHA Check Run through `gh api --method GET`, writes an optional `--evidence-file` JSON record with mode `0600`, and attempts remote branch deletion even if PR creation or Check Run polling fails. That makes it suitable for release evidence because failure paths still exercise cleanup instead of leaving smoke resources behind.

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.38.0`
+- Current published version: `0.40.0`
 - Next source candidate: none
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.38.0`
+- GitHub Release: `v0.40.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -18,7 +18,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.38.0`.
+1. Create and review a release tag such as `v0.40.0`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/hosted/cloudflare-worker/README.md

@@ -23,7 +23,7 @@ This Worker is a real hosted ingress with first-slice Check Run publishing code,
 - `HOSTED_EVENTS`: Cloudflare KV namespace for compact delivery and queued scan records.
 - `WEBHOOK_SECRET`: Worker secret matching the GitHub App webhook secret.
 - `GITHUB_APP_PRIVATE_KEY`: Worker secret for the staging GitHub App private key, used only in memory to sign short-lived GitHub App JWTs.
-- `SCANNER_VERSION`: public version string, currently `0.38.0`.
+- `SCANNER_VERSION`: public version string, currently `0.40.0`.
 - `GITHUB_APP_ID`, `GITHUB_APP_SLUG`, `GITHUB_APP_INSTALLATION_ID`: public staging identifiers for the private GitHub App installation.
 
 ## Deployment
@@ -68,6 +68,7 @@ Do not add raw app private keys, webhook secrets, installation tokens, source, d
 The Check Run is intentionally compact. It should answer:
 
 - What changed at a launch-risk boundary?
+- Which risk areas are involved: auth/session, billing/entitlement, tenant data, deploy/permissions, API contract, or tests/silent success?
 - Which files are in the Review queue?
 - What Manual proof should block merge until it passes?
 - What selected-repository permissions did the hosted check use?
@@ -84,6 +85,26 @@ The Worker handles signed GitHub cleanup events, including installation deletion
 
 Delivery audit records may remain for the normal KV TTL. They must not contain source, diffs, secrets, customer payloads, PR-authored text, checkout paths, or installation tokens.
 
+## Real PR Smoke Automation
+
+Use the repository smoke runner before each hosted release:
+
+```bash
+node scripts/hosted-pr-smoke.mjs --plan
+node scripts/hosted-pr-smoke.mjs --evidence-file /tmp/ai-saas-guard-hosted-smoke.json
+```
+
+The real run is intentionally narrow:
+
+- creates a temporary branch named `codex/hosted-smoke-<timestamp>`
+- commits one public smoke marker file with no secrets or source excerpts
+- opens a temporary PR against `zr9959/ai-saas-guard`
+- waits for the `ai-saas-guard PR risk` Check Run on the trusted head SHA
+- records only the Check Run conclusion, URL, safe output title, and cleanup status
+- closes the PR, deletes the branch, restores the local branch, and clears staging KV `delivery:` and `scan:` records with `wrangler kv bulk delete`
+
+The script refuses to run against another repository, requires HTTPS Worker URLs, and keeps the local CLI path available even if hosted smoke fails.
+
 ## Release Boundary
 
 Do not expose this as the full product. The hosted operational release gate still requires deployed evidence for Check Run publication, worker cleanup, monitoring, rollback, incident response, dependency and deployment artifact scanning, and GitHub App installation behavior.

package/hosted/cloudflare-worker/src/index.js

@@ -820,13 +820,16 @@ function summarizeFindings(findings) {
 }
 
 function renderCheckRunSummary({ identity, report, scannerVersion }) {
+  const riskAreas = summarizeHostedRiskAreas(report.topRiskyFiles);
   const lines = [
-    `Launch-risk gate: ai-saas-guard found ${report.summary.total} PR risk signal(s) for ${identity.repositoryFullName}#${identity.pullRequestNumber}. Review first: inspect the listed trust-boundary files before merge.`,
+    `Launch-risk gate: ai-saas-guard found ${report.summary.total} PR risk signal(s) for ${identity.repositoryFullName}#${identity.pullRequestNumber}.`,
     `Scanner version: ${scannerVersion}.`,
     "",
-    "Selected-repository hosted check: this App uses checks:write, contents:read, pull_requests:read, and metadata:read for the installed repository only.",
+    "Review task: inspect the files below before merge.",
+    "Manual proof: prove changed auth, billing, data, deploy, or tests fail closed.",
+    "Boundary: selected repository only; not an AI reviewer, pentest, full audit, or certification.",
     "",
-    "This is not an AI reviewer, pentest, certification, or full security audit. Review the listed files before merge.",
+    "Selected-repository hosted check: this App uses checks:write, contents:read, pull_requests:read, and metadata:read for the installed repository only.",
     "",
     "Launch decision queue:",
     "- Can a real user get access they should not have?",
@@ -837,11 +840,21 @@ function renderCheckRunSummary({ identity, report, scannerVersion }) {
   ];
 
   if (report.topRiskyFiles.length > 0) {
+    lines.push("", "Risk areas:");
+    for (const area of riskAreas.slice(0, 5)) {
+      lines.push(`- ${area.name}: ${area.count} file(s). Proof: ${area.proof}`);
+    }
     lines.push("", "Review queue:");
     for (const file of report.topRiskyFiles.slice(0, 5)) {
       lines.push(`- ${file.path}: ${file.categories.join(", ")} (${file.added}+/${file.removed}-)`);
     }
-    lines.push("", "Manual proof:", "- Review the listed files locally and prove auth, billing, data, deploy, or test changes fail closed before merge.");
+    lines.push(
+      "",
+      "Reviewer checklist:",
+      "- What trust boundary changed?",
+      "- Why is this auth, billing, data, deploy, or test decision safe?",
+      "- What manual proof shows it fails closed?"
+    );
   }
 
   if (report.truncated) {
@@ -851,6 +864,81 @@ function renderCheckRunSummary({ identity, report, scannerVersion }) {
   return lines.join("\n").slice(0, 6_000);
 }
 
+function summarizeHostedRiskAreas(files) {
+  const counts = new Map();
+  for (const file of files) {
+    for (const category of file.categories) {
+      const area = hostedRiskAreaForCategory(category);
+      counts.set(area.key, {
+        ...area,
+        count: (counts.get(area.key)?.count ?? 0) + 1
+      });
+    }
+  }
+
+  return [...counts.values()].sort((a, b) => {
+    if (b.weight !== a.weight) return b.weight - a.weight;
+    return b.count - a.count;
+  });
+}
+
+function hostedRiskAreaForCategory(category) {
+  if (category === "auth/session") {
+    return {
+      key: "auth",
+      name: "Auth and session",
+      weight: 50,
+      proof: "use two accounts and confirm access, session, and ownership checks fail closed"
+    };
+  }
+  if (category === "billing/subscription") {
+    return {
+      key: "billing",
+      name: "Billing and entitlement",
+      weight: 50,
+      proof: "force unsigned, duplicate, failed, and canceled billing events before granting access"
+    };
+  }
+  if (category === "database schema/migration" || category === "RLS/policy") {
+    return {
+      key: "data",
+      name: "Tenant data access",
+      weight: 45,
+      proof: "run cross-tenant SELECT, INSERT, UPDATE, and DELETE checks with user A and user B"
+    };
+  }
+  if (category === "env/secrets/deploy" || category === "permissions/storage") {
+    return {
+      key: "deploy",
+      name: "Deploy, secrets, and permissions",
+      weight: 35,
+      proof: "confirm production env, workflow permissions, and storage scopes are least privilege"
+    };
+  }
+  if (category === "tests removed or weakened") {
+    return {
+      key: "tests",
+      name: "Tests and silent success",
+      weight: 40,
+      proof: "make the upstream path fail and confirm tests catch an error instead of fake success"
+    };
+  }
+  if (category === "API contract") {
+    return {
+      key: "api",
+      name: "API contract",
+      weight: 30,
+      proof: "exercise invalid, unauthorized, and failed upstream requests against changed routes"
+    };
+  }
+  return {
+    key: "large-diff",
+    name: "Large AI diff",
+    weight: 20,
+    proof: "split unrelated UI, refactor, and trust-boundary changes before review"
+  };
+}
+
 async function createGitHubAppJwt({ appId, privateKeyPem }) {
   if (!appId || !privateKeyPem) throw createGitHubApiError("jwt", "missing_config");
 

package/hosted/cloudflare-worker/wrangler.jsonc

@@ -7,7 +7,7 @@
     "enabled": true
   },
   "vars": {
-    "SCANNER_VERSION": "0.38.0",
+    "SCANNER_VERSION": "0.40.0",
     "GITHUB_APP_ID": "3834787",
     "GITHUB_APP_SLUG": "ai-saas-guard-hosted",
     "GITHUB_APP_INSTALLATION_ID": "135085075"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Local-first CLI that catches launch blockers in AI-built Next.js/Supabase/Stripe SaaS apps.",
   "readmeFilename": "README.md",
   "type": "module",
@@ -100,6 +100,7 @@
     "dist",
     "examples",
     "hosted",
+    "scripts",
     "README.md"
   ],
   "license": "MIT",

package/scripts/hosted-pr-smoke.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULTS = {
+  repo: "zr9959/ai-saas-guard",
+  base: "main",
+  branchPrefix: "codex/hosted-smoke",
+  checkName: "ai-saas-guard PR risk",
+  workerUrl: "https://ai-saas-guard-hosted.zr9959.workers.dev",
+  kvNamespaceId: "fa5344fbd7944de6a776bf8731d58460",
+  waitSeconds: 180
+};
+
+const args = parseArgs(process.argv.slice(2));
+const options = {
+  ...DEFAULTS,
+  ...args
+};
+
+if (options.help) {
+  printHelp();
+  process.exit(0);
+}
+
+const plan = createPlan(options);
+
+if (options.plan) {
+  console.log(JSON.stringify(plan, null, 2));
+  process.exit(0);
+}
+
+await runSmoke(plan);
+
+function parseArgs(argv) {
+  const parsed = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--plan") parsed.plan = true;
+    else if (arg === "--help" || arg === "-h") parsed.help = true;
+    else if (arg.startsWith("--repo=")) parsed.repo = arg.slice("--repo=".length);
+    else if (arg === "--repo") parsed.repo = argv[++index];
+    else if (arg.startsWith("--base=")) parsed.base = arg.slice("--base=".length);
+    else if (arg === "--base") parsed.base = argv[++index];
+    else if (arg.startsWith("--worker-url=")) parsed.workerUrl = arg.slice("--worker-url=".length);
+    else if (arg === "--worker-url") parsed.workerUrl = argv[++index];
+    else if (arg.startsWith("--kv-namespace-id=")) parsed.kvNamespaceId = arg.slice("--kv-namespace-id=".length);
+    else if (arg === "--kv-namespace-id") parsed.kvNamespaceId = argv[++index];
+    else if (arg.startsWith("--wait-seconds=")) parsed.waitSeconds = Number(arg.slice("--wait-seconds=".length));
+    else if (arg === "--wait-seconds") parsed.waitSeconds = Number(argv[++index]);
+    else if (arg.startsWith("--evidence-file=")) parsed.evidenceFile = arg.slice("--evidence-file=".length);
+    else if (arg === "--evidence-file") parsed.evidenceFile = argv[++index];
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  return parsed;
+}
+
+function createPlan(input) {
+  validateSafeInput(input);
+  const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  const branch = `${input.branchPrefix}-${stamp}`;
+
+  return {
+    repo: input.repo,
+    base: input.base,
+    branch,
+    checkName: input.checkName,
+    workerUrl: input.workerUrl,
+    installInfoUrl: `${input.workerUrl.replace(/\/+$/g, "")}/github/app/install-info`,
+    healthUrl: `${input.workerUrl.replace(/\/+$/g, "")}/healthz`,
+    kvNamespaceId: input.kvNamespaceId,
+    evidenceFile: input.evidenceFile,
+    waitSeconds: input.waitSeconds,
+    privacy: {
+      writesSourceToLogs: false,
+      writesTokensToLogs: false,
+      uploadsLocalSource: false,
+      deletesTemporaryBranch: true,
+      closesTemporaryPullRequest: true,
+      clearsHostedKvSmokeRecords: true
+    },
+    steps: [
+      "Verify hosted /healthz and /github/app/install-info.",
+      "Create a temporary branch from the base branch.",
+      "Commit one public smoke marker file with no secrets or source excerpts.",
+      "Push the temporary branch and open a draft-free pull request.",
+      "Wait for the hosted GitHub App Check Run on the trusted head SHA.",
+      "Record only Check Run conclusion, URL, and safe summary fields.",
+      "Close the temporary pull request, delete the remote branch, restore the local branch.",
+      "Bulk-delete staging KV delivery and scan records."
+    ]
+  };
+}
+
+function validateSafeInput(input) {
+  if (input.repo !== DEFAULTS.repo) {
+    throw new Error(`Refusing hosted smoke outside ${DEFAULTS.repo}`);
+  }
+  if (!/^[a-z0-9._-]+\/[a-z0-9._-]+$/i.test(input.repo)) {
+    throw new Error("Invalid GitHub repository name");
+  }
+  if (!/^[a-z0-9._/-]+$/i.test(input.base) || input.base.startsWith("-")) {
+    throw new Error("Invalid base branch");
+  }
+  if (!String(input.workerUrl).startsWith("https://")) {
+    throw new Error("Worker URL must be HTTPS");
+  }
+  if (!/^[a-f0-9]{32}$/i.test(input.kvNamespaceId)) {
+    throw new Error("KV namespace id must be a 32-character hex id");
+  }
+  if (!Number.isSafeInteger(input.waitSeconds) || input.waitSeconds < 30 || input.waitSeconds > 600) {
+    throw new Error("wait-seconds must be between 30 and 600");
+  }
+  if (input.evidenceFile !== undefined && (!input.evidenceFile || input.evidenceFile.startsWith("-") || input.evidenceFile.includes("\0"))) {
+    throw new Error("Invalid evidence file path");
+  }
+}
+
+async function runSmoke(plan) {
+  let originalBranch;
+  let prNumber;
+  let result;
+  let cleanup;
+
+  try {
+    await verifyHostedEndpoints(plan);
+    const status = (await git(["status", "--porcelain"])).trim();
+    if (status) {
+      throw new Error("Refusing hosted smoke with dirty working tree");
+    }
+    originalBranch = (await git(["branch", "--show-current"])).trim();
+    await git(["fetch", "origin", plan.base]);
+    await git(["switch", "-c", plan.branch, `origin/${plan.base}`]);
+    await writeFile(
+      ".github/ai-saas-guard-hosted-smoke.md",
+      `# ai-saas-guard hosted smoke\n\nTemporary hosted GitHub App smoke for ${new Date().toISOString()}.\n`
+    );
+    await git(["add", ".github/ai-saas-guard-hosted-smoke.md"]);
+    await git(["commit", "-m", "Run hosted GitHub App smoke"]);
+    await git(["push", "-u", "origin", plan.branch]);
+
+    const prUrl = (
+      await gh([
+        "pr",
+        "create",
+        "--repo",
+        plan.repo,
+        "--base",
+        plan.base,
+        "--head",
+        plan.branch,
+        "--title",
+        "Hosted GitHub App smoke",
+        "--body",
+        "Temporary hosted smoke PR. It should be closed and deleted by scripts/hosted-pr-smoke.mjs."
+      ])
+    ).trim();
+    prNumber = Number(prUrl.split("/").pop());
+    if (!Number.isSafeInteger(prNumber)) throw new Error(`Could not parse PR number from ${prUrl}`);
+
+    const headSha = (await git(["rev-parse", "HEAD"])).trim();
+    const checkRun = await waitForCheckRun({ ...plan, headSha });
+
+    result = {
+      ok: true,
+      generatedAt: new Date().toISOString(),
+      repo: plan.repo,
+      base: plan.base,
+      branch: plan.branch,
+      pullRequest: prNumber,
+      headSha,
+      checkRun,
+      privacy: plan.privacy
+    };
+  } finally {
+    cleanup = await cleanupSmoke({ plan, prNumber, originalBranch });
+  }
+
+  if (result) {
+    result.cleanup = cleanup;
+    await writeEvidence(plan, result);
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+async function verifyHostedEndpoints(plan) {
+  const health = JSON.parse(await curlJson(plan.healthUrl));
+  if (health.ok !== true || health.checkRunPublisher !== "configured") {
+    throw new Error("Hosted health is not ready for smoke");
+  }
+  const installInfo = JSON.parse(await curlJson(plan.installInfoUrl));
+  if (installInfo.ok !== true || installInfo.installUrl !== "https://github.com/apps/ai-saas-guard-hosted/installations/new") {
+    throw new Error("Hosted install-info is not ready for smoke");
+  }
+}
+
+async function waitForCheckRun(plan) {
+  const deadline = Date.now() + plan.waitSeconds * 1000;
+  while (Date.now() < deadline) {
+    const response = JSON.parse(
+      await gh([
+        "api",
+        "--method",
+        "GET",
+        `repos/${plan.repo}/commits/${plan.headSha}/check-runs`,
+        "-f",
+        `check_name=${plan.checkName}`
+      ])
+    );
+    const run = response.check_runs?.find((candidate) => candidate.name === plan.checkName);
+    if (run?.status === "completed") {
+      return {
+        id: run.id,
+        conclusion: run.conclusion,
+        htmlUrl: run.html_url,
+        title: run.output?.title
+      };
+    }
+    await sleep(5000);
+  }
+  throw new Error(`Timed out waiting for Check Run: ${plan.checkName}`);
+}
+
+async function cleanupSmoke({ plan, prNumber, originalBranch }) {
+  const cleanup = {
+    closedPullRequest: false,
+    deletedRemoteBranch: false,
+    restoredBranch: false,
+    deletedLocalBranch: false,
+    kv: { deletedKeys: 0, remainingSmokeKeys: 0 }
+  };
+  if (prNumber) {
+    cleanup.closedPullRequest = await ignoreFailure(gh(["pr", "close", String(prNumber), "--repo", plan.repo, "--delete-branch"]));
+  }
+  cleanup.deletedRemoteBranch = await ignoreFailure(git(["push", "origin", "--delete", plan.branch]));
+  if (originalBranch) {
+    cleanup.restoredBranch = await ignoreFailure(git(["switch", originalBranch]));
+  }
+  cleanup.deletedLocalBranch = await ignoreFailure(git(["branch", "-D", plan.branch]));
+  cleanup.kv = await clearHostedKv(plan);
+  return cleanup;
+}
+
+async function clearHostedKv(plan) {
+  const listJson = await wrangler(["kv", "key", "list", "--namespace-id", plan.kvNamespaceId, "--remote"]);
+  const keys = JSON.parse(listJson)
+    .map((item) => item.name)
+    .filter((name) => /^(delivery|scan):/.test(name));
+  if (keys.length === 0) return { deletedKeys: 0, remainingSmokeKeys: 0 };
+
+  const file = join(tmpdir(), `ai-saas-guard-hosted-kv-delete-${Date.now()}.json`);
+  await writeFile(file, JSON.stringify(keys, null, 2));
+  try {
+    await wrangler(["kv", "bulk", "delete", file, "--namespace-id", plan.kvNamespaceId, "--remote", "--force"]);
+  } finally {
+    await rm(file, { force: true });
+  }
+  const remainingJson = await wrangler(["kv", "key", "list", "--namespace-id", plan.kvNamespaceId, "--remote"]);
+  const remainingSmokeKeys = JSON.parse(remainingJson).filter((item) => /^(delivery|scan):/.test(item.name)).length;
+  return { deletedKeys: keys.length, remainingSmokeKeys };
+}
+
+async function writeEvidence(plan, result) {
+  if (!plan.evidenceFile) return;
+  await mkdir(dirname(plan.evidenceFile), { recursive: true });
+  await writeFile(plan.evidenceFile, `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
+}
+
+async function git(args) {
+  return run("git", args);
+}
+
+async function gh(args) {
+  return run("gh", args);
+}
+
+async function wrangler(args) {
+  return run("npx", ["wrangler", ...args], { cwd: "hosted/cloudflare-worker" });
+}
+
+async function curlJson(url) {
+  return run("curl", ["-fsSL", url]);
+}
+
+async function run(command, args, options = {}) {
+  const { stdout } = await execFileAsync(command, args, {
+    cwd: options.cwd ?? process.cwd(),
+    maxBuffer: 1024 * 1024
+  });
+  return stdout;
+}
+
+async function ignoreFailure(promise) {
+  try {
+    await promise;
+    return true;
+  } catch {
+    // Cleanup should continue through already-removed branches, PRs, or KV records.
+    return false;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function printHelp() {
+  console.log(`Usage: node scripts/hosted-pr-smoke.mjs [--plan] [--evidence-file <path>]\n\nRuns a real hosted GitHub App staging smoke against ${DEFAULTS.repo}.\nThe real run creates a temporary PR, waits for the hosted Check Run, closes the PR, deletes the branch, and clears staging KV smoke records.`);
+}