totemlayer 0.1.0 → 0.1.2

package/bin/totem.mjs

@@ -4,9 +4,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { stripVTControlCharacters } from "node:util";
 
-const RFQ_EXAMPLE =
-  "Request a quote for 50,000 Industrial Sensors (SKU-1001) from SupplyCo using Acme Procurement Agent.";
-const CLI_VERSION = "0.1.0";
+const CLI_VERSION = "0.1.2";
 const DEFAULT_BASE_URL = "https://totemlayer.com";
 const API_KEY_PATTERN = /^at_(?:live|test)_[A-Za-z0-9_-]{20,}$/;
 const ACTION_PATTERN = /^[a-z0-9][a-z0-9._:-]*$/;
@@ -16,73 +14,361 @@ const TERMINAL_UNSAFE_PATTERN =
   /[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
 const MAX_JSON_INPUT_BYTES = 128 * 1_024;
 const MAX_REQUEST_FILE_BYTES = 16 * 1_024 * 1_024;
-const PRESENTATION_REJECTION_CODES = new Set([
-  "CHALLENGE_NOT_FOUND",
-  "CHALLENGE_NOT_PRESENTED",
-  "CHALLENGE_ALREADY_PRESENTED",
+const ISO_CURRENCY_CODES = new Set(Intl.supportedValuesOf("currency"));
+const BRAND_ART = [
+  "       ╭╮",
+  "   ╭───╯╰────╮   ╺┳╸┏━┓╺┳╸┏━╸┏┳┓",
+  "  ╰────╮╭────╯    ┃ ┃ ┃ ┃ ┣╸ ┃┃┃",
+  "       ╰╯          ╹ ┗━┛ ╹ ┗━╸╹ ╹",
+];
+const HANDSHAKE_REJECTION_CODES = new Set([
+  "AGENT_AUTHORITY_REVOKED",
+  "BEACON_VERIFICATION_FAILED",
   "CHALLENGE_ALREADY_CONSUMED",
+  "CHALLENGE_ALREADY_PRESENTED",
   "CHALLENGE_EXPIRED",
+  "CHALLENGE_NOT_FOUND",
+  "CHALLENGE_NOT_PENDING",
+  "CHALLENGE_NOT_PRESENTED",
+  "CONTACT_RELATIONSHIP_CHANGED",
+  "CONTACT_RELATIONSHIP_REQUIRED",
+  "CREDENTIAL_NOT_PRESENTABLE",
+  "ENVIRONMENT_MISMATCH",
+  "ENVIRONMENT_UNCLASSIFIED",
+  "IDEMPOTENCY_KEY_REUSED",
+  "INVALID_PRESENTATION_SIGNATURE",
   "PRESENTATION_EXPIRED",
+  "PRESENTATION_CLAIMS_MISMATCH",
   "PRESENTATION_MISMATCH",
   "PRESENTER_AGENT_INACTIVE",
-  "AGENT_AUTHORITY_REVOKED",
-  "INVALID_PRESENTATION_SIGNATURE",
-  "PRESENTATION_CLAIMS_MISMATCH",
+  "TRANSACTION_NOT_AUTHORIZED",
+  "VERIFIER_AGENT_INACTIVE",
+]);
+const ACTION_CHECK_SUITE_STATUSES = new Set(["QUEUED", "RUNNING", "COMPLETED", "STALE"]);
+const ACTION_CHECK_SUITE_CONCLUSIONS = new Set([
+  "ALLOW",
+  "ALLOW_WITH_WARNINGS",
+  "REQUIRES_APPROVAL",
+  "BLOCK",
+  "ERROR",
+]);
+const ACTION_EXECUTION_OUTCOMES = new Set(["SUCCEEDED", "FAILED", "UNKNOWN", "COMPENSATED"]);
+const ACTION_CHECK_POLICY_CODES = new Set([
+  "ACTION_APPROVAL_REQUIRED",
+  "ACTION_APPROVAL_STALE",
+  "ACTION_AUTHORITY_CHANGED",
+  "ACTION_CHECKS_NOT_ALLOWED",
+  "ACTION_CONFIRMATION_MISMATCH",
+  "ACTION_DIGEST_MISMATCH",
+  "ACTION_EXECUTION_ATTEMPT_CONFLICT",
+  "ACTION_EXPIRED",
+  "ACTION_FINAL_CHECKS_FAILED",
+  "ACTION_GRANT_BINDING_MISMATCH",
+  "ACTION_GRANT_EXPIRED",
+  "ACTION_GRANT_INVALID",
+  "ACTION_GRANT_REPLAYED",
+  "ACTION_POLICY_CHANGED",
+  "ACTION_RECEIPT_STATE_CHANGED",
+  "ACTION_SUITE_EXPIRED",
+  "ACTION_SUITE_INCOMPLETE",
+  "ACTION_SUITE_STALE",
+  "ACTION_SUITE_STATE_CHANGED",
+  "DEMO_FIXTURE_INACTIVE",
+  "DEMO_FIXTURE_NOT_OWNED",
+  "DESTRUCTIVE_TARGET_UNCONSTRAINED",
+  "EXECUTOR_ADAPTER_MISMATCH",
+  "EXECUTOR_ADAPTER_NOT_PUBLIC",
+  "FINANCIAL_CONTEXT_MISSING",
 ]);
 
+function supportsColor(stream = process.stdout) {
+  return Boolean(stream.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb");
+}
+
+function styled(value, code, stream = process.stdout) {
+  return supportsColor(stream) ? `\u001b[${code}m${value}\u001b[0m` : value;
+}
+
+function interactiveWidth(stream = process.stdout) {
+  const columns = Number(stream.columns);
+  if (!stream.isTTY || !Number.isInteger(columns) || columns < 48) return undefined;
+  return Math.min(columns, 120);
+}
+
+function wrappedTerminalLines(value, prefixLength, stream = process.stdout) {
+  const width = interactiveWidth(stream);
+  if (!width) return [value];
+  const available = Math.max(24, width - prefixLength - 1);
+  const words = value.split(" ");
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (!line) {
+      line = word;
+      continue;
+    }
+    if (line.length + word.length + 1 <= available) {
+      line += ` ${word}`;
+      continue;
+    }
+    lines.push(line);
+    line = word;
+  }
+  if (line) lines.push(line);
+  return lines.length > 0 ? lines : [""];
+}
+
+function writeHumanLine(
+  label,
+  value,
+  { stream = process.stdout, labelCode = "2", valueCode, suffix = ":" } = {},
+) {
+  const safeLabel = terminalText(label, "Result");
+  const safeValue = terminalText(value, "unknown");
+  const prefix = `${safeLabel}${suffix} `;
+  const continuation = " ".repeat(prefix.length);
+  for (const [index, line] of wrappedTerminalLines(safeValue, prefix.length, stream).entries()) {
+    const renderedValue = valueCode ? styled(line, valueCode, stream) : line;
+    stream.write(
+      index === 0
+        ? `${styled(`${safeLabel}${suffix}`, labelCode, stream)} ${renderedValue}\n`
+        : `${continuation}${renderedValue}\n`,
+    );
+  }
+}
+
+function wrappedHelpLines(line, width) {
+  if (!width || line.length <= width) return [line];
+
+  const optionMatch = line.match(
+    /^(\s{2}(?:--\S+(?:\s+<[^>]+>)?|-[hv],\s+--\S+|decision\.json|Install once|Confirm installation|Run one-off)\s+)(\S.*)$/,
+  );
+  const firstPrefix = optionMatch?.[1] ?? line.match(/^\s*/)?.[0] ?? "";
+  let continuationPrefix = optionMatch ? " ".repeat(firstPrefix.length) : firstPrefix;
+  const fallbackPrefix = firstPrefix ? "    " : "";
+  const words = (optionMatch?.[2] ?? line.slice(firstPrefix.length)).split(" ");
+  const output = [];
+  let prefix = firstPrefix;
+  let current = prefix;
+
+  for (const word of words) {
+    if (!word) continue;
+    const separator = current.length > prefix.length ? " " : "";
+    if (`${current}${separator}${word}`.length <= width) {
+      current += `${separator}${word}`;
+      continue;
+    }
+    if (current.length > prefix.length) output.push(current);
+    if (continuationPrefix.length + word.length > width) continuationPrefix = fallbackPrefix;
+    prefix = continuationPrefix;
+    current = `${prefix}${word}`;
+  }
+  if (current.length > prefix.length) output.push(current);
+  return output.length > 0 ? output : [line];
+}
+
+function writeHelpBody(body) {
+  const headings = new Set([
+    "Start here",
+    "Authorization handshake",
+    "Action Checks · local or self-hosted",
+    "Procurement demonstration",
+    "Shared options:",
+    "Challenge options:",
+    "Verification binding:",
+    "Presentation input:",
+    "Action Checks input (local/self-hosted only):",
+    "Authentication:",
+  ]);
+  const width = interactiveWidth();
+  const output = body
+    .split("\n")
+    .flatMap((line) => wrappedHelpLines(line, width))
+    .map((line) => (headings.has(line) ? styled(line, "1;38;2;58;153;200") : line))
+    .join("\n");
+  process.stdout.write(output);
+}
+
+function writeBrand() {
+  const art = BRAND_ART.map((line, index) =>
+    styled(line, index < 2 ? "38;2;58;153;200" : "38;2;21;37;131"),
+  ).join("\n");
+  process.stdout.write(`${art}\n`);
+  const title = `TotemLayer CLI ${CLI_VERSION} · cross-company agent authorization`;
+  const titleLines = wrappedTerminalLines(title, 0);
+  for (const [index, line] of titleLines.entries()) {
+    const versionPrefix = `TotemLayer CLI ${CLI_VERSION}`;
+    process.stdout.write(
+      `${index === 0 && line.startsWith(versionPrefix) ? styled(versionPrefix, "1") + line.slice(versionPrefix.length) : line}\n`,
+    );
+  }
+  process.stdout.write("\n");
+}
+
+function writeHumanResult(header, fields, nextStep, tone = "success", secrets = []) {
+  const toneCode = tone === "danger" ? "38;2;255;114;114" : "38;2;58;153;200";
+  process.stdout.write(`${styled(redactCliSecrets(header, secrets), `1;${toneCode}`)}\n`);
+  const dividerLength = Math.min(interactiveWidth() ?? 40, 56);
+  process.stdout.write(`${styled("─".repeat(dividerLength), "2")}\n`);
+  for (const [label, value] of fields) {
+    if (value === undefined || value === null || value === "") continue;
+    writeHumanLine(label, redactCliSecrets(value, secrets), {
+      valueCode: ["Status", "Decision", "Run", "Agent authority"].includes(label)
+        ? `1;${toneCode}`
+        : undefined,
+    });
+  }
+  if (nextStep) {
+    process.stdout.write("\n");
+    writeHumanLine("Next →", nextStep, { labelCode: `1;${toneCode}`, suffix: "" });
+  }
+}
+
+function writeHumanArtifact(payload, secrets) {
+  process.stdout.write(`\n${styled("Artifact JSON · save securely", "1")}\n`);
+  writeJson(redactJsonSecrets(payload, secrets));
+}
+
+function compactDigest(value) {
+  const digest = terminalText(value, "not returned");
+  return digest.length > 28 ? `${digest.slice(0, 16)}…${digest.slice(-8)}` : digest;
+}
+
 function help() {
-  process.stdout.write(`TotemLayer CLI ${CLI_VERSION}
+  writeBrand();
+  writeHelpBody(`Start here
+  Install once          npm install --global totemlayer
+  Confirm installation totem --version
+  Run one-off           npx --yes totemlayer --help
+
+Authorization handshake
+  totem challenge \\
+    --presenter-agent <agent-id> \\
+    --action <action> \\
+    (--request-digest <sha256> | \\
+      --request-file <path>) \\
+    [--amount <number> --currency <ISO-4217>] \\
+    --json
+  totem present \\
+    --credential-id <credential-id> \\
+    [--challenge-file <path>] \\
+    --json
+  totem verify \\
+    --challenge-file <receiver-challenge.json> \\
+    (--request-digest <sha256> | \\
+      --request-file <path>) \\
+    [--presentation-file <path>] \\
+    --json
 
-Install:
-  npm install --global totemlayer
-  npx --yes totemlayer --help
+Action Checks · local or self-hosted
+  totem checks run --file <action.json>
+  totem checks view <suite-id>
+  totem checks approve <suite-id> \\
+    [--file <decision.json>]
+  totem checks reject <suite-id> \\
+    [--file <decision.json>]
+  totem checks grant <suite-id> \\
+    --file <action.json>
+  totem checks execute <suite-id> \\
+    --file <execution.json>
 
-Usage:
-  totem challenge --presenter-agent <agent-id> --action <action> \\
-    (--request-digest <sha256> | --request-file <path>) [--amount <number> --currency <ISO-4217>] --json
-  totem present --credential-id <credential-id> [--challenge-file <path>] --json
-  totem verify --challenge-file <receiver-challenge.json> \\
-    (--request-digest <sha256> | --request-file <path>) [--presentation-file <path>] --json
-  totem rfq "${RFQ_EXAMPLE}"  # sandbox/self-hosted demo only
+Procurement demonstration
+  totem rfq \\
+    "Request a quote for 50,000 Industrial" \\
+    "Sensors (SKU-1001) from SupplyCo using" \\
+    "Acme Procurement Agent."
+  Sandbox/self-hosted demo only.
 
 Shared options:
-  --base-url <url>          Totem URL (default: TOTEM_URL or ${DEFAULT_BASE_URL})
-  --json                    Print the complete machine-readable JSON response
+  --base-url <url>          Totem URL; default:
+                            TOTEM_URL or
+                            ${DEFAULT_BASE_URL}
+  --json                    Print complete machine-readable
+                            JSON
   -h, --help                Show this help
   -v, --version             Print the CLI version
 
 Challenge options:
-  --presenter-agent <id>    Exact agent expected to present authority
-  --action <action>         Namespaced action, for example inventory.read
-  --request-digest <sha256> SHA-256 of the request being authorized
-  --request-file <path>     Hash this file locally; file contents are never uploaded
-  --amount <number>         Optional transaction amount; requires --currency
-  --currency <code>         Three-letter ISO currency; requires --amount
-  --idempotency-key <key>   Reuse for an exact retry (a random key is used by default)
+  --presenter-agent <id>    Exact expected presenter agent
+  --action <action>         Namespaced action; for example,
+                            inventory.read
+  --request-digest <sha256> SHA-256 of the exact request
+  --request-file <path>     Hash this file locally; contents
+                            are never uploaded
+  --amount <number>         Optional amount; requires
+                            --currency
+  --currency <code>         ISO currency; requires --amount
+  --idempotency-key <key>   Reuse for an exact retry; a
+                            random key is used by default
 
 Verification binding:
-  --challenge-file <path>   Receiver's original challenge; never trust a returned copy
-  --request-digest <sha256> Require approval evidence for this exact request digest
-  --request-file <path>     Hash the exact local request before accepting an approval
+  --challenge-file <path>   Receiver's original challenge;
+                            never trust a returned copy
+  --request-digest <sha256> Require evidence for this exact
+                            request digest
+  --request-file <path>     Hash the exact local request
+                            before accepting approval
 
 Presentation input:
-  present reads challenge JSON from stdin unless --challenge-file is supplied.
-  verify reads presentation JSON from stdin unless --presentation-file is supplied and
-  compares it with the receiver-owned --challenge-file before consuming the proof.
-  Raw keys, nonces, credentials, and presentation tokens are never accepted as arguments.
+  present reads challenge JSON from stdin unless
+  you supply --challenge-file.
+  verify reads presentation JSON from stdin unless
+  you supply --presentation-file. It compares that proof
+  with the receiver-owned --challenge-file before use.
+  Raw keys, nonces, credentials, and presentation tokens are
+  never accepted as arguments.
+
+Action Checks input (local/self-hosted only):
+  --file <path>             run/grant: exact action JSON
+                            execute: JSON containing
+                            "action" and "grant"
+  decision.json             Optional decision body; example:
+      {"confirmation":"...","reason":"..."}
+                            Never put confirmation, grant,
+                            session cookie, or action
+                            payload on the command line
+  Action Checks always emit structured JSON.
+  Blocked, rejected, expired, stale, or replayed actions
+  exit 2. Invalid input, network, authentication, and
+  operational failures exit 1.
 
 Authentication:
   challenge and verify use TOTEM_API_KEY.
-  present uses TOTEM_AGENT_API_KEY bound to the presenting agent.
-  Keys are sent only in the Authorization header and are never printed.
+  present uses TOTEM_AGENT_API_KEY bound to the presenter.
+  checks run/view/grant/execute use TOTEM_API_KEY with an
+  Action Checks scope.
+  checks approve/reject never use an API key. They require
+  an authenticated human browser session, supplied only
+  through TOTEM_SESSION_COOKIE as a Cookie header value.
+  Clear it after the command. Without it, use /checks.
+  Keys are sent only in the Authorization header and are
+  never printed.
 
-Production supports challenge, present, and verify. The RFQ command requires a
-sandbox or self-hosted Totem deployment with the procurement demo enabled.
+Production supports challenge, present, and verify.
+Action Checks and RFQ require a sandbox or self-hosted Totem
+deployment with their local demonstrations enabled.
+
+Human-readable commands show the decision, evidence, and
+safest next step. Successful human challenge and present
+commands also print their complete short-lived artifact.
+Save it securely: the next participant needs its nonce or
+presentation token. Add --json when another program needs
+the complete machine-readable response.
 `);
 }
 
 function fail(message) {
-  process.stderr.write(`Totem: ${terminalText(message, "The Totem command failed.")}\n`);
+  process.stderr.write(
+    `${styled("Totem: command failed", "1;38;2;255;114;114", process.stderr)}\n`,
+  );
+  writeHumanLine("Reason", terminalText(message, "The Totem command failed."), {
+    stream: process.stderr,
+    labelCode: "1;38;2;255;114;114",
+  });
+  writeHumanLine("Next", "Fix the reason above, or run `totem --help` for a complete example.", {
+    stream: process.stderr,
+    labelCode: "1;38;2;58;153;200",
+  });
   process.exitCode = 1;
 }
 
@@ -104,8 +390,23 @@ function failUnknownOutcome(message, idempotencyKey, json, machineStdout = false
   fail(`${message} The outcome is unknown; retry with --idempotency-key "${idempotencyKey}".`);
 }
 
+function failHandshakeUnknownOutcome(operation, message, json) {
+  const guidance =
+    operation === "presentation"
+      ? "Do not retry this challenge blindly; ask the receiver to reconcile it or create a fresh challenge."
+      : "Do not act on the request; reconcile the original challenge before retrying or create a fresh handshake.";
+  const safeMessage = `${message} The ${operation} outcome is unknown. ${guidance}`;
+  if (json) {
+    writeJson({ error: { message: safeMessage, outcome: "unknown", operation } });
+    process.exitCode = 1;
+    return;
+  }
+  fail(safeMessage);
+}
+
 function parseArguments(values) {
   const options = { json: false, positionals: [] };
+  let parsingOptions = true;
   const valuedOptions = new Set([
     "--base-url",
     "--idempotency-key",
@@ -118,10 +419,18 @@ function parseArguments(values) {
     "--challenge-file",
     "--credential-id",
     "--presentation-file",
+    "--file",
   ]);
   for (let index = 0; index < values.length; index += 1) {
     const value = values[index];
-    if (value === "--") continue;
+    if (parsingOptions && value === "--") {
+      parsingOptions = false;
+      continue;
+    }
+    if (!parsingOptions) {
+      options.positionals.push(value);
+      continue;
+    }
     if (value === "--json") {
       options.json = true;
       continue;
@@ -137,7 +446,9 @@ function parseArguments(values) {
     if (valuedOptions.has(value)) {
       const next = values[index + 1];
       if (!next || next.startsWith("--")) throw new Error(`${value} requires a value.`);
-      options[value.slice(2).replaceAll("-", "_")] = next;
+      const key = value.slice(2).replaceAll("-", "_");
+      if (options[key] !== undefined) throw new Error(`${value} may be supplied only once.`);
+      options[key] = next;
       index += 1;
       continue;
     }
@@ -149,8 +460,13 @@ function parseArguments(values) {
 
 function safeBaseUrl(value) {
   const url = new URL(value);
-  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) {
-    throw new Error("The Totem URL must be an HTTP(S) origin without credentials.");
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    (url.pathname !== "/" && url.pathname !== "")
+  ) {
+    throw new Error("The Totem URL must be an HTTP(S) origin without credentials or a path.");
   }
   const local = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
   if (url.protocol !== "https:" && !local) {
@@ -162,6 +478,29 @@ function safeBaseUrl(value) {
   return url;
 }
 
+function validIdempotencyKey(value, flag = "--idempotency-key") {
+  if (
+    typeof value !== "string" ||
+    value !== value.trim() ||
+    value.length < 8 ||
+    value.length > 128 ||
+    !SAFE_IDENTIFIER_PATTERN.test(value) ||
+    /^at_(?:live|test)_/i.test(value) ||
+    value.split(".").length === 3
+  ) {
+    throw new Error(`${flag} must contain 8 to 128 safe identifier characters.`);
+  }
+  return value;
+}
+
+function requireLocalActionChecks(baseUrl) {
+  if (baseUrl.origin === DEFAULT_BASE_URL) {
+    throw new Error(
+      "Action Checks commands are available only on a local or self-hosted Totem deployment. Set TOTEM_URL to that deployment; use the /checks browser page for human decisions.",
+    );
+  }
+}
+
 function aliasedEnvironment(primaryName, legacyName) {
   const primary = process.env[primaryName]?.trim();
   const legacy = process.env[legacyName]?.trim();
@@ -181,13 +520,115 @@ function apiKey(environmentName, legacyEnvironmentName) {
   return value;
 }
 
-function errorFrom(payload, fallback) {
-  if (!payload || typeof payload !== "object") return fallback;
+function actionCheckSessionCookie() {
+  const raw = process.env.TOTEM_SESSION_COOKIE;
+  if (!raw?.trim()) {
+    throw new Error(
+      "Action check decisions require an authenticated human browser session. Open the local /checks page, or set TOTEM_SESSION_COOKIE from your own current browser session. API keys cannot approve or reject.",
+    );
+  }
+  const value = raw.trim();
+  if (value.length > 16 * 1_024 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error("TOTEM_SESSION_COOKIE is not a valid browser Cookie header.");
+  }
+  const pairs = value
+    .split(";")
+    .map((pair) => pair.trim())
+    .filter(Boolean);
+  let hasSessionCookie = false;
+  for (const pair of pairs) {
+    const separator = pair.indexOf("=");
+    const name = separator > 0 ? pair.slice(0, separator) : "";
+    const cookieValue = separator > 0 ? pair.slice(separator + 1) : "";
+    if (
+      !/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name) ||
+      !cookieValue ||
+      /[\u0000-\u0020\u007f;]/.test(cookieValue)
+    ) {
+      throw new Error("TOTEM_SESSION_COOKIE is not a valid browser Cookie header.");
+    }
+    if (/^(?:__Secure-)?(?:next-auth|authjs)\.session-token(?:\.\d+)?$/.test(name)) {
+      hasSessionCookie = true;
+    }
+  }
+  if (!hasSessionCookie) {
+    throw new Error(
+      "TOTEM_SESSION_COOKIE does not contain a Totem browser session. Open the local /checks page to approve or reject instead; API keys cannot make human decisions.",
+    );
+  }
+  return value;
+}
+
+function errorFrom(payload, fallback, secrets = []) {
+  if (!payload || typeof payload !== "object") return redactCliSecrets(fallback, secrets);
   const error = payload.error;
-  if (!error || typeof error !== "object") return fallback;
+  if (!error || typeof error !== "object") return redactCliSecrets(fallback, secrets);
   const code = typeof error.code === "string" ? error.code : "REQUEST_FAILED";
   const message = typeof error.message === "string" ? error.message : fallback;
-  return `${code}: ${message}`;
+  return redactCliSecrets(`${code}: ${message}`, secrets);
+}
+
+function redactCliSecrets(value, secrets) {
+  let redacted = terminalText(value, "The Action Checks request failed.");
+  for (const secret of secrets) {
+    if (typeof secret === "string" && secret.length >= 8)
+      redacted = redacted.replaceAll(secret, "[REDACTED]");
+  }
+  return redacted;
+}
+
+function redactJsonSecrets(value, secrets) {
+  if (typeof value === "string") {
+    let redacted = value;
+    for (const secret of secrets) {
+      if (typeof secret === "string" && secret.length >= 8) {
+        redacted = redacted.replaceAll(secret, "[REDACTED]");
+      }
+    }
+    return redacted;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactJsonSecrets(item, secrets));
+  }
+  if (record(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        redactJsonSecrets(key, secrets),
+        redactJsonSecrets(item, secrets),
+      ]),
+    );
+  }
+  return value;
+}
+
+function writeActionCheckFailure(payload, fallback, status, secrets = []) {
+  const error = record(record(payload)?.error);
+  const code = redactCliSecrets(
+    typeof error?.code === "string" ? error.code : "ACTION_CHECK_REQUEST_FAILED",
+    secrets,
+  );
+  const message = redactCliSecrets(
+    typeof error?.message === "string" ? error.message : fallback,
+    secrets,
+  );
+  const safePayload = { error: { code, message } };
+  writeJson(safePayload);
+  const policyRejection =
+    status < 500 &&
+    (ACTION_CHECK_POLICY_CODES.has(code) ||
+      (status === 409 && code !== "ACTION_APPROVAL_NOT_REQUIRED"));
+  process.exitCode = policyRejection ? 2 : 1;
+}
+
+function writeActionCheckOperationalError(message, outcome) {
+  writeJson({
+    error: {
+      code: "ACTION_CHECK_OPERATIONAL_ERROR",
+      message: terminalText(message, "The Action Checks command failed."),
+      ...(outcome ? { outcome } : {}),
+    },
+  });
+  process.exitCode = 1;
 }
 
 function number(value) {
@@ -203,10 +644,33 @@ function terminalText(value, fallback = "unknown") {
   return sanitized.slice(0, 2_000) || fallback;
 }
 
+function organizationProofText(organization) {
+  if (organization?.verified !== true) return organization?.domain;
+  if (organization.accountType === "PERSONAL") return "Owner email · verified";
+  return `${terminalText(organization.domain, "verified domain")} · verified`;
+}
+
 function record(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }
 
+function validActionCheckSuite(suite, expectedId) {
+  if (
+    !suite ||
+    typeof suite.id !== "string" ||
+    suite.id.length > 200 ||
+    !SAFE_IDENTIFIER_PATTERN.test(suite.id) ||
+    (expectedId && suite.id !== expectedId) ||
+    !ACTION_CHECK_SUITE_STATUSES.has(suite.status)
+  ) {
+    return false;
+  }
+  if (suite.conclusion === null || suite.conclusion === undefined) {
+    return suite.status !== "COMPLETED";
+  }
+  return ACTION_CHECK_SUITE_CONCLUSIONS.has(suite.conclusion);
+}
+
 function requiredOption(options, key, flag, pattern = SAFE_IDENTIFIER_PATTERN) {
   const value = options[key]?.trim();
   if (!value || value.length > 200 || (pattern && !pattern.test(value))) {
@@ -237,6 +701,7 @@ function validateCommandOptions(command, options) {
       "request_digest",
       "request_file",
     ]),
+    checks: new Set([...shared, "file"]),
   }[command];
   if (!allowed) throw new Error(`Unknown command ${command || "(missing)"}.`);
   for (const [key, value] of Object.entries(options)) {
@@ -350,6 +815,7 @@ function receiverChallenge(input) {
     challenge.nonce.length < 32 ||
     challenge.nonce.length > 256 ||
     !/^[A-Za-z0-9_-]+$/.test(challenge.nonce) ||
+    !["SANDBOX", "PRODUCTION"].includes(challenge.environment) ||
     typeof challenge.requestedAction !== "string" ||
     !ACTION_PATTERN.test(challenge.requestedAction) ||
     typeof challenge.requestDigest !== "string" ||
@@ -383,6 +849,7 @@ function receiverChallenge(input) {
     issuerOrganizationId: challenge.issuerOrganizationId,
     verifierAgentId: challenge.verifierAgentId,
     presenterAgentId: challenge.presenterAgentId,
+    environment: challenge.environment,
     requestedAction: challenge.requestedAction,
     requestDigest: challenge.requestDigest.toLowerCase(),
     ...(hasAmount
@@ -432,6 +899,7 @@ function boundPresentationClaims(token, challenge, credentialId, expiresAt) {
     claims.credentialId !== credentialId ||
     claims.agentId !== challenge.presenterAgentId ||
     claims.organizationId !== challenge.issuerOrganizationId ||
+    claims.environment !== challenge.environment ||
     claims.requestedAction !== challenge.requestedAction ||
     claims.requestDigest !== challenge.requestDigest ||
     claims.transactionAmount !== expectedAmount ||
@@ -451,18 +919,28 @@ function boundPresentationClaims(token, challenge, credentialId, expiresAt) {
   return claims;
 }
 
-async function requestJson({ baseUrl, path, key, body, idempotencyKey, timeout = 30_000 }) {
-  const headers = {
-    authorization: `Bearer ${key}`,
-    "content-type": "application/json",
-  };
+async function requestJson({
+  baseUrl,
+  path,
+  key,
+  cookie,
+  method = "POST",
+  body,
+  idempotencyKey,
+  timeout = 30_000,
+}) {
+  const headers = { accept: "application/json" };
+  if (key) headers.authorization = `Bearer ${key}`;
+  if (cookie) headers.cookie = cookie;
+  if (body !== undefined) headers["content-type"] = "application/json";
   if (idempotencyKey) headers["idempotency-key"] = idempotencyKey;
   let response;
   try {
     response = await fetch(new URL(path, baseUrl), {
-      method: "POST",
+      method,
       headers,
-      body: JSON.stringify(body),
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      redirect: "manual",
       signal: AbortSignal.timeout(timeout),
     });
   } catch (error) {
@@ -493,25 +971,21 @@ async function runChallenge(options, baseUrl) {
   let transactionAmount;
   let currency;
   if (hasAmount) {
-    transactionAmount = Number(options.amount);
-    if (!Number.isFinite(transactionAmount) || transactionAmount < 0 || transactionAmount > 1e12) {
+    const rawAmount = options.amount.trim();
+    if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(rawAmount)) {
+      throw new Error("--amount must be a decimal number from 0 through 1000000000000.");
+    }
+    transactionAmount = Number(rawAmount);
+    if (!Number.isFinite(transactionAmount) || transactionAmount > 1e12) {
       throw new Error("--amount must be a finite number from 0 through 1000000000000.");
     }
     currency = options.currency.trim().toUpperCase();
-    if (!/^[A-Z]{3}$/.test(currency)) {
-      throw new Error("--currency must be a three-letter ISO currency code.");
+    if (!ISO_CURRENCY_CODES.has(currency)) {
+      throw new Error("--currency must be a recognized three-letter ISO 4217 currency code.");
     }
   }
 
-  const idempotencyKey = options.idempotency_key ?? `cli:${randomUUID()}`;
-  if (
-    typeof idempotencyKey !== "string" ||
-    idempotencyKey.length < 8 ||
-    idempotencyKey.length > 128 ||
-    !SAFE_IDENTIFIER_PATTERN.test(idempotencyKey)
-  ) {
-    throw new Error("--idempotency-key must contain 8 to 128 safe identifier characters.");
-  }
+  const idempotencyKey = validIdempotencyKey(options.idempotency_key ?? `cli:${randomUUID()}`);
   if (!options.json) process.stderr.write(`Totem retry key: ${idempotencyKey}\n`);
 
   let result;
@@ -533,15 +1007,39 @@ async function runChallenge(options, baseUrl) {
     failUnknownOutcome(message, idempotencyKey, options.json, true);
     return;
   }
-  const challenge = record(result.payload?.challenge);
   if (!result.response.ok) {
+    const apiError = record(result.payload?.error);
+    if (typeof apiError?.code === "string" && HANDSHAKE_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
+      else {
+        writeHumanResult(
+          "Totem challenge · REJECTED",
+          [
+            ["Status", "Challenge was not created"],
+            ["Presenter", presenterAgentId],
+            ["Action", requestedAction],
+            ["Reason", apiError.code],
+          ],
+          "Resolve the policy state before creating a new challenge; this request is not authorized.",
+          "danger",
+          [key],
+        );
+      }
+      process.exitCode = 2;
+      return;
+    }
     failCommand(
-      errorFrom(result.payload, `Challenge creation returned HTTP ${result.response.status}.`),
+      errorFrom(result.payload, `Challenge creation returned HTTP ${result.response.status}.`, [
+        key,
+      ]),
       options.json,
     );
     return;
   }
-  if (!challenge || typeof challenge.id !== "string" || typeof challenge.nonce !== "string") {
+  let challenge;
+  try {
+    challenge = receiverChallenge(result.payload);
+  } catch {
     failUnknownOutcome(
       "Totem returned an invalid challenge response.",
       idempotencyKey,
@@ -550,14 +1048,51 @@ async function runChallenge(options, baseUrl) {
     );
     return;
   }
-  if (options.json) writeJson(result.payload);
+  const responseHasTransaction = challenge.transactionAmount !== undefined;
+  const replayed = result.payload?.replayed;
+  if (
+    typeof replayed !== "boolean" ||
+    result.response.status !== (replayed ? 200 : 201) ||
+    challenge.presenterAgentId !== presenterAgentId ||
+    challenge.requestedAction !== requestedAction ||
+    challenge.requestDigest !== requestDigest ||
+    Date.parse(challenge.expiresAt) <= Date.now() ||
+    responseHasTransaction !== (transactionAmount !== undefined) ||
+    (responseHasTransaction &&
+      (challenge.transactionAmount !== transactionAmount || challenge.currency !== currency))
+  ) {
+    failUnknownOutcome(
+      "Totem returned a challenge that does not match the exact request.",
+      idempotencyKey,
+      options.json,
+      true,
+    );
+    return;
+  }
+  if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
   else {
-    process.stdout.write(`Totem challenge · ${terminalText(challenge.id)}\n`);
-    process.stdout.write(`Action: ${terminalText(challenge.requestedAction ?? requestedAction)}\n`);
-    process.stdout.write(`Expires: ${terminalText(challenge.expiresAt)}\n`);
-    process.stdout.write(
-      "Use --json to emit the nonce-bearing challenge for the presenting agent.\n",
+    writeHumanResult(
+      `Totem challenge · ${terminalText(challenge.id)}`,
+      [
+        [
+          "Status",
+          result.payload?.replayed ? "READY · existing idempotent result" : "READY · created",
+        ],
+        ["Presenter", challenge.presenterAgentId ?? presenterAgentId],
+        ["Action", challenge.requestedAction ?? requestedAction],
+        ["Request", compactDigest(challenge.requestDigest ?? requestDigest)],
+        [
+          "Transaction",
+          transactionAmount !== undefined ? `${number(transactionAmount)} ${currency}` : undefined,
+        ],
+        ["Expires", challenge.expiresAt],
+        ["Protection", "Recipient-bound · request-bound · single-use"],
+      ],
+      "Save the complete JSON artifact below as the receiver-owned challenge, then send a copy to the presenting agent.",
+      "success",
+      [key],
     );
+    writeHumanArtifact(result.payload, [key]);
   }
 }
 
@@ -572,6 +1107,7 @@ async function runPresent(options, baseUrl) {
   const nonce = challenge.nonce;
   if (
     typeof challengeId !== "string" ||
+    challengeId.length > 200 ||
     !SAFE_IDENTIFIER_PATTERN.test(challengeId) ||
     typeof nonce !== "string" ||
     nonce.length < 32 ||
@@ -581,46 +1117,89 @@ async function runPresent(options, baseUrl) {
     throw new Error("Challenge JSON is missing a valid challenge id or nonce.");
   }
 
-  const result = await requestJson({
-    baseUrl,
-    path: "/api/v1/presentations",
-    key,
-    body: { credentialId, challengeId, nonce },
-  });
+  let result;
+  try {
+    result = await requestJson({
+      baseUrl,
+      path: "/api/v1/presentations",
+      key,
+      body: { credentialId, challengeId, nonce },
+    });
+  } catch (error) {
+    failHandshakeUnknownOutcome(
+      "presentation",
+      error instanceof Error ? error.message : "Could not create the presentation.",
+      options.json,
+    );
+    return;
+  }
   const presentation = record(result.payload?.presentation);
   if (!result.response.ok) {
     const apiError = record(result.payload?.error);
-    if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
-      if (options.json) writeJson(result.payload);
+    if (typeof apiError?.code === "string" && HANDSHAKE_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
       else {
-        process.stdout.write("Totem presentation · REJECTED\n");
-        process.stdout.write(`Reason: ${apiError.code}\n`);
+        writeHumanResult(
+          "Totem presentation · REJECTED",
+          [
+            ["Status", "Proof was not created"],
+            ["Challenge", challengeId],
+            ["Reason", apiError.code],
+          ],
+          "Return to the receiver for a fresh challenge before trying again.",
+          "danger",
+          [key],
+        );
       }
       process.exitCode = 2;
       return;
     }
     failCommand(
-      errorFrom(result.payload, `Presentation creation returned HTTP ${result.response.status}.`),
+      errorFrom(result.payload, `Presentation creation returned HTTP ${result.response.status}.`, [
+        key,
+      ]),
       options.json,
     );
     return;
   }
   if (
     !presentation ||
-    typeof presentation.challengeId !== "string" ||
-    typeof presentation.credentialId !== "string" ||
+    result.response.status !== 201 ||
+    presentation.challengeId !== challengeId ||
+    presentation.credentialId !== credentialId ||
     typeof presentation.token !== "string" ||
-    typeof presentation.expiresAt !== "string"
+    presentation.token.length < 20 ||
+    presentation.token.length > 100_000 ||
+    presentation.token.split(".").length !== 3 ||
+    !presentation.token.split(".").every((part) => /^[A-Za-z0-9_-]+$/.test(part)) ||
+    !validIsoTimestamp(presentation.expiresAt) ||
+    Date.parse(presentation.expiresAt) <= Date.now()
   ) {
-    failCommand("Totem returned an invalid presentation response.", options.json);
+    failHandshakeUnknownOutcome(
+      "presentation",
+      "Totem returned an invalid or mismatched presentation response.",
+      options.json,
+    );
     return;
   }
-  if (options.json) writeJson(result.payload);
+  if (options.json) writeJson(redactJsonSecrets(result.payload, [key]));
   else {
-    process.stdout.write(`Totem presentation · ${terminalText(presentation.challengeId)}\n`);
-    process.stdout.write(`Credential: ${terminalText(presentation.credentialId)}\n`);
-    process.stdout.write(`Expires: ${terminalText(presentation.expiresAt)}\n`);
-    process.stdout.write("Use --json to emit the token-bearing presentation for the verifier.\n");
+    writeHumanResult(
+      `Totem presentation · ${terminalText(presentation.challengeId)}`,
+      [
+        ["Status", "READY · signed proof created"],
+        ["Challenge", presentation.challengeId],
+        ["Credential", presentation.credentialId],
+        ["Presenter", challenge.presenterAgentId],
+        ["Action", challenge.requestedAction],
+        ["Expires", presentation.expiresAt],
+        ["Protection", "Challenge-bound · recipient-bound · one-minute proof"],
+      ],
+      "Save the complete JSON artifact below and return it to the verifier before the proof expires.",
+      "success",
+      [key],
+    );
+    writeHumanArtifact(result.payload, [key]);
   }
 }
 
@@ -662,31 +1241,54 @@ async function runVerify(options, baseUrl) {
   }
   const claims = boundPresentationClaims(token, challenge, credentialId, presentation.expiresAt);
 
-  const result = await requestJson({
-    baseUrl,
-    path: "/api/v1/presentations/verify",
-    key,
-    body: { challengeId: challenge.id, presentation: token },
-  });
+  let result;
+  try {
+    result = await requestJson({
+      baseUrl,
+      path: "/api/v1/presentations/verify",
+      key,
+      body: { challengeId: challenge.id, presentation: token },
+    });
+  } catch (error) {
+    failHandshakeUnknownOutcome(
+      "verification",
+      error instanceof Error ? error.message : "Could not verify the presentation.",
+      options.json,
+    );
+    return;
+  }
   const payload = record(result.payload);
   if (!payload || typeof payload.verified !== "boolean" || typeof payload.result !== "string") {
     const apiError = record(payload?.error);
-    if (typeof apiError?.code === "string" && PRESENTATION_REJECTION_CODES.has(apiError.code)) {
-      if (options.json) writeJson(payload);
+    if (typeof apiError?.code === "string" && HANDSHAKE_REJECTION_CODES.has(apiError.code)) {
+      if (options.json) writeJson(redactJsonSecrets(payload, [key, token]));
       else {
-        process.stdout.write("Totem verification · REJECTED\n");
-        process.stdout.write(`Reason: ${apiError.code}\n`);
+        writeHumanResult(
+          "Totem verification · REJECTED",
+          [
+            ["Decision", "DO NOT ACT"],
+            ["Challenge", challenge.id],
+            ["Action", challenge.requestedAction],
+            ["Reason", apiError.code],
+          ],
+          "Create a fresh challenge and verify the exact request again before taking action.",
+          "danger",
+          [key, token],
+        );
       }
       process.exitCode = 2;
       return;
     }
-    failCommand(
-      errorFrom(
-        result.payload,
-        `Presentation verification returned HTTP ${result.response.status}.`,
-      ),
-      options.json,
+    const message = errorFrom(
+      result.payload,
+      `Presentation verification returned HTTP ${result.response.status}.`,
+      [key, token],
     );
+    if (result.response.status >= 500 || result.response.ok) {
+      failHandshakeUnknownOutcome("verification", message, options.json);
+    } else {
+      failCommand(message, options.json);
+    }
     return;
   }
 
@@ -738,25 +1340,295 @@ async function runVerify(options, baseUrl) {
     }
   }
 
-  if (options.json) writeJson(payload);
+  if (options.json) writeJson(redactJsonSecrets(payload, [key, token]));
   else {
-    process.stdout.write(`Totem verification · ${terminalText(payload.result)}\n`);
-    if (payload.agent?.name || payload.agent?.id) {
-      process.stdout.write(`Agent: ${terminalText(payload.agent.name ?? payload.agent.id)}\n`);
+    const approvedResult = payload.verified && payload.result === "APPROVED" && result.response.ok;
+    writeHumanResult(
+      `Totem verification · ${terminalText(payload.result)}`,
+      [
+        ["Decision", approvedResult ? "AUTHORIZED FOR THIS EXACT REQUEST" : "DO NOT ACT"],
+        ["Agent", payload.agent?.name ?? payload.agent?.id],
+        ["Agent ID", payload.agent?.id],
+        ["Organization", payload.organization?.name ?? payload.organization?.id],
+        ["Organization proof", organizationProofText(payload.organization)],
+        ["Action", payload.authorization?.requestedAction],
+        [
+          "Authority",
+          payload.authorization?.allowed ? "Active credential permits this action" : undefined,
+        ],
+        [
+          "Human review",
+          typeof payload.authorization?.humanApprovalRequired === "boolean"
+            ? payload.authorization.humanApprovalRequired
+              ? "Required"
+              : "Not required by credential"
+            : undefined,
+        ],
+        ["Credential", payload.evidence?.credentialId],
+        ["Request", compactDigest(payload.evidence?.requestDigest ?? expectedRequestDigest)],
+        ["Verified", payload.evidence?.verifiedAt],
+        ["Reason", payload.reasonCode],
+        ["Receipt", payload.requestId],
+      ],
+      approvedResult
+        ? "Continue only with the unchanged request bytes shown by this approval."
+        : "Do not process the request; resolve the reason and create a fresh proof.",
+      approvedResult ? "success" : "danger",
+      [key, token],
+    );
+  }
+  if (payload.verified && payload.result === "APPROVED" && result.response.ok) return;
+  process.exitCode = payload.result === "REJECTED" ? 2 : 1;
+}
+
+function checksFile(options, command) {
+  const path = options.file?.trim();
+  if (!path || path.length > 4_096 || path.includes("\0")) {
+    throw new Error(`${command} requires --file with a readable JSON file.`);
+  }
+  return path;
+}
+
+function checksSuiteId(options, subcommand) {
+  if (options.positionals.length !== 3) {
+    throw new Error(`checks ${subcommand} requires exactly one suite ID.`);
+  }
+  const suiteId = options.positionals[2];
+  if (
+    typeof suiteId !== "string" ||
+    suiteId.length > 200 ||
+    !SAFE_IDENTIFIER_PATTERN.test(suiteId)
+  ) {
+    throw new Error("The Action Checks suite ID is invalid.");
+  }
+  return suiteId;
+}
+
+async function decisionFile(options) {
+  if (!options.file) return { confirmation: null, reason: null };
+  const input = await readJson(checksFile(options, "The decision command"), "decision JSON");
+  if (Object.keys(input).some((key) => !["confirmation", "reason"].includes(key))) {
+    throw new Error("Decision JSON may contain only confirmation and reason.");
+  }
+  const confirmation = input.confirmation;
+  const reason = input.reason;
+  if (
+    confirmation !== undefined &&
+    confirmation !== null &&
+    (typeof confirmation !== "string" || confirmation.length > 500)
+  ) {
+    throw new Error("Decision confirmation must be a string of at most 500 characters.");
+  }
+  if (
+    reason !== undefined &&
+    reason !== null &&
+    (typeof reason !== "string" || reason.length > 1_000)
+  ) {
+    throw new Error("Decision reason must be a string of at most 1000 characters.");
+  }
+  return {
+    confirmation:
+      typeof confirmation === "string" && confirmation.trim() ? confirmation.trim() : null,
+    reason: typeof reason === "string" && reason.trim() ? reason.trim() : null,
+  };
+}
+
+async function actionCheckRequest({
+  baseUrl,
+  path,
+  method = "POST",
+  key,
+  cookie,
+  body,
+  secrets = [],
+}) {
+  let result;
+  try {
+    result = await requestJson({ baseUrl, path, method, key, cookie, body });
+  } catch (error) {
+    writeActionCheckOperationalError(
+      error instanceof Error ? error.message : "Could not reach Totem.",
+      method === "GET" ? undefined : "unknown",
+    );
+    return undefined;
+  }
+  if (!result.response.ok) {
+    writeActionCheckFailure(
+      result.payload,
+      `The Action Checks endpoint returned HTTP ${result.response.status}.`,
+      result.response.status,
+      secrets,
+    );
+    return undefined;
+  }
+  const payload = record(result.payload);
+  if (!payload) {
+    writeActionCheckOperationalError("Totem returned an invalid Action Checks response.");
+    return undefined;
+  }
+  return payload;
+}
+
+async function runChecks(options, baseUrl) {
+  requireLocalActionChecks(baseUrl);
+  const subcommand = options.positionals[1];
+  if (!subcommand)
+    throw new Error(
+      "Provide an Action Checks command: run, view, approve, reject, grant, or execute.",
+    );
+
+  if (subcommand === "run") {
+    if (options.positionals.length !== 2)
+      throw new Error("checks run does not accept positional values.");
+    const action = await readJson(checksFile(options, "checks run"), "action JSON");
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: "/api/action-checks",
+      key,
+      body: { action },
+      secrets: [key],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    if (!validActionCheckSuite(suite)) {
+      writeActionCheckOperationalError("Totem returned an invalid action check suite.");
+      return;
     }
-    if (payload.organization?.name || payload.organization?.id) {
-      process.stdout.write(
-        `Organization: ${terminalText(payload.organization.name ?? payload.organization.id)}\n`,
-      );
+    writeJson(redactJsonSecrets({ suite }, [key]));
+    if (suite.status === "STALE" || ["BLOCK", "REQUIRES_APPROVAL"].includes(suite.conclusion)) {
+      process.exitCode = 2;
+    } else if (suite.status !== "COMPLETED" || suite.conclusion === "ERROR") {
+      process.exitCode = 1;
     }
-    if (payload.authorization?.requestedAction) {
-      process.stdout.write(`Action: ${terminalText(payload.authorization.requestedAction)}\n`);
+    return;
+  }
+
+  if (subcommand === "view") {
+    if (options.file !== undefined) throw new Error("--file is not valid for checks view.");
+    const suiteId = checksSuiteId(options, subcommand);
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}`,
+      method: "GET",
+      key,
+      secrets: [key],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    if (!validActionCheckSuite(suite, suiteId)) {
+      writeActionCheckOperationalError("Totem returned an invalid action check suite.");
+      return;
     }
-    if (payload.reasonCode) process.stdout.write(`Reason: ${terminalText(payload.reasonCode)}\n`);
-    if (payload.requestId) process.stdout.write(`Receipt: ${terminalText(payload.requestId)}\n`);
+    writeJson(redactJsonSecrets({ suite }, [key]));
+    return;
   }
-  if (payload.verified && payload.result === "APPROVED" && result.response.ok) return;
-  process.exitCode = payload.result === "REJECTED" ? 2 : 1;
+
+  if (subcommand === "approve" || subcommand === "reject") {
+    const suiteId = checksSuiteId(options, subcommand);
+    const cookie = actionCheckSessionCookie();
+    const decision = subcommand === "approve" ? "APPROVE" : "REJECT";
+    const input = await decisionFile(options);
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}/decision`,
+      cookie,
+      body: { decision, confirmation: input.confirmation, reason: input.reason },
+      secrets: [cookie],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    if (!validActionCheckSuite(suite, suiteId)) {
+      writeActionCheckOperationalError("Totem returned an invalid action check decision response.");
+      return;
+    }
+    writeJson(redactJsonSecrets({ suite }, [cookie]));
+    if (decision === "REJECT") process.exitCode = 2;
+    return;
+  }
+
+  if (subcommand === "grant") {
+    const suiteId = checksSuiteId(options, subcommand);
+    const action = await readJson(checksFile(options, "checks grant"), "action JSON");
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}/grant`,
+      key,
+      body: { action },
+      secrets: [key],
+    });
+    if (!payload) return;
+    const grant = record(payload.grant);
+    const suite = record(grant?.suite);
+    if (
+      !grant ||
+      typeof grant.token !== "string" ||
+      grant.token.length < 32 ||
+      grant.token.length > 512 ||
+      !validIsoTimestamp(grant.expiresAt) ||
+      !validActionCheckSuite(suite, suiteId)
+    ) {
+      writeActionCheckOperationalError("Totem returned an invalid execution grant response.");
+      return;
+    }
+    writeJson(
+      redactJsonSecrets({ grant: { token: grant.token, expiresAt: grant.expiresAt, suite } }, [
+        key,
+      ]),
+    );
+    return;
+  }
+
+  if (subcommand === "execute") {
+    const suiteId = checksSuiteId(options, subcommand);
+    const input = await readJson(checksFile(options, "checks execute"), "execution JSON");
+    const action = record(input.action);
+    const grant = input.grant;
+    if (!action || typeof grant !== "string" || grant.length < 32 || grant.length > 512) {
+      throw new Error("Execution JSON must contain the exact action object and opaque grant.");
+    }
+    const key = apiKey("TOTEM_API_KEY", "AGENTTRUST_API_KEY");
+    const payload = await actionCheckRequest({
+      baseUrl,
+      path: `/api/action-checks/${encodeURIComponent(suiteId)}/execute`,
+      key,
+      body: { action, grant },
+      secrets: [key, grant],
+    });
+    if (!payload) return;
+    const suite = record(payload.suite);
+    const receipt = record(payload.receipt);
+    if (
+      !validActionCheckSuite(suite, suiteId) ||
+      !receipt ||
+      typeof receipt.id !== "string" ||
+      receipt.id.length > 200 ||
+      !SAFE_IDENTIFIER_PATTERN.test(receipt.id) ||
+      !ACTION_EXECUTION_OUTCOMES.has(receipt.outcome) ||
+      (typeof receipt.suiteId === "string" && receipt.suiteId !== suiteId)
+    ) {
+      writeActionCheckOperationalError("Totem returned an invalid execution receipt response.");
+      return;
+    }
+    writeJson(
+      redactJsonSecrets(
+        {
+          suite,
+          receipt,
+          ...(typeof payload.receiptId === "string" ? { receiptId: payload.receiptId } : {}),
+        },
+        [key, grant],
+      ),
+    );
+    if (["FAILED", "UNKNOWN", "COMPENSATED"].includes(receipt.outcome)) process.exitCode = 1;
+    return;
+  }
+
+  throw new Error(
+    "Unknown Action Checks command. Use run, view, approve, reject, grant, or execute.",
+  );
 }
 
 async function runRfq(options, baseUrl) {
@@ -768,8 +1640,11 @@ async function runRfq(options, baseUrl) {
   }
   const requestParts = options.positionals.slice(1);
   if (requestParts.length === 0) throw new Error('Provide an RFQ request after the "rfq" command.');
-  const idempotencyKey = options.idempotency_key ?? `cli:${randomUUID()}`;
   const prompt = requestParts.join(" ").trim();
+  if (prompt.length < 4 || prompt.length > 2_000) {
+    throw new Error("The RFQ request must contain 4 to 2000 characters.");
+  }
+  const idempotencyKey = validIdempotencyKey(options.idempotency_key ?? `cli:${randomUUID()}`);
   process.stderr.write(`Totem retry key: ${idempotencyKey}\n`);
 
   let result;
@@ -789,6 +1664,7 @@ async function runRfq(options, baseUrl) {
         : "Could not reach Totem.",
       idempotencyKey,
       options.json,
+      options.json,
     );
     return;
   }
