troxy-cli 1.21.1 → 1.22.0

package/src/policy-fields.js

@@ -0,0 +1,107 @@
+// Domain-aware condition validation for `policies create`, derived from the
+// same vendored spec the dashboard checks itself against (src/data/policy-spec.json,
+// see that file's _why and tools/export_policy_spec.py in troxy-tf-live for the
+// full story). Before this existed, `policies create --field` only knew about
+// three payment fields - amount, merchant_name, tx_per_day - because that was
+// the whole product when the command was written. The other 44 fields across
+// five more checkpoints (comms, access, destructive, model, secrets) were
+// simply unreachable from the CLI, even though the backend and the dashboard
+// both understood every one of them.
+//
+// Mirrors policies.py's _validate_field_op_and_value / _validate_condition_list
+// so a bad condition is rejected here - offline, no network round-trip - instead
+// of failing at the server with a message the user then has to map back onto
+// what they typed.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SPEC = JSON.parse(readFileSync(join(__dirname, 'data', 'policy-spec.json'), 'utf8'));
+
+export const DOMAIN_FIELDS = SPEC.domain_fields; // { domain: [field, ...] }
+export const FIELD_SPECS   = SPEC.field_specs;   // { field: { ops:[...], kind, values?:[...] } }
+export const DOMAINS       = Object.keys(DOMAIN_FIELDS).sort();
+
+// Friendly names for the canonical vocabulary. `access` means logins in the
+// persisted `domain` column - a naming trap the dashboard has a standing
+// comment about - so `login`/`signup` are accepted here rather than making
+// every CLI user learn the column name to build a login policy.
+const DOMAIN_ALIASES = {
+  payment: 'payment', payments: 'payment', spend: 'payment', spending: 'payment',
+  comms: 'comms', email: 'comms', messages: 'comms', messaging: 'comms', message: 'comms',
+  access: 'access', login: 'access', logins: 'access', signup: 'access', signin: 'access',
+  destructive: 'destructive', action: 'destructive', actions: 'destructive',
+  model: 'model', models: 'model', ai: 'model',
+  secrets: 'secrets', secret: 'secrets',
+};
+
+export function normalizeDomain(input) {
+  if (!input) return null;
+  const key = String(input).trim().toLowerCase();
+  return DOMAIN_ALIASES[key] || null;
+}
+
+// Which fields belong to exactly one domain - used to infer --domain from
+// --field when the user omits --domain, for backward compatibility with
+// scripts written against the original payment-only command. A field shared
+// by more than one domain (`destination` is both destructive and secrets) is
+// deliberately excluded from inference: guessing wrong would silently attach
+// a rule to the wrong checkpoint, which is the exact failure this file exists
+// to prevent. Ambiguous fields require an explicit --domain.
+const _domainsByField = {};
+for (const [domain, fields] of Object.entries(DOMAIN_FIELDS)) {
+  for (const f of fields) (_domainsByField[f] ||= []).push(domain);
+}
+export function inferDomain(field) {
+  const ds = _domainsByField[field];
+  return ds && ds.length === 1 ? ds[0] : null;
+}
+
+export function fieldsForDomain(domain) {
+  return DOMAIN_FIELDS[domain] || [];
+}
+
+/**
+ * Returns an error string, or null if the condition is valid. `field` may be
+ * omitted (a catch-all condition, matching every event in the domain) - only
+ * `domain` is mandatory whenever any condition is being validated at all.
+ */
+export function validateCondition(domain, field, operator, value, value2) {
+  if (!domain) return "domain is required (--domain, one of: " + DOMAINS.join(', ') + ")";
+  if (!DOMAINS.includes(domain)) return `domain must be one of: ${DOMAINS.join(', ')}`;
+  if (!field) return null;
+
+  const allowed = DOMAIN_FIELDS[domain] || [];
+  if (!allowed.includes(field)) {
+    return `'${field}' is not available on a '${domain}' policy (allowed: ${allowed.join(', ')})`;
+  }
+  const spec = FIELD_SPECS[field];
+  if (!spec) return `unknown field '${field}'`;
+  if (!operator) return `--operator is required with --field`;
+  if (!spec.ops.includes(operator)) {
+    return `'${operator}' does not apply to '${field}' - the engine has no way to compare it (allowed: ${spec.ops.join(', ')})`;
+  }
+  const text = value == null ? '' : String(value).trim();
+  if (!text) {
+    return `--value is required for '${field}' - an empty value matches everything or nothing depending on the operator`;
+  }
+  if (spec.kind === 'number') {
+    if (!isFinite(Number(text))) {
+      return `'${value}' is not a number, and '${field}' is read as 0 for anything that isn't - that would match far more than intended`;
+    }
+    if (operator === 'between') {
+      const t2 = value2 == null ? '' : String(value2).trim();
+      if (!t2 || !isFinite(Number(t2))) return `--value2 must be a number for 'between'`;
+    }
+  } else if (spec.kind === 'bool') {
+    if (!['true', 'false'].includes(text.toLowerCase())) {
+      return `'${field}' must be true or false, not '${value}'`;
+    }
+  } else if (spec.values && (operator === 'eq' || operator === 'neq')) {
+    if (!spec.values.includes(text.toLowerCase())) {
+      return `'${value}' is not one the '${field}' checkpoint can ever report (allowed: ${spec.values.join(', ')})`;
+    }
+  }
+  return null;
+}

