@rosthq/cli 0.7.156 → 0.7.157

package/dist/index.js

@@ -53026,6 +53026,121 @@ async function recordImplementationRunClosed(store, status, fields, closedAt = /
   });
 }
 
+// src/acting-principal.ts
+var ACTING_PRINCIPAL_KINDS = [
+  "none",
+  "unknown",
+  "user_session",
+  "implementation_bootstrap"
+];
+var actingPrincipalSchema = external_exports.object({
+  kind: external_exports.enum(ACTING_PRINCIPAL_KINDS),
+  // The human subject or run identity behind the credential: the email for a
+  // user session, the implementation-run id for the bounded credential.
+  subject: external_exports.string().nullable(),
+  email: external_exports.string().nullable(),
+  tenant_id: external_exports.string().nullable(),
+  // Resolving the tenant NAME requires a server round-trip, so it is null on
+  // the offline hot path — the id below is the proven fact.
+  tenant_name: external_exports.string().nullable(),
+  // The authority label. `null` for a user session (owner vs steward is a
+  // server-side fact this offline projection refuses to fake), the literal
+  // "implementation credential" for the bounded principal.
+  role: external_exports.string().nullable(),
+  // The credential store the credential was read from (store.describe()).
+  source: external_exports.string().nullable(),
+  // A note naming the selected principal when it was chosen while another
+  // credential was also available — the exact silent fall-through the defect
+  // was about. Null when there was no competing credential.
+  principal_switch: external_exports.string().nullable(),
+  note: external_exports.string().nullable()
+}).strict();
+function decodeSessionIdentity(accessToken) {
+  if (typeof accessToken !== "string" || accessToken.length === 0) {
+    return { email: null, tenantId: null };
+  }
+  const segments = accessToken.split(".");
+  if (segments.length < 2) {
+    return { email: null, tenantId: null };
+  }
+  const payloadSegment = segments[1];
+  if (payloadSegment === void 0 || payloadSegment.length === 0) {
+    return { email: null, tenantId: null };
+  }
+  try {
+    const json2 = Buffer.from(payloadSegment, "base64url").toString("utf8");
+    const claims = JSON.parse(json2);
+    if (typeof claims !== "object" || claims === null) {
+      return { email: null, tenantId: null };
+    }
+    const record2 = claims;
+    const email3 = typeof record2.email === "string" && record2.email.length > 0 ? record2.email : null;
+    const appMetadata = typeof record2.app_metadata === "object" && record2.app_metadata !== null ? record2.app_metadata : {};
+    const tenantId = typeof appMetadata.tenant_id === "string" && appMetadata.tenant_id.length > 0 ? appMetadata.tenant_id : null;
+    return { email: email3, tenantId };
+  } catch {
+    return { email: null, tenantId: null };
+  }
+}
+function userSessionActingPrincipal(params) {
+  const identity = decodeSessionIdentity(params.accessToken);
+  return {
+    kind: "user_session",
+    subject: identity.email,
+    email: identity.email,
+    tenant_id: identity.tenantId,
+    tenant_name: params.tenantName ?? null,
+    role: null,
+    source: params.source,
+    principal_switch: null,
+    note: null
+  };
+}
+function implementationActingPrincipal(params) {
+  const other = params.otherCredential ?? null;
+  return {
+    kind: "implementation_bootstrap",
+    subject: params.implementationRunId,
+    email: null,
+    tenant_id: params.tenantId,
+    tenant_name: null,
+    role: "implementation credential",
+    source: params.source,
+    principal_switch: other === null ? null : `selected over ${other}`,
+    note: null
+  };
+}
+function tenantClause(principal) {
+  if (principal.tenant_name !== null) {
+    return ` \xB7 tenant ${principal.tenant_name}`;
+  }
+  if (principal.tenant_id !== null) {
+    return ` \xB7 tenant ${principal.tenant_id}`;
+  }
+  return " \xB7 no tenant selected";
+}
+function renderActingPrincipalHeader(principal) {
+  if (principal.kind === "none") {
+    return "acting as: none";
+  }
+  if (principal.kind === "unknown") {
+    return "acting as: unknown";
+  }
+  if (principal.kind === "implementation_bootstrap") {
+    const sourceClause2 = principal.source === null ? "" : ` \xB7 via ${principal.source}`;
+    const switchClause = principal.principal_switch === null ? "" : ` \xB7 ${principal.principal_switch}`;
+    return `acting as implementation credential${tenantClause(principal)}${sourceClause2}${switchClause}`;
+  }
+  const sourceClause = principal.source === null ? "" : ` \xB7 via ${principal.source}`;
+  if (principal.email === null) {
+    return `acting as user session (identity unresolved)${tenantClause(principal)}${sourceClause}`;
+  }
+  return `acting as ${principal.email} (user session)${tenantClause(principal)}${sourceClause}`;
+}
+function actingPrincipalEnvelope(principal, output) {
+  return { acting_principal: principal, output };
+}
+
 // src/cli-version.ts
 import { readFile as readFile4 } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
