@vibecodr/cli 1.0.6 → 1.0.7

package/docs/SECURITY.md

@@ -1,13 +1,13 @@
-# vc-tools Security Notes
-
-`vc-tools` is a trust-boundary CLI. It validates local input before submitting
-requests to the hosted Vibecodr Tools API, but the hosted API remains the source
-of truth for auth, grants, quota, audit logging, retention, and Cloudflare
-credential custody.
-
-## Local Rules
-
-- Plain `vc-tools login` is the default human path. It starts a browser/device
+# Vibecodr CLI Security Notes
+
+The Vibecodr CLI is a trust-boundary tool. It validates local input before
+submitting requests to the hosted Vibecodr API, but the hosted API remains the
+source of truth for auth, grants, quota, audit logging, retention, and
+Cloudflare credential custody.
+
+## Local Rules
+
+- Plain `vibecodr login` is the default human path. It starts a browser/device
   approval session, prints a user-checkable code, optionally opens the Vibecodr
   approval page, and stores the durable credential returned to the polling CLI
   when the parent API issues one. The browser approval response must never
@@ -15,7 +15,7 @@ credential custody.
   device code.
 - Non-interactive credentials are preferably accepted through
   `--credential-file`, `--credential-stdin`, `VC_TOOLS_CREDENTIAL_FILE`, or
-  local credentials. The input may be an existing vc-tools grant, a Clerk OAuth
+  local credentials. The input may be an existing Vibecodr grant, a Clerk OAuth
   access token, or a scoped Clerk API key.
 - Clerk OAuth access tokens and scoped Clerk API keys are exchanged through
   Vibecodr Auth for short-lived scoped `vc-tools` grants. When supplied through
@@ -27,66 +27,66 @@ credential custody.
   file/stdin/native credential paths to avoid shell-history, process-list, and
   environment leakage.
 - The local auth SSOT is account-wide: one durable local credential plus a
-  cached short-lived grant. Direct vc-tools grants can still be cached, but they
+  cached short-lived grant. Direct Vibecodr grants can still be cached, but they
   are not refreshable and should be treated as advanced/temporary credentials.
 - Stored credentials use the native OS credential store by default through
   `@napi-rs/keyring`. The file-backed credential store is only for local
   automation and must be explicitly selected with `VC_TOOLS_CREDENTIAL_STORE=file`.
-- Authority-bearing tokens are redacted from stdout, stderr, JSON responses,
-  warnings, hosted provider error details, and API error details. Safe operator
-  handles and counters such as `artifactId`, `jobId`, `requestId`, `traceId`,
-  `tokenCount`, `totalTokens`, and `tokenKind` remain visible so operators can
-  debug without seeing reusable authority.
-- API URLs must use HTTPS. Local HTTP API URLs are denied unless the operator
-  explicitly passes `--allow-insecure-local-api` or sets
+- Authority-bearing tokens are redacted from stdout, stderr, JSON responses,
+  warnings, hosted provider error details, and API error details. Safe operator
+  handles and counters such as `artifactId`, `jobId`, `requestId`, `traceId`,
+  `tokenCount`, `totalTokens`, and `tokenKind` remain visible so operators can
+  debug without seeing reusable authority.
+- API URLs must use HTTPS. Local HTTP API URLs are denied unless the operator
+  explicitly passes `--allow-insecure-local-api` or sets
   `VC_TOOLS_ALLOW_INSECURE_LOCAL_API=true` for local development. This prevents a
   poisoned local config or environment variable from receiving a stored token.
-- Browser URLs must use HTTPS and must not target localhost, private IP ranges,
-  link-local ranges, multicast/unspecified ranges, internal hostnames, or URL
-  credentials. IPv6 loopback, unique-local, link-local, IPv4-mapped, NAT64, and
-  6to4 forms are denied before remote browser calls.
-- Sandbox commands are remote submissions only. The CLI never executes them
-  locally.
+- Browser URLs must use HTTPS and must not target localhost, private IP ranges,
+  link-local ranges, multicast/unspecified ranges, internal hostnames, or URL
+  credentials. IPv6 loopback, unique-local, link-local, IPv4-mapped, NAT64, and
+  6to4 forms are denied before remote browser calls.
+- Sandbox commands are remote submissions only. The CLI never executes them
+  locally.
 - Paid sandbox network access permits public HTTP(S) package/docs requests by
   default. Cloudflare host policy plus the hosted outbound handler block URL
   credentials, private/local/link-local/metadata/internal hosts, and hostnames
   resolving to those ranges.
-- Mutations require explicit confirmation flags.
-- `--quiet`, `--no-input`, and `--no-color` are accepted CLI convention flags;
-  the CLI does not prompt or emit color by default.
-- Artifact downloads must stay inside the current workspace unless a future
-  release adds an explicitly audited export mode. Users may target a directory
-  or an explicit file path inside the workspace, and `--filename` names the file
-  inside a directory output without weakening the workspace boundary.
-- Artifact downloads resolve existing output paths and nearest existing parents
-  through real paths so symlinked or junctioned directories cannot redirect a
-  pull outside the workspace.
-- Artifact uploads must also originate inside the current workspace.
-- Artifact upload size is enforced by the hosted service from the active plan
-  contract, not by a separate CLI hardcode.
-
-## Hosted Service Rules
-
-The API must enforce these before any cost-bearing Cloudflare work:
-
-- user authentication
-- browser/device vc-tools login sessions in the parent Vibecodr API, stored as
-  hashed device and user codes, single-use on redemption, and expired quickly
+- Mutations require explicit confirmation flags.
+- `--quiet`, `--no-input`, and `--no-color` are accepted CLI convention flags;
+  the CLI does not prompt or emit color by default.
+- Artifact downloads must stay inside the current workspace unless a future
+  release adds an explicitly audited export mode. Users may target a directory
+  or an explicit file path inside the workspace, and `--filename` names the file
+  inside a directory output without weakening the workspace boundary.
+- Artifact downloads resolve existing output paths and nearest existing parents
+  through real paths so symlinked or junctioned directories cannot redirect a
+  pull outside the workspace.
+- Artifact uploads must also originate inside the current workspace.
+- Artifact upload size is enforced by the hosted service from the active plan
+  contract, not by a separate CLI hardcode.
+
+## Hosted Service Rules
+
+The API must enforce these before any cost-bearing Cloudflare work:
+
+- user authentication
+- browser/device Vibecodr login sessions in the parent Vibecodr API, stored as
+  hashed device and user codes, single-use on redemption, and expired quickly
 - Clerk OAuth/API-key verification in the parent Vibecodr Auth API before any
   public user receives a `vc-tools` grant