package/src/simulate.js

@@ -0,0 +1,251 @@
+// Simulate a checkpoint call, the same way `troxy pay` simulates /evaluate.
+// Before this file existed, `pay` was the only one - the other five
+// checkpoints (email, login, destructive action, model, secrets) had no CLI
+// equivalent at all, even though api.js already had wrappers for four of
+// them (evaluateEmail/evaluateLogin/evaluateAction/evaluateModel) sitting
+// unused, and evaluateSecrets was missing outright.
+import { requireJwt } from './auth.js';
+import { loadConfig } from './config.js';
+import { api } from './api.js';
+
+const ICON = { ALLOW: '✓', BLOCK: '✗', ESCALATE: '⏳', NOTIFY: '~' };
+
+// The policy that answered lives in `result.policy` on /evaluate (payment)
+// but is embedded in the `reason` sentence on every other checkpoint
+// ("Matched policy 'X'."). Reading only `.policy`, the way an early version
+// of this file did by copying `pay`'s formatting verbatim, silently showed
+// "(default action)" on every one of these five commands even when a real
+// policy had fired - the report would have been wrong from the day it shipped.
+export function _policyName(result) {
+  if (result.policy) return result.policy;
+  const m = /[Mm]atched policy '([^']+)'/.exec(result.reason || '');
+  return m ? m[1] : null;
+}
+
+function _requireApiKey() {
+  requireJwt();
+  const apiKey = loadConfig()?.apiKey || process.env.TROXY_API_KEY;
+  if (!apiKey) { console.error('  No API key. Run: troxy init --key txy-...\n'); process.exit(1); }
+  return apiKey;
+}
+
+function _agentName() {
+  return loadConfig()?.agentName || 'troxy-cli';
+}
+
+function _report(result) {
+  const icon = ICON[result.decision] || '?';
+  const policy = _policyName(result);
+  const suffix = policy ? `  ←  "${policy}"` : result.reason ? `  (${result.reason})` : '  (default action)';
+  console.log(`\n  ${icon} ${result.decision}${suffix}`);
+  if (result.audit_id) console.log(`  audit: ${result.audit_id}`);
+  console.log();
+}
+
+const HELP = {
+  send: `  troxy send --recipient <address> [options]
+
+  Simulates a message evaluation (/evaluate/email) - the checkpoint an agent
+  calls before sending on any channel: email, WhatsApp, Telegram, Slack,
+  Teams, Discord, SMS. Use this to test your Messages policies. Login required.
+
+  Required:
+    --recipient <address>   Who it's going to (address, phone, handle, or channel name)
+
+  Optional:
+    --recipients <a,b,c>     Multiple recipients, comma-separated (adds to --recipient)
+    --subject <text>         Subject line (ignored off email)
+    --body <text>            Message body
+    --channel <name>         email, whatsapp, telegram, slack, teams, discord, sms (default: email)
+
+  Examples:
+    troxy send --recipient jane@acme.com --subject "Q3 numbers" --body "attached"
+    troxy send --recipient jane@gmail.com --body "the password is hunter2"
+    troxy send --recipient "#eng" --channel slack --body "deploying now"
+`,
+  signin: `  troxy signin --site <domain> [--type login|signup]
+
+  Simulates a login/signup evaluation (/evaluate/login). Use this to test your
+  Access & privacy policies. Login required.
+
+  Required:
+    --site <domain>   Site the agent is signing into (e.g. "coinbase.com")
+
+  Optional:
+    --type <type>     login or signup (default: login)
+
+  Examples:
+    troxy signin --site coinbase.com --type signup
+    troxy signin --site github.com
+`,
+  action: `  troxy action --verb <verb> --resource <what> [options]
+
+  Simulates a consequential-action evaluation (/evaluate/action) - deletes,
+  drops, overwrites, force-pushes, grants, exports, and other actions with
+  real consequences. Use this to test your Destructive/Access policies. Login required.
+
+  Required:
+    --verb <verb>        delete, drop, destroy, overwrite, force_push, share,
+                          grant_access, add_user, rotate, modify, export
+    --resource <text>    What it acts on (e.g. "prod users table")
+
+  Optional:
+    --destination <who>   Who can reach it afterwards: an address, a domain, a
+                           team name, or "public". Omit for actions that don't
+                           change who can see anything (e.g. storing your own file).
+    --items <n>            How many things this affects (default: 1)
+    --reversible <bool>    true or false (default: false)
+
+  Examples:
+    troxy action --verb delete --resource "prod users table" --items 500 --reversible false
+    troxy action --verb share --resource "Q3 revenue doc" --destination public
+    troxy action --verb modify --resource "billing settings"
+`,
+  'model-call': `  troxy model-call --model <id> --provider <name> [options]
+
+  Simulates a model-usage evaluation (/evaluate/model) - what an agent calls
+  before starting a run on a given model. Use this to test your AI & models
+  policies. Login required.
+
+  Required:
+    --model <id>         Model id, e.g. claude-opus-5
+    --provider <name>    anthropic, openai, google, or wherever it runs
+
+  Optional:
+    --cost <n>       Your best estimate of this run's cost in USD (default: 0)
+    --tokens <n>      Tokens you expect to use
+    --effort <level>  low, medium, or high (reasoning/thinking intensity)
+
+  Examples:
+    troxy model-call --model claude-opus-5 --provider anthropic --cost 4.50 --tokens 900000
+    troxy model-call --model gpt-4o --provider openai --cost 0.02 --tokens 500
+`,
+  scan: `  troxy scan --content <text> [options]
+
+  Simulates a sensitive-data evaluation (/evaluate/secrets) - the checkpoint
+  an agent calls before sending, writing, or publishing content that might
+  contain a secret. Content is scanned server-side; you don't pre-classify it.
+  Use this to test your Secrets & credentials policies. Login required.
+
+  Required:
+    --content <text>    The text/code/data about to be sent or written
+
+  Optional:
+    --destination <where>   A person, repo, channel, service, or "public" (default: public)
+    --do <action>            send, push, upload, write, or share (default: send)
+    --type <type>            code, message, file, config, log, or other (default: message)
+
+  Examples:
+    troxy scan --content "AWS_SECRET_ACCESS_KEY=wJalr...EXAMPLEKEY" --destination public --do push --type code
+    troxy scan --content "hey the password is hunter2" --do send --type message
+`,
+};
+
+export function printSimHelp(command) {
+  console.log('\n' + HELP[command]);
+}
+
+// Body builders are pure and exported separately from the run* functions
+// below, so field-name mistakes - the exact class of bug this whole session
+// has been about, a request shaped slightly wrong that saves/sends fine and
+// then never matches a policy - are testable without a live login session.
+// _requireApiKey() exits the process if there's no session, which would make
+// every one of these untestable in CI if the body-building logic lived
+// inside the same function.
+
+export function _sendBody(flags) {
+  if (!flags.recipient && !flags.recipients) { console.error('  --recipient is required\n'); process.exit(1); }
+  const recipients = [
+    ...(flags.recipient ? [flags.recipient] : []),
+    ...(flags.recipients ? String(flags.recipients).split(',').map(s => s.trim()).filter(Boolean) : []),
+  ];
+  return {
+    recipient: recipients[0],
+    recipients,
+    subject: flags.subject || '',
+    body: flags.body || '',
+    channel: flags.channel || 'email',
+    agent: _agentName(),
+  };
+}
+
+export function _signinBody(flags) {
+  if (!flags.site) { console.error('  --site is required\n'); process.exit(1); }
+  const type = (flags.type || 'login').toLowerCase();
+  if (!['login', 'signup'].includes(type)) { console.error('  --type must be login or signup\n'); process.exit(1); }
+  return { site: flags.site, login_action: type, agent: _agentName() };
+}
+
+export function _actionBody(flags) {
+  if (!flags.verb) { console.error('  --verb is required\n'); process.exit(1); }
+  if (!flags.resource) { console.error('  --resource is required\n'); process.exit(1); }
+  const items = flags.items != null ? parseInt(flags.items, 10) : 1;
+  if (isNaN(items)) { console.error('  --items must be a number\n'); process.exit(1); }
+  const reversible = flags.reversible != null ? String(flags.reversible).toLowerCase() === 'true' : false;
+  const body = {
+    action_verb: flags.verb,
+    resource: flags.resource,
+    item_count: items,
+    reversible,
+    agent: _agentName(),
+  };
+  if (flags.destination) body.destination = flags.destination;
+  return body;
+}
+
+export function _modelCallBody(flags) {
+  if (!flags.model) { console.error('  --model is required\n'); process.exit(1); }
+  if (!flags.provider) { console.error('  --provider is required\n'); process.exit(1); }
+  const cost = flags.cost != null ? parseFloat(flags.cost) : 0;
+  if (isNaN(cost)) { console.error('  --cost must be a number\n'); process.exit(1); }
+  const body = { model: flags.model, provider: flags.provider, estimated_cost: cost, agent: _agentName() };
+  if (flags.tokens != null) {
+    const tokens = parseInt(flags.tokens, 10);
+    if (isNaN(tokens)) { console.error('  --tokens must be a number\n'); process.exit(1); }
+    body.tokens = tokens;
+  }
+  if (flags.effort) body.effort = flags.effort;
+  return body;
+}
+
+export function _scanBody(flags) {
+  if (!flags.content) { console.error('  --content is required\n'); process.exit(1); }
+  return {
+    content: flags.content,
+    destination: flags.destination || 'public',
+    action: flags.do || 'send',
+    content_type: flags.type || 'message',
+    agent: _agentName(),
+  };
+}
+
+export async function runSend(flags) {
+  const apiKey = _requireApiKey();
+  _report(await api.evaluateEmail(_sendBody(flags), apiKey));
+}
+
+export async function runSignin(flags) {
+  const apiKey = _requireApiKey();
+  _report(await api.evaluateLogin(_signinBody(flags), apiKey));
+}
+
+export async function runAction(flags) {
+  const apiKey = _requireApiKey();
+  _report(await api.evaluateAction(_actionBody(flags), apiKey));
+}
+
+export async function runModelCall(flags) {
+  const apiKey = _requireApiKey();
+  _report(await api.evaluateModel(_modelCallBody(flags), apiKey));
+}
+
+export async function runScan(flags) {
+  const apiKey = _requireApiKey();
+  const result = await api.evaluateSecrets(_scanBody(flags), apiKey);
+  _report(result);
+  if (result.detection_count) {
+    console.log(`  ${result.detection_count} thing(s) detected, highest severity: ${result.highest_severity || 'n/a'}`);
+    (result.detections || []).forEach(d => console.log(`    - ${d.type} (${d.severity}): ${d.preview}`));
+    console.log();
+  }
+}

