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

package/assets/skill/SKILL.md

@@ -7,6 +7,10 @@ description: Route Metergraph setup by client, execution runtime and deployment,
 
 Public setup: https://www.metergraph.dev/docs/guides/agent-access/
 Connection and troubleshooting: https://www.metergraph.dev/docs/guides/agent-access/
+Documentation index, every public page with a one-line summary: https://www.metergraph.dev/llms.txt
+
+If a step fails or something is unclear, look it up in that index before
+improvising, asking for new credentials or stopping.
 
 ## Confirm setup before producing instructions
 
@@ -22,12 +26,28 @@ Use the routing below with those four choices. Follow the matching credential an
 For a first application trace, check the installed CLI's version and help before
 using it. `metergraph-cli@0.1.0` supports `doctor` and project skill
 installation; later versions may also offer `login`, `setup` and `verify`.
-Use those commands only if the installed package lists them. Use the [first
+Use those commands only if the installed package lists them. Install this skill
+with whichever the installed CLI lists, `metergraph setup --client <client>` or
+`metergraph skill install --client <client> --runtime local`, not by copying this
+file into the project: the CLI never replaces a skill file it did not install. Pass `--skip-skill` to `setup` when the person chose not to
+install the skill. Use the [first
 trace guide](https://www.metergraph.dev/docs/start/first-trace/) for steps the
 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.
 
+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
+`.metergraph/config.json` when none exists, reports a different existing value
+instead of changing it, and skips this with `--no-repository`. Otherwise, with the
+person's agreement, add `.metergraph/config.json` containing
+`{"version": 2, "repository": "owner/name"}`; it holds no secret, so show the diff
+and let them commit it. For several repositories, run setup once per repository,
+pass the same `--workspace` UUID each time, and give each repository its own
+identity. The SDK warning that repository identity is not configured does not
+stop capture.
+
 ## Route honestly
 
 | Client and runtime | Hosted | Customer-local bundle | Customer AWS | Open source self-hosted |
@@ -70,4 +90,4 @@ Use https://www.metergraph.dev/docs/ for public product documentation and https:
 4. Explain the failure or anomaly using only returned evidence. Cite workspace, time window, provenance, trace/report IDs, completeness/coverage, warnings and working app links when returned. Do not fabricate links. Distinguish no data, incomplete evidence, unavailable capability, classification pending, stale/mismatched identity, failed analysis and missing report. An empty result alone does not prove absence of traffic.
 5. An optional approved replay must be eligible, bounded and non-persistent. Do not claim that it changed production telemetry or fixed the application. Refuse autonomous dashboard mutations or production configuration changes.
 
-For an empty workspace, use https://www.metergraph.dev/docs/agents/instrument-a-repo/ after confirming the ingestion destination and obtaining a separate ingest credential securely. Do not initiate provider calls or paid work merely to validate setup. Ingestion accepted, processed, retained content, classification readiness and analysis readiness are distinct states. Label synthetic/demo fixtures; they do not prove a first real application trace.
+For an empty workspace, use https://www.metergraph.dev/docs/agents/instrument-a-repo/. If `metergraph setup` already ran in this project, it delivered the ingest credential: the project's `.env` holds `METERGRAPH_APP_TOKEN` and `METERGRAPH_INGEST_URL`. Use them; do not ask for or create another key, and never print their values. The SDK reads the process environment, not `.env`, so load it when you run the application (for example `set -a; . ./.env; set +a`, python-dotenv or `node --env-file=.env`). Otherwise confirm the ingestion destination and obtain a separate ingest credential securely. Ask before running anything that calls a paid model provider, and do not initiate provider calls or paid work merely to validate setup. Confirm the exact trace with `metergraph verify`; if the CLI is not installed, or `metergraph --version` lacks `verify`, use `npx --yes metergraph-cli@next verify`. Ingestion accepted, processed, retained content, classification readiness and analysis readiness are distinct states. Label synthetic/demo fixtures; they do not prove a first real application trace.

package/assets/skill/manifest.json

@@ -3,7 +3,7 @@
   "name": "metergraph",
   "file": "SKILL.md",
   "source_url": "https://www.metergraph.dev/SKILL.md",
-  "sha256": "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891",
-  "size": 10426,
-  "revision": "sha256-57b920677adf"
+  "sha256": "8b81eb27b6159c4447a5c300409c4c64917238b7797f5ee37a35248cba50fcae",
+  "size": 12436,
+  "revision": "sha256-8b81eb27b615"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "metergraph-cli",
-  "version": "0.2.0-preview.2",
+  "version": "0.2.0-preview.4",
   "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/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 = "57b920677adf62759c7221629327192a2d16b7e6034f7948ffd96cee402d4891";
+const PINNED_SHA256 = "8b81eb27b6159c4447a5c300409c4c64917238b7797f5ee37a35248cba50fcae";
 
 const ASSET_DIR = new URL("../assets/skill/", import.meta.url);
 const MANIFEST_KEYS = ["file", "manifest_version", "name", "revision", "sha256", "size", "source_url"];