-- scoped Vibecodr CLI grants with `vc-tools:use` plus a requested tool scope
-  such as `vc-tools:browser.render_url` or `vc-tools:*`, or an explicitly
-  configured static-token fallback for controlled deployments
-- vc-tools grant audience validation. Hosted Tools accepts only grants intended
-  for `vibecodr:vc-tools`, not broader Vibecodr CLI/API tokens.
-- actor-scoped job, artifact, usage, retention, and audit rows
-- authenticated hosted inspection and dashboard routes
-- workspace/project/user grant checks
-- plan entitlement checks
-- quota/spend checks
-- abuse/rate-limit checks
-- audit-log emission
-- retention policy classification
+- scoped Vibecodr CLI grants with `vc-tools:use` plus a requested tool scope
+  such as `vc-tools:browser.render_url` or `vc-tools:*`, or an explicitly
+  configured static-token fallback for controlled deployments
+- Grant audience validation. The hosted Vibecodr API accepts only grants
+  intended for `vibecodr:vc-tools`, not broader Vibecodr CLI/API tokens.
+- actor-scoped job, artifact, usage, retention, and audit rows
+- authenticated hosted inspection and dashboard routes
+- workspace/project/user grant checks
+- plan entitlement checks
+- quota/spend checks
+- abuse/rate-limit checks
+- audit-log emission
+- retention policy classification
 - Browser Run policy: initial URL, DNS address records, and bounded redirect
   chains must remain public HTTPS targets before cost-bearing dispatch and
   before the hosted Quick Action or Workflow-owned paid Browser Session request
@@ -94,19 +94,19 @@ The API must enforce these before any cost-bearing Cloudflare work:
   and 1 hour on Pro, closes after 10 minutes without meaningful action/artifact
   progress, and closes the browser in `finally` after storing a bounded artifact
   plus closure metadata in the job result and audit stream
-- Browser mode policy: public-web browsing is broad by default for public HTTPS
-  targets, while authenticated third-party sessions, private networks,
-  Vibecodr-owned infrastructure, and provider credentials remain isolated unless
-  a future explicit grant opens a narrow lane
-- Browser auth boundary: hosted browser calls reject cookies, credentials,
-  authorization headers, custom auth headers, storage state, sessions, or
-  secrets before provider execution
-- Browser Run crawl policy: bounded public crawls use the same URL/DNS guards,
-  plan page/depth caps, hosted artifact retention, and usage metering as other
-  browser tools
-- Browser Run provider-pressure policy: provider 429 responses return queued
-  jobs to a retry/defer state instead of exposing provider secrets or marking
-  the job failed on first rate-limit pressure
+- Browser mode policy: public-web browsing is broad by default for public HTTPS
+  targets, while authenticated third-party sessions, private networks,
+  Vibecodr-owned infrastructure, and provider credentials remain isolated unless
+  a future explicit grant opens a narrow lane
+- Browser auth boundary: hosted browser calls reject cookies, credentials,
+  authorization headers, custom auth headers, storage state, sessions, or
+  secrets before provider execution
+- Browser Run crawl policy: bounded public crawls use the same URL/DNS guards,
+  plan page/depth caps, hosted artifact retention, and usage metering as other
+  browser tools
+- Browser Run provider-pressure policy: provider 429 responses return queued
+  jobs to a retry/defer state instead of exposing provider secrets or marking
+  the job failed on first rate-limit pressure
 - Hosted capacity policy: Queue consumer concurrency, Workflow-owned Browser
   Agent execution, Browser Run account caps, Sandbox account caps, and Sandbox
   container `max_instances` are aligned to a 30-active-job launch ceiling so
@@ -115,9 +115,9 @@ The API must enforce these before any cost-bearing Cloudflare work:
   caps and Pro sandbox jobs route to `standard-2` containers with 30-minute task
   caps instead of the `lite` lane; both paid plans cap active sandbox tasks at 2
   per user
-- Sandbox quota policy: monthly sandbox seconds are reserved atomically before
-  queue insertion and reconciled when sandbox jobs are cancelled or reach a
-  terminal state
+- Sandbox quota policy: monthly sandbox seconds are reserved atomically before
+  queue insertion and reconciled when sandbox jobs are cancelled or reach a
+  terminal state
 - Sandbox egress policy: paid Agent Computer jobs can use public HTTP(S) egress
   for package installs and public docs. Private/local/link-local/metadata/
   internal CIDRs and host suffixes are denied by Cloudflare Sandbox host policy,
@@ -133,95 +133,95 @@ The API must enforce these before any cost-bearing Cloudflare work:
   queued-ahead counts without leaking payloads or adding a universal delay to
   interactive tools. Scheduled QA may still use bounded Cloudflare Queue
   per-message delays to spread due runs.