package/src/tests/mcp-checkpoints.test.js

@@ -0,0 +1,79 @@
+// Every checkpoint the product has needs an MCP tool, or an MCP-connected
+// agent - which is how most users connect - simply cannot reach it. Not "the
+// agent chose not to call it": there is nothing to call.
+//
+// Found live, 2026-08-15: asked a connected agent to leak an AWS key and to
+// bulk-delete prod rows, in an ordinary conversation, no mention of Troxy.
+// The delete got refused (evaluate_action exists). The key-leak request was
+// just carried out - not because the agent ignored a guardrail, but because
+// evaluate_secrets had no MCP tool at all. Every other checkpoint
+// (payment/email/login/action/model) had one; secrets did not. The backend's
+// own other_checkpoints discovery (every /evaluate* response advertises the
+// other five) did mention it, but as a raw HTTP URL - useless to an agent
+// whose only way to reach Troxy is through the tools this file defines.
+//
+// model-checkpoint.test.js already covers this exact wiring for model/
+// report_model_usage specifically, following a near-identical 2026-08-06
+// incident (this is the second time a checkpoint has shipped on the API and
+// dashboard without its MCP tool). This file generalizes the check across
+// every checkpoint so a sixth one added later can't repeat it.
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const src = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'mcp-server.js'),
+  'utf8',
+);
+const apiSrc = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '..', 'api.js'),
+  'utf8',
+);
+
+// One MCP tool per checkpoint, and the /evaluate* path each one must reach.
+// Deliberately a literal, not derived from mcp-server.js itself - a test
+// that reads its expectation from the code under test cannot fail the way
+// this one needs to, which is exactly how secrets went unnoticed despite
+// model-checkpoint.test.js already existing as a precedent for this check.
+const CHECKPOINTS = {
+  evaluate_payment: '/evaluate',
+  evaluate_email:   '/evaluate/email',
+  evaluate_login:   '/evaluate/login',
+  evaluate_action:  '/evaluate/action',
+  evaluate_model:   '/evaluate/model',
+  evaluate_secrets: '/evaluate/secrets',
+};
+
+test('every checkpoint has an MCP tool with a handler', () => {
+  for (const name of Object.keys(CHECKPOINTS)) {
+    assert.ok(
+      src.includes(`name: '${name}'`),
+      `${name} is not in the MCP tool list - an MCP-connected agent has no way to call it at all`,
+    );
+    assert.ok(
+      src.includes(`toolName === '${name}'`) || (name === 'evaluate_payment' && src.includes("toolName !== 'evaluate_payment'")),
+      `${name} is advertised but has no handler, so calling it does nothing`,
+    );
+  }
+});
+
+test('every checkpoint tool is wired to its real endpoint in the api client', () => {
+  for (const [name, path] of Object.entries(CHECKPOINTS)) {
+    assert.ok(
+      apiSrc.includes(`'${path}'`),
+      `${name} has no api.js wrapper for ${path} - the MCP tool would exist with nothing behind it`,
+    );
+  }
+});
+
+test('evaluate_secrets is exported from mcp-server.js\'s own api bindings, not just referenced', () => {
+  // The other tools each get a one-line local binding
+  // (`const evaluateAction = (body, apiKey) => api.evaluateAction(...)`)
+  // before the tool list. secrets needs the same, or the handler below
+  // throws a ReferenceError the first time an agent actually calls it -
+  // which the two tests above cannot see, since they only check that the
+  // NAME 'evaluateSecrets' appears somewhere, not that it resolves.
+  assert.match(src, /const evaluateSecrets\s*=\s*\(body, apiKey\)\s*=>\s*api\.evaluateSecrets\(body, apiKey\)/);
+});

