primcli 1.74.1 → 3.0.0-preview.1

package/dist/{api-command-fKP3NYa7.js → api-command-ctHBqTL5.js}

@@ -1,11 +1,603 @@
-import { $ as AutomatedFilterUnsupportedError, Cn as sdk_gen_exports, F as assertAwaitingFilterRows, Ft as getEmail, G as WEBHOOK_EVENT_TYPES, I as awaitingRejectedError, L as ensureSearchReportsReplyState, P as ReplyStateUnsupportedError, U as replyStateSurfaceForOperation, V as isAwaitingRejectedError, W as SENT_EMAIL_EVENT_TYPES, Wt as getThread, et as assertAutomatedVerdict, it as expectedAutomatedVerdicts, nn as listEndpoints, nt as automatedSurfaceForOperation, ot as isAutomatedRejectedError, rt as ensureSearchReportsAutomated, tt as automatedRejectedError, v as parseRetryAfter } from "./repeats-BL7ZC-_6-B_ESsWTH.js";
-import { C as resolveCliAuth, G as PrimitiveApiClient, I as agentProfilesDirectory, M as AGENT_PROFILE_ENV, P as agentProfileDirectory, S as normalizeApiBaseUrl, T as saveSignupCredentials, U as requireDefaultLoginProfile, _ as deleteCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, i as loadCliConfig, m as cliAccessTokenExpiresAt, p as acquireCliCredentialsLock, w as saveCliCredentials, x as loadCliCredentials, y as detectPrimitiveKeyEnvMisname, z as loadConnectedAgentProfile } from "./cli-config-C0Y_Ppol.js";
-import { d as readMailJson, h as writeMailJson, m as withMailLock, p as syncMailDirectory, u as privateMailPermissions } from "./shared-mail-files-CZfm7E2k.js";
+import { $ as AutomatedFilterUnsupportedError, An as sdk_gen_exports, F as assertAwaitingFilterRows, G as WEBHOOK_EVENT_TYPES, I as awaitingRejectedError, It as getEmail, Kt as getThread, L as ensureSearchReportsReplyState, P as ReplyStateUnsupportedError, U as replyStateSurfaceForOperation, V as isAwaitingRejectedError, W as SENT_EMAIL_EVENT_TYPES, et as assertAutomatedVerdict, it as expectedAutomatedVerdicts, nt as automatedSurfaceForOperation, on as listEndpoints, ot as isAutomatedRejectedError, rt as ensureSearchReportsAutomated, tt as automatedRejectedError, v as parseRetryAfter } from "./repeats-Dj_o6c-X-Bf9G0xds.js";
+import { C as saveCliCredentials, F as agentProfilesDirectory, H as requireDefaultLoginProfile, N as agentProfileDirectory, R as loadConnectedAgentProfile, S as resolveCliAuth, W as PrimitiveApiClient, _ as deleteCliCredentials, b as loadCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, i as loadCliConfig, j as AGENT_PROFILE_ENV, m as cliAccessTokenExpiresAt, p as acquireCliCredentialsLock, w as saveSignupCredentials, x as normalizeApiBaseUrl, y as detectPrimitiveKeyEnvMisname } from "./cli-config-Ms_0vNjq.js";
+import "./oclif/global-org-flag.js";
+import { d as readMailJson, h as writeMailJson, m as withMailLock, p as syncMailDirectory, u as privateMailPermissions } from "./shared-mail-files-BAQSGxxz.js";
 import { Command, Errors, Flags } from "@oclif/core";
 import { existsSync, lstatSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-//#region src/oclif/api-client.ts
+// src/oclif/user-grant.ts
+/**
+* CLI user logins: a login as the person, not bound to one organization,
+* that switches between the person's organizations without logging in again.
+*
+* The saved login holds the person's identity token (`prim_uat_`, short
+* lived) and refresh token (`prim_urt_`). Neither calls the API: the
+* identity token only lists organizations (`GET /v1/cli/orgs`) and is
+* exchanged (RFC 8693, at `/oauth/token`) for a short-lived access token in
+* one organization. That per-org token is what every other command sends.
+* It cannot be refreshed, so the CLI exchanges again when it expires or
+* when the API answers 401.
+*
+* Saved logins made by older CLIs, and logins against servers without this
+* feature, keep their org-bound OAuth format (`auth_method: "oauth"`) and
+* never reach this module.
+*/
+const TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+const ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
+/** Exchange or refresh this long before a token's stated expiry. */
+const TOKEN_SKEW_MS = 6e4;
+/** Cached tokens for organizations other than the current one. */
+const MAX_CACHED_ORG_TOKENS = 20;
+const USER_LOGIN_EXPIRED_MESSAGE = "Saved Primitive CLI login expired or was revoked. Run `primitive login` to sign in again.";
+const NO_CURRENT_ORG_MESSAGE = "No organization is selected for this login. Run `primitive orgs` to see where you can use the CLI, then `primitive org use <org>`.";
+const REFUSAL_FALLBACK_MESSAGES = {
+	not_a_member: "You are not a member of this organization.",
+	cli_access_disabled_by_org: "This organization does not allow CLI access.",
+	role_insufficient: "Your role in this organization does not allow CLI access. Ask an owner or admin to allow CLI access for members.",
+	cli_access_revoked: "Your CLI access to this organization was revoked. Run `primitive login` again to sign in afresh.",
+	grant_not_available: "The requested grant is not available for CLI logins on this server."
+};
+/** A refusal from the exchange or the org list, with the server's reason. */
+var CliOrgRefusedError = class extends Errors.CLIError {
+	reason;
+	orgId;
+	constructor(params) {
+		super(params.message, {
+			code: params.reason,
+			exit: 1
+		});
+		this.reason = params.reason;
+		this.orgId = params.orgId;
+	}
+};
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function apiOrigin(apiBaseUrl) {
+	const url = new URL(apiBaseUrl);
+	url.search = "";
+	url.hash = "";
+	return url;
+}
+function oauthEndpoint(apiBaseUrl, path) {
+	const url = apiOrigin(apiBaseUrl);
+	url.pathname = path;
+	return url.toString();
+}
+function cliOrgsEndpoint(apiBaseUrl) {
+	const url = apiOrigin(apiBaseUrl);
+	url.pathname = `${url.pathname.replace(/\/+$/, "")}/cli/orgs`;
+	return url.toString();
+}
+function expiringSoon(expiresAt, now) {
+	const at = Date.parse(expiresAt);
+	return !Number.isFinite(at) || at <= now() + TOKEN_SKEW_MS;
+}
+function isUuid(value) {
+	return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+function isOrgAccessToken(value) {
+	return isRecord(value) && typeof value.access_token === "string" && value.access_token.length > 0 && value.token_type === "Bearer" && typeof value.expires_in === "number" && value.expires_in > 0 && typeof value.org_id === "string" && (value.org_name === null || typeof value.org_name === "string") && typeof value.oauth_grant_id === "string";
+}
+function orgTokenFromResponse(token, now = Date.now) {
+	return {
+		access_token: token.access_token,
+		expires_at: cliAccessTokenExpiresAt(token.expires_in, now),
+		oauth_grant_id: token.oauth_grant_id,
+		org_id: token.org_id,
+		org_name: token.org_name ?? null,
+		role: typeof token.role === "string" ? token.role : null
+	};
+}
+/**
+* The org-bound view every other command reads: the per-org token in the
+* standard fields, the person's grant kept alongside.
+*/
+function credentialsForOrg(credentials, org) {
+	return {
+		...credentials,
+		access_token: org.access_token,
+		expires_at: org.expires_at,
+		oauth_grant_id: org.oauth_grant_id,
+		org_id: org.org_id,
+		org_name: org.org_name
+	};
+}
+function requireUserGrant(credentials) {
+	if (credentials.auth_method !== "user_grant" || !credentials.user_grant) throw new Errors.CLIError("This saved login is bound to one organization. Run `primitive logout`, then `primitive login`, to sign in as yourself and switch between organizations.", { exit: 1 });
+	return credentials.user_grant;
+}
+async function postTokenEndpoint(params) {
+	const fetchImpl = params.fetch ?? fetch;
+	let response;
+	try {
+		response = await fetchImpl(oauthEndpoint(params.apiBaseUrl, params.path ?? "/oauth/token"), {
+			body: new URLSearchParams(params.body),
+			headers: {
+				...params.headers ?? {},
+				"content-type": "application/x-www-form-urlencoded"
+			},
+			method: "POST"
+		});
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		throw new Errors.CLIError(`Could not reach the Primitive OAuth token endpoint: ${detail}`, { exit: 1 });
+	}
+	const payload = await response.json().catch(() => null);
+	if (response.ok && isRecord(payload)) return {
+		ok: true,
+		payload
+	};
+	if (response.ok && params.allowEmptySuccess) return {
+		ok: true,
+		payload: {}
+	};
+	const record = isRecord(payload) ? payload : {};
+	return {
+		ok: false,
+		status: response.status,
+		error: typeof record.error === "string" ? record.error : null,
+		description: typeof record.error_description === "string" ? record.error_description : null,
+		reason: typeof record.reason === "string" ? record.reason : null
+	};
+}
+/**
+* Refresh the identity token when it is about to expire. The refresh token
+* rotates on every use, so the new pair is saved before it is used.
+* `invalid_grant` means the login is gone: the saved login is removed.
+*/
+async function freshIdentity(params) {
+	const grant = requireUserGrant(params.credentials);
+	if (!params.force && !expiringSoon(grant.expires_at, params.now)) return params.credentials;
+	const result = await postTokenEndpoint({
+		apiBaseUrl: params.apiBaseUrl,
+		body: {
+			client_id: params.credentials.oauth_client_id,
+			grant_type: "refresh_token",
+			refresh_token: params.credentials.refresh_token
+		},
+		fetch: params.fetch,
+		headers: params.headers
+	});
+	if (!result.ok) {
+		if (result.error === "invalid_grant") {
+			deleteCliCredentials(params.configDir);
+			throw new Errors.CLIError(USER_LOGIN_EXPIRED_MESSAGE, { exit: 1 });
+		}
+		throw new Errors.CLIError(`Could not refresh the saved Primitive CLI login${result.description ? `: ${result.description}` : "."}`, { exit: 1 });
+	}
+	const payload = result.payload;
+	if (typeof payload.access_token !== "string" || typeof payload.refresh_token !== "string" || typeof payload.expires_in !== "number" || payload.expires_in <= 0) throw new Errors.CLIError("Primitive OAuth token endpoint returned an unexpected refresh response.", { exit: 1 });
+	const next = {
+		...params.credentials,
+		refresh_token: payload.refresh_token,
+		user_grant: {
+			...grant,
+			access_token: payload.access_token,
+			expires_at: cliAccessTokenExpiresAt(payload.expires_in, params.now)
+		}
+	};
+	saveCliCredentials(params.configDir, next);
+	return next;
+}
+function refusalMessage(reason, description) {
+	return description ?? (reason ? REFUSAL_FALLBACK_MESSAGES[reason] : void 0) ?? "Primitive refused access to this organization.";
+}
+/** One exchange of the identity token for an access token in `orgId`. */
+async function exchangeForOrg(params) {
+	const body = {
+		client_id: params.clientId,
+		grant_type: TOKEN_EXCHANGE_GRANT_TYPE,
+		org: params.orgId,
+		subject_token: params.identityToken,
+		subject_token_type: ACCESS_TOKEN_TYPE
+	};
+	if (params.requestedGrant) body.requested_grant = params.requestedGrant;
+	const result = await postTokenEndpoint({
+		apiBaseUrl: params.apiBaseUrl,
+		body,
+		fetch: params.fetch,
+		headers: params.headers
+	});
+	if (!result.ok) return result;
+	if (!isOrgAccessToken(result.payload)) throw new Errors.CLIError("Primitive OAuth token endpoint returned an unexpected token exchange response.", { exit: 1 });
+	return {
+		ok: true,
+		token: result.payload
+	};
+}
+/**
+* Exchange for `orgId`, refreshing the identity token first when needed and
+* once more if the exchange says it expired. Saves the result: as the
+* current organization when `makeCurrent`, otherwise in the per-org cache.
+* Must run while the credentials lock is held.
+*/
+async function exchangeAndSave(params) {
+	let credentials = await freshIdentity(params);
+	let attempt = 0;
+	for (;;) {
+		const grant = requireUserGrant(credentials);
+		const result = await exchangeForOrg({
+			apiBaseUrl: params.apiBaseUrl,
+			clientId: credentials.oauth_client_id,
+			fetch: params.fetch,
+			headers: params.headers,
+			identityToken: grant.access_token,
+			orgId: params.orgId,
+			requestedGrant: grant.requested_grant ?? null
+		});
+		if (result.ok) {
+			const org = orgTokenFromResponse(result.token, params.now);
+			const saved = saveOrgToken(credentials, org, params.makeCurrent);
+			saveCliCredentials(params.configDir, saved);
+			return {
+				credentials: saved,
+				org
+			};
+		}
+		if (result.error === "invalid_grant" && attempt === 0) {
+			attempt += 1;
+			credentials = await freshIdentity({
+				...params,
+				credentials,
+				force: true
+			});
+			continue;
+		}
+		if (result.error === "invalid_grant") {
+			deleteCliCredentials(params.configDir);
+			throw new Errors.CLIError(USER_LOGIN_EXPIRED_MESSAGE, { exit: 1 });
+		}
+		if (result.error === "unsupported_grant_type") throw new Errors.CLIError("This Primitive server does not support switching organizations for CLI logins. Run `primitive logout`, then `primitive login`, to sign in to one organization.", { exit: 1 });
+		if (result.reason) throw new CliOrgRefusedError({
+			message: refusalMessage(result.reason, result.description),
+			orgId: params.orgId,
+			reason: result.reason
+		});
+		throw new Errors.CLIError(`Could not get an access token for organization ${params.orgId}${result.description ? `: ${result.description}` : "."}`, { exit: 1 });
+	}
+}
+function saveOrgToken(credentials, org, makeCurrent) {
+	const grant = requireUserGrant(credentials);
+	const cache = { ...grant.org_tokens };
+	if (makeCurrent) {
+		if (credentials.org_id && credentials.access_token) cache[credentials.org_id] = {
+			access_token: credentials.access_token,
+			expires_at: credentials.expires_at,
+			oauth_grant_id: credentials.oauth_grant_id,
+			org_id: credentials.org_id,
+			org_name: credentials.org_name,
+			role: grant.org_role ?? null
+		};
+		delete cache[org.org_id];
+		return {
+			...credentialsForOrg(credentials, org),
+			user_grant: {
+				...grant,
+				org_role: org.role,
+				org_tokens: pruneOrgTokens(cache)
+			}
+		};
+	}
+	if (org.org_id === credentials.org_id) return {
+		...credentialsForOrg(credentials, org),
+		user_grant: {
+			...grant,
+			org_role: org.role
+		}
+	};
+	cache[org.org_id] = org;
+	return {
+		...credentials,
+		user_grant: {
+			...grant,
+			org_tokens: pruneOrgTokens(cache)
+		}
+	};
+}
+function pruneOrgTokens(cache) {
+	const entries = Object.entries(cache).sort(([, left], [, right]) => Date.parse(right.expires_at) - Date.parse(left.expires_at));
+	return Object.fromEntries(entries.slice(0, MAX_CACHED_ORG_TOKENS));
+}
+/** The organizations the person can switch to. */
+async function fetchCliOrgs(params) {
+	const now = params.now ?? Date.now;
+	let credentials = params.credentials;
+	requireUserGrant(credentials);
+	const grant = credentials.user_grant;
+	if (expiringSoon(grant.expires_at, now)) credentials = await withLock(params, () => {
+		const current = loadCliCredentials(params.configDir) ?? credentials;
+		return freshIdentity({
+			...params,
+			credentials: current,
+			now
+		});
+	});
+	const request = async (token) => (params.fetch ?? fetch)(cliOrgsEndpoint(params.apiBaseUrl), {
+		headers: {
+			...params.headers ?? {},
+			authorization: `Bearer ${token}`
+		},
+		method: "GET"
+	});
+	let response = await request(credentials.user_grant.access_token);
+	if (response.status === 401) {
+		credentials = await withLock(params, () => {
+			const current = loadCliCredentials(params.configDir) ?? credentials;
+			return freshIdentity({
+				...params,
+				credentials: current,
+				force: true,
+				now
+			});
+		});
+		response = await request(credentials.user_grant.access_token);
+	}
+	const payload = await response.json().catch(() => null);
+	if (!response.ok) {
+		const error = isRecord(payload) && isRecord(payload.error) ? payload.error : {};
+		if (response.status === 404 && error.code === "feature_disabled") throw new Errors.CLIError("This Primitive server does not support switching organizations for CLI logins.", { exit: 1 });
+		throw new Errors.CLIError(`Could not list organizations${typeof error.message === "string" ? `: ${error.message}` : ` (HTTP ${response.status}).`}`, { exit: 1 });
+	}
+	const data = isRecord(payload) ? payload.data : null;
+	if (!isRecord(data) || !Array.isArray(data.orgs)) throw new Errors.CLIError("Primitive API returned an unexpected organization list.", { exit: 1 });
+	return data;
+}
+/** How long a command waits for another CLI process to finish with the saved login. */
+const LOCK_WAIT_MS = 15e3;
+const LOCK_RETRY_MS = 100;
+function isLockBusy(error) {
+	return error instanceof Error && error.message.startsWith("Another Primitive CLI credential operation is already in progress");
+}
+/**
+* Run `fn` holding the credentials lock. Exchanges happen every few minutes
+* and from parallel commands, so a busy lock is waited for (briefly) rather
+* than refused; callers re-read the saved login once they hold it.
+*/
+async function withLock(params, fn) {
+	let release;
+	if (!params.credentialsLockHeld) {
+		const deadline = Date.now() + LOCK_WAIT_MS;
+		for (;;) try {
+			release = acquireCliCredentialsLock(params.configDir);
+			break;
+		} catch (error) {
+			if (isLockBusy(error) && Date.now() < deadline) {
+				await new Promise((done) => setTimeout(done, LOCK_RETRY_MS));
+				continue;
+			}
+			if (isLockBusy(error)) throw new Errors.CLIError("Another Primitive CLI command is still updating the saved login. Retry in a moment.", { exit: 1 });
+			const detail = error instanceof Error ? error.message : String(error);
+			throw new Errors.CLIError(detail, { exit: 1 });
+		}
+	}
+	try {
+		return await fn();
+	} finally {
+		release?.();
+	}
+}
+/**
+* Match `selection` (an organization id, or a name) against the person's
+* organizations. Ids pass through without a lookup.
+*/
+function matchOrg(selection, orgs) {
+	const wanted = selection.trim();
+	const byId = orgs.find((org) => org.id.toLowerCase() === wanted.toLowerCase());
+	if (byId) return byId;
+	const byName = orgs.filter((org) => (org.name ?? "").trim().toLowerCase() === wanted.toLowerCase());
+	if (byName.length === 1) return byName[0];
+	if (byName.length > 1) throw new Errors.CLIError(`More than one organization is named ${JSON.stringify(wanted)}. Use its id: ${byName.map((org) => org.id).join(", ")}.`, { exit: 1 });
+	throw new Errors.CLIError(`No organization matches ${JSON.stringify(wanted)}. Run \`primitive orgs\` to list yours.`, { exit: 1 });
+}
+/** Resolve an `--org` value to an organization id, listing orgs only for a name. */
+async function resolveOrgSelection(params) {
+	const selection = params.selection.trim();
+	if (isUuid(selection)) return selection.toLowerCase();
+	requireUserGrant(params.credentials);
+	return matchOrg(selection, (await fetchCliOrgs(params)).orgs).id;
+}
+/**
+* The org-bound credentials for this command: the current organization, or
+* `orgSelection` (from `--org`) when given. Exchanges when the token for
+* that organization is missing or about to expire.
+*/
+async function ensureUserGrantSession(params) {
+	const now = params.now ?? Date.now;
+	requireUserGrant(params.credentials);
+	const raw = params.orgSelection?.trim() || null;
+	const selection = raw === null ? null : await resolveOrgSelection({
+		...params,
+		credentials: params.credentials,
+		now,
+		selection: raw
+	});
+	const fast = usableOrgToken(params.credentials, selection, now);
+	if (fast && !params.forceExchange) return fast;
+	return withLock(params, async () => {
+		const current = loadCliCredentials(params.configDir);
+		if (!current) throw new Errors.CLIError(USER_LOGIN_EXPIRED_MESSAGE, { exit: 1 });
+		requireUserGrant(current);
+		const orgId = selection ?? (current.org_id || null);
+		if (!orgId) throw new Errors.CLIError(NO_CURRENT_ORG_MESSAGE, { exit: 1 });
+		const saved = usableOrgToken(current, orgId, now);
+		if (saved && (!params.forceExchange || params.staleToken !== void 0 && saved.access_token !== params.staleToken)) return saved;
+		const { credentials, org } = await exchangeAndSave({
+			apiBaseUrl: params.apiBaseUrl,
+			configDir: params.configDir,
+			credentials: current,
+			fetch: params.fetch,
+			headers: params.headers,
+			makeCurrent: false,
+			now,
+			orgId
+		});
+		return credentialsForOrg(credentials, org);
+	});
+}
+function usableOrgToken(credentials, selection, now) {
+	const grant = credentials.user_grant;
+	if (!grant) return null;
+	const wanted = selection?.toLowerCase() ?? null;
+	if (wanted === null || wanted === credentials.org_id.toLowerCase()) {
+		if (!credentials.org_id || !credentials.access_token) return null;
+		return expiringSoon(credentials.expires_at, now) ? null : credentials;
+	}
+	const cached = Object.values(grant.org_tokens).find((token) => token.org_id.toLowerCase() === wanted);
+	if (!cached || expiringSoon(cached.expires_at, now)) return null;
+	return credentialsForOrg(credentials, cached);
+}
+/** `primitive org use`: exchange for `selection` and make it the current organization. */
+async function switchCurrentOrg(params) {
+	const now = params.now ?? Date.now;
+	return withLock(params, async () => {
+		const current = loadCliCredentials(params.configDir);
+		if (!current) throw new Errors.CLIError("Not logged in. Run `primitive login` first.", { exit: 1 });
+		requireUserGrant(current);
+		const orgId = await resolveOrgSelection({
+			...params,
+			credentials: current,
+			credentialsLockHeld: true,
+			now
+		});
+		const latest = loadCliCredentials(params.configDir);
+		if (!latest) throw new Errors.CLIError(USER_LOGIN_EXPIRED_MESSAGE, { exit: 1 });
+		return exchangeAndSave({
+			apiBaseUrl: params.apiBaseUrl,
+			configDir: params.configDir,
+			credentials: latest,
+			fetch: params.fetch,
+			headers: params.headers,
+			makeCurrent: true,
+			now,
+			orgId
+		});
+	});
+}
+/**
+* Wrap `fetch` so a 401 on a per-org token is answered by one fresh
+* exchange and one retry, as the server asks. If the exchange is refused,
+* the caller sees a 403 carrying the refusal's reason as its error code.
+*/
+function reexchangingFetch(params) {
+	const base = (input, init) => (params.base ?? globalThis.fetch)(input, init);
+	let pending = null;
+	const wrapped = async (input, init) => {
+		const request = new Request(input, init);
+		const sent = /^Bearer\s+(\S+)$/i.exec(request.headers.get("authorization") ?? "")?.[1];
+		const retry = request.clone();
+		const response = await base(request);
+		if (response.status !== 401 || !sent) return response;
+		if (params.token.current === sent) {
+			pending ??= params.reexchange(sent).finally(() => {
+				pending = null;
+			});
+			const outcome = await pending;
+			if (!outcome.ok) return Response.json({
+				success: false,
+				error: {
+					code: outcome.code,
+					message: outcome.message
+				}
+			}, { status: outcome.status });
+			params.token.current = outcome.token;
+		}
+		retry.headers.set("authorization", `Bearer ${params.token.current}`);
+		return base(retry);
+	};
+	return wrapped;
+}
+/** The reexchange callback for `reexchangingFetch`, for a saved user login. */
+function savedLoginReexchange(params) {
+	return async (staleToken) => {
+		try {
+			const current = loadCliCredentials(params.configDir);
+			if (!current?.user_grant) return {
+				ok: false,
+				status: 401,
+				code: "unauthorized",
+				message: USER_LOGIN_EXPIRED_MESSAGE
+			};
+			return {
+				ok: true,
+				token: (await ensureUserGrantSession({
+					apiBaseUrl: params.apiBaseUrl,
+					configDir: params.configDir,
+					credentials: current,
+					fetch: params.fetch,
+					forceExchange: true,
+					headers: params.headers,
+					now: params.now,
+					orgSelection: params.orgId,
+					staleToken
+				})).access_token
+			};
+		} catch (error) {
+			if (error instanceof CliOrgRefusedError) return {
+				ok: false,
+				status: 403,
+				code: error.reason,
+				message: error.message
+			};
+			return {
+				ok: false,
+				status: 401,
+				code: "unauthorized",
+				message: error instanceof Error ? error.message : String(error)
+			};
+		}
+	};
+}
+/** Sign the person out of every organization by revoking the user login. */
+async function revokeUserLogin(params) {
+	const result = await postTokenEndpoint({
+		apiBaseUrl: params.apiBaseUrl,
+		body: {
+			client_id: params.credentials.oauth_client_id,
+			token: params.credentials.refresh_token,
+			token_type_hint: "refresh_token"
+		},
+		fetch: params.fetch,
+		headers: params.headers,
+		path: "/oauth/revoke",
+		allowEmptySuccess: true
+	});
+	if (result.ok) return { ok: true };
+	return {
+		ok: false,
+		status: result.status,
+		message: result.description ?? result.error ?? `The server answered HTTP ${result.status}.`
+	};
+}
+/** Build the saved credentials for a user login from the login poll. */
+function credentialsFromUserLogin(params) {
+	const now = params.now ?? Date.now;
+	const org = isOrgAccessToken(params.login.org) ? orgTokenFromResponse(params.login.org, now) : null;
+	return {
+		access_token: org?.access_token ?? "",
+		api_base_url: params.apiBaseUrl,
+		auth_method: "user_grant",
+		created_at: new Date(now()).toISOString(),
+		expires_at: org?.expires_at ?? (/* @__PURE__ */ new Date(0)).toISOString(),
+		oauth_client_id: params.login.oauth_client_id,
+		oauth_grant_id: org?.oauth_grant_id ?? "",
+		org_id: org?.org_id ?? "",
+		org_name: org?.org_name ?? null,
+		refresh_token: params.login.refresh_token,
+		token_type: "Bearer",
+		user_grant: {
+			access_token: params.login.access_token,
+			expires_at: cliAccessTokenExpiresAt(params.login.expires_in, now),
+			org_role: org?.role ?? null,
+			org_tokens: {},
+			requested_grant: params.requestedGrant ?? null,
+			user_grant_id: params.login.user_grant_id,
+			user_id: params.login.user_id
+		}
+	};
+}
+// src/oclif/api-client.ts
 const API_HEADERS_ENV = "PRIMITIVE_API_HEADERS";
 const OAUTH_REFRESH_SKEW_MS = 6e4;
 const SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE = "Saved Primitive CLI OAuth session expired or was revoked. Run `primitive signin` to authenticate again.";
@@ -99,8 +691,47 @@ function oauthErrorDescription(value) {
 	const raw = value.error_description;
 	return typeof raw === "string" && raw.trim() ? raw : null;
 }
+/** The organization the global `--org` flag (or PRIMITIVE_CLI_ORG) selects, if any. */
+function selectedOrgFromEnv(env = process.env) {
+	return env["PRIMITIVE_CLI_ORG"]?.trim() || null;
+}
+/**
+* Refuse `--org` before a command acts with a connected agent profile's own
+* key: the profile belongs to one organization and cannot act in another.
+*/
+function refuseOrgSelectionForProfile(profileName, env = process.env) {
+	const selection = selectedOrgFromEnv(env);
+	if (!selection) return;
+	const who = profileName ? `Connected agent profile ${profileName}` : "A connected agent credential";
+	throw new Errors.CLIError(`--org (PRIMITIVE_CLI_ORG=${selection}) selects an organization for a saved \`primitive login\`. ${who} belongs to one organization; drop --org, or unset PRIMITIVE_CLI_ORG.`, { exit: 1 });
+}
+function orgMatches(credentials, selection) {
+	const wanted = selection.toLowerCase();
+	return credentials.org_id.toLowerCase() === wanted || (credentials.org_name ?? "").trim().toLowerCase() === wanted;
+}
+/**
+* Refuse `--org` for an org-bound login unless it names that login's own
+* organization: an org-bound login cannot act anywhere else.
+*/
+function assertOrgBoundSelection(credentials, selection) {
+	if (!selection || orgMatches(credentials, selection)) return;
+	const org = credentials.org_name ? `${credentials.org_name} (${credentials.org_id})` : credentials.org_id;
+	throw new Errors.CLIError(`This saved login is bound to organization ${org}, so --org ${selection} cannot be used with it. Run \`primitive logout\`, then \`primitive login\`, to sign in as yourself and switch between organizations.`, { exit: 1 });
+}
 async function refreshStoredCliCredentials(params) {
 	const now = params.now ?? Date.now;
+	const orgSelection = params.orgSelection === void 0 ? selectedOrgFromEnv() : params.orgSelection;
+	if (params.credentials.auth_method === "user_grant") return ensureUserGrantSession({
+		apiBaseUrl: params.apiBaseUrl,
+		configDir: params.configDir,
+		credentials: params.credentials,
+		credentialsLockHeld: params.credentialsLockHeld,
+		fetch: params.fetch,
+		headers: params.headers,
+		now,
+		orgSelection
+	});
+	assertOrgBoundSelection(params.credentials, orgSelection);
 	if (!shouldRefresh(params.credentials, now)) return params.credentials;
 	let releaseLock;
 	try {
@@ -112,6 +743,16 @@ async function refreshStoredCliCredentials(params) {
 		}
 		const current = loadCliCredentials(params.configDir);
 		if (!current) throw new Errors.CLIError("Saved Primitive CLI OAuth session is no longer available. Run `primitive signin` to authenticate again.", { exit: 1 });
+		if (current.auth_method === "user_grant") return ensureUserGrantSession({
+			apiBaseUrl: params.apiBaseUrl,
+			configDir: params.configDir,
+			credentials: current,
+			credentialsLockHeld: true,
+			fetch: params.fetch,
+			headers: params.headers,
+			now,
+			orgSelection
+		});
 		if (!shouldRefresh(current, now)) return current;
 		const fetchImpl = params.fetch ?? fetch;
 		const body = new URLSearchParams({
@@ -172,6 +813,9 @@ async function createAuthenticatedCliApiClient(params) {
 		if (hint) process.stderr.write(`${hint}\n`);
 	}
 	if (params.requireConnectedAgentKey && (auth.source === "stored" || !auth.apiKey?.startsWith("pconn_"))) throw new ConnectedAgentKeyRequiredError("A connected agent credential is required.");
+	const orgSelection = selectedOrgFromEnv(params.env ?? process.env);
+	if (orgSelection && auth.source !== "stored") throw new Errors.CLIError(`--org (PRIMITIVE_CLI_ORG=${orgSelection}) selects an organization for a saved \`primitive login\`. ${auth.source === "connected-profile" ? "A connected agent profile" : auth.source === "flag-or-env" ? "An API key" : "This command's credential"} belongs to one organization; drop --org, or unset PRIMITIVE_CLI_ORG.`, { exit: 1 });
+	let userLoginToken = null;
 	if (auth.source === "stored" && auth.credentials) {
 		const refreshed = await refreshStoredCliCredentials({
 			apiBaseUrl: auth.apiBaseUrl,
@@ -180,17 +824,33 @@ async function createAuthenticatedCliApiClient(params) {
 			credentialsLockHeld: params.credentialsLockHeld,
 			fetch: params.fetch,
 			headers: requestConfig.headers,
-			now: params.now
+			now: params.now,
+			orgSelection
 		});
 		auth = {
 			...auth,
 			apiKey: refreshed.access_token,
 			credentials: refreshed
 		};
+		if (refreshed.auth_method === "user_grant") userLoginToken = { current: refreshed.access_token };
 	}
+	const tokenHolder = userLoginToken;
 	return {
 		apiClient: new PrimitiveApiClient({
-			apiKey: auth.apiKey,
+			...tokenHolder && auth.credentials ? {
+				auth: (security) => security.type === "http" && security.scheme === "bearer" ? tokenHolder.current : void 0,
+				fetch: reexchangingFetch({
+					reexchange: savedLoginReexchange({
+						apiBaseUrl: auth.apiBaseUrl,
+						configDir: params.configDir,
+						fetch: params.fetch,
+						headers: requestConfig.headers,
+						now: params.now,
+						orgId: auth.credentials.org_id
+					}),
+					token: tokenHolder
+				})
+			} : { apiKey: auth.apiKey },
 			apiBaseUrl: auth.apiBaseUrl,
 			headers: auth.connectedAgent ? void 0 : requestConfig.headers
 		}),
@@ -199,8 +859,7 @@ async function createAuthenticatedCliApiClient(params) {
 		requestConfig
 	};
 }
-//#endregion
-//#region src/oclif/attachment-wait.ts
+// src/oclif/attachment-wait.ts
 /** Generated download commands that wait for attachment content by default. */
 const ATTACHMENT_WAIT_OPERATIONS = /* @__PURE__ */ new Set([
 	"downloadAttachments",
@@ -255,8 +914,7 @@ async function withAttachmentWait(call, options) {
 	}
 	return result;
 }
-//#endregion
-//#region src/oclif/endpoint-event-types.ts
+// src/oclif/endpoint-event-types.ts
 const EVENT_TYPES_FLAG_OPERATIONS = /* @__PURE__ */ new Set(["createEndpoint", "updateEndpoint"]);
 const EVENT_TYPES_FLAG_DESCRIPTION = "Event types this endpoint subscribes to, comma separated or repeated (sets rules.event_types). Omitting the subscription means every event type except the opt-in sent_email.* events, which an endpoint receives only when it lists them; sent_email.* expands to all four. Keep email.received in the list if the endpoint also handles inbound mail. On update, the endpoint's other rules are kept.";
 const SENT_EMAIL_WILDCARD = "sent_email.*";
@@ -328,8 +986,7 @@ function withEventTypes(body, eventTypes, baseRules = {}) {
 function bodyHasRules(body) {
 	return isPlainObject(body) && body.rules !== void 0;
 }
-//#endregion
-//#region src/oclif/endpoints-test-redirect.ts
+// src/oclif/endpoints-test-redirect.ts
 async function detectFunctionEndpoint(endpointId, listEndpoints) {
 	let response;
 	try {
@@ -371,8 +1028,7 @@ async function maybeWriteFunctionEndpointRedirect(inputs) {
 	inputs.writeStderr(`${formatFunctionEndpointRedirect(match)}\n`);
 	return match;
 }
-//#endregion
-//#region src/oclif/flag-suggestions.ts
+// src/oclif/flag-suggestions.ts
 /**
 * "Did you mean" hints for unknown flags. oclif reports an unknown flag as
 * `Nonexistent flag: --query` and prints the full help; this adds the
@@ -437,8 +1093,7 @@ function withFlagSuggestion(error, valid) {
 	].join("\n");
 	return error;
 }
-//#endregion
-//#region src/oclif/from-verified-filter.ts
+// src/oclif/from-verified-filter.ts
 /**
 * The `from_verified` filter on GET /emails and GET /emails/search: the
 * `from_verified=true|false` parameter (`--from-verified`) and the
@@ -494,8 +1149,7 @@ function assertFromVerifiedRows(rows, expectation) {
 	}).length;
 	if (wrong > 0) throw new FromVerifiedFilterUnsupportedError(`${expectation.surface} returned ${wrong} of ${rows.length} email${rows.length === 1 ? "" : "s"} without the requested \`from_verified\` value.`);
 }
-//#endregion
-//#region src/oclif/idempotent-replay-banner.ts
+// src/oclif/idempotent-replay-banner.ts
 /**
 * If `data` carries `idempotent_replay: true`, write a stderr notice
 * that nothing new was sent and why. Otherwise no-op.
@@ -509,7 +1163,7 @@ function isReplay(data) {
 	if (data === null || typeof data !== "object") return false;
 	return data.idempotent_replay === true;
 }
-function nonEmptyString(value) {
+function nonEmptyString$1(value) {
 	return typeof value === "string" && value ? value : null;
 }
 /**
@@ -529,8 +1183,8 @@ function readReplayDetail(sent, keyOrigin) {
 	else return null;
 	return {
 		kind,
-		originalId: nonEmptyString(object.original_sent_email_id) ?? nonEmptyString(sent.id),
-		originalCreatedAt: nonEmptyString(object.original_created_at)
+		originalId: nonEmptyString$1(object.original_sent_email_id) ?? nonEmptyString$1(sent.id),
+		originalCreatedAt: nonEmptyString$1(object.original_created_at)
 	};
 }
 /** "12s ago", "4m ago", "3h ago", "9d ago"; null when the time is unusable. */
@@ -547,8 +1201,8 @@ function formatReplayAge(createdAt, now) {
 	return `${Math.round(hours / 24)}d ago`;
 }
 function statusSuffix(sent) {
-	const status = nonEmptyString(sent.status);
-	const deliveryStatus = nonEmptyString(sent.delivery_status);
+	const status = nonEmptyString$1(sent.status);
+	const deliveryStatus = nonEmptyString$1(sent.delivery_status);
 	const details = [];
 	if (status) details.push(`status ${status}`);
 	if (deliveryStatus && deliveryStatus !== status) details.push(`delivery status ${deliveryStatus}`);
@@ -564,7 +1218,7 @@ function formatSpecificNotice(sent, detail, options) {
 	switch (detail.kind) {
 		case "auto_content": return `Not sent: identical to ${id}${when}${state}.${advise ? ` Pass ${keyHint} to send again.` : ""}`;
 		case "explicit": {
-			const key = nonEmptyString(sent.client_idempotency_key);
+			const key = nonEmptyString$1(sent.client_idempotency_key);
 			return `Not sent: ${key ? `idempotency key ${key}` : "this idempotency key"} was already used for ${id}${when}${state}. A key you pass never expires.${advise ? " Use a different key only for a different message." : ""}`;
 		}
 		case "function_trigger": return `Not sent: this Function already sent this message as ${id}${when}${state}, for the same email or event that invoked it. A Function that runs again for one trigger sends once.`;
@@ -593,18 +1247,66 @@ function formatAlreadySentNotice(sent, options = {}) {
 	if (deliveryStatus && deliveryStatus !== status) details.push(`delivery status ${deliveryStatus}`);
 	return `Already sent: this exact message went out earlier${details.length > 0 ? ` (${details.join(", ")})` : ""}. Nothing new was sent.`;
 }
-//#endregion
-//#region src/oclif/mail-session.ts
+// src/oclif/runtime-session.ts
+/**
+* The variables each runtime sets to its exact session ID, first match wins.
+* The loaded Codex thread is the receiving identity; the process session ID
+* is only a fallback when no thread ID is exposed.
+*/
+const RUNTIME_SESSION_VARIABLES = {
+	claude: ["CLAUDE_CODE_SESSION_ID"],
+	codex: ["CODEX_THREAD_ID", "CODEX_SESSION_ID"]
+};
+const UUID$3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** Each runtime whose environment names a session UUID. Never guessed from history or cwd. */
+function runtimeSessions(env) {
+	return Object.keys(RUNTIME_SESSION_VARIABLES).flatMap((runtime) => {
+		for (const variable of RUNTIME_SESSION_VARIABLES[runtime]) {
+			const value = env[variable]?.trim().toLowerCase();
+			if (!value) continue;
+			return UUID$3.test(value) ? [{
+				runtime,
+				session: value,
+				variable
+			}] : [];
+		}
+		return [];
+	});
+}
+/** The one session the runtime environment names, if exactly one runtime names one. */
+function detectRuntimeSession(env = process.env) {
+	const candidates = runtimeSessions(env);
+	const [only] = candidates;
+	if (!only) return { kind: "none" };
+	return candidates.length === 1 ? {
+		kind: "detected",
+		...only
+	} : {
+		kind: "ambiguous",
+		candidates
+	};
+}
+/**
+* The runtime whose tool environment names this exact session. A session ID
+* that matches neither runtime's variable, or both, has no detectable runtime.
+*/
+function detectAgentRuntime(session, env = process.env) {
+	const wanted = session.trim().toLowerCase();
+	const matches = runtimeSessions(env).filter((candidate) => candidate.session === wanted);
+	return matches.length === 1 ? matches[0]?.runtime ?? null : null;
+}
+/** Every variable a runtime may name its session in, for messages. */
+function runtimeSessionVariableList() {
+	const names = Object.values(RUNTIME_SESSION_VARIABLES).flat();
+	return `${names.slice(0, -1).join(", ")} or ${names.at(-1)}`;
+}
+// src/oclif/mail-session.ts
 /** Runtime-provided identity only. Never guess a session from history or cwd. */
 function currentMailSessionKey(env = process.env) {
-	const codex = env.CODEX_THREAD_ID ?? env.CODEX_SESSION_ID;
-	const claude = env.CLAUDE_CODE_SESSION_ID;
-	if (codex && claude) return null;
-	const value = codex ?? claude;
-	return value && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(value) ? `${codex ? "codex" : "claude"}:${value.toLowerCase()}` : null;
-}
-//#endregion
-//#region src/oclif/agent-identity-suggestions.ts
+	const detection = detectRuntimeSession(env);
+	return detection.kind === "detected" ? `${detection.runtime}:${detection.session}` : null;
+}
+// src/oclif/agent-identity-suggestions.ts
 /** The connection name enrollment uses when none is given. */
 const DEFAULT_ENROLL_NAME = "Coding agent";
 /** npx runs the CLI from its cache; print follow-up commands the same way. */
@@ -687,8 +1389,7 @@ function identitySuggestions(params) {
 		suggestions
 	};
 }
-//#endregion
-//#region src/oclif/send-outcome.ts
+// src/oclif/send-outcome.ts
 const SEND_OUTCOME_EXIT_CODES = {
 	replied: 0,
 	sent: 0,
@@ -1156,8 +1857,7 @@ function thrownErrorExitCode(error) {
 	const exit = error?.oclif?.exit;
 	return typeof exit === "number" ? exit : 1;
 }
-//#endregion
-//#region src/oclif/interaction-actions.ts
+// src/oclif/interaction-actions.ts
 const HINTS = /* @__PURE__ */ new Set([
 	"status",
 	"card",
@@ -1173,7 +1873,6 @@ function record$1(value) {
 function categoryOf(hint, kind, fyi, candidate) {
 	if (hint === "pending") return candidate ? "pending" : "ordinary";
 	if (hint === "card") switch (kind) {
-		case "x402.payment/1": return "payment";
 		case "primitive.contact/1": return "contact";
 		case "repeat.tick/1": return "repeat";
 		case "repeat.stop/1": return "repeat_stopped";
@@ -1188,7 +1887,6 @@ function replyExpectation(category) {
 		case "fyi":
 		case "signal":
 		case "repeat_stopped": return "no_reply";
-		case "payment":
 		case "contact": return "answer_with_command";
 		case "repeat": return "repeat";
 		case "unsupported": return "unsupported";
@@ -1240,19 +1938,6 @@ function interactionNextActions(interaction, emailId, options = {}) {
 	const id = emailId.toLowerCase();
 	switch (interaction?.category ?? "ordinary") {
 		case "ordinary": return [replyAction(bin, id)];
-		case "payment": return [buildFollowUpCommand("inspect_payment", "Show the payment request's terms before paying", [
-			bin,
-			"payments",
-			"challenge-from-email",
-			"--id",
-			id
-		]), buildFollowUpCommand("pay", "Pay the payment request (signs with your wallet key and sends the payment)", [
-			bin,
-			"payments",
-			"pay-email",
-			"--in-reply-to",
-			id
-		])];
 		case "contact": return [buildFollowUpCommand("accept_contact", "Accept the contact request, if the owner's policy allows it", [
 			bin,
 			"contacts",
@@ -1295,11 +1980,6 @@ function interactionHumanLine(interaction, actions) {
 		case "fyi": return "Informational (fyi): no reply needed, not even another fyi.";
 		case "signal": return `Status signal (${kind}): no reply needed.`;
 		case "repeat_stopped": return `Notice that a repeating message stopped (${kind}): no reply needed.`;
-		case "payment": {
-			const inspect = command("inspect_payment");
-			const pay = command("pay");
-			return inspect && pay ? `Payment interaction (${kind}). If it requests payment, review it with ${inspect} and pay with ${pay}. A plain reply does not pay or decline it.` : null;
-		}
 		case "contact": {
 			const accept = command("accept_contact");
 			return accept ? `Contact interaction (${kind}). If it is a contact request, accept it under the owner's policy with ${accept}. A plain reply does not accept it.` : null;
@@ -1374,12 +2054,6 @@ function replyInteractionWarning(detail, emailId) {
 	const expectation = replyExpectation(interaction.category);
 	if (expectation === "reply" || expectation === "repeat") return null;
 	switch (interaction.category) {
-		case "payment": return {
-			...base,
-			code: "interaction_not_answered",
-			message: `Warning: email ${id} is a payment interaction (${label}). A plain reply does not pay or decline it; sending anyway. To pay: ${commandFor("pay")}`,
-			expected
-		};
 		case "contact": return {
 			...base,
 			code: "interaction_not_answered",
@@ -1413,8 +2087,7 @@ function replyInteractionWarning(detail, emailId) {
 		default: return null;
 	}
 }
-//#endregion
-//#region src/oclif/pending-mail.ts
+// src/oclif/pending-mail.ts
 const RELATIONSHIPS = [
 	"owner",
 	"member",
@@ -1771,8 +2444,7 @@ function pendingMailProfiles(configDir, session, emailId) {
 		}
 	}).sort();
 }
-//#endregion
-//#region src/oclif/wake-context.ts
+// src/oclif/wake-context.ts
 /**
 * Mail from a verified owner, member or connected peer agent is mail the
 * agent may act on, so its wake starts with the line that loads the rules
@@ -2009,8 +2681,7 @@ function formatMailWakeLine(input) {
 	const skillFirst = skillFirstLine(input.relation ?? context?.relationship, input.skillFile);
 	return `${skillFirst ? `${skillFirst}\n` : ""}Primitive mail arrived: ${input.emailId}${input.recipient}${metadata}. Read with ${wakeReadCommand(input.emailId, input.profileName)}.${interaction} ${wakeAuthority(input.relation)}\n`;
 }
-//#endregion
-//#region src/oclif/pending-mail-miss.ts
+// src/oclif/pending-mail-miss.ts
 /** At most this many other profiles are named in one hint line. */
 const HINT_PROFILE_LIMIT = 3;
 function currentProfile(configDir) {
@@ -2064,7 +2735,7 @@ function savedConnectedProfiles(configDir, exclude) {
 */
 async function otherProfiles(configDir, session, current) {
 	if (session) try {
-		const { connectedProfilesForSession } = await import("./machine-session-B6V5-grn.js").then((n) => n.s);
+		const { connectedProfilesForSession } = await import("./machine-session-Cp_eQ9t_.js").then((n) => n.s);
 		return {
 			inSession: true,
 			profiles: connectedProfilesForSession(configDir, session, current)
@@ -2138,8 +2809,7 @@ async function explainPendingMailNotFound(configDir, emailId, write = (line) =>
 		if (outcome.kind === "dropped") write(`Dropped the pending notice for ${id} from profile ${current.profile} after ${outcome.reads} consecutive not_found reads; the email is no longer visible to this profile.\n`);
 	} catch {}
 }
-//#endregion
-//#region src/oclif/sent-list-labels.ts
+// src/oclif/sent-list-labels.ts
 /**
 * `sent list` under a connected agent profile returns this address's own
 * sends and also delivered sends from other addresses in the organization
@@ -2172,12 +2842,13 @@ function sentListOtherSendersNote(rows, self) {
 	const named = senders.length > 3 ? `${senders.slice(0, 3).join(", ")} and ${senders.length - 3} more` : senders.join(", ");
 	return `${count} of ${rows.length} rows were sent by another address in this organization (${named}) to ${own}; they are mail ${own} received, not its own sends. Rows with from_address ${own} are this address's sends; pass --from ${own} to list only those.`;
 }
-//#endregion
-//#region src/oclif/api-command.ts
+// src/oclif/api-command.ts
 const API_ERROR_CODES = {
 	accessDenied: "access_denied",
 	authorizationPending: "authorization_pending",
 	expiredToken: "expired_token",
+	forbidden: "forbidden",
+	grantForbidden: "grant_forbidden",
 	invalidDeviceCode: "invalid_device_code",
 	notFound: "not_found",
 	slowDown: "slow_down",
@@ -2455,6 +3126,47 @@ function rateLimitHint(response) {
 	const delay = parseRetryAfter(response?.headers.get("retry-after"));
 	return delay === void 0 ? "Hint: this request was rate limited. Wait before retrying: the API request limits use a 60 second window, and send limits can take longer to reset." : `Hint: this request was rate limited. Retry in ${Math.max(1, Math.ceil(delay / 1e3))} s.`;
 }
+/**
+* True when the API refused because of the credential's grant or role. The
+* credential itself was accepted, so this is not an authentication failure.
+*/
+function isGrantRefusal(payload) {
+	const code = extractErrorCode(payload);
+	return code === API_ERROR_CODES.grantForbidden || code === API_ERROR_CODES.forbidden;
+}
+/** `details` of a refusal, whether the payload is the error or its envelope. */
+function refusalDetails(payload) {
+	const outer = payload && typeof payload === "object" ? payload : {};
+	const inner = outer.error && typeof outer.error === "object" ? outer.error : {};
+	const details = outer.details ?? inner.details;
+	return details && typeof details === "object" ? details : {};
+}
+function nonEmptyString(value) {
+	return typeof value === "string" && value ? value : null;
+}
+/**
+* The hint for a `403 grant_forbidden`: which permission the credential's
+* grant lacks, and how to check a credential before using it.
+*/
+function grantForbiddenHint(payload) {
+	const record = refusalDetails(payload);
+	const permission = nonEmptyString(record.permission);
+	const reason = nonEmptyString(record.reason);
+	const missing = nonEmptyString(record.missing);
+	return `Hint: ${permission ? `This credential's grant does not include ${missing ?? permission}${reason ? ` (${reason})` : ""}.` : "This credential's grant does not allow this operation."} Use a credential whose grant includes it, or ask an owner or admin to widen it.${permission ? ` Check a credential with \`primitive whoami --check ${missing ?? permission}\`.` : ""}`;
+}
+/**
+* The hint for a `403 forbidden` that names a permission, or null when it does
+* not (a dashboard-only route, say, explains itself in its message). Unlike
+* `grant_forbidden`, this refusal can come from a route closed to keys and the
+* CLI altogether, so it never promises that a wider credential opens it.
+*/
+function forbiddenHint(payload) {
+	const record = refusalDetails(payload);
+	const permission = nonEmptyString(record.permission);
+	if (!permission || record.reason !== "permission_missing") return null;
+	return `Hint: This operation needs ${permission}, which this credential does not have. Some operations stay closed to keys and the CLI even with it. Check a credential with \`primitive whoami --check ${permission}\`.`;
+}
 function writeErrorWithHints(payload, response) {
 	process.stderr.write(`${formatErrorPayload(payload)}\n`);
 	const code = extractErrorCode(payload);
@@ -2463,6 +3175,15 @@ function writeErrorWithHints(payload, response) {
 		return;
 	}
 	if (!code) return;
+	if (code === "grant_forbidden") {
+		process.stderr.write(`${grantForbiddenHint(payload)}\n`);
+		return;
+	}
+	if (code === API_ERROR_CODES.forbidden) {
+		const hint = forbiddenHint(payload);
+		if (hint) process.stderr.write(`${hint}\n`);
+		return;
+	}
 	if (code in ERROR_CODE_HINTS) {
 		const hint = ERROR_CODE_HINTS[code];
 		process.stderr.write(`${hint}\n`);
@@ -2646,14 +3367,25 @@ function operationJsonDocument(envelope, summary = []) {
 	if (summary.length > 0) document.summary = summary.join("\n");
 	return document;
 }
-function isIncompleteDomainVerification(operation, envelope) {
-	if (operation.sdkName !== "verifyDomain") return false;
-	const data = envelope?.data;
-	if (!data || typeof data !== "object") return false;
-	return data.verified === false;
-}
-function writeIncompleteDomainVerificationHint() {
-	process.stderr.write("Domain verification is incomplete. Add or fix the DNS records shown above, or run `primitive domains zone-file --id <domain-id>` to download the complete zone file, then retry `primitive domains verify --id <domain-id>`.\n");
+const SETTLED_DNS_RECORD_STATUSES = /* @__PURE__ */ new Set(["found", "legacy"]);
+/**
+* The hint for a failed domain verification: the API answers 400
+* `dns_verification_failed` with every expected record, each with its
+* `status`, in `error.details.records`. Lists the records that still need
+* work, then how to finish.
+*/
+function domainVerificationFailedHint(payload) {
+	const body = payload !== null && typeof payload === "object" ? payload : {};
+	const records = body.details?.records ?? body.error?.details?.records;
+	const lines = (Array.isArray(records) ? records : []).filter((record) => record !== null && typeof record === "object" && !SETTLED_DNS_RECORD_STATUSES.has(String(record.status))).map((record) => {
+		const name = record.fqdn ?? record.name ?? "?";
+		return `  ${String(record.type ?? "?")} ${String(name)} ${String(record.value ?? "")} (${String(record.status ?? "unknown")})`;
+	});
+	return [
+		"Domain verification is incomplete.",
+		...lines.length > 0 ? ["Records to add or fix:", ...lines] : [],
+		"Add or fix those DNS records, or run `primitive domains zone-file --id <domain-id>` to download the complete zone file, then retry `primitive domains verify --id <domain-id>`."
+	].join("\n");
 }
 const OPERATION_HINTS = {
 	addDomain: "Tip: after this returns a domain id, run `primitive domains zone-file --id <domain-id> --output <domain>.zone` when the user wants an importable DNS zone file.",
@@ -2680,11 +3412,14 @@ const OPERATION_EXTRA_BODY_FLAGS = { addDomain: { "mail-relay": {
 } } };
 const MAIL_RELAY_NOT_ENABLED_MESSAGE = "Mail relay is not enabled for this account, so the domain was not added. Retry without --mail-relay to point the domain's MX at Primitive directly, or ask Primitive to enable mail relay for your account.";
 const MAIL_RELAY_UNAVAILABLE_MESSAGE = "No mail relay is available on this API server right now, so the domain was not added. Retry later, or retry without --mail-relay to point the domain's MX at Primitive directly.";
-const OPERATION_ERROR_HINTS = { addDomain: (code, body) => {
-	if (code === "mail_relay_unavailable") return MAIL_RELAY_UNAVAILABLE_MESSAGE;
-	const mailRelay = body !== null && typeof body === "object" && body.mail_relay === true;
-	if (code === "feature_disabled" && mailRelay) return MAIL_RELAY_NOT_ENABLED_MESSAGE;
-} };
+const OPERATION_ERROR_HINTS = {
+	verifyDomain: (code, _body, payload) => code === "dns_verification_failed" ? domainVerificationFailedHint(payload) : void 0,
+	addDomain: (code, body) => {
+		if (code === "mail_relay_unavailable") return MAIL_RELAY_UNAVAILABLE_MESSAGE;
+		const mailRelay = body !== null && typeof body === "object" && body.mail_relay === true;
+		if (code === "feature_disabled" && mailRelay) return MAIL_RELAY_NOT_ENABLED_MESSAGE;
+	}
+};
 const OPERATION_SUCCESS_HOOKS = { verifyAgentSignup: ({ envelope, configDir, apiBaseUrl, writeStderr }) => {
 	const data = envelope?.data;
 	if (!data?.access_token || !data?.refresh_token) return;
@@ -2776,7 +3511,7 @@ function createOperationCommand(operation) {
 				if (result.error) {
 					const errorPayload = extractErrorPayload(result.error);
 					writeErrorWithHints(errorPayload, result.response);
-					const operationErrorHint = OPERATION_ERROR_HINTS[operation.sdkName]?.(extractErrorCode(errorPayload), body);
+					const operationErrorHint = OPERATION_ERROR_HINTS[operation.sdkName]?.(extractErrorCode(errorPayload), body, errorPayload);
 					if (operationErrorHint) process.stderr.write(`${operationErrorHint}\n`);
 					if (replyStateSurface && isAwaitingRejectedError(errorPayload)) process.stderr.write(`${awaitingRejectedError(replyStateSurface).message}\n`);
 					if (automatedSurface && isAutomatedRejectedError(errorPayload)) process.stderr.write(`${automatedRejectedError(automatedSurface).message}\n`);
@@ -2880,10 +3615,6 @@ function createOperationCommand(operation) {
 					process.stderr.write(`Warning: ${operation.sdkName} succeeded but its post-success hook threw (${detail}). The response below is still valid; act on it manually.\n`);
 				}
 				this.log(JSON.stringify(jsonOutput && withEnvelope ? operationJsonDocument(envelope, summary) : operationOutputPayload(envelope, withEnvelope), null, 2));
-				if (isIncompleteDomainVerification(operation, envelope)) {
-					writeIncompleteDomainVerificationHint();
-					process.exitCode = 1;
-				}
 			});
 		}
 	}
@@ -2900,5 +3631,4 @@ const EMPTY_RESULT_HINTS = {
 function canonicalizeCliReferences(description) {
 	return description.replaceAll("`primitive emails:latest`", "`primitive emails latest`").replaceAll("`primitive describe emails:get-email | jq '.responseSchema.properties'`", "`primitive describe emails:get | jq '.responseSchema.properties'`");
 }
-//#endregion
-export { formatDeletedEarlierSendNotice as $, clearReadPendingMail as A, createCliApiClient as At, wakeInteractionSentence as B, serverRelationship as C, withFlagSuggestion as Ct, wakeRelationship as D, ConnectedAgentKeyRequiredError as Dt, wakeRecipientField as E, withAttachmentWait as Et, interactionHumanLine as F, assertValidIdempotencyKey as G, MAX_SEND_WAIT_TIMEOUT_MS as H, interactionNextActions as I, checkPriorReplies as J, buildFollowUpCommand as K, readEmailInteraction as L, readPendingMail as M, resolveCliApiRequestConfig as Mt, recordPendingMail as N, claimPendingMail as O, SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE as Ot, removePendingMail as P, followUpCommandPrefix as Q, replyExpectation as R, serverMuted as S, writeIdempotentReplayBannerIfReplay as St, wakeReadCommand as T, ATTACHMENT_WAIT_MAX_MS as Tt, SEND_OUTCOME_HELP as U, IDEMPOTENCY_KEY_FLAG_DESCRIPTION as V, apiResultHttpStatus as W, deriveSendIdempotencyKey as X, classifySendError as Y, excludeSignalReplies as Z, displayAddress as _, generatedAgentName as _t, extractErrorCode as a, reportSendCommandResult as at, readThreadContext as b, currentMailSessionKey as bt, hasControlCharacter as c, sendWaitClampNotice as ct, runWithTiming as d, successfulSendOutcome as dt, formatPriorRepliesCheckSkipped as et, surfaceUnauthorizedHint as f, thrownErrorExitCode as ft, describeWake as g, defaultConnectionName as gt, bareAddress$1 as h, connectNextSteps as ht, createOperationCommand as i, priorRepliesThatWentOut as it, pendingMailPath as j, refreshStoredCliCredentials as jt, clearConsumedPendingMail as k, createAuthenticatedCliApiClient as kt, headerFlagName as l, sentHistoryWindowStart as lt, explainPendingMailNotFound as m, cliInvocation as mt, API_ERROR_CODES as n, formatSendFailureSummary as nt, extractErrorPayload as o, sendIdentityFields as ot, writeErrorWithHints as p, DEFAULT_ENROLL_NAME as pt, buildThrownSendFailureEnvelope as q, TIME_FLAG_DESCRIPTION as r, formatSendRecordFailureSummary as rt, formatErrorPayload as s, sendOutcomeExitCode as st, API_BASE_URL_FLAG_DESCRIPTION as t, formatPriorRepliesWarning as tt, readTextFileFlag as u, serializeErrorPayload as ut, formatMailWakeLine as v, identitySuggestions as vt, skillFirstLine as w, ATTACHMENT_WAIT_FLAG_DESCRIPTION as wt, sentInThread as x, formatAlreadySentNotice as xt, latestOwnOutbound as y, loadSkillLine as yt, replyInteractionWarning as z };
+export { followUpCommandPrefix as $, clearConsumedPendingMail as A, ConnectedAgentKeyRequiredError as At, replyInteractionWarning as B, fetchCliOrgs as Bt, serverMuted as C, detectRuntimeSession as Ct, wakeRecipientField as D, ATTACHMENT_WAIT_FLAG_DESCRIPTION as Dt, wakeReadCommand as E, withFlagSuggestion as Et, removePendingMail as F, refuseOrgSelectionForProfile as Ft, apiResultHttpStatus as G, IDEMPOTENCY_KEY_FLAG_DESCRIPTION as H, switchCurrentOrg as Ht, interactionHumanLine as I, resolveCliApiRequestConfig as It, buildThrownSendFailureEnvelope as J, assertValidIdempotencyKey as K, interactionNextActions as L, selectedOrgFromEnv as Lt, pendingMailPath as M, createAuthenticatedCliApiClient as Mt, readPendingMail as N, createCliApiClient as Nt, wakeRelationship as O, ATTACHMENT_WAIT_MAX_MS as Ot, recordPendingMail as P, refreshStoredCliCredentials as Pt, excludeSignalReplies as Q, readEmailInteraction as R, CliOrgRefusedError as Rt, sentInThread as S, detectAgentRuntime as St, skillFirstLine as T, formatAlreadySentNotice as Tt, MAX_SEND_WAIT_TIMEOUT_MS as U, wakeInteractionSentence as V, revokeUserLogin as Vt, SEND_OUTCOME_HELP as W, classifySendError as X, checkPriorReplies as Y, deriveSendIdempotencyKey as Z, describeWake as _, defaultConnectionName as _t, extractErrorCode as a, priorRepliesThatWentOut as at, latestOwnOutbound as b, loadSkillLine as bt, hasControlCharacter as c, sendOutcomeExitCode as ct, readTextFileFlag as d, serializeErrorPayload as dt, formatDeletedEarlierSendNotice as et, runWithTiming as f, successfulSendOutcome as ft, bareAddress$1 as g, connectNextSteps as gt, explainPendingMailNotFound as h, cliInvocation as ht, createOperationCommand as i, formatSendRecordFailureSummary as it, clearReadPendingMail as j, SAVED_CLI_OAUTH_SESSION_EXPIRED_MESSAGE as jt, claimPendingMail as k, withAttachmentWait as kt, headerFlagName as l, sendWaitClampNotice as lt, writeErrorWithHints as m, DEFAULT_ENROLL_NAME as mt, API_ERROR_CODES as n, formatPriorRepliesWarning as nt, extractErrorPayload as o, reportSendCommandResult as ot, surfaceUnauthorizedHint as p, thrownErrorExitCode as pt, buildFollowUpCommand as q, TIME_FLAG_DESCRIPTION as r, formatSendFailureSummary as rt, formatErrorPayload as s, sendIdentityFields as st, API_BASE_URL_FLAG_DESCRIPTION as t, formatPriorRepliesCheckSkipped as tt, isGrantRefusal as u, sentHistoryWindowStart as ut, displayAddress as v, generatedAgentName as vt, serverRelationship as w, runtimeSessionVariableList as wt, readThreadContext as x, currentMailSessionKey as xt, formatMailWakeLine as y, identitySuggestions as yt, replyExpectation as z, credentialsFromUserLogin as zt };