-- Queue completion policy: the consumer rechecks current D1 job state after
-  execution and cannot mark a job completed if cancellation was requested while
-  it was running
-- Retention policy: artifact retention is capped by the active plan, expired
-  artifacts are hidden from list/get/download paths, and a scheduled cleanup
-  removes expired R2 objects plus D1 metadata
-- Artifact storage policy: uploaded and generated artifacts are checked against
-  active actor storage before writes, D1 metadata insertion repeats the storage
-  predicate, and newly written R2 bytes are deleted if that metadata reservation
-  fails
-- Artifact deletion is actor-scoped and explicit: the hosted Worker deletes the
-  R2 object and D1 shelf row for the authenticated actor, and CLI deletion
-  requires `--yes`
-
-The CLI's validation is a usability and early-safety layer. It is not a
-replacement for hosted enforcement.
-
-## Open-Source Client Boundary
-
-The public `@vibecodr/vc-tools` package is a client/control-plane helper, not
-the quota or billing authority. Users can fork or edit the local CLI, local
-fallback plan constants, local help text, and local development API targets, but
-those edits do not change the official hosted service.
-
-Authoritative state remains hosted:
-
+- Queue completion policy: the consumer rechecks current D1 job state after
+  execution and cannot mark a job completed if cancellation was requested while
+  it was running
+- Retention policy: artifact retention is capped by the active plan, expired
+  artifacts are hidden from list/get/download paths, and a scheduled cleanup
+  removes expired R2 objects plus D1 metadata
+- Artifact storage policy: uploaded and generated artifacts are checked against
+  active actor storage before writes, D1 metadata insertion repeats the storage
+  predicate, and newly written R2 bytes are deleted if that metadata reservation
+  fails
+- Artifact deletion is actor-scoped and explicit: the hosted Worker deletes the
+  R2 object and D1 shelf row for the authenticated actor, and CLI deletion
+  requires `--yes`
+
+The CLI's validation is a usability and early-safety layer. It is not a
+replacement for hosted enforcement.
+
+## Open-Source Client Boundary
+
+The public `@vibecodr/cli` package is a client/control-plane helper, not the
+quota or billing authority. Users can fork or edit the local CLI, local
+fallback plan constants, local help text, and local development API targets, but
+those edits do not change the official hosted service.
+
+Authoritative state remains hosted:
+
 - Vibecodr Auth verifies Clerk OAuth/API-key inputs passed through the generic
   credential path and issues scoped `vc-tools` grants.
-- The hosted Tools API resolves the authenticated actor, plan, grants, and
-  server-side limits.
+- The hosted Vibecodr API resolves the authenticated actor, plan, grants, and
+  server-side limits.
 - `/v1/usage` and the `usage.read` MCP tool expose read-only hosted account
   state. In live mode the response is marked authoritative and
   `mutableByClient: false`. User-facing usage and readiness responses stay
   account-scoped: operator alert configuration, internal binding presence,
   provider account caps, hosted account pressure, ntfy/webhook topics, and raw
   actor ids belong only on operator-scoped endpoints.
-- `/v1/plans` and local fallback plan constants are packaging/reference data.
-  They are not authoritative for an actor's entitlement, usage, billing, quota,
-  or provider execution.
-- Cost-bearing Browser Run and Sandbox work is accepted only after hosted auth,
-  grant, plan, quota, audit, and reservation checks.
-
-If a user points `VC_TOOLS_API_URL` or `--api-url` at a forked service, that
-service can return different local display data. It is not Vibecodr Tools Cloud
-authority and cannot spend Vibecodr provider credentials or mutate official D1,
-R2, Queue, billing, grant, or usage state.
-
-## Remaining Hosted Proofs
-
-Local validation verifies the shipped control surface and contract behavior. A
-live production release must still produce fresh smoke evidence for:
-
-- deployed Worker secrets and routes
-- D1 migrations, including actor-scope columns
-- real Browser Run Quick Action execution with SSRF guards and metered-time
-  usage active
-- real Browser Run crawl execution with R2 artifact readback and crawl-page
-  usage active
+- `/v1/plans` and local fallback plan constants are packaging/reference data.
+  They are not authoritative for an actor's entitlement, usage, billing, quota,
+  or provider execution.
+- Cost-bearing Browser Run and Sandbox work is accepted only after hosted auth,
+  grant, plan, quota, audit, and reservation checks.
+
+If a user points `VC_TOOLS_API_URL` or `--api-url` at a forked service, that
+service can return different local display data. It is not the hosted Vibecodr
+authority and cannot spend Vibecodr provider credentials or mutate official D1,
+R2, Queue, billing, grant, or usage state.
+
+## Remaining Hosted Proofs
+
+Local validation verifies the shipped control surface and contract behavior. A
+live production release must still produce fresh smoke evidence for:
+
+- deployed Worker secrets and routes
+- D1 migrations, including actor-scope columns
+- real Browser Run Quick Action execution with SSRF guards and metered-time
+  usage active
+- real Browser Run crawl execution with R2 artifact readback and crawl-page
+  usage active
 - real Sandbox execution with public HTTP(S) egress and private/internal denial
-- real Pro `standard-2` Sandbox execution after the split lane is deployed
-- R2 artifact download scoped to the authenticated actor
-- usage/quota counters scoped to the authenticated actor
+- real Pro `standard-2` Sandbox execution after the split lane is deployed
+- R2 artifact download scoped to the authenticated actor
+- usage/quota counters scoped to the authenticated actor
 - audit rows written before cost-bearing Queue/Workflow dispatch
