metergraph-cli 0.2.0-preview.2 → 0.2.0-preview.3

package/README.md

@@ -1,6 +1,6 @@
 # metergraph-cli
 
-The Metergraph command line tool. Version `0.2.0-preview.2` is published on the
+The Metergraph command line tool. Version `0.2.0-preview.3` is published on the
 `next` npm tag. The `latest` tag remains on `0.1.0`.
 
 Install the released preview channel with npm or run it directly:
@@ -11,7 +11,7 @@ npx --yes metergraph-cli@next doctor --json
 npm install -g metergraph-cli@next
 ```
 
-The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.2`
+The installed command is `metergraph`. Pin `metergraph-cli@0.2.0-preview.3`
 when you need this exact preview rather than whichever version `next` names later.
 
 **Availability:**
@@ -28,6 +28,14 @@ when you need this exact preview rather than whichever version `next` names late
   when its deadline expires after the service reported the trace as pending, lets
   `login` and `setup` reruns that need no approval succeed with `--json
   --no-browser`, and reports why `verify --open` did not launch a browser.
+- `metergraph-cli@0.2.0-preview.3` makes a `verify` deadline that expires after
+  the service reported the trace as pending return `trace_not_found_within_bounds`,
+  the same result as running out of attempts, instead of `verification_timeout`.
+  `setup --json --no-browser` now returns a `run_in_terminal` next action when
+  approval is needed.
+  `login` and `setup` use a pre-registered CLI client when the service names one
+  in `metergraph_cli_client_id`, instead of registering a new client, and still
+  register one on services that do not.
 - Sign in needs a Metergraph service that offers Metadata-only CLI grants and grant
   revocation. A service without them is reported as unsupported, and the CLI never
   falls back to broader access.
@@ -111,9 +119,12 @@ was given but that flag returned the link instead of launching it.
 
 If `--timeout-ms` expires after the service has answered at least once with a
 pending result, `verify` exits 11 `verification_failed` with reason
-`verification_timeout`: the origin is reachable and the trace is not visible yet.
-Exit 4 `connection_failed` with that reason means no valid answer arrived before
-the deadline.
+`trace_not_found_within_bounds`, the same result as running out of
+`--max-attempts`: the origin is reachable and the trace is not visible yet. Exit 4
+`connection_failed` is kept for transport failures. Its reason is
+`verification_timeout` when no valid answer arrived before the deadline. A deadline
+while `--open` launches a trace that was already found exits 11 with
+`verification_timeout`.
 
 ### doctor
 
@@ -238,7 +249,7 @@ metergraph logout
 | `--config-dir DIR` | see below | Private per-user directory for the saved grant. |
 | `--timeout-ms N` | `300000` | How long to wait for the browser, 1000 to 900000. |
 | `--signup` | off | Start at the hosted sign up page, which returns to the same authorization request. Managed service only; other profiles exit 6. |
-| `--no-browser` | off | Print the authorization URL on stderr for you to open on this machine, then wait. With `--json`, a rerun that needs no approval succeeds; one that needs approval exits 6 `no_browser_requires_terminal`. |
+| `--no-browser` | off | Print the authorization URL on stderr for you to open on this machine, then wait. With `--json`, a rerun that needs no approval succeeds; one that needs approval exits 6 `no_browser_requires_terminal` with a `run_in_terminal` next action. |
 | `--reconnect` | off | Allow replacing a binding to a different origin or workspace. |
 | `--json` | off | Print exactly one JSON line on stdout and nothing on stderr. |
 
@@ -253,10 +264,14 @@ What `login` does, in order:
 3. Runs the same checks as `doctor`, then reads the service's OAuth metadata from the
    same origin. Every endpoint must be a fixed path on that origin, and the service must
    offer `agent:metadata`, PKCE with `S256`, public clients and revocation.
-4. Registers a public client named `Metergraph CLI` for one loopback redirect,
-   `http://127.0.0.1:PORT/callback` on an ephemeral port, creates a random state and
-   PKCE verifier, and arms the callback listener and its timeout before the browser
-   opens.
+4. Chooses the OAuth client for a loopback redirect, `http://127.0.0.1:PORT/callback`
+   on an ephemeral port. When the service's OAuth metadata names a pre-registered
+   Metergraph CLI client in `metergraph_cli_client_id`, the CLI uses that client and
+   registers nothing; the service accepts the loopback redirect on any port (RFC 8252
+   section 7.3). Otherwise it registers a new public client named `Metergraph CLI` for
+   that one redirect, as servers without the field expect. A malformed value stops
+   sign in. The CLI then creates a random state and PKCE verifier, and arms the callback
+   listener and its timeout before the browser opens.
 5. Opens the authorization URL with the operating system's launcher (no shell). The
    listener accepts one `GET` with the exact host, path and state. Other requests get a
    fixed page and do not end the wait.