@@ -54524,7 +54639,7 @@ External connectors are being rolled out provider by provider, conservatively (r
     order: 48,
     title: "CLI and MCP installation guide",
     summary: "Install the public CLI, register remote token-backed MCP clients, and find the full command and tool catalog.",
-    version: "2026-08-04.4",
+    version: "2026-08-05.1",
     public: true,
     audiences: ["human", "cli", "mcp", "in_app_agent"],
     stages: ["company_setup", "staffing"],
@@ -55064,6 +55179,7 @@ These are the security posture rules for operating after install \u2014 a checkl
 ### Onboarding
 
 \`\`\`text
+{{cli}} onboard preflight [--json]
 {{cli}} onboard status
 {{cli}} onboard resume
 {{cli}} onboard run
@@ -55077,6 +55193,7 @@ Every tenant-scoped \`onboard\` verb (\`status\`, \`resume\`, \`source-ingest\`,
 
 | Command | Purpose | Scope | Safe example |
 |---|---|---|---|
+| \`{{cli}} onboard preflight\` | Print one pass/fail/unknown line per readiness condition (acting principal, implementation credential, CLI version, deployment reachability, pre-existing onboarding state) and exit nonzero on any fail or unknown. Runs before the session gate, so it works with no credentials. | Public (reports on whatever credential resolves) | \`{{cli}} onboard preflight --json\` |
 | \`{{cli}} onboard status\` | Return onboarding progress, graph summary, and next actions. | Tenant | \`{{cli}} onboard status\` |
 | \`{{cli}} onboard resume\` | Resume the guided onboarding flow where it left off. | Tenant | \`{{cli}} onboard resume\` |
 | \`{{cli}} onboard run\` | Print the deterministic agent onboarding prompt. | Public reference | \`{{cli}} onboard run\` |
@@ -59666,12 +59783,23 @@ ${onboardingUsage()}
     return 1;
   }
   const client = await deps.makeClient();
-  return executeOnboardingInvocation(invocation, io, client);
+  return executeOnboardingInvocation(invocation, io, client, {
+    ...deps.actingPrincipal === void 0 ? {} : { actingPrincipal: deps.actingPrincipal }
+  });
 }
 async function executeOnboardingInvocation(invocation, io, client, options = {}) {
+  const actingPrincipal = options.actingPrincipal;
   try {
     const result = await client.execute(invocation.commandId, invocation.body);
-    const rendered = invocation.json ? JSON.stringify(result.output, null, 2) : formatOnboardingOutput(invocation.action, result.output);
+    if (actingPrincipal !== void 0 && !invocation.json) {
+      io.stderr.write(`${renderActingPrincipalHeader(actingPrincipal)}
+`);
+    }
+    const rendered = invocation.json ? JSON.stringify(
+      actingPrincipal === void 0 ? result.output : actingPrincipalEnvelope(actingPrincipal, result.output),
+      null,
+      2
+    ) : formatOnboardingOutput(invocation.action, result.output);
     io.stdout.write(`${rendered}
 `);
     return 0;
@@ -59956,6 +60084,7 @@ function parseSetupInvocation(action, args) {
 function onboardingUsage() {
   return [
     `Usage: ${cliBrand.binName} onboard status|resume [--json]`,
+    `  ${cliBrand.binName} onboard preflight [--json]`,
     `  ${SOURCE_INGEST_USAGE}`,
     `  ${SETUP_USAGE}`,
     `  The plan's first seat (seats[0]) must be the single parentless root Seat and adopt the provisioned root Seat; its name must match the provisioned root seat's name after whitespace/case normalization.`,
@@ -60101,6 +60230,139 @@ function printCommandError(io, error51) {
   throw error51;
 }
 
+// src/commands/onboarding-preflight.ts
+var preflightCheckSchema = external_exports.object({
+  name: external_exports.string(),
+  status: external_exports.enum(["pass", "fail", "unknown"]),
+  detail: external_exports.string()
+}).strict();
+var preflightResultSchema = external_exports.object({
+  ok: external_exports.boolean(),
+  acting_principal: actingPrincipalSchema,
+  checks: external_exports.array(preflightCheckSchema)
+}).strict();
+function checkActingPrincipal(principal, sessionRefreshError, serverRejectedSession) {
+  if (principal.kind === "none") {
+    return {
+      name: "acting principal",
+      status: "fail",
+      detail: "no credential resolved; run login or start an implementation run"
+    };
+  }
+  if (principal.kind === "unknown") {
+    return {
+      name: "acting principal",
+      status: "unknown",
+      detail: "a credential is present but its identity could not be projected"
+    };
+  }
+  if (sessionRefreshError !== null) {
+    return {
+      name: "acting principal",
+      status: "fail",
+      detail: `${renderActingPrincipalHeader(principal).replace(/^acting as:? /, "")} \u2014 but the session could not be refreshed (${sessionRefreshError}); run login again`
+    };
+  }
+  if (serverRejectedSession) {
+    return {
+      name: "acting principal",
+      status: "fail",
+      detail: `${renderActingPrincipalHeader(principal).replace(/^acting as:? /, "")} \u2014 but the deployment rejected this session (HTTP 401); run login again`
+    };
+  }
+  return {
+    name: "acting principal",
+    status: "pass",
+    detail: renderActingPrincipalHeader(principal).replace(/^acting as:? /, "")
+  };
+}
+function checkImplementationCredential(credential, principal) {
+  const name = "implementation credential";
+  if (credential.kind === "error") {
+    return { name, status: "fail", detail: credential.detail };
+  }
+  if (credential.kind === "present") {
+    if (credential.expired) {
+      return { name, status: "fail", detail: `present but expired, stored_in ${credential.storedIn}` };
+    }
+    return { name, status: "pass", detail: `present and valid, stored_in ${credential.storedIn}` };
+  }
+  if (principal.kind === "user_session") {
+    return { name, status: "pass", detail: "absent; not required \u2014 acting via the user session" };
+  }
+  return { name, status: "unknown", detail: "no implementation credential found" };
+}
+async function checkCliVersion(deps) {
+  const name = "cli version";
+  const current = deps.cliVersion ?? "unknown";
+  const latest = await deps.fetchLatestVersion();
+  if (latest === null) {
+    return {
+      name,
+      status: "unknown",
+      detail: `local ${current}; deployment provenance not verifiable without a version/git endpoint`
+    };
+  }
+  if (deps.cliVersion !== null && deps.cliVersion === latest) {
+    return { name, status: "pass", detail: `local ${current} matches the latest published ${latest}` };
+  }
+  return {
+    name,
+    status: "unknown",
+    detail: `local ${current} differs from the latest published ${latest}; deployment build not proven`
+  };
+}
+function renderDeploymentReachability(probe2) {
+  const status = probe2.status === null ? "no HTTP status" : `HTTP ${probe2.status}`;
+  return {
+    name: "deployment reachability",
+    // Both the HTTP status AND the command outcome must have held; a printed
+    // 200 with a nonzero command exit is a fail.
+    status: probe2.ok ? "pass" : "fail",
+    detail: `${status} \u2014 ${probe2.detail}`
+  };
+}
+async function checkOnboardingState(deps) {
+  const name = "onboarding state";
+  if (deps.readOnboardingState === null) {
+    return { name, status: "unknown", detail: "skipped \u2014 no acting principal to resolve tenant state" };
+  }
+  const state = await deps.readOnboardingState();
+  if (!state.ok) {
+    return { name, status: "unknown", detail: state.detail };
+  }
+  return {
+    name,
+    status: "pass",
+    detail: state.alreadyOnboarded ? `already onboarded \u2014 ${state.detail}` : state.detail
+  };
+}
+async function runOnboardingPreflight(io, deps) {
+  const probe2 = await deps.probeDeployment();
+  const serverRejectedSession = !probe2.ok && probe2.status === 401 && deps.principal.kind === "user_session";
+  const checks = [
+    checkActingPrincipal(deps.principal, deps.sessionRefreshError, serverRejectedSession),
+    checkImplementationCredential(deps.implementationCredential, deps.principal),
+    await checkCliVersion(deps),
+    renderDeploymentReachability(probe2),
+    await checkOnboardingState(deps)
+  ];
+  const ok2 = checks.every((check2) => check2.status === "pass");
+  const result = { ok: ok2, acting_principal: deps.principal, checks };
+  if (deps.json) {
+    io.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+  } else {
+    io.stdout.write(`${renderActingPrincipalHeader(deps.principal)}
+`);
+    for (const check2 of checks) {
+      io.stdout.write(`${check2.status}: ${check2.name} \u2014 ${check2.detail}
+`);
+    }
+  }
+  return ok2 ? 0 : 1;
+}
+
 // src/commands/implementation-access.ts
 var implementationCredentialSchema = external_exports.object({
   token: external_exports.string().regex(/^rost_impl_[A-Za-z0-9_-]+$/),
@@ -70464,7 +70726,7 @@ function createImplementationLifecycleHooks(reader, tombstoneStore, credential)
     }
   };
 }
-function createImplementationBootstrapRun(io, outcome, lifecycle) {
+function createImplementationBootstrapRun(io, outcome, lifecycle, actingPrincipal) {
   return async (client, commandId, body, format, options) => {
     try {
       const result = await client.execute(commandId, body, options ?? {});
@@ -70483,7 +70745,11 @@ function createImplementationBootstrapRun(io, outcome, lifecycle) {
           return 1;
         }
       }
-      const rendered = format ? format(result.output) : JSON.stringify(result.output, null, 2);
+      if (actingPrincipal !== void 0 && format !== void 0) {
+        io.stderr.write(`${renderActingPrincipalHeader(actingPrincipal)}
+`);
+      }
+      const rendered = actingPrincipal !== void 0 && format === void 0 ? JSON.stringify(actingPrincipalEnvelope(actingPrincipal, result.output), null, 2) : format ? format(result.output) : JSON.stringify(result.output, null, 2);
       io.stdout.write(`${rendered}
 `);
       return 0;
@@ -70794,6 +71060,40 @@ async function main(argv = process.argv.slice(2), options = {}) {
   }
   const implCredentialReader = createImplementationCredentialReader(options.implementationCredentialStore);
   const tombstoneStore = (options.implementationRunTombstoneStore ?? createImplementationRunTombstoneStore)();
+  if (command === "onboard" && args[0] === "preflight") {
+    let sessionRefreshError = null;
+    const implCredentialPresent = (await implCredentialReader.read()).kind === "present";
+    if (session && !implCredentialPresent) {
+      try {
+        const refreshed2 = await refreshSession(config2, session);
+        if (refreshed2 !== session) {
+          session = refreshed2;
+          try {
+            await store.write(session);
+          } catch (error51) {
+            io.stderr.write(
+              `Session refreshed, but storing it failed: ${redactForLog(error51 instanceof Error ? error51.message : String(error51))}
+Run ${cliBrand.binName} login --device again if the next command asks you to authenticate.
+`
+            );
+          }
+        }
+      } catch (error51) {
+        sessionRefreshError = redactForLog(error51 instanceof Error ? error51.message : String(error51));
+      }
+    }
+    return executeOnboardPreflight({
+      io,
+      json: args.includes("--json"),
+      session,
+      sessionRefreshError,
+      appUrl: config2.appUrl,
+      storeSource: store.describe(),
+      CommandClientCtor: options.commandClient ?? CommandClient,
+      implCredentialReader,
+      env: process.env
+    });
+  }
   if (command === "onboard" && (args[0] === "status" || args[0] === "resume" || args[0] === "rehearse" || args[0] === "activate" || args[0] === "source-ingest" || args[0] === "setup" || args[0] === "setup-status")) {
     const credentialResolution = await resolveImplementationCredential(
       implCredentialReader,
@@ -70829,6 +71129,12 @@ ${onboardingUsage()}
       });
       let unusable = false;
       let denied = false;
+      const implPrincipal = implementationActingPrincipal({
+        tenantId: implCredential.tenant_id,
+        implementationRunId: implCredential.implementation_run_id,
+        source: implCredentialReader.describe(),
+        otherCredential: session ? "your logged-in user session" : null
+      });
       const exit = await executeOnboardingInvocation(invocation, io, implClient, {
         onError: (error51) => {
           if (error51 instanceof ImplementationBootstrapDeniedError) {
@@ -70840,7 +71146,8 @@ ${onboardingUsage()}
             return "handled";
           }
           return "print";
-        }
+        },
+        actingPrincipal: implPrincipal
       });
       if (exit !== "fall-through") {
         if (exit === 0 && !invocation.json && (invocation.action === "status" || invocation.action === "resume")) {
@@ -70876,6 +71183,12 @@ ${onboardingUsage()}
     if (credentialResolution.kind === "usable") {
       const implCredential = credentialResolution.credential;
       const outcome = { unusable: false, denied: false, cleanupFailed: false };
+      const implPrincipal = implementationActingPrincipal({
+        tenantId: implCredential.tenant_id,
+        implementationRunId: implCredential.implementation_run_id,
+        source: implCredentialReader.describe(),
+        otherCredential: session ? "your logged-in user session" : null
+      });
       const exit = await runOperation("seat", args, {
         io,
         client: createImplementationBootstrapClient(options.commandClient ?? CommandClient, {
@@ -70883,7 +71196,7 @@ ${onboardingUsage()}
           token: implCredential.token
         }),
         binName: cliBrand.binName,
-        run: createImplementationBootstrapRun(io, outcome)
+        run: createImplementationBootstrapRun(io, outcome, void 0, implPrincipal)
       });
       if (!outcome.unusable && !outcome.denied && !outcome.cleanupFailed) {
         return exit;
@@ -70938,7 +71251,15 @@ ${onboardingUsage()}
               credentialResolution.credential
             ),
             hasUserSession: Boolean(session),
-            CommandClientCtor: options.commandClient ?? CommandClient
+            CommandClientCtor: options.commandClient ?? CommandClient,
+            // DER-2812: name the bounded principal; a co-resident session means
+            // it was selected over the owner's own session for this command.
+            actingPrincipal: implementationActingPrincipal({
+              tenantId: credentialResolution.credential.tenant_id,
+              implementationRunId: credentialResolution.credential.implementation_run_id,
+              source: implCredentialReader.describe(),
+              otherCredential: session ? "your logged-in user session" : null
+            })
           });
           if (routed !== "fall-through") {
             return routed;
@@ -70982,6 +71303,10 @@ Run ${cliBrand.binName} login --device again if the next command asks you to aut
     token: session.accessToken,
     credentialKind: "user_session"
   });
+  const actingPrincipal = userSessionActingPrincipal({
+    accessToken: session.accessToken,
+    source: store.describe()
+  });
   if (justLoggedIn) {
     await maybePrintSignupBootstrap(io, client, config2.appUrl);
   }
@@ -70992,16 +71317,16 @@ Run ${cliBrand.binName} login --device again if the next command asks you to aut
     return runTenantCreate(io, client, args, (tenantIo, tenantClient, commandId, body) => executeCommandWithResult(tenantIo, tenantClient, commandId, body));
   }
   if (command === "whoami") {
-    return printCommandOutput(io, client, "user.whoami");
+    return printCommandOutput(io, client, "user.whoami", {}, void 0, {}, actingPrincipal);
   }
   if (command === "tenants") {
-    return printCommandOutput(io, client, "user.tenants");
+    return printCommandOutput(io, client, "user.tenants", {}, void 0, {}, actingPrincipal);
   }
   if (command === "command") {
-    return executeDirectCommand(io, client, args);
+    return executeDirectCommand(io, client, args, void 0, actingPrincipal);
   }
   if (command === "onboard") {
-    return runOnboarding(args, io, { makeClient: async () => client });
+    return runOnboarding(args, io, { makeClient: async () => client, actingPrincipal });
   }
   if (command === "mcp") {
     return executeMcp(io, client, config2.appUrl, args);
@@ -71012,18 +71337,18 @@ Run ${cliBrand.binName} login --device again if the next command asks you to aut
         io,
         client,
         binName: cliBrand.binName,
-        run: (wrapperClient, commandId, body, format, options2) => printCommandOutput(io, wrapperClient, commandId, body, format, options2)
+        run: (wrapperClient, commandId, body, format, options2) => printCommandOutput(io, wrapperClient, commandId, body, format, options2, actingPrincipal)
       });
     }
     return runSkills({
       io,
       client,
       binName: cliBrand.binName,
-      run: (wrapperClient, commandId, body, format, options2) => printCommandOutput(io, wrapperClient, commandId, body, format, options2)
+      run: (wrapperClient, commandId, body, format, options2) => printCommandOutput(io, wrapperClient, commandId, body, format, options2, actingPrincipal)
     }, args);
   }
   if (command === "init") {
-    return executeInit(io, client, config2.appUrl, args);
+    return executeInit(io, client, config2.appUrl, args, actingPrincipal);
   }
   if (isOperationGroup(command)) {
     return runOperation(command, args, {
@@ -71032,7 +71357,7 @@ Run ${cliBrand.binName} login --device again if the next command asks you to aut
       binName: cliBrand.binName,
       // Single execution path: wrappers route through printCommandOutput, the
       // same helper `rost command <id> --json` uses (shared client + redaction).
-      run: (wrapperClient, commandId, body, format, options2) => printCommandOutput(io, wrapperClient, commandId, body, format, options2)
+      run: (wrapperClient, commandId, body, format, options2) => printCommandOutput(io, wrapperClient, commandId, body, format, options2, actingPrincipal)
     });
   }
   const tenant = args[0];
@@ -71041,7 +71366,7 @@ Run ${cliBrand.binName} login --device again if the next command asks you to aut
 `);
     return 1;
   }