-
-## Secret Handling
-
-Do not add debug flags that print raw request headers, environment variables,
-stored credentials, Cloudflare tokens, OAuth tokens, or hosted API responses
-without redaction.
-
-Clerk server secrets and the ES256 `CLI_GRANT_PRIVATE_JWK` belong only in the
-parent Vibecodr API Worker secrets. The hosted Worker receives only
-`VC_TOOLS_CLI_GRANT_PUBLIC_JWKS` for normal vc-tools grants, plus
-`VC_TOOLS_TOKEN_SHA256`, `VC_TOOLS_INTERNAL_ALERT_TOKEN`, optional operator
-alert webhook/ntfy secrets, and Cloudflare provider credentials as hosted
-Worker secrets. Legacy HMAC grant secrets are beta/internal-only, require
-the explicit `*_LEGACY_HMAC_ENABLED="true"` switches on both parent and hosted
-surfaces, and should be removed by 2026-06-30 after live ES256 smoke and
-migration. None of those values belong in source, Wrangler plaintext vars, docs,
-tests, or package artifacts. Soft-cap operator alerts are account-wide capacity
-signals only and must remain metadata-only: surface, capability, plan name,
-current usage, included limit, percent used, and suggested action are allowed;
-raw commands, target URLs, bearer tokens, provider API tokens, actor
-identifiers, artifact contents, and user cookies are not. Per-user usage and
-quota pressure stays in usage/COGS/audit analytics without outbound operator
-notification fanout. D1 alert dedupe/reset-window rows may store capacity
-metadata details and suppression counts, but not user payload contents.
-
-The public npm artifact is a CLI/client package. Hosted Worker source,
-migrations, deployment configuration, repository-maintainer docs, and
-Cloudflare platform primitive packages must not be shipped as public CLI
-runtime surface.
+
+## Secret Handling
+
+Do not add debug flags that print raw request headers, environment variables,
+stored credentials, Cloudflare tokens, OAuth tokens, or hosted API responses
+without redaction.
+
+Clerk server secrets and the ES256 `CLI_GRANT_PRIVATE_JWK` belong only in the
+parent Vibecodr API Worker secrets. The hosted Worker receives only
+`VC_TOOLS_CLI_GRANT_PUBLIC_JWKS` for normal Vibecodr grants, plus
+`VC_TOOLS_TOKEN_SHA256`, `VC_TOOLS_INTERNAL_ALERT_TOKEN`, optional operator
+alert webhook/ntfy secrets, and Cloudflare provider credentials as hosted
+Worker secrets. Legacy HMAC grant secrets are beta/internal-only, require
+the explicit `*_LEGACY_HMAC_ENABLED="true"` switches on both parent and hosted
+surfaces, and should be removed by 2026-06-30 after live ES256 smoke and
+migration. None of those values belong in source, Wrangler plaintext vars, docs,
+tests, or package artifacts. Soft-cap operator alerts are account-wide capacity
+signals only and must remain metadata-only: surface, capability, plan name,
+current usage, included limit, percent used, and suggested action are allowed;
+raw commands, target URLs, bearer tokens, provider API tokens, actor
+identifiers, artifact contents, and user cookies are not. Per-user usage and
+quota pressure stays in usage/COGS/audit analytics without outbound operator
+notification fanout. D1 alert dedupe/reset-window rows may store capacity
+metadata details and suppression counts, but not user payload contents.
+
+The public npm artifact is a CLI/client package. Hosted Worker source,
+migrations, deployment configuration, repository-maintainer docs, and
+Cloudflare platform primitive packages must not be shipped as public CLI
+runtime surface.

package/docs/VALIDATION-MATRIX.md

@@ -1,28 +1,28 @@
-# vc-tools Validation Matrix
-
-This file maps `goal.md` and the `vc-tools-goal.md` product requirements to concrete CLI
-artifacts and tests.
-
-| Goal requirement | CLI artifact | Validation |
-| --- | --- | --- |
-| Separate tool from Vibecodr CLI | package `@vibecodr/vc-tools`, bin `vc-tools`, `VC_TOOLS_*` env namespace | `test/cli.behavior.test.ts` verifies help/version identity |
+# Vibecodr CLI Validation Matrix
+
+This file maps `goal.md` and the `vc-tools-goal.md` product requirements to concrete CLI
+artifacts and tests.
+
+| Goal requirement | CLI artifact | Validation |
+| --- | --- | --- |
+| Unified Vibecodr CLI surface | package `@vibecodr/cli`, canonical bin `vibecodr` with back-compat `vibecodr-mcp` and `vc-tools` bins, `VC_TOOLS_*` env namespace preserved for back-compat | `test/cli.behavior.test.ts` verifies help/version identity |
 | CLI Guidelines compliance | `src/cli/parser.ts`, `src/cli/run.ts`, `src/cli/output.ts`, `docs/CLI-GUIDELINES-AUDIT.md` | tests verify command-specific help, docs/support links, typo suggestions, stable JSON, product-safe default output, quiet mode, agent-computer primary nouns, and secure credential file/stdin sources |