@@ -268,7 +283,9 @@ What `login` does, in order:
    the deployment profile must match step 3, the access scopes must be exactly
    `agent:metadata`, and content, evidence and replay capabilities must be unavailable.
    Nothing else is read.
-8. Saves the grant in the config directory and writes `.metergraph/project.json`.
+8. Saves the grant in the config directory and writes `.metergraph/project.json`. The
+   saved grant keeps the client ID it was issued to, so a grant from a registered client
+   still refreshes and revokes after the service starts offering a pre-registered one.
 
 Once the token response has been validated and holds a usable refresh token, a grant
 the CLI decides not to keep (a workspace other than the one expected or bound, failed
@@ -341,7 +358,9 @@ If the project has no usable Metadata sign in, `setup` opens the deployment's
 browser sign in and workspace choice. `--signup` starts at hosted sign up;
 `--workspace UUID` requires that exact workspace. An existing binding to a
 different origin or workspace requires explicit `--reconnect`. The selected
-deployment must advertise `metergraph.cli-setup/v1` on its own origin. Setup
+deployment must advertise `metergraph.cli-setup/v1` on its own origin. Its setup
+metadata may name a pre-registered CLI client in `metergraph_cli_client_id`, which
+setup then uses for ingest approval instead of registering a new client. Setup
 refuses reconnecting an existing ingest family to another workspace; its
 original workspace must be restored before that family can be reused. Setup
 checks the env file and Git state, then opens the deployment's consent page. An
@@ -382,12 +401,60 @@ The JSON result includes a secret-free `receipt` with the origin, workspace ID,
 deployment profile, selected client, and completed and pending steps. A skill
 conflict leaves the delivered key in place and reports `credential_ready_skill_pending`;
 resolve the skill file conflict and rerun setup without another approval.
+With `--no-browser`, setup prints the approval URL on stderr instead of opening a
+browser. Under `--json` it cannot show that URL, so a rerun that needs no approval
+(a working saved key) still succeeds, and one that needs approval exits 6
+`no_browser_requires_terminal` before any approval request or env write, with
+`data.next_action` set to `{"kind": "run_in_terminal", "message": "..."}`. The
+message is fixed text and holds no URL or credential. Non-hosted operator
+handoffs carry their own deployment `next_action`; every other setup result has
+`next_action: null`.
 Success means the key was delivered and the project is ready to instrument.
 It does **not** mean application traffic has arrived. Run your application and
 verify one exact trace afterward. The hosted service advertises the setup
 contract, but each non-hosted deployment must be checked at its own origin.
 Local protocol tests do not prove browser approval or real application traffic.
 
+#### Repository identity
+
+After the key is ready, setup records which repository the project belongs to,
+so traces from several repositories in one workspace stay apart. The SDKs read
+`METERGRAPH_REPOSITORY`, then the nearest `.metergraph/config.json`:
+
+```json
+{
+  "version": 2,
+  "repository": "example-org/example-app"
+}
+```
+
+Setup takes `owner/name` from `--repository`, or else from the git `origin`
+remote (or the only remote). It writes `.metergraph/config.json` in the project
+directory only when no identity exists yet. The file holds no secret; review
+and commit it. An identity already set in `METERGRAPH_REPOSITORY` in the env
+file, or in a `.metergraph/config.json` in the project or a parent directory, is
+kept. If it differs from the remote or `--repository`, setup reports a mismatch
+and changes nothing. Setup never rewrites a config file the SDKs cannot use.
+Remotes with nested groups are not guessed; pass `--repository OWNER/NAME`.
+`--no-repository` records nothing.
+
+The JSON result reports the outcome in `data.repository`: `status` is
+`written`, `existing`, `mismatch`, `invalid_config`, `not_inferred`,
+`write_failed` or `skipped`, with the `repository`, its `source`
+(`git_remote`, `flag`, `config` or `env_file`), the config `path`, and, for a
+mismatch, the `expected` value. Only `owner/name` is reported, never a remote
+URL. Recording an identity never fails setup.
+
+With an identity configured, the SDKs exchange the ingest key for a
+repository-scoped session before sending traces. Without one they keep the
+older ingestion path and log that the identity is not configured; capture
+continues either way.
+
+Several repositories can send to one workspace. Run `setup` once in each
+repository, so each has its own project binding and private `.env`; pass the
+same `--workspace UUID` each time to pin the workspace; and give each
+repository its own identity.
+
 ### Read commands
 
 The read commands use the grant `login` saved for this project. They never open a
@@ -538,14 +605,14 @@ added in `0.2.0-preview.0` and are unavailable in `0.1.0`.
 | 1 | `internal_error` | Unexpected failure inside the CLI. |
 | 2 | `invalid_input` | Unknown command or argument, or an invalid option value. No request was made. |
 | 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. |
+| 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. 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, or `--json --no-browser` needs a browser approval it cannot show (`no_browser_requires_terminal`). 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. |
 | 10 | `authorization_failed` | Browser authorization did not finish: it was denied, cancelled, timed out or returned an invalid callback. Nothing was saved. |
-| 11 | `verification_failed` | The service issued a grant that does not match the requested origin, workspace, client, resource or Metadata scope. Nothing was saved. |
+| 11 | `verification_failed` | The service issued a grant that does not match the requested origin, workspace, client, resource or Metadata scope. Nothing was saved. For `verify`, the exact trace was not confirmed: for example `trace_not_found_within_bounds` when the service kept answering but the trace was not visible before attempts or the deadline ran out. |
 | 12 | `login_required` | No usable sign in for this project: none was saved, it expired, was revoked, lost access or could not be refreshed safely. Run login again. |
 | 13 | `revocation_unconfirmed` | Local credentials were removed, but the service did not confirm that the grant was revoked. |
 | 14 | `capability_unavailable` | The service does not make this read available to the project's Metadata grant. No data was read. |
@@ -776,7 +843,7 @@ To try a packed artifact without publishing:
 
 ```sh
 npm pack --pack-destination "$(mktemp -d)"
-npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.2.tgz -- metergraph --version
+npx --yes --package=/path/to/metergraph-cli-0.2.0-preview.3.tgz -- metergraph --version
 ```
 
 Do not commit tarballs or other generated files.
@@ -785,7 +852,7 @@ Do not commit tarballs or other generated files.
 
 The source of truth is the public repository
 [github.com/metergraph/cli](https://github.com/metergraph/cli), licensed Apache-2.0.
-`0.2.0-preview.2` is published on the `next` npm tag; `latest` remains on
+`0.2.0-preview.3` is published on the `next` npm tag; `latest` remains on
 `0.1.0`. The hosted service supports sign in, Metadata reads and ingest bootstrap.
 Subsequent releases must pass the checks below before publication.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.2",
+  "version": "0.2.0-preview.3",
   "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/args.js

@@ -1,3 +1,4 @@
+import { parseRepository } from "./repository-identity.js";
 import {
   DEFAULT_ORIGIN,
   DEFAULT_TIMEOUT_MS,
@@ -33,7 +34,7 @@ const OPTIONS = {
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
   login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
-  setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file"]),
+  setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file", "--repository"]),
   logout: new Set(["--project", "--config-dir"]),
   status: new Set(READ_BASE),
   context: new Set(READ_BASE),
@@ -75,7 +76,7 @@ const REFUSED_MESSAGES = {
 // Options that take no value.
 const FLAGS = {
   login: new Set(["--signup", "--no-browser", "--reconnect"]),
-  setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites"]),
+  setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites", "--no-repository"]),
   verify: new Set(["--open", "--no-browser"]),
 };
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -388,6 +389,14 @@ function parseSetup(values, flags, json, fail) {
   }
   const envFile = values["--env-file"] ?? ".env";
   if (envFile === "" || envFile.includes("\0")) return fail("invalid_env_file", "--env-file must name a project-relative env file.");
+  const rawRepository = values["--repository"];
+  const repository = rawRepository === undefined ? null : parseRepository(rawRepository);
+  if (rawRepository !== undefined && repository === null) {
+    return fail("invalid_repository", "--repository must be owner/name, for example example-org/example-app.");
+  }
+  if (repository !== null && flags.has("--no-repository")) {
+    return fail("repository_conflict", "Use either --repository or --no-repository, not both.");
+  }
   const rawTimeout = values["--timeout-ms"];
   const timeoutMs = rawTimeout === undefined ? LOGIN_DEFAULT_TIMEOUT_MS :
     parseTimeout(rawTimeout, LOGIN_MIN_TIMEOUT_MS, LOGIN_MAX_TIMEOUT_MS);
@@ -397,7 +406,8 @@ function parseSetup(values, flags, json, fail) {
     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"),
-    signup: flags.has("--signup"), reconnect: flags.has("--reconnect"), json };
+    signup: flags.has("--signup"), reconnect: flags.has("--reconnect"),
+    repository, skipRepository: flags.has("--no-repository"), json };
 }
 
 // Read commands take the project and config directory, one total timeout and,

package/src/auth-login.js

@@ -10,11 +10,11 @@ import {
 } from "./auth-binding.js";
 import {
   authorizationUrl,
+  clientFor,
   discover,
   endpointsFor,
   exchangeCode,
   newPkce,
-  register,
   revoke,
   verifyContext,
 } from "./auth-oauth.js";
@@ -164,10 +164,11 @@ export async function runLogin(options, progress) {
   }
 }
 
-// Preflight, discovery, registration, the browser round trip, the code
-// exchange and server-side verification. Nothing is 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.
+// Preflight, discovery, the client (offered or newly registered), the browser
+// round trip, the code exchange and server-side verification. Nothing is
+// 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) {
   const preflight = await runDoctor({ origin: ctx.origin, timeoutMs: AUTH_HTTP_TIMEOUT_MS });
   if (cancel.aborted) return fail("authorization_failed", "cancelled");
@@ -181,7 +182,7 @@ async function authorize(options, ctx, cancel, progress) {
   let limit = deadline(AUTH_HTTP_TIMEOUT_MS, cancel);
   const discovered = await discover(ctx.origin, limit.signal);
   if (!discovered.ok) return httpFailure(discovered, cancel);
-  const { endpoints, requireIss } = discovered;
+  const { endpoints, requireIss, offeredClientId } = discovered;
 
   const listener = await startCallbackListener();
   let callback;
@@ -189,9 +190,9 @@ async function authorize(options, ctx, cancel, progress) {
   let verifier;
   try {
     limit = deadline(AUTH_HTTP_TIMEOUT_MS, cancel);
-    const registered = await register(endpoints, listener.redirectUri, limit.signal);
-    if (!registered.ok) return httpFailure(registered, cancel);
-    clientId = registered.clientId;
+    const client = await clientFor(endpoints, offeredClientId, listener.redirectUri, limit.signal);
+    if (!client.ok) return httpFailure(client, cancel);
+    clientId = client.clientId;
 
     const pkce = newPkce();
     verifier = pkce.verifier;

package/src/auth-oauth.js

@@ -23,6 +23,12 @@ const ACCESS_TOKEN = /^[\x21-\x7e]{16,8192}$/;
 const REFRESH_TOKEN = /^[\x21-\x7e]{16,4096}$/;
 const MAX_EXPIRES_IN = 366 * 24 * 60 * 60;
 
+// A deployment that configures the Metergraph CLI as a known OAuth client
+// names its client ID in this metadata field, in the authorization server
+// metadata and in the setup discovery document. Without it the CLI registers
+// a new public client for each sign in, as servers without the field expect.
+export const CLI_CLIENT_ID_FIELD = "metergraph_cli_client_id";
+
 // The access token claim that names the workspace the grant is for. The
 // claim is a sanity check only; the CLI does not verify token signatures.
 // The server-authoritative check is GET /v1/agent/workspace.
@@ -109,13 +115,33 @@ export async function discover(origin, signal) {
   ) {
     return stop("unsupported", "revocation_unsupported");
   }
+  const offered = offeredClientId(server);
+  if (offered === undefined) return stop("unsupported", "oauth_metadata_invalid");
   return {
     ok: true,
     endpoints: expected,
     requireIss: server.authorization_response_iss_parameter_supported === true,
+    offeredClientId: offered,
   };
 }
 
+// The client ID a metadata document offers for the CLI: the ID, null when the
+// field is absent or null, or undefined when the value is malformed. A
+// malformed value is refused rather than ignored, like any other bad field.
+export function offeredClientId(doc) {
+  const value = doc[CLI_CLIENT_ID_FIELD];
+  if (value === undefined || value === null) return null;
+  return typeof value === "string" && CLIENT_ID.test(value) ? value : undefined;
+}
+
+// The client for one sign in: the pre-registered client the service offered,
+// or a newly registered one when it offered none. The offered client accepts
+// the loopback redirect on any port, so it needs no registration request.
+export async function clientFor(endpoints, offered, redirectUri, signal) {
+  if (offered !== null) return { ok: true, clientId: offered };
+  return register(endpoints, redirectUri, signal);
+}
+
 async function fetchMetadata(origin, paths, signal) {
   for (const path of paths) {
     const response = await send(origin, path, { signal, maxBytes: METADATA_BYTES });

package/src/cli.js

@@ -105,7 +105,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 human = `Metergraph setup: ${result.data?.status ?? "not_ready"}\n${summary}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 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`}`;
     if (containsKnownCredential(human, routed)) {
       result = envelope({ command: "setup", outcome: "unsupported", reason: "credential_echo" });
       stdout.write(parsed.json ? toJsonLine(result) : "Setup stopped.\n");
@@ -164,3 +165,20 @@ async function run(argv, { stdout, stderr }) {
   stdout.write(parsed.json ? toJsonLine(result) : doctorText(result));
   return result;
 }
+
+// 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) {
+  if (!repository) return "";
+  const where = repository.path ? ` in ${repository.path}` : repository.source === "env_file" ? " in the env file" : "";
+  switch (repository.status) {
+    case "written": return `Repository: ${repository.repository} (recorded${where}; commit it)\n`;
+    case "existing": return repository.repository === null
+      ? `Repository: already set${where}\n` : `Repository: ${repository.repository} (already set${where})\n`;
+    case "mismatch": return `Repository: ${repository.repository} (already set${where}; differs from ${repository.expected}, left unchanged)\n`;
+    case "invalid_config": return `Repository: not recorded (${repository.path} is not a usable config; left unchanged)\n`;
+    case "skipped": return "Repository: not recorded (--no-repository)\n";
+    case "write_failed": return `Repository: not recorded (could not write ${repository.path})\n`;
+    default: return "Repository: not recorded (no owner/name git remote; pass --repository OWNER/NAME)\n";
+  }
+}

package/src/output.js

@@ -112,7 +112,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. Not with --json." },
+  { 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: "--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." },
 ];
@@ -130,6 +130,7 @@ const LOGOUT_USAGE = "metergraph logout [--project DIR] [--config-dir DIR] [--js
 const SETUP_USAGE = "metergraph setup --runtime local (--client codex|claude|cursor | --skip-skill) " +
   "[--url ORIGIN] [--workspace UUID] [--project DIR] [--config-dir DIR] [--env-file .env] " +
   "[--deployment managed|customer-local|byoc|oss] [--confirm-prerequisites] [--agent-token-file FILE] " +
+  "[--repository OWNER/NAME | --no-repository] " +
   "[--timeout-ms N] [--signup] [--reconnect] [--no-browser] [--repair] [--json]";
 const JSON_OPTION = { name: "--json", value: null, summary: "Print one JSON line on stdout." };
 const VERIFY_USAGE =
@@ -310,11 +311,13 @@ 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; requires terminal output." },
+          { name: "--no-browser", value: null, summary: "Print approval URL on stderr. With --json, only a rerun that needs no approval succeeds." },
           { 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." },
           { name: "--agent-token-file", value: "FILE", summary: "Optional separate Metadata token for local/BYOC; required for OSS handoff." },
+          { name: "--repository", value: "OWNER/NAME", summary: "Repository identity to record in .metergraph/config.json when none exists. Default: inferred from the git remote." },
+          { name: "--no-repository", value: null, summary: "Leave the repository identity unrecorded." },
           JSON_OPTION,
         ],
       },

package/src/repository-identity.js

@@ -0,0 +1,246 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+// Repository identity for the SDKs: `.metergraph/config.json` with
+// {"version": 2, "repository": "owner/name"}. The SDKs read
+// METERGRAPH_REPOSITORY first, then the nearest config.json walking up from
+// the app root. The file holds no secret and is meant to be committed.
+//
+// Setup records the identity only when none exists. An existing identity is
+// never changed; a different value from the git remote or --repository is
+// reported as a mismatch for the person to resolve. A git remote URL can
+// carry credentials, so only the parsed owner/name ever leaves this module.
+
+export const CONFIG_PATH = ".metergraph/config.json";
+const CONFIG_VERSION = 2;
+const MAX_CONFIG_BYTES = 16384;
+const MAX_WALK_UP = 64;
+const NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
+const NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
+// One owner and one name, each a plain path segment. Hosts that nest groups
+// (owner/group/name) are not guessed at; pass --repository instead.
+const SEGMENT = /^(?!\.{1,2}$)[A-Za-z0-9_.-]{1,100}$/;
+
+export function parseRepository(value) {
+  if (typeof value !== "string") return null;
+  const parts = value.trim().split("/");
+  if (parts.length !== 2 || !parts.every((part) => SEGMENT.test(part))) return null;
+  return `${parts[0]}/${parts[1]}`;
+}
+
+// owner/name from a git remote URL, or null. Accepts https://host/owner/name,
+// ssh://user@host[:port]/owner/name and user@host:owner/name, each with an
+// optional .git suffix.
+export function repositoryFromRemote(url) {
+  if (typeof url !== "string") return null;
+  const text = url.trim();
+  let pathname = null;
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(text)) {
+    try {
+      const parsed = new URL(text);
+      if (!["https:", "http:", "ssh:", "git:"].includes(parsed.protocol)) return null;
+      pathname = decodeURIComponent(parsed.pathname);
+    } catch {
+      return null;
+    }
+  } else {
+    const scp = /^[^@/\s]+@[^:/\s]+:(.+)$/.exec(text);
+    if (scp === null) return null;
+    pathname = scp[1];
+  }
+  const trimmed = pathname.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "");
+  return parseRepository(trimmed);
+}
+
+function gitEnv() {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (!key.toUpperCase().startsWith("GIT_") ||
+        ["GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_CONFIG_NOSYSTEM", "GIT_CEILING_DIRECTORIES",
+          "GIT_DISCOVERY_ACROSS_FILESYSTEM"].includes(key.toUpperCase())) env[key] = value;
+  }
+  env.GIT_TERMINAL_PROMPT = "0";
+  env.GIT_OPTIONAL_LOCKS = "0";
+  return env;
+}
+
+// Read-only: git runs without a shell, from the project, with fixed arguments.
+function git(root, args) {
+  const result = spawnSync("git", ["-c", "core.fsmonitor=false", ...args], {
+    cwd: root, env: gitEnv(), shell: false, windowsHide: true, timeout: 15000,
+    maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.error?.code === "ENOENT") return { missing: true, out: null };
+  if (result.error || result.status !== 0) return { missing: false, out: null };
+  return { missing: false, out: result.stdout.toString("utf8").trim() };
+}
+
+// The origin remote, or the only remote when there is exactly one. Returns
+// { repository, reason } and never the URL itself.
+export function inferFromGit(root) {
+  const inside = git(root, ["rev-parse", "--is-inside-work-tree"]);
+  if (inside.missing) return { repository: null, reason: "git_unavailable" };
+  if (inside.out !== "true") return { repository: null, reason: "not_a_git_repository" };
+  let url = git(root, ["config", "--get", "remote.origin.url"]).out;
+  if (url === null) {
+    const remotes = (git(root, ["remote"]).out ?? "").split("\n").filter(Boolean);
+    if (remotes.length !== 1) return { repository: null, reason: remotes.length ? "remote_ambiguous" : "no_remote" };
+    url = git(root, ["config", "--get", `remote.${remotes[0]}.url`]).out;
+  }
+  const repository = repositoryFromRemote(url);
+  return repository ? { repository, reason: null } : { repository: null, reason: "remote_unrecognized" };
+}
+
+function readConfig(file) {
+  // Check the type before opening: opening a FIFO for reading would block.
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return { exists: false };
+    return { exists: true, invalid: true };
+  }
+  if (!stat.isFile()) return { exists: true, invalid: true };
+  let fd;
+  try {
+    // O_NONBLOCK also covers a file swapped for a FIFO after the check.
+    fd = fs.openSync(file, fs.constants.O_RDONLY | NONBLOCK);
+  } catch {
+    return { exists: true, invalid: true };
+  }
+  try {
+    if (!fs.fstatSync(fd).isFile()) return { exists: true, invalid: true };
+    const buffer = Buffer.alloc(MAX_CONFIG_BYTES + 1);
+    const length = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    if (length > MAX_CONFIG_BYTES) return { exists: true, invalid: true };
+    const doc = JSON.parse(buffer.subarray(0, length).toString("utf8"));
+    if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return { exists: true, invalid: true };
+    return { exists: true, doc };
+  } catch {
+    return { exists: true, invalid: true };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// The nearest config.json walking up from root, as the SDKs search.
+function nearestConfig(root) {
+  let dir = root;
+  for (let i = 0; i < MAX_WALK_UP; i += 1) {
+    const file = path.join(dir, CONFIG_PATH);
+    const found = readConfig(file);
+    if (found.exists) return { ...found, rel: path.relative(root, file).split(path.sep).join("/") };
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Writes a temporary file, then links it into place: link never replaces an
+// existing entry, so a config that appeared meanwhile is kept, and a failed
+// write never leaves a partial config.json behind.
+function writeNewConfig(root, repository) {
+  const dir = path.join(root, ".metergraph");
+  try {
+    if (!fs.lstatSync(dir).isDirectory()) throw new Error("unsafe_path");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    fs.mkdirSync(dir, { mode: 0o755 });
+  }
+  const dest = path.join(dir, "config.json");
+  const temp = path.join(dir, `.config.json.${process.pid}.${Date.now()}.tmp`);
+  const content = `${JSON.stringify({ version: CONFIG_VERSION, repository }, null, 2)}\n`;
+  try {
+    const fd = fs.openSync(temp, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | NOFOLLOW, 0o644);
+    try { fs.writeFileSync(fd, content); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+    fs.linkSync(temp, dest);
+  } finally {
+    try { fs.unlinkSync(temp); } catch { /* already gone */ }
+  }
+}
+
+const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+
+// METERGRAPH_REPOSITORY from the project env file, read only, so an identity
+// the person already set there is respected. Setup has validated envFile as
+// project-relative before this runs. Returns null when unset or unreadable.
+export function envRepository(root, envFile) {
+  let text;
+  try {
+    const file = path.join(root, envFile);
+    if (fs.lstatSync(file).size > 1024 * 1024) return null;
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  let value = null;
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*(?:export\s+)?METERGRAPH_REPOSITORY\s*=\s*(.*?)\s*$/.exec(line);
+    if (match === null) continue;
+    let raw = match[1];
+    const quoted = /^(["'])(.*?)\1(?:\s+#.*)?$/.exec(raw);
+    raw = quoted ? quoted[2] : raw.replace(/\s+#.*$/, "");
+    value = raw.trim() || null;
+  }
+  return value;
+}
+
+// Ensures the project has a repository identity and returns the setup result
+// field. requested is a validated --repository value or null; envValue is
+// METERGRAPH_REPOSITORY from the project env file, or null.
+export function ensureRepositoryIdentity(root, { requested = null, skip = false, envValue = null, retried = false } = {}) {
+  if (skip) return { status: "skipped", repository: null, source: null, path: null, reason: null };
+  const inferred = requested === null ? inferFromGit(root) : { repository: requested, reason: null };
+  const expected = inferred.repository;
+  const expectedSource = requested === null ? "git_remote" : "flag";
+
+  // The SDK uses any env value containing "/". Respect it, but report only a
+  // parsed owner/name: the env file also holds secrets, so a raw value is
+  // never echoed.
+  if (typeof envValue === "string" && envValue.includes("/")) {
+    const current = parseRepository(envValue);
+    if (current === null) {
+      return { status: "existing", repository: null, source: "env_file", path: null,
+        reason: "env_value_unrecognized" };
+    }
+    const mismatch = expected !== null && !same(current, expected);
+    return { status: mismatch ? "mismatch" : "existing", repository: current, source: "env_file",
+      path: null, reason: mismatch ? `${expectedSource}_differs` : null, ...(mismatch ? { expected } : {}) };
+  }
+
+  const found = nearestConfig(root);
+  if (found !== null) {
+    const raw = found.invalid ? null : found.doc.repository;
+    const usable = !found.invalid && (found.doc.version === undefined || found.doc.version === CONFIG_VERSION) &&
+      typeof raw === "string" && raw.includes("/");
+    if (!usable) {
+      // Never rewrite an existing config; the person fixes it.
+      return { status: "invalid_config", repository: null, source: "config", path: found.rel,
+        reason: "config_unusable", ...(expected !== null ? { expected } : {}) };
+    }
+    // The SDK accepts any value containing "/"; report it only as owner/name.
+    const current = parseRepository(raw);
+    if (current === null) {
+      return { status: "existing", repository: null, source: "config", path: found.rel,
+        reason: "config_value_unrecognized" };
+    }
+    const mismatch = expected !== null && !same(current, expected);
+    return { status: mismatch ? "mismatch" : "existing", repository: current, source: "config", path: found.rel,
+      reason: mismatch ? `${expectedSource}_differs` : null, ...(mismatch ? { expected } : {}) };
+  }
+
+  if (expected === null) {
+    return { status: "not_inferred", repository: null, source: null, path: null, reason: inferred.reason };
+  }
+  try {
+    writeNewConfig(root, expected);
+  } catch (error) {
+    // Another setup created it first: report what is there now.
+    if (error.code === "EEXIST" && !retried) return ensureRepositoryIdentity(root, { requested, envValue, retried: true });
+    return { status: "write_failed", repository: null, source: expectedSource, path: CONFIG_PATH,
+      reason: "config_not_written", expected };
+  }
+  return { status: "written", repository: expected, source: expectedSource, path: CONFIG_PATH, reason: null };
+}

package/src/setup.js

@@ -2,13 +2,14 @@ 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 { newPkce, register, endpointsFor } from "./auth-oauth.js";
+import { clientFor, endpointsFor, newPkce, offeredClientId } from "./auth-oauth.js";
 import { Stop } from "./auth-store.js";
 import { verifiedSession } from "./auth-session.js";
 import { AUTH_HTTP_TIMEOUT_MS } from "./constants.js";
 import { preflightEnv, currentEnvValues, commitEnv, isAppToken } from "./setup-env.js";
 import { newSetupState, readSetupState, setupReceipt, withSetupState, writeSetupState } from "./setup-state.js";
 import { runSkill } from "./skill.js";
+import { ensureRepositoryIdentity, envRepository } from "./repository-identity.js";
 import { parseJsonObject } from "./http.js";
 import { deadline, failureOf, send, trapSignals } from "./transport.js";
 
@@ -23,8 +24,15 @@ 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 } });
+  data: { status, application_traffic_verified: false, receipt,
+    next_action: reason === "no_browser_requires_terminal" ? RUN_IN_TERMINAL : null } });
 
 // This command never receives an ingest key from argv, stdin, an environment
 // variable or a Metadata OAuth grant. Only the purpose-bound redemption
@@ -159,9 +167,10 @@ export async function runSetup(options, progress = () => {}) {
     let clientId;
     let pkce;
     try {
-      const registered = await register(endpointsFor(origin), listener.redirectUri, deadline(AUTH_HTTP_TIMEOUT_MS, trap.signal).signal);
-      if (!registered.ok) return stop(registered.outcome, registered.reason);
-      clientId = registered.clientId;
+      const client = await clientFor(endpointsFor(origin), setup.offeredClientId, listener.redirectUri,
+        deadline(AUTH_HTTP_TIMEOUT_MS, trap.signal).signal);
+      if (!client.ok) return stop(client.outcome, client.reason);
+      clientId = client.clientId;
       pkce = newPkce();
       const pending = listener.wait({ state: pkce.state, issuer: `${origin}/v1/oauth`, requireIss: false,
         timeoutMs: options.timeoutMs, cancel: trap.signal });
@@ -225,7 +234,8 @@ function finishSkill(root, options, envStatus) {
       previous = readSetupState(root);
     }
     return { outcome: "ok", reason: null, data: { status: "ready_for_instrumentation",
-      application_traffic_verified: false, env: envStatus, skill: "skipped", receipt: setupReceipt(previous.value) } };
+      application_traffic_verified: false, env: envStatus, skill: "skipped", receipt: setupReceipt(previous.value),
+      repository: repositoryIdentity(root, options), next_action: null } };
   }
   let skill = runSkill({ action: "install", client: options.client, runtime: "local", project: root });
   if (skill.reason === "update_required") {
@@ -252,7 +262,18 @@ function finishSkill(root, options, envStatus) {
   }
   return { outcome: "ok", reason: null, data: { status: "ready_for_instrumentation",
     application_traffic_verified: false, env: envStatus, skill: skill.data.status,
-    receipt: setupReceipt(previous.value) } };
+    receipt: setupReceipt(previous.value), repository: repositoryIdentity(root, options), next_action: null } };
+}
+
+// Records the repository identity the SDKs read, after the credential is
+// ready. It never fails setup and never changes an existing identity; the
+// returned field says what was found, written or left for the person.
+function repositoryIdentity(root, options) {
+  return ensureRepositoryIdentity(root, {
+    requested: options.repository ?? null,
+    skip: options.skipRepository === true,
+    envValue: envRepository(root, options.envFile ?? ".env"),
+  });
 }
 
 async function discoverSetup(origin, profile, cancel) {
@@ -273,7 +294,9 @@ async function discoverSetup(origin, profile, cancel) {
     !Array.isArray(doc.code_challenge_methods_supported) || !doc.code_challenge_methods_supported.includes("S256")) {
     return { ok: false, outcome: "unsupported", reason: "setup_contract_mismatch" };
   }
-  return { ok: true };
+  const offered = offeredClientId(doc);
+  if (offered === undefined) return { ok: false, outcome: "unsupported", reason: "setup_contract_mismatch" };
+  return { ok: true, offeredClientId: offered };
 }
 
 async function redeem(origin, form, profile, cancel) {

package/src/verify.js

@@ -28,15 +28,19 @@ export async function runVerify(options, dependencies = {}) {
   const limit = deadline(timeoutMs, cancel);
   let known = [];
   let receipt = null;
+  let found = false;
   let attempts = 0;
   const end = (outcome, reason, data = receipt) => {
     if (holdsKnown(data, known)) return { outcome: "verification_failed", reason: "credential_in_metadata_response", data: null };
     return { outcome, reason, data: data === null ? null : { ...data, attempts } };
   };
   // Once the origin has answered with a valid pending receipt, a deadline
-  // means the trace is not visible yet, not that the origin is unreachable.
+  // means the trace is not visible yet, exactly as when attempts run out.
+  // Only a deadline with no valid answer is reported as a connection failure.
+  // A deadline while opening an already found trace keeps the timeout reason.
   const interrupted = () => !limit.timedOut() ? end("cancelled", "cancelled")
-    : end(receipt === null ? "connection_failed" : "verification_failed", "verification_timeout");
+    : receipt === null ? end("connection_failed", "verification_timeout")
+      : end("verification_failed", found ? "verification_timeout" : "trace_not_found_within_bounds");
   try {
     const sessionResult = await (dependencies.session ?? verifiedSession)({ project: options.project, configDir: options.configDir, cancel: limit.signal });
     if (limit.signal.aborted) return interrupted();
@@ -58,6 +62,7 @@ export async function runVerify(options, dependencies = {}) {
       receipt = checked.value;
       if (holdsKnown(receipt, known)) return end("verification_failed", "credential_in_metadata_response", null);
       if (checked.found) {
+        found = true;
         if (options.open) {
           const opened = await openTrace(receipt, { ...options, signal: limit.signal }, dependencies.launch);
           if (limit.signal.aborted) return interrupted();