-  return printCommandOutput(io, client, "user.use_tenant", { tenant });
+  return printCommandOutput(io, client, "user.use_tenant", { tenant }, void 0, {}, actingPrincipal);
 }
 function resolveRoutableCommandId(command, args) {
   if (command === "command") {
@@ -71077,7 +71402,7 @@ async function runImplementationBootstrapCommand(params) {
     token: params.token
   });
   const outcome = { unusable: false, denied: false, cleanupFailed: false };
-  const run2 = createImplementationBootstrapRun(io, outcome, params.lifecycle);
+  const run2 = createImplementationBootstrapRun(io, outcome, params.lifecycle, params.actingPrincipal);
   let exit;
   try {
     if (command === "command") {
@@ -71108,7 +71433,103 @@ async function runImplementationBootstrapCommand(params) {
   }
   return exit;
 }
-async function executeDirectCommand(io, client, args, send = (sendClient, commandId, body, format, options) => printCommandOutput(io, sendClient, commandId, body, format, options)) {
+async function executeOnboardPreflight(params) {
+  const { io, session, appUrl: appUrl2, CommandClientCtor, implCredentialReader } = params;
+  const implResult = await implCredentialReader.read();
+  const implExpired = implResult.kind === "present" && isImplementationCredentialExpired(implResult.credential.expires_at);
+  const implementationCredential = implResult.kind === "present" ? { kind: "present", expired: implExpired, storedIn: implCredentialReader.describe() } : implResult.kind === "error" ? { kind: "error", detail: `unable to read the implementation credential from ${implCredentialReader.describe()}` } : { kind: "absent" };
+  const presentImpl = implResult.kind === "present" ? implResult.credential : null;
+  const principal = presentImpl ? implementationActingPrincipal({
+    tenantId: presentImpl.tenant_id,
+    implementationRunId: presentImpl.implementation_run_id,
+    source: implCredentialReader.describe(),
+    otherCredential: session ? "your logged-in user session" : null
+  }) : session ? userSessionActingPrincipal({ accessToken: session.accessToken, source: params.storeSource }) : { kind: "none", subject: null, email: null, tenant_id: null, tenant_name: null, role: null, source: null, principal_switch: null, note: null };
+  const probeWith = async (client, commandId, label) => {
+    try {
+      await client.execute(commandId);
+      return { ok: true, status: 200, detail: `${label} succeeded` };
+    } catch (error51) {
+      const status = error51 instanceof CommandClientError ? error51.status : null;
+      return { ok: false, status, detail: `${label} did not complete` };
+    }
+  };
+  const probeDeployment = async () => {
+    if (presentImpl) {
+      const client = createImplementationBootstrapClient(CommandClientCtor, { appUrl: appUrl2, token: presentImpl.token });
+      return probeWith(client, "onboarding.status", "implementation-credential round-trip");
+    }
+    if (session) {
+      const client = new CommandClientCtor({ appUrl: appUrl2, token: session.accessToken, credentialKind: "user_session" });
+      return probeWith(client, "user.whoami", "authenticated user-session round-trip");
+    }
+    try {
+      const response = await fetch(appUrl2, { method: "GET" });
+      return {
+        ok: response.ok,
+        status: response.status,
+        detail: `unauthenticated GET ${response.ok ? "reachable" : "not reachable"}`
+      };
+    } catch (error51) {
+      return {
+        ok: false,
+        status: null,
+        detail: `unauthenticated GET failed: ${redactForLog(error51 instanceof Error ? error51.message : String(error51))}`
+      };
+    }
+  };
+  const stateClient = presentImpl ? createImplementationBootstrapClient(CommandClientCtor, { appUrl: appUrl2, token: presentImpl.token }) : session ? new CommandClientCtor({ appUrl: appUrl2, token: session.accessToken, credentialKind: "user_session" }) : null;
+  const readOnboardingState = stateClient === null ? null : async () => {
+    try {
+      const result = await stateClient.execute("onboarding.status");
+      const record2 = asRecord5(result.output);
+      const onboarded = record2.onboarded === true;
+      return {
+        ok: true,
+        alreadyOnboarded: onboarded,
+        detail: onboarded ? "onboarding.status reports onboarded" : "onboarding.status reports not yet onboarded"
+      };
+    } catch {
+      return { ok: false, alreadyOnboarded: false, detail: "onboarding.status could not be read for this principal" };
+    }
+  };
+  return runOnboardingPreflight(io, {
+    json: params.json,
+    principal,
+    // Only meaningful for a session-backed principal; a present implementation
+    // credential skips the refresh entirely, so this is null on that path.
+    sessionRefreshError: presentImpl ? null : params.sessionRefreshError,
+    implementationCredential,
+    cliVersion: await readCliVersion(),
+    fetchLatestVersion: () => fetchLatestCliVersion(params.env),
+    probeDeployment,
+    readOnboardingState
+  });
+}
+async function fetchLatestCliVersion(env) {
+  if (env.CI || env.VITEST || env[`${cliBrand.envPrefix}_CLI_NO_UPDATE_CHECK`] === "1") {
+    return null;
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 750);
+  try {
+    const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(cliBrand.packageName)}/latest`, {
+      headers: { accept: "application/json" },
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      return null;
+    }
+    const body = await response.json();
+    return typeof body.version === "string" ? body.version : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function executeDirectCommand(io, client, args, send, actingPrincipal) {
+  const sendCommand = send ?? ((sendClient, commandId2, body2, format, options) => printCommandOutput(io, sendClient, commandId2, body2, format, options, actingPrincipal));
   const first = args[0];
   if (first === "schema") {
     const id = args[1];
@@ -71118,11 +71539,11 @@ async function executeDirectCommand(io, client, args, send = (sendClient, comman
       return 1;
     }
     const json2 = args.includes("--json");
-    return send(client, "command.describe", { id }, json2 ? void 0 : formatCommandSchema);
+    return sendCommand(client, "command.describe", { id }, json2 ? void 0 : formatCommandSchema);
   }
   if (first === "list") {
     const json2 = args.includes("--json");
-    return send(client, "command.list", {}, json2 ? void 0 : formatCommandList);
+    return sendCommand(client, "command.list", {}, json2 ? void 0 : formatCommandList);
   }
   const commandId = first;
   if (isSecretBlockedCommand(commandId)) {
@@ -71155,7 +71576,7 @@ async function executeDirectCommand(io, client, args, send = (sendClient, comman
 `);
     return 1;
   }
-  return send(client, commandId, body, void 0, {
+  return sendCommand(client, commandId, body, void 0, {
     ...seat === void 0 ? {} : { targetSeatId: seat },
     autoConfirm
   });
@@ -71233,10 +71654,10 @@ async function executeMcp(io, client, appUrl2, args) {
     return 1;
   }
 }
-async function executeInit(io, client, appUrl2, args) {
+async function executeInit(io, client, appUrl2, args, actingPrincipal) {
   const { tenant, mcpArgs } = parseInitArgs(args);
   if (tenant) {
-    const tenantExitCode = await printCommandOutput(io, client, "user.use_tenant", { tenant });
+    const tenantExitCode = await printCommandOutput(io, client, "user.use_tenant", { tenant }, void 0, {}, actingPrincipal);
     if (tenantExitCode !== 0) {
       return tenantExitCode;
     }
@@ -71273,11 +71694,23 @@ function parseInitArgs(args) {
     mcpArgs: hasScope || isRotate ? baseArgs : [...baseArgs, "--scope", "tenant-admin"]
   };
 }
-async function printCommandOutput(io, client, commandId, body = {}, format, options = {}) {
+async function printCommandOutput(io, client, commandId, body = {}, format, options = {}, actingPrincipal) {
+  const emitHeader = () => {
+    if (actingPrincipal !== void 0 && format !== void 0) {
+      io.stderr.write(`${renderActingPrincipalHeader(actingPrincipal)}
+`);
+    }
+  };
+  const renderResult = (output) => {
+    if (actingPrincipal !== void 0 && format === void 0) {
+      return JSON.stringify(actingPrincipalEnvelope(actingPrincipal, output), null, 2);
+    }
+    return format ? format(output) : JSON.stringify(output, null, 2);
+  };
   try {
     const result = await client.execute(commandId, body, options);
-    const rendered = format ? format(result.output) : JSON.stringify(result.output, null, 2);
-    io.stdout.write(`${rendered}
+    emitHeader();
+    io.stdout.write(`${renderResult(result.output)}
 `);
     return 0;
   } catch (error51) {
@@ -71297,8 +71730,8 @@ async function printCommandOutput(io, client, commandId, body = {}, format, opti
             reviewed: true
           });
           const approvedOutput = asRecord5(approvedResult.output).output ?? approvedResult.output;
-          const rendered = format ? format(approvedOutput) : JSON.stringify(approvedOutput, null, 2);
-          io.stdout.write(`${rendered}
+          emitHeader();
+          io.stdout.write(`${renderResult(approvedOutput)}
 `);
           return 0;
         } catch (approvalError) {
@@ -71311,8 +71744,8 @@ async function printCommandOutput(io, client, commandId, body = {}, format, opti
       try {
         const approvedResult = await client.execute("confirmation.approve", { confirmation_id: pending.confirmationId });
         const approvedOutput = asRecord5(approvedResult.output).output ?? approvedResult.output;
-        const rendered = format ? format(approvedOutput) : JSON.stringify(approvedOutput, null, 2);
-        io.stdout.write(`${rendered}
+        emitHeader();
+        io.stdout.write(`${renderResult(approvedOutput)}
 `);
         return 0;
       } catch (approvalError) {
@@ -71435,6 +71868,7 @@ function printUsage(io) {
     `${cliBrand.binName} command list [--json]`,
     `${cliBrand.binName} doctor`,
     ...operationUsageLines(cliBrand.binName),
+    `${cliBrand.binName} onboard preflight [--json]`,
     `${cliBrand.binName} onboard status`,
     `${cliBrand.binName} onboard resume`,
     `${cliBrand.binName} onboard run`,