-| Agent Computer first-use path | `vc-tools start`, `vc-tools setup`, `vc-tools try`, `vc-tools agent connect/status`, `vc-tools computer status` | tests verify `start` checks account identity, hosted health, MCP connection metadata, usage state, safe readiness output, and agent-native connection details without exposing tokens; `try` proves auth, hosted API, browser, computer, proof saving, and usage readback |
-| CLI login and auth diagnostics | `vc-tools login`, `vc-tools auth status`, `vc-tools auth diagnose`, `vc-tools auth export-agent-env`, safe generic credential file/stdin forms | tests verify browser/device auth starts when no credential is provided, `start` recovers from unreadable stored approval state by opening the normal browser login path, cost-bearing browser commands treat unreadable stored approval as missing auth instead of failing on credential storage shape, the private device code is never printed or stored, approval metadata points to `/settings/vc-tools/approve`, `--no-input` refuses interactive login without network calls, direct token grant caching, generic credential classification for Clerk OAuth/API-key exchange through Vibecodr Auth, durable API-key/OAuth local storage, expired grant refresh from stored API keys, file/stdin credential paths, one-off env credential auth without persistence, status reporting for active credential sources without exposing internal profiles, ambiguous credential denial, redaction, optional API verification, explicit file-store test mode, friendly expired-login errors, isolated config warnings, strict-permission agent credential-file export without printing the secret, and no stored-token forwarding to insecure local API URLs unless explicitly allowed |
-| Remote agent connection setup | `vc-tools agent connect`, advanced `vc-tools connect` | tests verify Streamable HTTP metadata, agent-native tool names, and no token leakage |
+| Agent Computer first-use path | `vibecodr start`, `vibecodr setup`, `vibecodr try`, `vibecodr agent connect/status`, `vibecodr computer status` | tests verify `start` checks account identity, hosted health, MCP connection metadata, usage state, safe readiness output, and agent-native connection details without exposing tokens; `try` proves auth, hosted API, browser, computer, proof saving, and usage readback |
+| CLI login and auth diagnostics | `vibecodr login`, `vibecodr auth status`, `vibecodr auth diagnose`, `vibecodr auth export-agent-env`, safe generic credential file/stdin forms | tests verify browser/device auth starts when no credential is provided, `start` recovers from unreadable stored approval state by opening the normal browser login path, cost-bearing browser commands treat unreadable stored approval as missing auth instead of failing on credential storage shape, the private device code is never printed or stored, approval metadata points to `/settings/vc-tools/approve`, `--no-input` refuses interactive login without network calls, direct token grant caching, generic credential classification for Clerk OAuth/API-key exchange through Vibecodr Auth, durable API-key/OAuth local storage, expired grant refresh from stored API keys, file/stdin credential paths, one-off env credential auth without persistence, status reporting for active credential sources without exposing internal profiles, ambiguous credential denial, redaction, optional API verification, explicit file-store test mode, friendly expired-login errors, isolated config warnings, strict-permission agent credential-file export without printing the secret, and no stored-token forwarding to insecure local API URLs unless explicitly allowed |
+| Remote agent connection setup | `vibecodr agent connect`, advanced `vibecodr connect` | tests verify Streamable HTTP metadata, agent-native tool names, and no token leakage |
 | Remote MCP tool server | `/mcp` in `src/hosted/worker.ts` | tests verify MCP `initialize`, `tools/list`, and `tools/call` JSON-RPC contract flow with agent-native `browser.*`, `computer.*`, `work.*`, `proof.*`, and `usage.status` tool names mapped to hosted canonical capabilities |