@@ -796,47 +1672,70 @@ async function runRfq(options, baseUrl) {
     const message = errorFrom(
       result.payload,
       `The RFQ endpoint returned HTTP ${result.response.status}.`,
+      [key],
     );
-    if (result.response.status >= 500) failUnknownOutcome(message, idempotencyKey, options.json);
-    else fail(message);
+    if (result.response.status >= 500) {
+      failUnknownOutcome(message, idempotencyKey, options.json, options.json);
+    } else {
+      failCommand(message, options.json);
+    }
     return;
   }
   const run = record(result.payload?.run);
   if (!run) {
-    failUnknownOutcome("Totem returned an invalid success response.", idempotencyKey, options.json);
+    failUnknownOutcome(
+      "Totem returned an invalid success response.",
+      idempotencyKey,
+      options.json,
+      options.json,
+    );
     return;
   }
   if (options.json) {
-    writeJson(result.payload);
+    writeJson(redactJsonSecrets(result.payload, [key]));
+    if (run.status !== "SUCCEEDED") process.exitCode = 1;
     return;
   }
 
   const verification = record(run.verification);
   const supplier = record(run.supplierRequest);
-  process.stdout.write(`Totem RFQ · ${terminalText(run.id, "unknown run")}\n`);
-  process.stdout.write(`Run: ${terminalText(run.status, "UNKNOWN")}\n`);
-  if (run.summary) process.stdout.write(`${terminalText(run.summary)}\n`);
-  if (verification)
-    process.stdout.write(`Agent authority: ${terminalText(verification.result, "UNKNOWN")}\n`);
-  if (supplier) {
-    process.stdout.write(`Delivery: ${terminalText(supplier.status, "UNKNOWN")}\n`);
-    process.stdout.write(
-      `Supplier response: ${terminalText(supplier.businessStatus, "UNKNOWN")}\n`,
-    );
-    process.stdout.write(
-      `Available now: ${number(supplier.availableQuantity)} ${terminalText(supplier.unit, "units")}\n`,
-    );
-    process.stdout.write(
-      `Backorder: ${number(supplier.backorderQuantity)} ${terminalText(supplier.unit, "units")}\n`,
-    );
-    if (supplier.supplierReference)
-      process.stdout.write(`Reference: ${terminalText(supplier.supplierReference)}\n`);
-  }
+  const succeeded = run.status === "SUCCEEDED";
+  writeHumanResult(
+    `Totem RFQ · ${terminalText(run.id, "unknown run")}`,
+    [
+      ["Run", run.status ?? "UNKNOWN"],
+      ["Request", prompt],
+      ["Summary", run.summary],
+      ["Agent authority", verification?.result ?? "UNKNOWN"],
+      ["Delivery", supplier?.status ?? "UNKNOWN"],
+      ["Supplier response", supplier?.businessStatus ?? "UNKNOWN"],
+      [
+        "Available now",
+        supplier
+          ? `${number(supplier.availableQuantity)} ${terminalText(supplier.unit, "units")}`
+          : undefined,
+      ],
+      [
+        "Backorder",
+        supplier
+          ? `${number(supplier.backorderQuantity)} ${terminalText(supplier.unit, "units")}`
+          : undefined,
+      ],
+      ["Reference", supplier?.supplierReference],
+      ["Mode", "Non-binding procurement demonstration"],
+    ],
+    succeeded
+      ? "Review the supplier response and retain the run ID as the audit reference."
+      : "Open the Totem operator run for the bounded trace before retrying.",
+    succeeded ? "success" : "danger",
+    [key],
+  );
   if (run.status !== "SUCCEEDED") process.exitCode = 1;
 }
 
 async function main() {
   let options;
+  const jsonRequested = process.argv.slice(2).includes("--json");
   try {
     options = parseArguments(process.argv.slice(2));
     const command = options.positionals[0];
@@ -855,12 +1754,13 @@ async function main() {
     if (command === "challenge") await runChallenge(options, baseUrl);
     else if (command === "present") await runPresent(options, baseUrl);
     else if (command === "verify") await runVerify(options, baseUrl);
+    else if (command === "checks") await runChecks(options, baseUrl);
     else await runRfq(options, baseUrl);
   } catch (error) {
     const message = error instanceof Error ? error.message : "The Totem command failed.";
-    const command = options?.positionals?.[0];
-    if (command && command !== "rfq") failCommand(message, options?.json);
-    else fail(message);
+    const command = options?.positionals?.[0] ?? process.argv[2];
+    if (command === "checks") writeActionCheckOperationalError(message);
+    else failCommand(message, options?.json ?? jsonRequested);
   }
 }