metergraph-cli 0.2.0-preview.5 → 0.2.0-preview.6

package/README.md

@@ -52,7 +52,7 @@ npx --yes metergraph-cli@next traces --limit 20   # one page of trace metadata
 ```
 
 To install it globally instead, run `npm install -g metergraph-cli@next`. The command is
-`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.0-preview.5`, when a
+`metergraph`. Pin an exact version, such as `metergraph-cli@0.2.0-preview.6`, when a
 script must not change with the `next` tag.
 
 ## Requirements
@@ -80,11 +80,11 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   network access:
 
   ```sh
-  npx --yes metergraph-cli@next skill install --client codex --runtime local
+  npx --yes metergraph-cli@next skill install --client codex
   ```
 
   Python users can run `pip install metergraph-skills` and
-  `metergraph-skills install --client codex --runtime local` instead
+  `metergraph-skills install --client codex` instead
   ([details](https://github.com/metergraph/cli/blob/main/python/metergraph-skills/README.md)).
   Both write the same files and recognise each other's installs.
 - **Model-swap skills.** `skills install` adds the workflow skills from
@@ -94,17 +94,26 @@ The CLI is built to be run by Codex, Claude Code and Cursor as well as by people
   the `metergraph/skills` plugin marketplace instead.
 
   ```sh
-  npx --yes metergraph-cli@next skills install --client claude --runtime local
+  npx --yes metergraph-cli@next skills install --client claude
   ```
 
+  `--runtime` defaults to `local`. Pass `--runtime cloud` when the client runs in a
+  cloud environment with a checkout of the project.
+
 - **Machine output.** Every command takes `--json` and then prints exactly one JSON
   line on stdout and nothing on stderr. All results share one envelope:
   `schema_version`, `command`, `ok`, `outcome`, `exit_code`, `data` and `error`.
   Failures carry a fixed `error.reason` and, where useful, a `data.next_action` that
   tells the agent what to do next.
 - **No hidden prompts.** No command reads stdin or asks a question. `--no-browser`
-  prints the sign in URL for a person to open instead of launching a browser; with
-  `--json`, a step that needs approval exits 6 with a `run_in_terminal` next action.
+  prints the sign in URL for a person to open instead of launching a browser. With
+  `--json`, a step that needs approval exits within seconds with 18
+  `action_required` and `data.next_action` set to
+  `{"kind": "open_url", "url": "...", "timeout_seconds": N, "message": "..."}`, so an
+  agent can show the URL to the person. A background process waits for the approval
+  until `--timeout-ms`; afterwards, run the same command again to continue from the
+  saved state
+  ([details](https://github.com/metergraph/cli/blob/main/docs/reference.md#approval-from-an-agent)).
 - **MCP.** Workspace tools for agents are served by the hosted MCP endpoint, not by this
   CLI. See the [MCP server guide](https://www.metergraph.dev/docs/guides/mcp-server/)
   and the [agent access guide](https://www.metergraph.dev/docs/guides/agent-access/).
@@ -141,7 +150,7 @@ writes, and full JSON examples.
 
 ## Exit codes
 
-Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 are not in
+Exit codes are stable. Changing one is a breaking change. Codes 10 to 18 are not in
 `0.1.0`.
 
 | Code | Outcome | Meaning |
@@ -152,7 +161,7 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 are not
 | 3 | `authentication_required` | Service is reachable, healthy and supported, and requires authentication. No workspace is connected. |
 | 4 | `connection_failed` | The origin could not be reached, the connection failed, or the probe timed out. For `verify`, the deadline expired before any valid answer arrived. A trace that is still pending is exit 11, not 4. |
 | 5 | `unhealthy` | The service answered but reported that it is not healthy, or answered with a server error. |
-| 6 | `unsupported` | The service answered with a response, deployment profile or status this CLI does not support, or the skill client or runtime cannot use project skill files, or sign in cannot run in this environment, or `--json --no-browser` needs a browser approval it cannot show (`no_browser_requires_terminal`). Nothing was written. |
+| 6 | `unsupported` | The service answered with a response, deployment profile or status this CLI does not support, or the skill client or runtime cannot use project skill files, or sign in cannot run in this environment. Nothing was written. |
 | 7 | `redirect_rejected` | The service answered with a redirect. Redirects are never followed. |
 | 8 | `conflict` | The skill target is not owned by this CLI, was modified, is unsafe, is locked or needs an explicit update, or the project is bound to a different origin or workspace. Nothing was changed. |
 | 9 | `filesystem_error` | Project or credential files could not be read or written. Partial changes were rolled back unless the message says otherwise. |
@@ -164,6 +173,7 @@ Exit codes are stable. Changing one is a breaking change. Codes 10 to 17 are not
 | 15 | `permission_denied` | The service refused this read for the signed in grant, for example for a missing scope or permission. |
 | 16 | `rate_limited` | The service asked the CLI to slow down. Nothing was retried. Try again later. |
 | 17 | `cancelled` | A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry. |
+| 18 | `action_required` | A person must act before the command can finish; `data.next_action` says what to do. `login` and `setup` with `--json --no-browser` exit with this as soon as an approval URL exists (`next_action.kind: "open_url"`), while a background process waits for the approval until `--timeout-ms`. After approval, run the same command again to continue. |
 
 ## Security and privacy
 
@@ -194,9 +204,11 @@ report. See [SECURITY.md](https://github.com/metergraph/cli/blob/main/SECURITY.m
 
 `--url ORIGIN` selects the service; the default is `https://app.metergraph.dev`. It
 accepts a bare `https://` origin, or `http://` on `localhost`, `127.0.0.1` or `[::1]`.