-| Browser render/screenshot/markdown/PDF tests, crawl, snapshot, and paid agent tasks | `vc-tools browser *`, advanced `vc-tools tools test browser.*` | tests verify capability aliases including `browser.snapshot`, canonical browser and crawl payloads, default submit/wait behavior, `--out` proof saving without exposed IDs, Creator `browser.agent_task` acceptance up to 20 minutes, Pro acceptance up to 1 hour, Free denial, Quick Actions staying short, HTTPS-only validation, localhost/private/internal denial with safe-next-action messaging, URL credential denial, direct cookie/header/storage-state auth material denial, IPv4/IPv6 private, link-local, mapped, NAT64, and 6to4 denial, hosted unsafe redirect-chain denial before cost-bearing dispatch, and Workflow dispatch for paid browser agent tasks |
-| Agent Computer run/tests | `vc-tools computer run/test`, advanced `vc-tools tools test sandbox.*`, hosted Sandbox SDK queue execution | tests verify no local shell execution, bounded command payload, default submit/wait behavior, `--out` proof saving without exposed IDs, public HTTP(S) package/docs egress by default for paid Agent Computer jobs, explicit `--network public`/`--network off` payloads, no private-network opt-in flag, no per-command host allowlist requirement, Cloudflare host policy plus hosted outbound handler denial for private/local/internal destinations and private-resolving DNS, per-command Sandbox SDK timeout forwarding, timeout/fork-storm failure cleanup through sandbox teardown, minimal sandbox env injection, stdout/stderr truncation, sandbox-returned files/output-file paths ignored in favor of one fixed transcript artifact, artifact storage accounting, and sandbox-minute metering |
-| Proof store/read/save/delete | `vc-tools proof list/show/save/delete`, advanced `vc-tools artifacts list/get/pull/create/delete` | tests verify metadata shape, bounded list limits, safe filenames, overwrite guard, explicit in-workspace pull file targets, automatic proof saving from browser/computer aliases and `work follow --out`, explicit confirmation before delete, actor-scoped hosted deletion of D1 shelf rows plus R2 bytes, hosted plan-owned upload caps, hard total artifact storage caps, R2 cleanup after D1 reservation races, workspace-bounded upload/download paths, and symlink/junction escape denial |
-| Work status/cancel/list | `vc-tools work list/show/follow/cancel`, advanced `vc-tools jobs list/status/cancel` | tests verify list limit propagation, ID validation, alias routing, real follow polling until terminal status, optional terminal proof saving, queued fairness-delay metadata in status output, and `--yes` on cancellation |
-| Usage quotas and limits | `vc-tools usage`, `vc-tools limits`, `usage.status`/`usage.read` MCP tools | tests verify stable JSON output, human quota bars, alias routing, warning preservation, and no operator-only alert/account-pressure metadata in user-facing usage payloads |
-| Open-source client authority boundary | `vc-tools plans`, `/v1/plans`, `/v1/usage`, `/v1/health`, `/v1/mcp/connection`, `usage.read`, docs/SECURITY.md | tests verify local plan fallback is marked non-authoritative, hosted plan packaging is not actor entitlement authority, usage snapshots are read-only/not client-mutable, default product JSON excludes internal/future/operator/provider/auth metadata, and internal/future launch metadata plus overage-meter details are actor/operator-scoped instead of global while keeping operator readiness on operator-scoped endpoints |
-| Account identity | `vc-tools whoami`, `/v1/me` | tests verify the standard whoami command reads hosted identity and prints account-first Agent Computer output plus redacted payload data, and hosted JSON omits synthetic `@vibecodr.local` email fallbacks |
-| Tool grants | `vc-tools grants`, `vc-tools grants list` | tests verify default list routing and scoped grant rendering |
-| Retention settings | `vc-tools retention show/set` | tests verify day bounds, plan-capped artifact retention, recordings policy, `--yes` on mutation |
-| Usage dashboard | `vc-tools dashboard [section]` | tests verify safe dashboard section URL generation without auth leakage and shared API URL validation |
-| Plan packaging | `vc-tools plans` | tests verify local fallback plan contract and hosted response handling |
-| Free/Creator/Pro plan limits | `DEFAULT_PLANS`, `OVERAGE_METERS` in `src/core/contracts.ts` | `test/limits.test.ts` verifies the exact Free, Creator, and Pro launch matrix: prices, monthly/daily VC Tool credits, browser seconds, Creator 20-minute and Pro 1-hour Browser Session caps, crawl caps, scheduled QA, Creator `standard-1`/10-minute sandbox lane, Pro `standard-2`/30-minute sandbox lane, shared paid 2-active-sandbox cap, per-upload artifact caps, artifact limits, and compatibility meters |
+| Browser render/screenshot/markdown/PDF tests, crawl, snapshot, and paid agent tasks | `vibecodr browser *`, advanced `vibecodr tools test browser.*` | tests verify capability aliases including `browser.snapshot`, canonical browser and crawl payloads, default submit/wait behavior, `--out` proof saving without exposed IDs, Creator `browser.agent_task` acceptance up to 20 minutes, Pro acceptance up to 1 hour, Free denial, Quick Actions staying short, HTTPS-only validation, localhost/private/internal denial with safe-next-action messaging, URL credential denial, direct cookie/header/storage-state auth material denial, IPv4/IPv6 private, link-local, mapped, NAT64, and 6to4 denial, hosted unsafe redirect-chain denial before cost-bearing dispatch, and Workflow dispatch for paid browser agent tasks |
+| Agent Computer run/tests | `vibecodr computer run/test`, advanced `vibecodr tools test sandbox.*`, hosted Sandbox SDK queue execution | tests verify no local shell execution, bounded command payload, default submit/wait behavior, `--out` proof saving without exposed IDs, public HTTP(S) package/docs egress by default for paid Agent Computer jobs, explicit `--network public`/`--network off` payloads, no private-network opt-in flag, no per-command host allowlist requirement, Cloudflare host policy plus hosted outbound handler denial for private/local/internal destinations and private-resolving DNS, per-command Sandbox SDK timeout forwarding, timeout/fork-storm failure cleanup through sandbox teardown, minimal sandbox env injection, stdout/stderr truncation, sandbox-returned files/output-file paths ignored in favor of one fixed transcript artifact, artifact storage accounting, and sandbox-minute metering |
+| Proof store/read/save/delete | `vibecodr proof list/show/save/delete`, advanced `vibecodr artifacts list/get/pull/create/delete` | tests verify metadata shape, bounded list limits, safe filenames, overwrite guard, explicit in-workspace pull file targets, automatic proof saving from browser/computer aliases and `work follow --out`, explicit confirmation before delete, actor-scoped hosted deletion of D1 shelf rows plus R2 bytes, hosted plan-owned upload caps, hard total artifact storage caps, R2 cleanup after D1 reservation races, workspace-bounded upload/download paths, and symlink/junction escape denial |
+| Work status/cancel/list | `vibecodr work list/show/follow/cancel`, advanced `vibecodr jobs list/status/cancel` | tests verify list limit propagation, ID validation, alias routing, real follow polling until terminal status, optional terminal proof saving, queued fairness-delay metadata in status output, and `--yes` on cancellation |
+| Usage quotas and limits | `vibecodr usage`, `vibecodr limits`, `usage.status`/`usage.read` MCP tools | tests verify stable JSON output, human quota bars, alias routing, warning preservation, and no operator-only alert/account-pressure metadata in user-facing usage payloads |
+| Open-source client authority boundary | `vibecodr plans`, `/v1/plans`, `/v1/usage`, `/v1/health`, `/v1/mcp/connection`, `usage.read`, docs/SECURITY.md | tests verify local plan fallback is marked non-authoritative, hosted plan packaging is not actor entitlement authority, usage snapshots are read-only/not client-mutable, default product JSON excludes internal/future/operator/provider/auth metadata, and internal/future launch metadata plus overage-meter details are actor/operator-scoped instead of global while keeping operator readiness on operator-scoped endpoints |
+| Account identity | `vibecodr whoami`, `/v1/me` | tests verify the standard whoami command reads hosted identity and prints account-first Agent Computer output plus redacted payload data, and hosted JSON omits synthetic `@vibecodr.local` email fallbacks |
+| Tool grants | `vibecodr grants`, `vibecodr grants list` | tests verify default list routing and scoped grant rendering |
+| Retention settings | `vibecodr retention show/set` | tests verify day bounds, plan-capped artifact retention, recordings policy, `--yes` on mutation |
+| Usage dashboard | `vibecodr dashboard [section]` | tests verify safe dashboard section URL generation without auth leakage and shared API URL validation |
+| Plan packaging | `vibecodr plans` | tests verify local fallback plan contract and hosted response handling |
+| Free/Creator/Pro plan limits | `DEFAULT_PLANS`, `OVERAGE_METERS` in `src/core/contracts.ts` | `test/limits.test.ts` verifies the exact Free, Creator, and Pro launch matrix: prices, monthly/daily VC Tool credits, browser seconds, Creator 20-minute and Pro 1-hour Browser Session caps, crawl caps, scheduled QA, Creator `standard-1`/10-minute sandbox lane, Pro `standard-2`/30-minute sandbox lane, shared paid 2-active-sandbox cap, per-upload artifact caps, artifact limits, and compatibility meters |
 | Separate ledgers | Parent `PLAN_LIMITS[*].builds`, parent `PLAN_LIMITS[*].vcTools`, hosted `enforceQuota` | tests verify build seconds reserve independently from VC Tool credits; hosted quota checks count browser and sandbox work against one VC Tools ledger before Queue/Workflow dispatch; hosted quota tests deny plan-specific active browser run caps for Free/Creator/Pro plus monthly credit, daily credit, browser-second, and sandbox-second exhaustion before cost-bearing dispatch; a parallel atomic reservation race test proves only one dispatch wins when two requests contend for the same reservation window |
 | Account-wide hosted capacity breakers | parent `VC_TOOLS_GLOBAL_LIMITS`, child hosted/Browser Run/Sandbox account cap vars and kill-switch vars, Workflow binding, queue `max_concurrency`, container `max_instances`, scheduled-only bounded per-message Queue delays, internal-api alert codes, D1 `operator_alert_dedupe`, `JOB_QUEUE.metrics()`, `JOB_DLQ.metrics()`, account-wide active artifact bytes, expired-artifact cleanup failure alert, execution-health failure/timeout alert, hosted Worker 5xx alert, auth failure anomaly alert, Cloudflare spend anomaly alert, and API contract docs | parent tests verify soft/hard cap policy and filter all user-scoped vc-tools payloads before fanout; hosted tests verify browser and sandbox jobs do not start above hard caps, repeat-actor jobs report queued-ahead metadata without delaying interactive Queue sends, Browser Agent jobs create `BROWSER_AGENT_WORKFLOW` instances instead of Queue messages, Queue consumers reject Browser Agent execution, hard caps are operator-configurable, `VC_TOOLS_PAUSE_COST_BEARING_JOBS` pauses all cost-bearing work before D1 job insertion or Queue/Workflow dispatch, `VC_TOOLS_DISABLE_BROWSER_RUN`, `VC_TOOLS_DISABLE_BROWSER_SESSIONS`, and `VC_TOOLS_DISABLE_SANDBOX` pause their lanes separately, 70/85/95 soft-cap crossings fan sanitized alerts to internal-api plus ntfy/webhook surfaces, duplicate crossings in the same reset window are suppressed, missing notifier bindings are audit-visible, scheduled Queue/DLQ/artifact-storage/retention-cleanup/execution-health/auth-failure/Cloudflare-spend alerts stay account-scoped without user fanout, unexpected hosted 500 alerts omit user/query/token data, and auth-failure metrics omit token/query material |
 | Dashboard sections | `DASHBOARD_SECTIONS` and `OPERATOR_DASHBOARD_SECTIONS` in `src/core/contracts.ts`, authenticated hosted `/dashboard/*` | tests verify unauthenticated dashboard access is denied, authenticated customer dashboard sections stay beta-safe without internal/future billing metadata, configured internal-metadata actors can still inspect that launch metadata, the CLI does not print the internal COGS URL, customer grants cannot read `/dashboard/cogs/`, and an explicit operator grant can read the internal COGS section |
