metergraph-cli 0.2.0-preview.5 → 0.2.0

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;