package/src/tests/model-checkpoint.test.js

@@ -242,6 +242,10 @@ test('no new tool was introduced for the chat path', () => {
   const toolsSeg = src.slice(src.indexOf('tools: ['), src.indexOf('server.setRequestHandler(CallToolRequestSchema'));
   const toolNames = [...toolsSeg.matchAll(/name: '([a-z_]+)'/g)].map(m => m[1]);
   const unique = new Set(toolNames);
-  assert.strictEqual(unique.size, 8, 'a tool was added or removed for this change');
+  // 9, not this test's original 8: evaluate_secrets was added afterward
+  // (2026-08-15, mcp-checkpoints.test.js) to close a real gap, not to give
+  // chat its own tool - the assertion this test cares about is still that no
+  // *tenth*, chat-specific tool exists.
+  assert.strictEqual(unique.size, 9, 'a tool was added or removed for this change');
   assert.ok(unique.has('evaluate_model') && unique.has('report_model_usage'));
 });

package/src/tests/policies-create.test.js

@@ -0,0 +1,218 @@
+// `policies create` used to know about exactly three fields - amount,
+// merchant_name, tx_per_day - because payment was the whole product when it
+// was written. These tests cover the domain-aware rewrite: every field in
+// every checkpoint should be reachable, a field that belongs to more than one
+// domain should require an explicit --domain rather than guessing, and the
+// three condition-building paths (single/--and/--or, --json, --template)
+// should each produce exactly the request body the server expects - checked
+// directly against the built object, not by diffing console output.
+import { test } from 'node:test';
+import assert from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { _buildConditionsFromFlags, _findTemplate } from '../policies.js';
+
+// _buildConditionsFromFlags and _findTemplate call process.exit(1) on a bad
+// input rather than throwing - this makes that path testable without ending
+// the test process, by turning the exit into a catchable error. console.error
+// still prints its message, matching how a user would actually see it.
+function _expectExit(fn) {
+  const orig = process.exit;
+  process.exit = (code) => { throw new Error(`__EXIT_${code}__`); };
+  try {
+    fn();
+    throw new Error('expected process.exit to be called, but it was not');
+  } catch (e) {
+    if (!/^__EXIT_\d+__$/.test(e.message)) throw e;
+  } finally {
+    process.exit = orig;
+  }
+}
+
+test('a payment field with no --domain still infers payment (backward compat)', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'BLOCK', field: 'amount', operator: 'gt', value: '100' }, {}, { requireAction: true },
+  );
+  assert.strictEqual(r.domain, 'payment');
+  assert.deepStrictEqual(r.conditions, [{ field: 'amount', operator: 'gt', value: '100' }]);
+  assert.deepStrictEqual(r.or_conditions, []);
+});
+
+test('a non-payment field works with an explicit --domain - this is the whole point of the rewrite', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'ESCALATE', domain: 'access', field: 'login_action', operator: 'eq', value: 'signup' }, {}, { requireAction: true },
+  );
+  assert.strictEqual(r.domain, 'access');
+  assert.deepStrictEqual(r.conditions, [{ field: 'login_action', operator: 'eq', value: 'signup' }]);
+});
+
+test('domain aliases resolve (login -> access, the persisted-column naming trap)', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'ESCALATE', domain: 'login', field: 'login_action', operator: 'eq', value: 'signup' }, {}, { requireAction: true },
+  );
+  assert.strictEqual(r.domain, 'access');
+});
+
+test('a field shared by two domains (destination) requires an explicit --domain', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', field: 'destination', operator: 'eq', value: 'public' }, {}, { requireAction: true },
+  ));
+});
+
+test('an operator the field does not support is rejected before it reaches the server', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'payment', field: 'amount', operator: 'contains', value: '100' }, {}, { requireAction: true },
+  ));
+});
+
+test('a boolean field rejects anything but true/false', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'secrets', field: 'has_api_key', operator: 'eq', value: 'yes' }, {}, { requireAction: true },
+  ));
+});
+
+test('an enum field rejects a value the checkpoint never reports', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'access', field: 'login_action', operator: 'eq', value: 'signin' }, {}, { requireAction: true },
+  ));
+});
+
+test('repeated --and builds one AND block, no branches', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'destructive', field: 'action_verb', operator: 'eq', value: 'export' },
+    { and: ['field=resource,operator=contains,value=customer'] },
+    { requireAction: true },
+  );
+  assert.deepStrictEqual(r.conditions, [
+    { field: 'action_verb', operator: 'eq', value: 'export' },
+    { field: 'resource', operator: 'contains', value: 'customer' },
+  ]);
+  assert.deepStrictEqual(r.or_conditions, []);
+});
+
+test('repeated --or builds one branch per alternative, sharing --action', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'comms' },
+    { or: [
+      'field=recipient_domain,operator=contains,value=gmail.com',
+      'field=recipient_domain,operator=contains,value=yahoo.com',
+    ] },
+    { requireAction: true },
+  );
+  assert.strictEqual(r.conditions.length, 0);
+  assert.strictEqual(r.or_conditions.length, 2);
+  assert.deepStrictEqual(r.or_conditions[0], { action: 'BLOCK', conditions: [{ field: 'recipient_domain', operator: 'contains', value: 'gmail.com' }] });
+  assert.deepStrictEqual(r.or_conditions[1], { action: 'BLOCK', conditions: [{ field: 'recipient_domain', operator: 'contains', value: 'yahoo.com' }] });
+});
+
+test('--and conditions apply to every --or branch, not just the first', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'destructive', field: 'action_verb', operator: 'eq', value: 'delete' },
+    { or: ['field=resource,operator=contains,value=prod', 'field=resource,operator=contains,value=staging'] },
+    { requireAction: true },
+  );
+  assert.strictEqual(r.or_conditions.length, 2);
+  for (const branch of r.or_conditions) {
+    assert.ok(branch.conditions.some(c => c.field === 'action_verb'), 'the AND condition must be present in every branch');
+  }
+});
+
+test('a malformed --and (missing operator=) is rejected with a clear error, not a silent partial condition', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'payment' }, { and: ['field=amount,value=100'] }, { requireAction: true },
+  ));
+});
+
+test('--json is a full escape hatch and is still domain-validated', () => {
+  const r = _buildConditionsFromFlags(
+    { action: 'ESCALATE', domain: 'model', json: JSON.stringify({ conditions: [{ field: 'output_price', operator: 'gt', value: '10' }] }) },
+    {}, { requireAction: true },
+  );
+  assert.strictEqual(r.domain, 'model');
+  assert.deepStrictEqual(r.conditions, [{ field: 'output_price', operator: 'gt', value: '10' }]);
+});
+
+test('--json rejects a condition the field spec would reject', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'model', json: JSON.stringify({ conditions: [{ field: 'output_price', operator: 'contains', value: '10' }] }) },
+    {}, { requireAction: true },
+  ));
+});
+
+test('--json cannot be combined with --field', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { action: 'BLOCK', domain: 'payment', field: 'amount', operator: 'gt', value: '1', json: '{}' }, {}, { requireAction: true },
+  ));
+});
+
+test('--template applies the template\'s own domain, action and conditions', () => {
+  const r = _buildConditionsFromFlags({ template: 'Block all destructive actions' }, {}, { requireAction: true });
+  assert.strictEqual(r.domain, 'destructive');
+  assert.strictEqual(r.action, 'BLOCK');
+  assert.deepStrictEqual(r.conditions, []);
+  assert.deepStrictEqual(r.or_conditions, []);
+});
+
+test('--template --value overrides the threshold on a single-condition template', () => {
+  const r = _buildConditionsFromFlags({ template: 'Block models over $10/MTok output', value: '25' }, {}, { requireAction: true });
+  assert.strictEqual(r.conditions[0].value, '25');
+  assert.strictEqual(r.conditions[0].field, 'output_price'); // unchanged
+});
+
+test('--template --value is refused on a template with more than one condition', () => {
+  _expectExit(() => _buildConditionsFromFlags({ template: 'Escalate making a file public', value: '5' }, {}, { requireAction: true }));
+});
+
+test('--template --action overrides the template default', () => {
+  const r = _buildConditionsFromFlags({ template: 'Escalate making a file public', action: 'BLOCK' }, {}, { requireAction: true });
+  assert.strictEqual(r.action, 'BLOCK');
+});
+
+test('--template cannot be combined with --field', () => {
+  _expectExit(() => _buildConditionsFromFlags(
+    { template: 'Block all destructive actions', field: 'amount', operator: 'gt', value: '1' }, {}, { requireAction: true },
+  ));
+});
+
+test('an unknown template name exits with suggestions rather than a stack trace', () => {
+  _expectExit(() => _findTemplate('Block all destructve actions')); // typo
+});
+
+test('a template is found case-insensitively', () => {
+  const t = _findTemplate('block all destructive actions');
+  assert.strictEqual(t.label, 'Block all destructive actions');
+});
+
+// ── _displayAction: the raw `action` column is stale on essentially every
+// dashboard-built policy; effective_action (added server-side, see
+// troxy-tf-live's policies.py _effective_action) is the resolved value. This
+// is only a fallback for a server that hasn't deployed the field yet.
+
+test('_displayAction prefers effective_action when present', async () => {
+  const { _displayAction } = await import('../policies.js');
+  assert.strictEqual(_displayAction({ action: 'ESCALATE', effective_action: 'BLOCK' }), 'BLOCK');
+});
+
+test('_displayAction falls back to the raw action against an older server', async () => {
+  const { _displayAction } = await import('../policies.js');
+  assert.strictEqual(_displayAction({ action: 'BLOCK' }), 'BLOCK');
+});
+
+// ── --describe: handle_ai_policy only knows a binary payment/comms allowlist,
+// gated on is_email. Source-inspection style, matching model-checkpoint.test.js -
+// this branch needs a live login session + org AI key to drive end to end.
+
+test('--describe sends is_email when --domain comms is requested', () => {
+  const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'policies.js'), 'utf8');
+  const start = src.indexOf('if (flags.describe)');
+  const chunk = src.slice(start, start + 2000);
+  assert.ok(
+    /is_email:\s*describeDomain\s*===\s*'comms'/.test(chunk),
+    '--describe must forward is_email to api.aiPolicy, or every request silently uses the payment field allowlist regardless of what was described',
+  );
+  assert.ok(
+    /\['payment', 'comms'\]\.includes\(describeDomain\)/.test(chunk),
+    '--describe must reject any domain the AI builder does not actually support, rather than silently mis-drafting against the payment allowlist',
+  );
+});