@@ -30,29 +30,29 @@ artifacts and tests.
 | No raw provider credential exposure | hosted API boundary only; CLI stores Vibecodr account credentials, not Cloudflare/provider credentials | redaction tests verify authority-bearing token values are hidden while safe operator handles/counters stay visible; OAuth/API-key exchange tests verify durable local storage plus output redaction; docs contract |
 | All tool calls quota-checked and logged | API contract requires hosted enforcement; CLI submits through `/v1/tools/test` only | hosted tests verify quota lookup before Queue/Workflow dispatch, audit/job state before Queue send or Workflow create, quota-denial audit metrics, and unsafe-URL denial audit metrics without notification fanout |
 | Browser Run timeout mapping | `src/hosted/worker.ts` Quick Action payload builders and Browser Session navigation | hosted tests verify Quick Action `goToOptions.timeout` clamps to 60s, non-PDF Quick Actions stay on a minimal provider-compatible payload without top-level `actionTimeout`, PDF keeps its documented `pdfOptions.timeout`, dynamic public-page navigation uses Cloudflare's recommended `networkidle2` default instead of the stricter `networkidle0`, Browser Sessions launch with bounded `keep_alive`, and Browser Session large-page navigation timeout failures close the browser, mark the job failed, and do not write artifacts or browser-minute usage |