-`setup --deployment` supports the hosted service (`managed`), the commercial
-`customer-local` bundle, customer-owned cloud (`byoc`) and the open source server
-(`oss`). See [self-hosting](https://www.metergraph.dev/docs/self-host/local/) and the
+`setup --deployment` routes to the hosted service (`managed`), the commercial
+`customer-local` bundle, customer-owned cloud (`byoc`) or the open source server
+(`oss`). The hosted service and released customer-local bundle are the release
+targets; `byoc` and `oss` are not yet verified against a live deployment. See
+[self-hosting](https://www.metergraph.dev/docs/self-host/local/) and the
 [setup reference](https://github.com/metergraph/cli/blob/main/docs/reference.md#setup).
 
 ## Links

package/assets/skill/SKILL.md

@@ -36,6 +36,15 @@ package does not support. A CLI login or health probe alone does not prove
 application traffic. Verification needs an exact trace or request ID from an
 application invocation, its time window and the intended workspace.
 
+`login` and `setup` need the person to approve in a browser on this machine. If the
+installed CLI's help lists exit code 18 `action_required`, run them with
+`--json --no-browser`. When a step needs approval, the command exits 18 within
+seconds. Show `data.next_action.url` to the person and ask them to approve; a
+background process waits for the approval. After they approve, run the same command
+again. A new project takes three runs: sign in, ingest approval, then a final check.
+An older CLI exits 6 `no_browser_requires_terminal` instead. Then the person has to
+run setup in their own terminal.
+
 Repository identity is optional for capture but keeps traces attributable when
 several repositories share a workspace. If the installed CLI's `setup` help lists
 `--repository`, setup records `owner/name` from the git remote in a committed
@@ -68,7 +77,7 @@ For hosted Claude Desktop on an individual account, guide the human through Cust
 
 For a fresh hosted workspace, first ask whether the human already has a Metergraph account and workspace. Direct them to https://app.metergraph.dev/ and the signup, invitation or sign-in flow actually offered. The hosted UI can offer "Get a free API key" for self-service signup, but do not assume that button or a workspace invitation is available to everyone. If access is unavailable, direct them to their workspace owner or Metergraph. Confirm the workspace before creating a coding-agent key.
 
-For the commercial customer-local bundle, direct them to https://www.metergraph.dev/docs/self-host/local/#the-customer-local-bundle and the signed public release. They need a separate pull-only registry credential from Metergraph to pull the images; the public bundle download does not grant registry access. Verify the release before installation. Local admin credentials from the bundle's private configuration provide dashboard sign-in; create a coding-agent key in that installation's Keys page. Do not substitute hosted signup or a hosted key. Do not clone the private implementation or run development seed commands.
+For the commercial customer-local bundle, direct them to https://www.metergraph.dev/docs/self-host/local/#the-customer-local-bundle and the signed public release. They need a separate pull-only registry credential from Metergraph to pull the images; the public bundle download does not grant registry access. Verify the release before installation. Local admin credentials from the bundle's private configuration provide dashboard sign-in; create a coding-agent key in that installation's Keys page. Do not substitute hosted signup or a hosted key. Do not clone the private implementation or run development seed commands. Use `metergraph-local-bundle` to stand the bundle up when that skill is installed.
 
 For customer-owned AWS, direct them to https://www.metergraph.dev/docs/self-host/aws/. An operator provisions the installation, identity and membership. There is no public signup. Ask for the installation's actual reachable address and use a coding-agent key from its Keys page. Its default internal load balancer is private, and its Agent Access surface excludes trace content and replay.
 

package/assets/skill/manifest.json

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "92f7955f6f8761a20a1886ad81f22dfcee239afddf8e9f1e761c35eb8e70f218",
-  "size": 12980,
-  "revision": "sha256-92f7955f6f87"
+  "sha256": "e7fc4eb7a22eeb16c357bede9d0a080ad3b415aaab1d9c72f164d5350d48c4b1",
+  "size": 13664,
+  "revision": "sha256-e7fc4eb7a22e"
 }

package/assets/skills/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 1,
   "repository": "metergraph/skills",
-  "commit": "25a62e420589cb805e3dd7d9bb3e3a35d85e2ece",
+  "commit": "dda4d5f130448f12a7fb2549ed264503d8b51d8d",
   "skills": [
     {
       "name": "metergraph-analyze",
@@ -33,6 +33,12 @@
       "size": 3789,
       "revision": "sha256-9ce5a2cf527e"
     },
+    {
+      "name": "metergraph-local-bundle",
+      "sha256": "692cd8952a8a8896ec2c06091b329a7a01912e261e87d62a9458452172a7c9b0",
+      "size": 12245,
+      "revision": "sha256-692cd8952a8a"
+    },
     {
       "name": "metergraph-model-swap",
       "sha256": "d77ee37f882ab1e50dc4a093e64a2c3661f4cd9bb59f184da6dccbd76fd51a18",
@@ -41,9 +47,9 @@
     },
     {
       "name": "metergraph-onboarding",
-      "sha256": "15be9083f5b0d18cc6fe0d225f0921e2f16c5b4fb3d811c3984cef5cbc7941ba",
-      "size": 10208,
-      "revision": "sha256-15be9083f5b0"
+      "sha256": "6e6f418933f37b34437035ab3171344d43f37dee3770815b19f97efb62e5f1d1",
+      "size": 10267,
+      "revision": "sha256-6e6f418933f3"
     },
     {
       "name": "metergraph-report",

package/assets/skills/metergraph-local-bundle/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: metergraph-local-bundle
+description: Verify and start the signed Metergraph customer-local bundle on a person's own machine, preserve existing local data and secrets, then hand over to metergraph setup. Use when customer-local setup reports that the bundle_started_verified prerequisite is incomplete or when installing the commercial local bundle from a public release.
+---
+
+# Start the signed customer-local bundle
+
+Stand up the released bundle only on the person's own machine, then run
+`metergraph setup`. The CLI does not provision it, and
+`--confirm-prerequisites` records confirmation rather than installing anything.
+
+Keep registry, admin and database secrets out of chat, command arguments and
+output. Never read or print `.env` values, `~/.docker/config.json`,
+`docker compose config` output or container environment from `docker inspect`.
+Do not configure model-provider keys.
+
+## Stop in remote runtimes
+
+Before changing anything, determine where the agent executes. Check only
+whether these variables exist, never their values:
+
+```sh
+for name in SSH_CONNECTION SSH_CLIENT SSH_TTY CODESPACES GITPOD_WORKSPACE_ID CLOUD_SHELL CI; do
+  if printenv "$name" >/dev/null 2>&1; then printf '%s is set\n' "$name"; fi
+done
+```
+
+If any is set, or this is otherwise a hosted/cloud runtime, download, verify,
+extract and start nothing. Prefer an installed `metergraph` whose `--help`
+lists `setup`; otherwise state that the fallback fetches the preview CLI and
+use `npx --yes metergraph-cli@next` as the prefix. Run only:
+
+```sh
+metergraph setup --runtime cloud --deployment customer-local --url http://localhost:8080 --workspace 11111111-1111-4111-8111-111111111111 --skip-skill --json
+```
+
+Relay its `data.next_action.kind: "run_on_customer_machine"` handoff and tell
+the person to run this skill on their own machine. The placeholder workspace is
+intentional: the runtime check refuses before making a request or writing a
+file. When an SSH, cloud or CI marker is set, even `--runtime local` is refused
+with reason `run_on_local_machine` and the same handoff. Valid runtimes are
+`local`, `cloud` and `cloud-no-shell`. Never expose localhost to the remote
+session.
+
+## Preflight and reuse
+
+Ask for the coding client and bundle version. Default to the newest version at
+https://www.metergraph.dev/docs/releases/ and record its `v`-prefixed value.
+Record the application repository directory to return to for setup. Run:
+
+```sh
+docker info >/dev/null
+docker compose version
+cosign version
+curl -fsS http://localhost:8080/v1/deployment
+lsof -nP -iTCP:8080 -sTCP:LISTEN
+```
+
+Docker with Compose must be running and `cosign` installed. If the deployment
+endpoint returns the `local` profile, reuse that stack and download nothing.
+Find its bundle directory using only the Compose working-directory label:
+
+```sh
+container_id="$(docker ps --filter publish=8080 --format '{{.ID}}' | head -n 1)"
+bundle_dir="$(docker inspect --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}' "$container_id")"
+(cd "$bundle_dir" && ./bin/status)
+```
+
+Do not inspect container environment. Read the workspace ID from the
+`workspace` check and skip to **Run setup**. If the directory cannot be found,
+ask for the workspace ID from Settings. If nothing listens on 8080, continue.
+If anything else owns it, stop and ask; never stop or reconfigure it.
+
+Use `~/metergraph/<version>` and set
+`bundle_dir="$HOME/metergraph/$version/local"`. If it contains `.env`, reuse
+that existing installation: never overwrite, delete or read the file, and
+never extract over `local/`. Continue at **Log in and start**. Otherwise check:
+
+```sh
+docker volume inspect local_pgdata >/dev/null 2>&1
+```
+
+Because the extracted directory and Compose project are `local`, an existing
+volume is `local_pgdata`. If it exists without the matching `local/.env`, stop
+and ask for the prior bundle/configuration. Postgres fixed its password when
+the volume was created; a new `.env` can cause `password authentication failed`.
+Never remove the volume, delete `.env` or use `down --volumes`.
+
+## Download and verify
+
+Require a fresh, empty version directory. Before creating it, tell the person
+the directory and four public files that will be written. No account is needed.
+Set `version` to the recorded version and run:
+
+```sh
+release_dir="$HOME/metergraph/$version"; mkdir -p "$release_dir"; cd "$release_dir"
+archive="metergraph-customer-local-$version.tar.gz"
+base="https://www.metergraph.dev/releases/$version"
+curl -fsSLO "$base/$archive"
+curl -fsSLO "$base/metergraph-byoc-release.json"
+curl -fsSLO "$base/metergraph-byoc-release.json.sig"
+curl -fsSLO "$base/metergraph-byoc-release.json.pem"
+```
+
+Do not list, extract or run archive contents. Verify the manifest signature
+with exactly this command. The issuer and identity are pinned here, not read
+from the release page, so a changed download site cannot change who must have
+signed the release:
+
+```sh
+cosign verify-blob \
+  --certificate metergraph-byoc-release.json.pem \
+  --signature metergraph-byoc-release.json.sig \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-identity-regexp '^https://github\.com/PioneerSquareLabs/metergraph-internal/\.github/workflows/byoc-release\.yml@refs/(heads/main|tags/v.+)$' \
+  metergraph-byoc-release.json
+```
+
+Never loosen or drop the issuer or identity, and never add
+`--insecure-ignore-tlog` or a similar bypass. If the release page publishes a
+different identity, stop and tell the person rather than using it.
+
+If cosign fails, stop: "The manifest signature did not verify. Do not extract
+or run this bundle." After it succeeds, check signed fields:
+
+```sh
+python3 - "$version" "$archive" <<'EOF'
+import json, sys
+version, archive = sys.argv[1:]
+m = json.load(open("metergraph-byoc-release.json"))
+required = ("release", "local_bundle", "local_bundle_sha256",
+            "local_image_digest", "local_analysis_image_digest")
+missing = [key for key in required if not m.get(key)]
+if missing: sys.exit("Signed manifest is missing: " + ", ".join(missing))
+if m["release"] != version: sys.exit("Signed manifest release mismatch. Do not run it.")
+if m["local_bundle"] != archive: sys.exit("Signed archive name mismatch. Do not run it.")
+print("Signed manifest release, archive, and image digests are present.")
+EOF
+```
+
+Then run this digest check, still before any `tar` command:
+
+```sh
+python3 - <<'EOF'
+import hashlib, json, sys
+manifest = json.load(open("metergraph-byoc-release.json"))
+name = manifest["local_bundle"]
+actual = hashlib.sha256(open(name, "rb").read()).hexdigest()
+if actual != manifest["local_bundle_sha256"]:
+    sys.exit(f"{name} does not match the signed manifest. Do not run it.")
+print(f"{name} matches the signed manifest.")
+EOF
+```
+
+Stop on failure. After both checks pass, list and validate archive paths:
+
+```sh
+tar -tzf "$archive"
+python3 - "$archive" <<'EOF'
+from pathlib import PurePosixPath
+import sys, tarfile
+bad = []
+with tarfile.open(sys.argv[1], "r:gz") as bundle:
+    for member in bundle.getmembers():
+        path = PurePosixPath(member.name)
+        if path.is_absolute() or not path.parts or path.parts[0] != "local" or ".." in path.parts:
+            bad.append(member.name)
+if bad: sys.exit("Unsafe archive paths; do not extract: " + ", ".join(bad[:10]))
+print("Every archive entry is beneath local/ with a safe relative path.")
+EOF
+```
+
+Only now tell the person extraction will create `local/`, then run:
+
+```sh
+tar xzf "$archive"
+mv metergraph-byoc-release.json* local/
+cd local
+```
+
+## Configure without exposing passwords
+
+Reuse an existing `.env` unchanged. For a new installation, state that a
+mode-0600 file with random admin/database passwords and empty provider keys
+will be created. Confirm `local_pgdata` did not exist, then run:
+
+```sh
+umask 077; cp .env.example .env; chmod 600 .env
+python3 - <<'EOF'
+from pathlib import Path
+import secrets
+path = Path(".env")
+keys = ("METERGRAPH_LOCAL_ADMIN_PASSWORD", "METERGRAPH_DB_PASSWORD")
+values = {key: secrets.token_urlsafe(24) for key in keys}
+lines, found = path.read_text().splitlines(), set()
+for i, line in enumerate(lines):
+    for key in keys:
+        if line.startswith(key + "="):
+            lines[i], found = key + "=" + values[key], found | {key}
+if found != set(keys): raise SystemExit("Password keys missing from .env.example")
+path.write_text("\n".join(lines) + "\n")
+print("Set random values for: " + ", ".join(keys))
+EOF
+```
+
+Do not display, source or parse `.env`. Leave `AI_GATEWAY_API_KEY`,
+`FIREWORKS_API_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and `GOOGLE_API_KEY`
+empty.
+
+## Log in and start
+
+Stop for the person to log in to the registry in their own terminal. They use
+the pull-only invitation values, never chat or an agent-visible command:
+
+```sh
+echo "$METERGRAPH_PULL_TOKEN" | docker login ghcr.io -u "$METERGRAPH_PULL_USER" --password-stdin
+```
+
+Wait for confirmation only; never read Docker's credential file. State that
+`./bin/start` will re-verify the manifest and both image digests, pull by digest,
+start containers, and on a new database send one synthetic demo trace labeled
+`environment=local-demo`. Then run:
+
+```sh
+./bin/start
+./bin/status
+```
+
+An image-pull failure usually means login is missing or expired. On other
+failure, read only the log named by `./bin/start` and `./bin/status`; never read
+rendered Compose configuration or container environment. On password
+authentication failure with `local_pgdata`, stop and ask for its matching
+`.env`. Never delete data. Read the workspace ID and suggested command from the
+status JSON's `workspace` check. The service listens only on localhost:8080.
+
+## Run setup
+
+Return to the application repository. Prefer installed `metergraph` only when
+its help lists `setup`; otherwise state that `npx --yes metergraph-cli@next`
+fetches the preview CLI and use it as the prefix. Run with `--json`:
+
+```sh
+metergraph setup --runtime local --deployment customer-local --url http://localhost:8080 --workspace 11111111-1111-4111-8111-111111111111 --confirm-prerequisites --client <client> --json
+```
+
+Replace the example UUID and client only. Setup writes an ingest key to the
+application `.env`, installs the skill and requests Metadata access only; never
+print that file. Setup opens the deployment's browser consent page and waits;
+the person signs in as the local admin and completes two approvals. If the
+browser cannot open, follow the `metergraph` skill's guidance for handing the
+person the approval URL. Continue until `data.status` is `ok`. For
+`operator_handoff`, relay `data.next_action.kind` (`complete_prerequisite`,
+`run_on_customer_machine`, `connection_guide`, or other); never report a
+handoff as success.
+
+The agent never runs a command that reads `.env`. To see the admin login without
+printing it, the person runs these no-output pipelines themselves, one at a
+time, in their own terminal or in Claude Code with the `!` prefix. Fill in the
+absolute bundle directory for them; their shell does not have `bundle_dir`:
+
+```sh
+sed -n 's/^METERGRAPH_LOCAL_ADMIN_EMAIL=//p' ~/metergraph/<version>/local/.env | pbcopy
+sed -n 's/^METERGRAPH_LOCAL_ADMIN_PASSWORD=//p' ~/metergraph/<version>/local/.env | pbcopy
+```
+
+They may instead use their own editor. Never use `cat`, `grep` or any other
+command that prints `.env`, particularly with `!`, because `!` output lands in
+the transcript. A new configuration keeps `admin@example.com` as the email.
+
+## Recovery and stopping
+
+| State | Action |
+| --- | --- |
+| Signature, manifest, digest or path check fails | Stop; extract and run nothing |
+| Port 8080 belongs to something else | Stop and ask; do not alter it |
+| Registry pull is denied | Person repeats private login; never request the token |
+| Existing `.env` | Reuse unchanged; never regenerate passwords |
+| `local_pgdata` lacks its matching `.env` | Stop and find prior configuration; never remove it |
+| Startup fails | Use status and only the named log; preserve secrets and data |
+| Setup returns a handoff | Relay exact status/next action; do not report success |
+
+To stop later, follow the bundle README's `stop`. Prefer it over `down`, which
+loses raw payloads in local object storage. Never use `down --volumes`.

package/assets/skills/metergraph-onboarding/SKILL.md

@@ -34,8 +34,9 @@ skill installation; a later installed version may offer `login`, `setup` and
 https://www.metergraph.dev/docs/start/first-trace/ and its manual setup steps.
 Do not infer that a server endpoint or source-only CLI command has shipped.
 
-For customer-local MeterGraph, use the released bundle and its included
-README, signed manifest and verification files. The human obtains the current
+For customer-local MeterGraph, use `metergraph-local-bundle` to stand up the
+released bundle, then continue here. Use its included README, signed manifest
+and verification files. The human obtains the current
 pull-only registry credential; registry access is not yet universally self-serve.
 Use password-stdin and the local secret store for registry login. Verify the
 archive before running its scripts. Configure the bundle's local settings,

package/bin/metergraph.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
+import { handOff, handsOff } from "../src/approval-handoff.js";
 import { main } from "../src/cli.js";
 
 // A closed pipe on stdout (for example "metergraph --help | head -1") is not
 // a CLI failure.
 process.stdout.on("error", () => {});
 
-process.exitCode = await main(process.argv.slice(2), {
-  stdout: process.stdout,
-  stderr: process.stderr,
-});
+const argv = process.argv.slice(2);
+const io = { stdout: process.stdout, stderr: process.stderr };
+process.exitCode = handsOff(argv) ? await handOff(argv, io) : await main(argv, io);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.5",
+  "version": "0.2.0-preview.6",
   "description": "Preview Metergraph command line tool with a read-only connection probe, a project skill installer, Metadata-only sign in and bounded workspace Metadata reads",
   "type": "module",
   "bin": {

package/src/approval-handoff.js

@@ -0,0 +1,91 @@
+import childProcess from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import { parseArgs } from "./args.js";
+import { envelope, toJsonLine } from "./output.js";
+
+// login and setup with --json --no-browser may need a person to approve in a
+// browser. The approval returns to a loopback listener, so something must
+// keep listening after the agent has the URL. Agent shells usually show a
+// command's output only after it exits, so that cannot be this process.
+//
+// This process runs the same command as a detached waiter and relays the
+// waiter's one JSON line. When the line is action_required, it exits with it
+// at once and leaves the waiter listening until approval or --timeout-ms; the
+// waiter saves what the approval completes and prints nothing more. Any other
+// line is the command's result, and this process waits for the waiter to
+// finish. The arguments carry no credential, and the waiter's environment is
+// this one plus a marker.
+const BIN = fileURLToPath(new URL("../bin/metergraph.js", import.meta.url));
+const WAITER = "METERGRAPH_APPROVAL_WAITER";
+
+export function handsOff(argv, env = process.env) {
+  if (env[WAITER] === "1") return false;
+  const parsed = parseArgs(argv);
+  return parsed.ok && (parsed.command === "login" || parsed.command === "setup") && parsed.json && parsed.noBrowser;
+}
+
+export function handOff(argv, { stdout }) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = childProcess.spawn(process.execPath, [...process.execArgv, BIN, ...argv], {
+        env: { ...process.env, [WAITER]: "1" },
+        stdio: ["ignore", "pipe", "ignore"],
+        detached: true,
+        windowsHide: true,
+      });
+    } catch {
+      resolve(failed(argv, stdout));
+      return;
+    }
+    let text = "";
+    let settled = false;
+    // Ctrl+C before the line arrives cancels the waiter, which reports it.
+    const forward = (signal) => child.kill(signal);
+    const signals = ["SIGINT", "SIGTERM"];
+    for (const signal of signals) process.on(signal, forward);
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      for (const signal of signals) process.removeListener(signal, forward);
+      resolve(code);
+    };
+    child.once("error", () => finish(failed(argv, stdout)));
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      if (settled) return;
+      text += chunk;
+      const end = text.indexOf("\n");
+      if (end === -1) return;
+      let line;
+      try { line = JSON.parse(text.slice(0, end)); } catch { line = null; }
+      if (line?.outcome !== "action_required") return;
+      stdout.write(text.slice(0, end + 1));
+      child.stdout.destroy();
+      child.unref();
+      finish(line.exit_code);
+    });
+    child.once("close", (code) => {
+      if (settled) return;
+      if (text.endsWith("\n") && text.indexOf("\n") === text.length - 1) {
+        stdout.write(text);
+        finish(code ?? 1);
+      } else {
+        finish(failed(argv, stdout));
+      }
+    });
+  });
+}
+
+function failed(argv, stdout) {
+  const parsed = parseArgs(argv);
+  const result = envelope({
+    command: parsed.command ?? null,
+    outcome: "internal_error",
+    reason: "unexpected_failure",
+    message: "The CLI failed unexpectedly. No details are shown to avoid exposing sensitive input.",
+  });
+  stdout.write(toJsonLine(result));
+  return result.exit_code;
+}

package/src/args.js

@@ -279,9 +279,10 @@ function parseVerify(values, flags, json, fail) {
     open: flags.has("--open"), noBrowser: flags.has("--no-browser"), json };
 }
 
-// Client and runtime are required, so a script states where the skill is
-// used instead of the CLI guessing. Values for clients and runtimes that
-// cannot use project skill files are accepted here and handed off later.
+// The client is required, so a script states which client loads the skill.
+// The runtime defaults to local, the runtime setup installs the skill for;
+// pass --runtime cloud for a cloud checkout. Values for clients and runtimes
+// that cannot use project skill files are accepted here and handed off later.
 function parseSkill(action, values, json, fail) {
   if (action === null) {
     return fail(
@@ -296,10 +297,7 @@ function parseSkill(action, values, json, fail) {
   if (!Object.hasOwn(SKILL_CLIENTS, client) && !Object.hasOwn(HANDOFF_SKILL_CLIENTS, client)) {
     return fail("invalid_client", "--client must be codex, claude or cursor.");
   }
-  const runtime = values["--runtime"];
-  if (runtime === undefined) {
-    return fail("missing_runtime", "--runtime is required. Use local or cloud.");
-  }
+  const runtime = values["--runtime"] ?? "local";
   if (!SKILL_RUNTIMES.includes(runtime) && !HANDOFF_SKILL_RUNTIMES.includes(runtime)) {
     return fail("invalid_runtime", "--runtime must be local or cloud.");
   }
@@ -442,7 +440,8 @@ function parseSetup(values, flags, json, fail) {
     parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
   if (timeoutMs === null) return fail("invalid_timeout", `--timeout-ms must be a whole number from ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}.`);
   return { ok: true, command: "setup", runtime, origin, originExplicit: values["--url"] !== undefined,
-    deployment, confirmPrerequisites: flags.has("--confirm-prerequisites"), agentTokenFile,
+    deployment, deploymentExplicit: values["--deployment"] !== undefined,
+    confirmPrerequisites: flags.has("--confirm-prerequisites"), agentTokenFile,
     workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
     project: paths.project, configDir: paths.configDir, envFile, client, skipSkill: flags.has("--skip-skill"),
     timeoutMs, noBrowser: flags.has("--no-browser"), repair: flags.has("--repair"),

package/src/auth-login.js

@@ -39,6 +39,11 @@ import { deadline, trapSignals } from "./transport.js";
 // server-verified workspace UUID. Token values, the authorization code, the
 // PKCE verifier, absolute paths and server text never leave this module.
 // progress(text) prints human progress lines; it is a no-op with --json.
+// options.announce(data), given only with --json --no-browser, receives the
+// login data with an open_url next action as soon as the authorization URL
+// exists, while the listener keeps waiting. The caller prints it as the one
+// JSON line, so an agent can hand the URL to a person; approval-handoff.js
+// lets the agent's command exit then while this process keeps waiting.
 
 export async function runLogin(options, progress) {
   const ctx = {
@@ -58,21 +63,12 @@ export async function runLogin(options, progress) {
   if (options.runtime !== "local") return end("unsupported", "runtime_not_supported", GUIDE);
   const remote = detectRemoteSession();
   if (remote !== null) return end("unsupported", remote, GUIDE);
-  // --json cannot show a person the --no-browser URL. A rerun with a saved,
-  // working grant needs no URL, so only refuse once approval is required.
-  const noBrowserHandoff = () => end("unsupported", "no_browser_requires_terminal", {
-    kind: "run_in_terminal",
-    message: "Run the same login command in a terminal without --json to see the sign in URL.",
-  });
-  const urlUnshowable = options.json && options.noBrowser;
-
   const trap = trapSignals();
   try {
     const root = resolveProject(options.project);
     const configDir = resolveConfigDir(options.configDir);
     const existing = readBinding(root);
     const bound = existing?.binding ?? null;
-    if (urlUnshowable && (bound === null || options.reconnect)) return noBrowserHandoff();
     // Setup pins a deployment model before sign in. A stale binding for a
     // different profile must never be silently reused or reconnected.
     if (options.expectedProfile && bound !== null && !options.reconnect &&
@@ -102,9 +98,11 @@ export async function runLogin(options, progress) {
       }
       if (session.outcome !== "login_required") return end(session.outcome, session.reason);
     }
-    if (urlUnshowable) return noBrowserHandoff();
 
-    const flow = await authorize(options, ctx, trap.signal, progress);
+    const announce = options.announce
+      ? (next) => options.announce(loginData({ ...ctx, status: "approval_pending" }, next))
+      : null;
+    const flow = await authorize(options, ctx, trap.signal, progress, announce);
     if (!flow.ok) return end(flow.outcome, flow.reason, flow.next ?? null);
     const { endpoints, clientId, grant } = flow;
 
@@ -169,7 +167,7 @@ export async function runLogin(options, progress) {
 // written here. A validated grant that is not accepted is sent for revocation
 // before returning; that is best effort, and a token response that fails
 // validation cannot be revoked.
-async function authorize(options, ctx, cancel, progress) {
+async function authorize(options, ctx, cancel, progress, announce) {
   const preflight = await runDoctor({ origin: ctx.origin, timeoutMs: AUTH_HTTP_TIMEOUT_MS });
   if (cancel.aborted) return fail("authorization_failed", "cancelled");
   if (preflight.outcome !== "authentication_required") return fail(preflight.outcome, preflight.reason);
@@ -217,7 +215,9 @@ async function authorize(options, ctx, cancel, progress) {
     const seconds = Math.round(options.timeoutMs / 1000);
     // A wait armed after Ctrl+C has already settled; do not show the URL.
     if (cancel.aborted) return fail("authorization_failed", "cancelled");
-    if (options.noBrowser) {
+    if (options.noBrowser && announce) {
+      announce(openUrl(url, seconds, "sign in with Metadata access"));
+    } else if (options.noBrowser) {
       progress(
         "Open this URL in a browser on this machine to sign in:\n" +
           `${url}\n` +
@@ -375,6 +375,20 @@ function fail(outcome, reason, next = null) {
   return { ok: false, outcome, reason, next };
 }
 
+// The next action a --json --no-browser run prints while it waits. The URL is
+// the authorization request: public client ID, loopback redirect, state and
+// PKCE challenge. It carries no token, code or verifier.
+export function openUrl(url, seconds, purpose) {
+  return {
+    kind: "open_url",
+    url,
+    timeout_seconds: seconds,
+    message: `Show this URL to the person now and ask them to open it in a browser on this machine to ` +
+      `${purpose}. A background process waits up to ${seconds} seconds for their approval. ` +
+      "After they approve, run the same command again to continue.",
+  };
+}
+
 const GUIDE = { kind: "connection_guide", url: CONNECTION_GUIDE_URL };
 const RECONNECT = {
   kind: "reconnect",

package/src/cli.js

@@ -18,7 +18,7 @@ import { runRead } from "./read.js";
 import { readMessage, readText } from "./read-output.js";
 import { listSkillPack, runSkill, runSkillPack } from "./skill.js";
 import { runSetup } from "./setup.js";
-import { containsKnownCredential, preflightNonHostedSetup } from "./setup-deployment.js";
+import { containsKnownCredential, preflightNonHostedSetup, prerequisiteGuide, resumeNonHostedRoute } from "./setup-deployment.js";
 import { VERSION } from "./constants.js";
 import { runVerify } from "./verify.js";
 import { verifyMessage, verifyText } from "./verify-output.js";
@@ -75,8 +75,10 @@ async function run(argv, { stdout, stderr }) {
     // Human progress goes to stderr, never with --json, so stdout carries
     // only the final result.
     const progress = parsed.json ? () => {} : (text) => stderr.write(`${text}\n`);
+    const pending = announcer(parsed, stdout, (data) => data);
     const { outcome, reason, data } =
-      parsed.command === "login" ? await runLogin(parsed, progress) : await runLogout(parsed);
+      parsed.command === "login" ? await runLogin({ ...parsed, announce: pending.announce }, progress) : await runLogout(parsed);
+    if (pending.result) return pending.result;
     const message = authMessage(outcome, reason);
     const result = envelope({
       command: parsed.command,
@@ -90,14 +92,18 @@ async function run(argv, { stdout, stderr }) {
   }
 
   if (parsed.command === "setup") {
-    const routed = parsed.deployment === "managed"
+    const options = resumeNonHostedRoute(parsed);
+    const routed = options.deployment === "managed"
       ? { proceed: true, profile: "managed" }
-      : await preflightNonHostedSetup(parsed);
+      : await preflightNonHostedSetup(options);
     const progress = parsed.json ? () => {} : (line) =>
       stderr.write(containsKnownCredential(line, routed) ? "Setup progress.\n" : `${line}\n`);
+    // The announced line is checked for known credentials like the final one.
+    const pending = announcer(parsed, stdout, (data) => containsKnownCredential(data, routed) ? null : data);
     const response = routed.proceed
-      ? await runSetup({ ...parsed, expectedProfile: routed.profile ?? null }, progress)
+      ? await runSetup({ ...options, expectedProfile: routed.profile ?? null, announce: pending.announce }, progress)
       : routed;
+    if (pending.result) return pending.result;
     const { outcome, reason, data } = response;
     let result = envelope({ command: "setup", outcome, reason, data,
       message: outcome === "ok" ? null : "Setup did not complete. Review the reason and retry safely." });
@@ -107,7 +113,8 @@ async function run(argv, { stdout, stderr }) {
     const receipt = result.data?.receipt;
     const summary = receipt ? `Workspace: ${receipt.workspace_id}\nDeployment: ${receipt.deployment_profile} at ${receipt.origin}\nCompleted: ${receipt.completed_steps.join(", ")}\nPending: ${receipt.pending_steps.join(", ")}\n` : "";
     const identity = repositoryLine(result.data?.repository);
-    const human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}${identity}Application traffic verified: no\n${result.ok ? "Next: instrument your application and verify an exact trace.\n" : `Result: ${result.outcome} (${result.error.reason})\n`}`;
+    const guide = handoffLines(result.data);
+    const human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}${identity}${guide}Application traffic verified: no\n${result.ok ? "Next: instrument your application and verify an exact trace.\n" : `Result: ${result.outcome} (${result.error.reason})\n`}`;
     if (containsKnownCredential(human, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
       stdout.write(parsed.json ? toJsonLine(result) : "Setup stopped.\n");
@@ -181,6 +188,47 @@ async function run(argv, { stdout, stderr }) {
   return result;
 }
 
+// With --json --no-browser, login and setup print their one JSON line as
+// soon as a person must open an approval URL, then keep waiting for the
+// callback; bin/metergraph.js has already moved this process to the
+// background (approval-handoff.js). Whatever the run does afterwards, that
+// line is its result; the agent reruns the command to continue. screen(data) returns
+// the data to print, or null to print a credential_echo refusal instead.
+function announcer(parsed, stdout, screen) {
+  const pending = { announce: null, result: null };
+  if (!parsed.json || !parsed.noBrowser) return pending;
+  pending.announce = (data) => {
+    if (pending.result) return;
+    const safe = screen(data);
+    pending.result = safe === null
+      ? envelope({ command: parsed.command, outcome: "unsupported", reason: "credential_echo" })
+      : envelope({ command: parsed.command, outcome: "action_required", reason: "browser_approval_required",
+        data: safe, message: authMessage("action_required", "browser_approval_required") });
+    stdout.write(toJsonLine(pending.result));
+  };
+  return pending;
+}
+
+// What an operator handoff is waiting for, in fixed text: the route, each
+// unconfirmed prerequisite with its guidance, and the next action.
+function handoffLines(data) {
+  if (data?.status !== "operator_handoff") return "";
+  let text = data.origin ? `Deployment: ${data.deployment_profile} at ${data.origin}\n` : "";
+  if (data.workspace_id) text += `Workspace: ${data.workspace_id}\n`;
+  if (data.pending_prerequisites.length > 0) {
+    text += "Confirm each prerequisite, then rerun with --confirm-prerequisites:\n";
+    for (const name of data.pending_prerequisites) {
+      text += `  - ${name}: ${prerequisiteGuide(name, data.deployment_profile) ?? "see the guide"}\n`;
+    }
+  }
+  const next = data.next_action;
+  if (next?.message && !(next.kind === "complete_prerequisite" && data.pending_prerequisites.includes(next.prerequisite))) {
+    text += `Next: ${next.message}\n`;
+  }
+  if (next?.url) text += `Guide: ${next.url}\n`;
+  return text;
+}
+
 // One line on the repository identity setup found or recorded. The value is
 // owner/name only; a remote URL is never shown.
 function repositoryLine(repository) {

package/src/constants.js

@@ -141,6 +141,7 @@ export const EXIT_CODES = Object.freeze({
   permission_denied: 15,
   rate_limited: 16,
   cancelled: 17,
+  action_required: 18,
 });
 
 export const EXIT_CODE_MEANINGS = Object.freeze({
@@ -177,4 +178,8 @@ export const EXIT_CODE_MEANINGS = Object.freeze({
   rate_limited: "The service asked the CLI to slow down. Nothing was retried. Try again later.",
   cancelled:
     "A read command was interrupted before it finished. Read commands never change workspace configuration or telemetry.",
+  action_required:
+    "A person must act before this command can finish; data.next_action says what to do. " +
+    "With --json --no-browser the command exits as soon as the approval URL exists, and a background " +
+    "process waits for approval until --timeout-ms. After approval, run the same command again to continue.",
 });

package/src/deployment-route.js

@@ -117,7 +117,7 @@ const DEPLOYMENT_PATH = "/v1/deployment";
 const MIN_TIMEOUT_MS = 100;
 const MAX_TIMEOUT_MS = 60000;
 
-function action(kind, prerequisite = null) {
+export function action(kind, prerequisite = null) {
   // Kinds are constants from this module, so this is a programming error.
   if (!ACTION_KINDS.includes(kind)) throw new Error("unknown next action kind");
   return { kind, prerequisite, url: CONNECTION_GUIDE_URL };

package/src/output.js

@@ -73,20 +73,20 @@ const SKILL_OPTIONS = [
   {
     name: "--runtime",
     value: "RUNTIME",
-    summary: "Required. local or cloud: where the client runs. Recorded, not detected.",
+    summary: "local (default) or cloud: where the client runs. Recorded, not detected.",
   },
   { name: "--project", value: "DIR", summary: "Existing project directory. Default: the current directory." },
   { name: "--json", value: null, summary: "Print one JSON line on stdout." },
 ];
 
 const SKILL_USAGE = [
-  "metergraph skill install --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
-  "metergraph skill update --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+  "metergraph skill install --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
+  "metergraph skill update --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
 ];
 
 const SKILLS_USAGE = [
-  "metergraph skills install --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
-  "metergraph skills update --client CLIENT --runtime RUNTIME [--project DIR] [--json]",
+  "metergraph skills install --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
+  "metergraph skills update --client CLIENT [--runtime RUNTIME] [--project DIR] [--json]",
   "metergraph skills list [--project DIR] [--json]",
 ];
 
@@ -106,6 +106,15 @@ const SKILLS_STATE_LABELS = {
   unsafe_path: "unsafe path",
 };
 
+// How a coding agent gets an approval URL from login or setup. Many agent
+// shells show output only after the command exits, which is too late.
+const AGENT_APPROVAL_HELP = [
+  "From a coding agent: with --json --no-browser, a step that needs approval exits at once",
+  "with exit 18 action_required and the URL in data.next_action.url, while a background",
+  "process keeps waiting for the approval until --timeout-ms. Show the URL to the person,",
+  "and after they approve, run the same command again to continue.",
+];
+
 const CONFIG_DIR_OPTION = {
   name: "--config-dir",
   value: "DIR",
@@ -134,7 +143,7 @@ const LOGIN_OPTIONS = [
     summary: `Time to wait for the browser, ${LOGIN_MIN_TIMEOUT_MS} to ${LOGIN_MAX_TIMEOUT_MS}. Default ${LOGIN_DEFAULT_TIMEOUT_MS}.`,
   },
   { name: "--signup", value: null, summary: "Start at the hosted sign up page. Managed service only." },
-  { name: "--no-browser", value: null, summary: "Print the sign in URL on stderr instead of opening a browser. With --json, only a rerun that needs no sign in succeeds." },
+  { name: "--no-browser", value: null, summary: "Print the sign in URL on stderr instead of opening a browser. With --json, exit 18 with it in data.next_action (open_url)." },
   { name: "--reconnect", value: null, summary: "Allow switching a bound project to another origin or workspace." },
   { name: "--json", value: null, summary: "Print one JSON line on stdout." },
 ];
@@ -353,7 +362,7 @@ export function helpData(topic) {
           { name: "--timeout-ms", value: "N", summary: "Time to wait for browser approval." },
           { name: "--signup", value: null, summary: "Start at hosted sign up when the project needs login." },
           { name: "--reconnect", value: null, summary: "Permit switching an existing project binding." },
-          { name: "--no-browser", value: null, summary: "Print approval URL on stderr. With --json, only a rerun that needs no approval succeeds." },
+          { name: "--no-browser", value: null, summary: "Print approval URL on stderr. With --json, exit 18 with it in data.next_action (open_url); rerun after approval." },
           { name: "--repair", value: null, summary: "Explicitly approve replacement of an acknowledged key that no longer verifies." },
           { name: "--deployment", value: "MODEL", summary: "managed, customer-local, byoc or oss. Default managed." },
           { name: "--confirm-prerequisites", value: null, summary: "Attest deployment prerequisites are met; it does not verify bundle publication." },
@@ -417,6 +426,7 @@ export function helpText(topic) {
       const flag = option.value ? `${option.name} ${option.value}` : option.name;
       lines.push(`  ${flag.padEnd(25)}${option.summary}`);
     }
+    lines.push("", ...AGENT_APPROVAL_HELP);
   } else if (topic === "login" || topic === "logout") {
     const login = topic === "login";
     lines.push(`Usage: ${login ? LOGIN_USAGE : LOGOUT_USAGE}`, "");
@@ -449,6 +459,7 @@ export function helpText(topic) {
       const flag = option.value ? `${option.name} ${option.value}` : option.name;
       lines.push(`  ${flag.padEnd(18)}${option.summary}`);
     }
+    if (login) lines.push("", ...AGENT_APPROVAL_HELP);
   } else if (topic === "verify") {
     lines.push(`Usage: ${VERIFY_USAGE}`, "", "Uses the saved Metadata grant to poll for one exact, processed trace.",
       "The source label is supplied by the caller. A Metadata match alone does not prove application traffic.",
@@ -719,9 +730,9 @@ const AUTH_MESSAGES = {
     "so sign in cannot finish here. Follow the connection guide instead. Nothing was written.",
   ci_environment:
     "This is a CI environment, where no person can approve sign in in a browser. Nothing was written.",
-  no_browser_requires_terminal:
-    "Approval is needed, and --no-browser prints its URL for a person to open, which --json cannot do. " +
-    "Run the same command without --json in a terminal. Nothing was done.",
+  browser_approval_required:
+    "A person must approve in a browser. Open data.next_action.url on this machine; a background process " +
+    "waits for the approval until the timeout. After approval, run the same command again to continue.",
   bound_to_other_origin:
     "This project is bound to a different origin. Nothing was changed. Use --reconnect to switch it.",
   bound_to_other_workspace:
@@ -737,7 +748,7 @@ const AUTH_MESSAGES = {
   timeout: "The operation did not finish within the time limit. Nothing was saved.",
   cancelled: "Sign in was cancelled. Nothing was saved.",
   browser_unavailable:
-    "The browser could not be opened. Run login again with --no-browser, without --json, and open the URL it prints.",
+    "The browser could not be opened. Run login again with --no-browser and open the URL it prints.",
   oauth_metadata_missing: "This service does not support CLI sign in yet. Nothing was written.",
   metadata_scope_unsupported:
     "This service does not offer Metadata-only access for the CLI yet. The CLI does not fall back to broader access.",

package/src/setup-deployment.js

@@ -1,6 +1,9 @@
+import { detectRemoteSession } from "./auth-browser.js";
 import { runDoctor } from "./doctor.js";
-import { planDeploymentRoute, verifyDeploymentRoute } from "./deployment-route.js";
+import { action, planDeploymentRoute, verifyDeploymentRoute } from "./deployment-route.js";
 import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
+import { resolveProject } from "./auth-binding.js";
+import { readSetupState } from "./setup-state.js";
 
 // Setup routing uses the same deployment model and Metadata credential checks
 // as the standalone routing contract. Operator prerequisites are assertions,
@@ -24,6 +27,55 @@ const PREREQUISITES = Object.freeze({
 
 const EXPECTED_PROFILE = Object.freeze({ "customer-local": "local", byoc: "byoc-core", oss: "oss" });
 
+const DEPLOYMENT_FOR_PROFILE = Object.freeze({ local: "customer-local", "byoc-core": "byoc" });
+
+// Fixed guidance for each prerequisite, so a person or agent can act on a
+// handoff without the docs. None of it names a credential value, and none of
+// it asks for a credential to be passed to this CLI.
+const PREREQUISITE_GUIDE = Object.freeze({
+  released_signed_bundle: "Download the released customer-local bundle and its signed manifest, and verify the signature before starting it. A bundle built from source is not a release.",
+  registry_invitation: "Accept the workspace's registry invitation so the bundle can pull its images. The registry pull credential is only for pulling images: never give it to this CLI or put it in the project env file.",
+  bundle_started_verified: "Start the bundle with bin/start and wait until bin/status reports it healthy. Pass its origin as --url and the workspace ID that bin/status shows as --workspace.",
+  local_admin_configured: "Sign in to the installation once as its local admin, in a browser on this machine. Setup asks that account to approve sign in and an ingest-only key.",
+  operator_provisioning: "The operator must already have provisioned the customer-owned AWS deployment. Setup connects to it and never provisions anything.",
+  private_network_reachability: "Run setup from a machine that reaches the deployment's private HTTPS origin, for example over the customer VPN. Setup never opens a tunnel or a public endpoint.",
+  identity_membership_configured: "The operator must already have given your identity membership of the workspace through the deployment's configured identity provider.",
+  server_distribution_installed: "The open source server must already be installed and running under the operator's management.",
+  deployment_discovery_supported: "The open source server must answer GET /v1/deployment with the oss profile. If it does not, ask the operator to upgrade it.",
+  metadata_scope_supported: "The open source server must advertise the agent:metadata scope in its OAuth metadata. If it does not, ask the operator to upgrade it.",
+  ingestion_tokens_configured: "The operator configures ingestion tokens in MG_TOKENS and gives the application one as METERGRAPH_APP_TOKEN. Setup never issues or writes open source ingest tokens.",
+  agent_read_tokens_configured: "The operator configures agent read tokens in MG_AGENT_TOKENS, separately from MG_TOKENS. Never reuse an ingestion token for agent reads.",
+});
+const METADATA_CREDENTIAL_GUIDE = Object.freeze({
+  local: "Setup obtains its own Metadata-only sign in through the browser. --agent-token-file is optional and must hold a Metadata-only agent token.",
+  "byoc-core": "Setup obtains its own Metadata-only sign in through the browser. --agent-token-file is optional and must hold a Metadata-only agent token.",
+  oss: "Put one MG_AGENT_TOKENS value in a private file (mode 0600) and pass its absolute path as --agent-token-file.",
+});
+const ACTION_GUIDE = Object.freeze({
+  complete_prerequisite: "Complete the named prerequisite, then rerun setup with --confirm-prerequisites.",
+  oss_operator_handoff: "Ask the open source server operator to complete this step. This CLI does not create open source credentials or change the server.",
+  run_on_customer_machine: "Run setup in a terminal on the machine that reaches the deployment. Setup does not tunnel or forward credentials from a remote or cloud session.",
+  use_https_origin: "Pass the deployment's HTTPS origin. A customer-owned AWS deployment is never reached over plain HTTP.",
+  connection_guide: "Check that --url is the installation's own origin and that it reports the expected deployment profile.",
+  check_private_network: "This machine cannot reach the private origin. Connect to the deployment's network, for example over the customer VPN, and rerun. Do not expose the deployment publicly.",
+  platform_credential_handoff: "This platform cannot prove the agent token file is private. Rerun without --agent-token-file, or on macOS or Linux.",
+  fix_credential_file: "Make --agent-token-file an absolute path to a regular file you own, with mode 0600, holding one token.",
+  use_metadata_only_credential: "The agent token was refused or has more than Metadata access. Use a Metadata-only agent token for this workspace.",
+  retry: "Rerun the same command.",
+});
+
+export function prerequisiteGuide(name, profile) {
+  if (name === "metadata_agent_credential") return METADATA_CREDENTIAL_GUIDE[profile] ?? null;
+  return PREREQUISITE_GUIDE[name] ?? null;
+}
+
+function guided(nextAction, profile) {
+  if (nextAction === null) return null;
+  const message = nextAction.kind === "complete_prerequisite" && nextAction.prerequisite !== null
+    ? prerequisiteGuide(nextAction.prerequisite, profile) : ACTION_GUIDE[nextAction.kind] ?? null;
+  return { ...nextAction, message };
+}
+
 const handoff = (outcome, reason, nextAction = null, details = {}) => ({
   proceed: false,
   outcome,
@@ -38,10 +90,21 @@ const handoff = (outcome, reason, nextAction = null, details = {}) => ({
     pending_prerequisites: details.pendingPrerequisites ?? [],
     metadata_access: details.metadataAccess ?? "not_checked",
     ingest_credential: "not_checked",
-    next_action: nextAction,
+    next_action: guided(nextAction, details.profile ?? null),
   },
 });
 
+// The next action when the service did not answer as a healthy deployment.
+// An unreachable customer-local origin usually means the bundle is not
+// running; an unreachable BYOC origin is private networking. Neither is
+// tunnelled or relaxed.
+function unreachedAction(deployment, outcome) {
+  if (deployment === "oss") return action("oss_operator_handoff");
+  if (outcome !== "connection_failed") return action("connection_guide");
+  if (deployment === "byoc") return action("check_private_network");
+  return action("complete_prerequisite", "bundle_started_verified");
+}
+
 // The static agent token can be any printable string of at least 16 bytes.
 // Even a fixed status such as "operator_handoff" might equal that token. Keep
 // the verifier's non-enumerable knownCredentials on every later result and
@@ -94,13 +157,21 @@ export function planNonHostedSetup(options) {
   return { proceed: true, plan: planned.plan, prerequisites };
 }
 
-export async function preflightNonHostedSetup(options) {
+export async function preflightNonHostedSetup(options, { env = process.env } = {}) {
   const planned = planNonHostedSetup(options);
   if (!planned.proceed) return planned;
   const { plan, prerequisites } = planned;
+  // Setup itself refuses a remote session, but only after this preflight.
+  // Refuse here first, so a remote shell sends no request and never reads the
+  // separate agent token file.
+  if (detectRemoteSession(env) !== null) {
+    return handoff("unsupported", "run_on_local_machine", action("run_on_customer_machine"), {
+      profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
+    });
+  }
   const timeoutMs = Math.min(options.timeoutMs, AUTH_HTTP_TIMEOUT_MS);
   if (options.deployment === "oss" && !options.agentTokenFile) {
-    return handoff("unsupported", "oss_agent_token_file_required", "oss_operator_handoff", {
+    return handoff("unsupported", "oss_agent_token_file_required", action("oss_operator_handoff"), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed",
     });
@@ -123,7 +194,7 @@ export async function preflightNonHostedSetup(options) {
     // The OSS operator provisions MG_TOKENS and MG_AGENT_TOKENS separately.
     // No released OSS server implements the purpose-bound ingest bootstrap,
     // and a Metadata agent token cannot issue a key. Keep this a handoff.
-    return guardKnownCredentials(handoff("unsupported", "oss_ingest_operator_handoff", "oss_operator_handoff", {
+    return guardKnownCredentials(handoff("unsupported", "oss_ingest_operator_handoff", action("oss_operator_handoff"), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed", metadataAccess: "verified",
     }), verified);
@@ -134,13 +205,13 @@ export async function preflightNonHostedSetup(options) {
   // and unsafe network responses and reports only a fixed profile token.
   const doctor = await runDoctor({ origin: plan.origin, timeoutMs });
   if (doctor.report.deployment_profile !== null && doctor.report.deployment_profile !== plan.deployment_profile) {
-    return handoff("unsupported", "deployment_profile_mismatch", "connection_guide", {
+    return handoff("unsupported", "deployment_profile_mismatch", action("connection_guide"), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed",
     });
   }
   if (doctor.outcome !== "authentication_required") {
-    return handoff(doctor.outcome, doctor.reason, options.deployment === "oss" ? "oss_operator_handoff" : "connection_guide", {
+    return handoff(doctor.outcome, doctor.reason, unreachedAction(options.deployment, doctor.outcome), {
       profile: plan.deployment_profile, origin: plan.origin, workspaceId: plan.workspace_id,
       prerequisites: "operator_confirmed",
     });
@@ -176,3 +247,28 @@ export async function preflightNonHostedSetup(options) {
     metadataAccess: "pending_login",
   };
 }
+
+// A rerun of non-hosted setup may omit the route it was first given, as a
+// hosted rerun does. Only a saved setup state for a customer-local or BYOC
+// route is resumed, and only to that same origin and workspace. The earlier
+// run's operator confirmation stands for that route; every live check still
+// runs again. Anything else is left for setup's own conflict checks.
+export function resumeNonHostedRoute(options) {
+  let saved;
+  try {
+    saved = readSetupState(resolveProject(options.project));
+  } catch {
+    return options;
+  }
+  const deployment = DEPLOYMENT_FOR_PROFILE[saved?.value.deployment_profile];
+  if (deployment === undefined) return options;
+  const { origin, workspace_id: workspaceId } = saved.value;
+  const sameRoute = (!options.originExplicit || options.origin === origin) &&
+    (options.workspace === null || options.workspace === workspaceId);
+  if (!sameRoute) return options;
+  if (!options.deploymentExplicit) {
+    return { ...options, deployment, origin, originExplicit: true, workspace: workspaceId, confirmPrerequisites: true };
+  }
+  if (options.deployment === deployment && options.originExplicit) return { ...options, confirmPrerequisites: true };
+  return options;
+}

package/src/setup.js

@@ -1,7 +1,7 @@
 import { detectRemoteSession, openBrowser } from "./auth-browser.js";
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { startCallbackListener } from "./auth-callback.js";
-import { runLogin } from "./auth-login.js";
+import { openUrl, runLogin } from "./auth-login.js";
 import { clientFor, endpointsFor, newPkce, offeredClientId } from "./auth-oauth.js";
 import { Stop } from "./auth-store.js";
 import { verifiedSession } from "./auth-session.js";
@@ -24,26 +24,26 @@ const PURPOSE = "ingest-bootstrap-v1";
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const RECEIPT = /^mgbs_[A-Za-z0-9_-]{32,256}$/;
 const KEY = (value) => typeof value === "string" && UUID.test(value);
-// --json cannot show a person the --no-browser approval URL. The refusal names
-// a fixed, secret-free next step instead of only a reason token.
-const RUN_IN_TERMINAL = Object.freeze({
-  kind: "run_in_terminal",
-  message: "Run the same setup command in a terminal without --json to see the approval URL.",
-});
-const fail = (outcome, reason, status = "not_ready", receipt = null) => ({ outcome, reason,
-  data: { status, application_traffic_verified: false, receipt,
-    next_action: reason === "no_browser_requires_terminal" ? RUN_IN_TERMINAL : null } });
+const fail = (outcome, reason, status = "not_ready", receipt = null, next = null) => ({ outcome, reason,
+  data: { status, application_traffic_verified: false, receipt, next_action: next } });
 
 // This command never receives an ingest key from argv, stdin, an environment
 // variable or a Metadata OAuth grant. Only the purpose-bound redemption
 // response can supply it. Every returned string is fixed and non-secret.
+//
+// With --json --no-browser the caller passes options.announce(data). The
+// first approval this run needs (sign in, or ingest-only setup approval) is
+// announced as setup data with an open_url next action while the listener
+// keeps waiting; stdout has room for one line, so a second approval in the
+// same run is not started. The person approves, the run saves what it
+// finished, and the agent reruns setup, which resumes from the saved state.
 export async function runSetup(options, progress = () => {}) {
   if (options.runtime !== "local" || detectRemoteSession() !== null) return fail("unsupported", "run_on_local_machine");
   const trap = trapSignals();
   let receipt = null;
   let loginVerified = false;
   let credentialVerified = false;
-  const stop = (outcome, reason, status = "not_ready") => {
+  const currentReceipt = () => {
     let current = receipt;
     if (current !== null && (!loginVerified || !credentialVerified)) {
       const completed = loginVerified ? ["login"] : [];
@@ -52,8 +52,14 @@ export async function runSetup(options, progress = () => {}) {
           ...(!loginVerified ? ["login"] : []), "credential", "skill", "instrument", "verify", "view",
         ] };
     }
-    return fail(outcome, reason, status, current);
+    return current;
   };
+  const stop = (outcome, reason, status = "not_ready") => fail(outcome, reason, status, currentReceipt());
+  let announced = false;
+  const announce = options.announce ? (status, next) => {
+    announced = true;
+    options.announce(fail("action_required", "browser_approval_required", status, currentReceipt(), next).data);
+  } : null;
   try {
     const root = resolveProject(options.project);
     const saved = readSetupState(root);
@@ -67,6 +73,13 @@ export async function runSetup(options, progress = () => {}) {
         (bound !== null && (bound.origin !== saved.value.origin || bound.workspace_id !== saved.value.workspace_id)))) {
       return stop("conflict", "setup_binding_changed");
     }
+    // An env key this setup does not own stops before any sign in, so the
+    // refusal costs no approval and leaves the binding untouched. The check
+    // after sign in stays, against a fresh read.
+    if (!saved) {
+      const early = currentEnvValues(preflightEnv({ project: root, envFile: options.envFile, signal: trap.signal }));
+      if (early.token !== null) return stop("conflict", "existing_ingest_key_unowned");
+    }
     const bindingDiffers = bound !== null && (bound.origin !== intendedOrigin ||
       (intendedWorkspace !== null && bound.workspace_id !== intendedWorkspace));
     if (bindingDiffers && !options.reconnect) return stop("conflict", "bound_to_other_workspace");
@@ -74,7 +87,8 @@ export async function runSetup(options, progress = () => {}) {
       await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
     if (!signedIn.ok && signedIn.outcome === "login_required") {
       const login = await runLogin({ ...options, origin: intendedOrigin, workspace: intendedWorkspace,
-        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null }, progress);
+        project: root, reconnect: options.reconnect, expectedProfile: options.expectedProfile ?? null,
+        announce: announce && ((data) => announce("login_pending", data.next_action)) }, progress);
       if (login.outcome !== "ok") return stop(login.outcome, login.reason, "login_pending");
       signedIn = await verifiedSession({ project: root, configDir: options.configDir, cancel: trap.signal });
     }
@@ -146,8 +160,9 @@ export async function runSetup(options, progress = () => {}) {
     }
 
     // A verified rerun returned above without approval. From here a person
-    // must open an approval URL, which --json cannot show with --no-browser.
-    if (options.json && options.noBrowser) return stop("unsupported", "no_browser_requires_terminal");
+    // must open an approval URL. A run that already announced its sign in URL
+    // has used its one JSON line, so it stops here and the rerun continues.
+    if (announced) return stop("action_required", "browser_approval_required", "approval_pending");
     const setup = await discoverSetup(origin, profile, trap.signal);
     if (!setup.ok) return stop(setup.outcome, setup.reason);
 
@@ -183,7 +198,9 @@ export async function runSetup(options, progress = () => {}) {
       if (intent === "repair") params.expected_key_id = state.key_id;
       url.search = new URLSearchParams(params).toString();
       if (trap.signal.aborted) return stop("authorization_failed", "cancelled");
-      if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
+      if (options.noBrowser && announce) {
+        announce("approval_pending", openUrl(url.href, Math.round(options.timeoutMs / 1000), "approve ingest-only setup"));
+      } else if (options.noBrowser) progress(`Open this URL on this machine to approve ingest-only setup:\n${url.href}`);
       else if (!(await openBrowser(url.href))) return stop("authorization_failed", "browser_unavailable");
       else progress("Opened your browser for ingest-only setup approval.");
       callback = await pending;

package/src/skill-bundle.js

@@ -5,7 +5,7 @@ import { readFileSync } from "node:fs";
 // public skill at the manifest's source_url. The source has no version of its
 // own, so the revision is derived from the content hash. The hash is pinned
 // here as well as in the manifest, so editing either file alone is detected.
-const PINNED_SHA256 = "92f7955f6f8761a20a1886ad81f22dfcee239afddf8e9f1e761c35eb8e70f218";
+const PINNED_SHA256 = "e7fc4eb7a22eeb16c357bede9d0a080ad3b415aaab1d9c72f164d5350d48c4b1";
 
 const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
 const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];
@@ -55,7 +55,7 @@ export function loadBundledSkill() {
 // The workflow skills that "skills install" writes, vendored from the public
 // skills repository at one commit. The manifest's own hash is pinned here, and
 // the manifest pins each skill's hash, so changing any file alone is detected.
-const PINNED_PACK_SHA256 = "c8e4d9b0d90bd201e90758e16ab0827b8ea36e3620a28223a7e73e91c035d835";
+const PINNED_PACK_SHA256 = "f08a188abba2018770dc3ba071509ff22f3af76ebc5c30a9f3a2ec2b2eae75b5";
 
 const PACK_DIR = new URL("../assets/skills/", import.meta.url);
 const PACK_KEYS = ["commit", "manifest_version", "repository", "skills"];