-| Browser Run crawl provider path | `browser.crawl_site`, hosted `/crawl` Quick Action integration | CLI tests verify `browser.crawl` payloads; hosted tests verify crawl start, result fetch, artifact storage, browser-minute usage, and crawl-page usage |
-| Browser Run provider retry/defer | `src/hosted/worker.ts` queue failure handling | hosted tests verify provider 429 responses return jobs to queued/retryable state and do not mark them failed on first rate-limit pressure |
+| Browser Run crawl provider path | `browser.crawl_site`, hosted `/crawl` Quick Action integration | CLI tests verify `browser.crawl` payloads; hosted tests verify crawl start, result fetch, artifact storage, browser-minute usage, and crawl-page usage |
+| Browser Run provider retry/defer | `src/hosted/worker.ts` queue failure handling | hosted tests verify provider 429 responses return jobs to queued/retryable state and do not mark them failed on first rate-limit pressure |
 | Human-use security hardening | CLI and hosted Worker trust-boundary controls | tests verify insecure local API opt-in, workspace-bounded artifacts including symlink/junction denial, scoped Vibecodr CLI grants with per-tool capability scopes, actor-scoped live job/artifact/usage/audit SQL, DNS address-record and redirect-chain enforcement with denial metrics, authenticated-browser material denial, Browser Run Quick Action routing and metered time, crawl metering, paid sandbox public HTTP(S) egress with private/local/internal denial, quota denial metrics, pre-execution and during-execution cancellation guards, hard artifact storage caps, D1/R2 artifact write cleanup, explicit artifact deletion cleanup, and retention-backed artifact expiry |
 | Hosted API/MCP scaffold | `src/hosted/worker.ts`, `wrangler.jsonc`, `migrations/0001_live_schema.sql`, `migrations/0002_actor_scope.sql`, `migrations/0003_quota_reservations.sql`, `migrations/0004_sandbox_quota_reservations.sql`, `migrations/0005_operator_alert_dedupe.sql`, `migrations/0006_scheduled_qa.sql`, `migrations/0007_job_queue_metadata.sql` | `npm run check:worker` and `test/hosted-worker.test.ts` verify health, auth fail-closed behavior, auth-failure audit metrics, user-safe public readiness, protected inspection/dashboard routes, scoped CLI grants, capability-scope denial, MCP metadata, MCP tool flow, dashboard contract, actor-scoped live acceptance, atomic quota reservation including sandbox seconds and parallel race conflict handling, queued-ahead metadata without interactive fairness delay, Workflow-owned paid agent browser dispatch without a Queue binding, Queue rejection for Browser Agent execution, Browser Run Quick Action hard-cap deferral, Browser Session hard-cap deferral, Sandbox hard-cap deferral, provider retry/defer handling, Browser Run large-page timeout bounds, failed-job DLQ retry-boundary behavior without provider re-execution, exhausted failed-job loop prevention, scheduled Queue/DLQ/artifact-storage/retention-cleanup/execution-health/auth-failure/Cloudflare-spend alerting, unexpected hosted 500 alerting, crawl artifacts, scheduled QA config/create/list/run-now enqueue/cron enqueue, sandbox execution timeout/env/output/teardown behavior, sandbox timeout/fork-storm failure cleanup, sandbox-returned file/path suppression, sandbox reservation reconciliation, unsafe redirect rejection before cost-bearing dispatch, D1-backed operator alert dedupe, and contract-mode tool acceptance |
 | Live Cloudflare provider | `src/hosted/worker.ts`, `wrangler.jsonc`, `Dockerfile`, `migrations/0001_live_schema.sql`, `migrations/0002_actor_scope.sql`, `migrations/0003_quota_reservations.sql`, `migrations/0004_sandbox_quota_reservations.sql`, `migrations/0005_operator_alert_dedupe.sql`, `migrations/0006_scheduled_qa.sql`, `migrations/0007_job_queue_metadata.sql` | hosted-required for live releases: apply all migrations, set Browser Run Quick Actions secrets and `BROWSER_AGENT_WORKFLOW`, deploy, then smoke health, authenticated login, real Quick Action browser job, real scheduled QA create/list/run-now enqueue/job-readback/monthly-cap denial plus natural cron-tick readback at a real trigger time, real Creator browser agent-task job through `BROWSER_AGENT_WORKFLOW`/`BROWSER`, real Pro browser agent-task job through `BROWSER_AGENT_WORKFLOW`/`BROWSER`, real crawl job, real Creator `standard-1` sandbox job capped at 10 minutes, real Pro `standard-2` sandbox job capped at 30 minutes, R2 artifact download, actor-scoped user-safe usage, crawl-page usage, sandbox-second quota denial, operator-alert dedupe/readback on operator surfaces, COGS dashboard readback, and audit rows against `https://tools.vibecodr.space` |
 | Cloudflare dynamic primitive fit | `docs/CLOUDFLARE-PRIMITIVE-FIT.md`, `docs/API-CONTRACT.md`, `wrangler.jsonc` | docs verify Cloudflare Workflows are the v1 durable `browser.agent_task` lane; Dynamic Workers/Facets/Dynamic Workflows remain future supervised dynamic-code capabilities, not replacements for v1 Browser Run Quick Actions, Sandbox SDK, D1, R2, Queue/DLQ, or platform-owned quota/audit/billing authority |
-| Production-grade packaging | build, typecheck, test, explicit npm exports, CLI-only runtime dependencies, pack verifier, CI | `npm run verify`; pack verifier rejects `docs/`, hosted Worker source, migrations, deployment config, tests, scripts, and Cloudflare primitive runtime dependencies from the public npm artifact |
-| Inspectable goal coverage | `vc-tools inspect`, `src/core/goal-coverage.ts`, `scripts/check-goal-coverage.mjs` | `npm run verify:goal` and `test/cli.behavior.test.ts` verify coverage output |
-
-## Completion Gate
-
-Before shipping:
-
-1. `npm run check`
-2. `npm run check:worker`
-3. `npm test`
-4. `npm run build`
-5. `npm run verify:artifact`
-6. `npm run verify:goal`
-7. Manual CLI smoke against a mock or real API
-8. Hosted service smoke against `https://tools.vibecodr.space`
-
-The CLI-contract release channel may ship with `live-hosted-production` marked
-`hosted-required`. A live release must clear that pending inspection with fresh
-production smoke evidence after any Worker binding, live tool execution,
-retention, quota, audit, queue, D1, R2, Browser Run, or Sandbox behavior change.
+| Production-grade packaging | build, typecheck, test, explicit npm exports, CLI-only runtime dependencies, pack verifier, CI | `npm run verify`; pack verifier rejects `docs/`, hosted Worker source, migrations, deployment config, tests, scripts, and Cloudflare primitive runtime dependencies from the public npm artifact |
+| Inspectable goal coverage | `vibecodr inspect`, `src/core/goal-coverage.ts`, `scripts/check-goal-coverage.mjs` | `npm run verify:goal` and `test/cli.behavior.test.ts` verify coverage output |
+
+## Completion Gate
+
+Before shipping:
+
+1. `npm run check`
+2. `npm run check:worker`
+3. `npm test`
+4. `npm run build`
+5. `npm run verify:artifact`
+6. `npm run verify:goal`
+7. Manual CLI smoke against a mock or real API
+8. Hosted service smoke against `https://tools.vibecodr.space`
+
+The CLI-contract release channel may ship with `live-hosted-production` marked
+`hosted-required`. A live release must clear that pending inspection with fresh
+production smoke evidence after any Worker binding, live tool execution,
+retention, quota, audit, queue, D1, R2, Browser Run, or Sandbox behavior change.