quoxcli 0.3.1 → 0.4.0

package/lib/commands/chat.js

@@ -5,6 +5,10 @@
 import chalk from 'chalk';
 import { formatDetail } from '../core/output.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { existsSync } from 'node:fs';
+import { lastConversation, saveLastConversation } from './chatState.js';
+import { loadChatCompanion } from './chatCompanion.js';
+import { companionPlan, motionPolicy, VENDORED_DRAGONLAB } from '../dragon/select.js';
 
 /**
  * Build the POST body for /chat/stream (quox#782). The prompt and context
@@ -74,7 +78,7 @@ function generateQueryId() {
  * Consume a chat SSE stream, printing chunks as they arrive.
  * Returns { text, sessionId, agentUsed } once the stream completes.
  */
-export async function consumeStream(client, { message, agent, sessionId, context }, { onAgentLabel, trace = false } = {}) {
+export async function consumeStream(client, { message, agent, sessionId, context }, { onAgentLabel, trace = false, companionPath, companionDisplay } = {}) {
   const queryId = generateQueryId();
   const body = buildStreamQuery({ queryId, message, agent, sessionId, context });
 
@@ -90,19 +94,25 @@ export async function consumeStream(client, { message, agent, sessionId, context
     onAgentLabel?.(agentUsed);
   };
 
-  const iter = client.stream(resolveEndpoint('chat.stream').path, { service: resolveEndpoint('chat.stream').service, body, untilClose: Boolean(trace) })[Symbol.asyncIterator]();
+  const companion = await loadChatCompanion(companionPath, { display: companionDisplay });
+  const write = text => companion ? companion.write(text) : process.stdout.write(text);
+  // Native terminal status follows legacy `done`; observe it when opted in.
+  let iter;
+  try {
+  iter = client.stream(resolveEndpoint('chat.stream').path, { service: resolveEndpoint('chat.stream').service, body, untilClose: Boolean(trace || companion) })[Symbol.asyncIterator]();
   while (true) {
     let step;
     try {
       step = await iter.next();
     } catch (err) {
       // A refusal before the stream opened carries the layers it really evaluated.
-      if (trace && Array.isArray(err?.body?.aocl_layers)) for (const l of err.body.aocl_layers) printTrace({ type: 'aocl.layer', ...l });
+      if (trace && Array.isArray(err?.body?.aocl_layers)) { companion?.suspend(); for (const l of err.body.aocl_layers) printTrace({ type: 'aocl.layer', ...l }); }
       throw err;
     }
     if (step.done) break;
     const event = step.value;
-    if (trace) printTrace(event);
+    companion?.event(event);
+    if (trace) { companion?.suspend(); printTrace(event); }
     switch (event.type) {
       case 'connected':
         break;
@@ -110,9 +120,9 @@ export async function consumeStream(client, { message, agent, sessionId, context
       case 'thinking': {
         const stage = event.stage || '';
         if (stage === 'tool_call' || stage.includes('tool')) {
-          console.log(chalk.dim(`  ⚙ using tool: ${event.message}`));
+          write(chalk.dim(`  ⚙ using tool: ${event.message}`) + '\n');
         } else if (process.argv.includes('--verbose') || process.argv.includes('-v')) {
-          console.log(chalk.dim(`  … ${event.message}`));
+          write(chalk.dim(`  … ${event.message}`) + '\n');
         }
         break;
       }
@@ -120,19 +130,19 @@ export async function consumeStream(client, { message, agent, sessionId, context
       case 'chunk':
         printLabel();
         sawChunk = true;
-        process.stdout.write(event.content || '');
+        write(event.content || '');
         text += event.content || '';
         break;
 
       case 'done':
         if (!sawChunk && event.full_response) {
           printLabel();
-          process.stdout.write(event.full_response);
+          write(event.full_response);
           text = event.full_response;
         }
         if (event.session_id) resultSessionId = event.session_id;
         if (event.agent_used) agentUsed = event.agent_used;
-        console.log();
+        write('\n');
         break;
 
       case 'error':
@@ -142,28 +152,99 @@ export async function consumeStream(client, { message, agent, sessionId, context
         break;
     }
   }
+  } catch (err) {
+    companion?.event({ type: 'error' });
+    throw err;
+  } finally {
+    await companion?.close();
+    try { await iter?.return?.(); } catch { /* cleanup must not mask a stream error */ }
+  }
 
   return { text, sessionId: resultSessionId, agentUsed };
 }
 
-/** One-shot (non-streaming) chat via POST /chat/claude. */
-async function sendOneShot(client, { message, agent, sessionId }) {
-  const body = { prompt: message };
-  if (agent) body.selected_agent = agent;
-  if (sessionId) body.session_id = sessionId;
+/** The words for a failed turn: the server's plain message first, the bare error code only as a fallback. */
+export function turnFailureText(result, httpStatus) {
+  return result?.message || result?.error || `chat turn failed (HTTP ${httpStatus})`;
+}
 
-  const data = await client.post(resolveEndpoint('chat.claude').path, {
-    service: resolveEndpoint('chat.claude').service,
-    body,
-    timeout: 120000,
-  });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Poll a server-side chat turn until it is done. The turn keeps running on the server whatever this
+ * client does, so giving up early would hide a result (and any objects it created) from the user.
+ */
+async function awaitTurn(client, turnId) {
+  const capMs = Number(process.env.QUOX_CHAT_TURN_TIMEOUT_MS) || 20 * 60 * 1000;
+  const fixed = Number(process.env.QUOX_CHAT_POLL_MS) || 0;
+  const started = Date.now();
+  let wait = fixed || 1500;
+  let failures = 0;
+  const ep = resolveEndpoint('chat.turn.get', { id: turnId });
+  while (true) {
+    let t;
+    try {
+      t = await client.get(ep.path, { service: ep.service });
+      failures = 0;
+    } catch (err) {
+      if (err?.status === 404 || /not.found/i.test(err?.message || '')) {
+        throw new Error(`The server no longer has chat turn ${turnId} (expired, or the collector restarted). Check \`quox conversation list\` to see whether it finished.`);
+      }
+      if (++failures >= 5) throw err;
+      t = { status: 'running' };
+    }
+    if (t.status === 'done') {
+      if (t.http_status >= 400) throw new Error(turnFailureText(t.result, t.http_status));
+      return t.result || {};
+    }
+    if (t.status === 'error') throw new Error(`chat turn ${turnId} failed on the server: ${t.error || 'unknown error'}`);
+    if (Date.now() - started > capMs) {
+      throw new Error(`Chat turn ${turnId} is still running after ${Math.round(capMs / 1000)}s. It has not been lost: fetch it with \`quox chat --resume ${turnId}\`.`);
+    }
+    await sleep(wait);
+    if (!fixed) wait = Math.min(wait + 500, 5000);
+  }
+}
+
+/** One-shot (non-streaming) chat via POST /chat/claude, kept server side as a pollable turn. */
+async function sendOneShot(client, { message, agent, sessionId, resumeTurn }) {
+  let data;
+  if (resumeTurn) {
+    data = await awaitTurn(client, resumeTurn);
+  } else {
+    const body = { prompt: message };
+    if (agent) body.selected_agent = agent;
+    if (sessionId) body.session_id = sessionId;
+
+    // Prefer: respond-async returns 202 {turn_id} at once, so no client timeout can orphan a
+    // multi-tool turn. An older collector ignores it and answers synchronously (handled below).
+    data = await client.post(resolveEndpoint('chat.claude').path, {
+      service: resolveEndpoint('chat.claude').service,
+      body,
+      headers: { Prefer: 'respond-async' },
+      timeout: 30000,
+    });
+    if (data && data.turn_id && data.status === 'running') data = await awaitTurn(client, data.turn_id);
+  }
 
   const response = data.result || data.response || data.text || JSON.stringify(data);
   return { data, response, sessionId: data.session_id || sessionId };
 }
 
+/** Explicit --dragon-module wins; otherwise pick the dragon for the attached agent (null path = ordinary chat). */
+export function chooseCompanion({ options, config, env = process.env, isTTY = Boolean(process.stdout.isTTY), exists = existsSync }) {
+  const policy = motionPolicy(env);
+  if (options.dragonModule) return { companionPath: options.dragonModule, companionDisplay: { still: policy.still, mono: policy.mono } };
+  let settings = {};
+  try { settings = config?.getActiveProfile?.()?.quoxon || {}; } catch { /* no profile settings */ }
+  const e = options.dragon ? { ...env, QUOX_DRAGON_COMPANION: options.dragon } : env;
+  const plan = companionPlan({ agent: options.agent, settings, env: e, isTTY, exists, bundled: VENDORED_DRAGONLAB });
+  if (!plan.enabled) return { companionPath: undefined, companionDisplay: undefined };
+  return { companionPath: plan.file, companionDisplay: { still: plan.still, mono: plan.mono, persist: plan.persist } };
+}
+
 export function registerChatCommands(program, ctx) {
-  const { client, auth } = ctx;
+  const { client, auth, config } = ctx;
 
   const chat = program
     .command('chat')
@@ -172,13 +253,25 @@ export function registerChatCommands(program, ctx) {
     .option('--agent <name>', 'route to a specific agent (e.g. sentinel, cipher, nova)')
     .option('--no-stream', 'disable streaming output (one-shot request/response)')
     .option('--conversation <id>', 'continue a conversation (session id)')
+    .option('--continue', 'continue the last conversation for this profile and directory')
+    .option('--resume <turn>', 'fetch a chat turn that was still running (its id is printed if a turn outlives the wait)')
     .option('--trace', 'print the turn\'s protocol events (per-layer AOCL, traces, summary) to stderr as they arrive')
+    .option('--dragon <mode>', 'dragon companion for dragon-backed agents: on, greeting or off (default from /dragon companion; art is bundled; QUOX_DRAGONLAB overrides it)')
+    .option('--dragon-module <path>', 'opt in to a trusted local dragon companion module (streaming, single-message mode)')
     .action(async (message, options) => {
       auth.requireAuth();
       const streaming = options.stream !== false;
+      const profileName = (() => { try { return config?.getActiveProfileName?.(); } catch { return undefined; } })();
+      const noteConversation = (id) => {
+        if (!id) return;
+        saveLastConversation(profileName, process.cwd(), id);
+        if (program.opts().output !== 'json') process.stderr.write(`conversation: ${id}\n`);
+      };
+      if (!options.conversation && options.continue) options.conversation = lastConversation(profileName, process.cwd());
+      if (options.dragonModule && (!message || !streaming)) throw new Error('--dragon-module requires a single message with streaming enabled.');
 
-      // Interactive mode if no message
-      if (!message) {
+      // Interactive mode if no message (a --resume fetch is not interactive)
+      if (!message && !options.resume) {
         const { default: inquirer } = await import('inquirer');
         let currentAgent = options.agent || 'quox';
         let sessionId = options.conversation;
@@ -216,7 +309,7 @@ export function registerChatCommands(program, ctx) {
                 onAgentLabel: (agentUsed) => process.stdout.write(chalk.green(`${(agentUsed || currentAgent).toUpperCase()}: `)),
                 trace: Boolean(options.trace),
               });
-              if (result.sessionId) sessionId = result.sessionId;
+              if (result.sessionId) { sessionId = result.sessionId; saveLastConversation(profileName, process.cwd(), sessionId); }
               console.log();
             } else {
               const { response, sessionId: newSessionId } = await sendOneShot(client, {
@@ -224,7 +317,7 @@ export function registerChatCommands(program, ctx) {
                 agent: currentAgent,
                 sessionId,
               });
-              if (newSessionId) sessionId = newSessionId;
+              if (newSessionId) { sessionId = newSessionId; saveLastConversation(profileName, process.cwd(), sessionId); }
               console.log(chalk.green(`${currentAgent.toUpperCase()}:`), response);
               console.log();
             }
@@ -236,16 +329,19 @@ export function registerChatCommands(program, ctx) {
       }
 
       // Single message mode
-      if (streaming) {
+      if (streaming && !options.resume) {
+        const companion = chooseCompanion({ options, config });
         try {
-          await consumeStream(client, {
+          const result = await consumeStream(client, {
             message,
             agent: options.agent,
             sessionId: options.conversation,
           }, {
             onAgentLabel: () => {}, // no label prefix in single-shot streaming; just print tokens
             trace: Boolean(options.trace),
+            ...companion,
           });
+          noteConversation(result?.sessionId);
         } catch (err) {
           console.error(chalk.red(`Error: ${err.message}`));
           process.exitCode = 1;
@@ -257,15 +353,17 @@ export function registerChatCommands(program, ctx) {
       const spinner = ora('Thinking...').start();
 
       try {
-        const { data, response } = await sendOneShot(client, {
+        const { data, response, sessionId: convId } = await sendOneShot(client, {
           message,
           agent: options.agent,
           sessionId: options.conversation,
+          resumeTurn: options.resume,
         });
         spinner.stop();
+        noteConversation(convId);
 
         if (program.opts().output === 'json') {
-          console.log(JSON.stringify(data, null, 2));
+          console.log(JSON.stringify({ ...data, conversation_id: convId || null }, null, 2));
         } else {
           console.log(response);
 
@@ -293,3 +391,4 @@ export function registerChatCommands(program, ctx) {
       });
     });
 }
+

package/lib/commands/chatCompanion.js

@@ -0,0 +1,27 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** Explicit local opt-in only. A display failure must not interrupt a chat. */
+export async function loadChatCompanion(path, { output = process.stdout, warn = console.error, display = {} } = {}) {
+  if (!path || !output.isTTY) return null;
+  try {
+    const mod = await import(pathToFileURL(resolve(path)).href);
+    const c = await mod.createCompanion({ output, ...display });
+    if (!c || !['event', 'write', 'close', 'suspend'].every(k => typeof c[k] === 'function')) {
+      try { c?.close?.(); } catch {}
+      throw new Error('Expected createCompanion() with event/write/close/suspend');
+    }
+    let active = true;
+    const stop = async () => { active = false; try { await c.close(); } catch {} };
+    return {
+      event(e) { if (active) try { c.event(e); } catch { stop(); } },
+      write(text) { if (!active) output.write(text); else c.write(text); },
+      // Trace writes to stderr: relinquish the block first to prevent overlap.
+      suspend() { if (active) try { c.suspend(); } catch { stop(); } },
+      close: stop,
+    };
+  } catch (e) {
+    warn('Dragon companion unavailable; continuing normal chat: ' + e.message);
+    return null;
+  }
+}

package/lib/commands/chatState.js

@@ -0,0 +1,45 @@
+/**
+ * Last conversation per (profile, cwd), so `quox chat --continue` keeps context without the user
+ * copying a session id. Best-effort: a read/write failure never breaks a chat turn.
+ */
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync, readlinkSync } from 'node:fs';
+
+const stateFile = () => process.env.QUOX_CHAT_STATE || join(homedir(), '.config', 'quox', 'chat-last.json');
+/**
+ * Who is calling: $QUOX_SESSION when set, else this terminal's tty, else nothing (a headless
+ * caller with no session id falls back to profile + cwd only). Parallel terminals/sessions must
+ * never share a "last conversation".
+ */
+export function callerScope(env = process.env) {
+  if (env.QUOX_SESSION) return `session:${String(env.QUOX_SESSION).slice(0, 64)}`;
+  for (const fd of [0, 1, 2]) {
+    try {
+      const t = readlinkSync(`/proc/self/fd/${fd}`);
+      if (/^\/dev\/(pts\/\d+|tty\w*)$/.test(t)) return `tty:${t}`;
+    } catch { /* not linux, or fd closed */ }
+  }
+  return '';
+}
+const keyOf = (profile, cwd) => `${profile || 'default'}|${cwd || process.cwd()}|${callerScope()}`;
+
+function read() {
+  try { return JSON.parse(readFileSync(stateFile(), 'utf8')) || {}; } catch { return {}; }
+}
+
+export function lastConversation(profile, cwd) {
+  const v = read()[keyOf(profile, cwd)];
+  return typeof v === 'string' && v ? v : undefined;
+}
+
+export function saveLastConversation(profile, cwd, id) {
+  if (!id) return;
+  try {
+    const all = read();
+    all[keyOf(profile, cwd)] = id;
+    const f = stateFile();
+    mkdirSync(dirname(f), { recursive: true });
+    writeFileSync(f, JSON.stringify(all, null, 2));
+  } catch { /* best-effort */ }
+}

package/lib/commands/claude.js

@@ -1,5 +1,5 @@
 /**
- * quox claude / codex / gemini / run / sessions: governed tmux sessions. The runner
+ * quox claude / codex / run / sessions: governed tmux sessions. The runner
  * lives in core/governedSession.js; this file holds argument parsing and the
  * commander wiring. argv arrays only; user input never reaches a shell string.
  */
@@ -102,22 +102,6 @@ export const runClaude = ({ as, slot, ...opts } = {}, over) => gs.runGoverned({
   program: 'claude',
   ...(as || slot ? { preattach: { agent: as, slot, session: opts.name } } : {}),
 }, over);
-/**
- * quox gemini <args>: verbatim to `gemini`. Gemini resumes by index or
- * "latest" (`--resume latest`, `-r 5`), not by name, so the tmux session is
- * auto-named; reattach with `quox sessions attach NAME`.
- */
-export function parseGeminiArgs(raw) {
-  let noTmux = false;
-  const args = [];
-  for (const a of raw) {
-    if (a === '--no-tmux') noTmux = true;
-    else args.push(a);
-  }
-  const resume = args.some((a) => a === '--resume' || a === '-r' || a.startsWith('--resume='));
-  return { args, name: undefined, resume, noTmux };
-}
-
 /**
  * quox wrap <program> [args...]: wrap ANY command. Known programs use their
  * registry entry (so `quox wrap codex` == `quox codex`); unknown ones get the
@@ -135,12 +119,11 @@ export function parseRunArgs(raw) {
 }
 
 export function runRun({ bin, args = [], noTmux = false } = {}, over) {
-  const known = ['claude', 'codex', 'gemini'].find((k) => PROGRAMS[k].bin === bin);
+  const known = ['claude', 'codex'].find((k) => PROGRAMS[k].bin === bin);
   if (known) return gs.runGoverned({ program: known, args, noTmux }, over);
   return gs.runGoverned({ program: 'run', bin, args, noTmux }, over);
 }
 
-export const runGemini = (opts, over) => gs.runGoverned({ ...opts, program: 'gemini' }, over);
 export const runCodex = (opts, over) => gs.runGoverned({ ...opts, program: 'codex' }, over);
 export const runTui = (opts, over) => gs.runGoverned({ ...opts, program: 'tui' }, over);
 export const runHelp = gs.runHelp;
@@ -219,18 +202,6 @@ Claude's own --agent is untouched and passes through to claude.`)
       const parsed = parseCodexArgs(i >= 0 ? raw.slice(i + 1) : []);
       process.exitCode = runCodex(parsed, over);
     });
-  markForwardsRawArgs(program
-    .command('gemini'), 'forwards argv after the verb verbatim')
-    .description('Run Gemini CLI (same arguments as gemini) in a tmux session that survives sleep and drops')
-    .argument('[args...]', 'passed to gemini exactly as given (quox adds only --no-tmux)')
-    .helpOption(false)
-    .allowUnknownOption()
-    .allowExcessArguments()
-    .action((_a, _o, cmd) => {
-      const raw = (cmd.parent && cmd.parent.rawArgs) || process.argv;
-      const i = raw.indexOf('gemini', 2);
-      process.exitCode = runGemini(parseGeminiArgs(i >= 0 ? raw.slice(i + 1) : []), over);
-    });
   markForwardsRawArgs(program
     .command('wrap'), 'forwards argv after the verb verbatim')
     .description('Run any program in a governed tmux session: quox wrap <program> [args...]')
@@ -299,7 +270,7 @@ Claude's own --agent is untouched and passes through to claude.`)
   sessions.command('heartbeat <tmuxSession>', { hidden: true })
     .description('Heartbeat one wrapped tmux session to the org session index (started by quox claude)')
     .option('--loop', 'keep beating until the tmux session ends')
-    .option('--backend <program>', 'claude, codex, gemini, ...')
+    .option('--backend <program>', 'claude, codex, ...')
     .option('--agent <agent>', 'agent the session started attached to (--as)')
     .option('--slot <slot>', 'slot the session started holding (--slot)')
     .action(async (name, o) => {

package/lib/commands/contacts.js

@@ -14,6 +14,7 @@ import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { runSelftest } from './contactsSelftest.js';
 import { resolveOrgId } from './helpers.js';
+import { atToSendAt } from './contactsSendAt.js';
 
 const KINDS = ['person', 'organisation'];
 const REASONS = ['dnc', 'do_not_market', 'bounced'];
@@ -38,6 +39,8 @@ async function call(fn, { forbidden } = {}) {
     return await fn();
   } catch (e) {
     if (e instanceof QuoxApiError) {
+      // A refusal that says why (scheduled/immediate send) is shown as said, never swapped for a generic line.
+      if ((e.status === 403 || e.status === 409) && e.body && typeof e.body.reason === 'string' && e.body.reason) throw new QuoxError(e.body.reason, 1);
       if (e.status === 403 && forbidden) throw new QuoxError(forbidden, 1);
       if (e.status === 404 && e.body && e.body.error === 'tombstone_not_found') {
         throw new QuoxError('No erasure tombstone exists for that identifier in this org.', 1);
@@ -109,12 +112,15 @@ export function registerContactsCommands(program, ctx) {
     if (options.status) query.status = options.status;
     if (options.relationship) query.relationship = options.relationship;
     if (options.limit !== undefined) query.limit = Number(options.limit);
+    if (options.offset !== undefined) query.offset = Number(options.offset);
     const ep = resolveEndpoint('contactsq.contacts.list');
     const data = await call(() => client.get(ep.path, { service: ep.service, query }));
     if (isJson(program)) return printJson(data);
     const rows = (data.contacts || []).map(cardRow);
     formatOutput({ columns: CARD_COLS, headers: CARD_HEADS, rows }, { format: program.opts().output });
-    announce('contacts list', `${rows.length} contacts`);
+    const total = Number.isInteger(data.total) ? data.total : rows.length;
+    const next = (data.offset || 0) + rows.length;
+    announce('contacts list', next < total ? `${rows.length} of ${total} contacts, next: --offset ${next}` : `${rows.length} of ${total} contacts`);
   };
 
   addNameOptions(contacts
@@ -186,9 +192,10 @@ export function registerContactsCommands(program, ctx) {
     .command('list')
     .description('List contacts')
     .option('--q <text>', 'name filter')
-    .option('--status <s>', 'active | candidate | archived')
+    .option('--status <s>', 'active | candidate | archived | all (default: everyone except archived)')
     .option('--relationship <r>', 'primary relationship, e.g. customer | supplier | partner')
-    .option('--limit <n>', 'max contacts')
+    .option('--limit <n>', 'page size (default 25, max 100)')
+    .option('--offset <n>', 'skip this many (paging: the footer prints the next --offset)')
     .action((options) => list(options));
 
   contacts
@@ -480,7 +487,7 @@ export function registerContactsCommands(program, ctx) {
     .description('Dial a contact by id through the phone bridge; you never see or type the number')
     .argument('<id>', 'contact id (find it with `quox contacts search`)')
     .option('--reason <text>', 'what the call is about (the agent opens with it)')
-    .option('--purpose <p>', 'service | transactional | marketing | research', 'service')
+    .option('--purpose <p>', 'service | transactional | marketing | research | personal', 'service')
     .action(async (id, options) => {
       auth.requireAuth();
       const body = { contact_id: id, projection: 'dial', channel: 'voice', purpose: options.purpose };
@@ -495,6 +502,80 @@ export function registerContactsCommands(program, ctx) {
       announce('contacts call', `${l.id || '?'} queued for the phone bridge`);
     });
 
+  // ---- send: SMS or email now or at a time (the server delivers; you approve by running it) ----
+  const DEFAULT_TZ = 'Europe/London';
+  async function resolveContactArg(arg) {
+    if (/^ct_[a-z0-9_]+$/i.test(arg)) return arg;
+    const ep = resolveEndpoint('contactsq.search');
+    const data = await call(() => client.get(ep.path, { service: ep.service, query: { q: arg } }));
+    const c = data.candidates || [];
+    if (!c.length) throw new QuoxError(`No contact matches "${arg}". Try \`quox contacts search\`.`, 1);
+    if (data.ambiguous || c.length > 1) {
+      throw new QuoxError(`"${arg}" matches more than one contact (${c.slice(0, 5).map((x) => `${x.display_name} ${x.id}`).join('; ')}). Pass the contact id.`, 1);
+    }
+    return c[0].id;
+  }
+
+  contacts
+    .command('send')
+    .description('Send an SMS or email to a contact now, or at a time with --at (the server delivers it; the answer says exactly when)')
+    .argument('<contact>', 'contact id (ct_...) or an unambiguous name')
+    .argument('<text>', 'the message')
+    .option('--channel <c>', 'sms | email', 'sms')
+    .option('--at <time>', 'send later: ISO time with offset, or a clock time like 10am / 14:30 (next occurrence, in --tz)')
+    .option('--tz <zone>', 'IANA zone for --at', DEFAULT_TZ)
+    .option('--title <t>', 'subject (email)')
+    .option('--purpose <p>', 'service | transactional | marketing | research | personal', 'service')
+    .option('--reason <text>', 'why (recorded as a hash only)')
+    .action(async (contactArg, text, options) => {
+      auth.requireAuth();
+      checkEnum(options.channel, ['sms', 'email'], '--channel');
+      checkEnum(options.purpose, ['service', 'transactional', 'marketing', 'research', 'personal'], '--purpose');
+      const contactId = await resolveContactArg(contactArg);
+      const body = { contact_id: contactId, channel: options.channel, message: text, purpose: options.purpose };
+      if (options.title) body.title = options.title;
+      if (options.reason) body.reason = options.reason;
+      if (options.at) { body.send_at = atToSendAt(options.at, options.tz); body.timezone = options.tz; }
+      const ep = resolveEndpoint('contactsq.sends.create');
+      const data = await call(() => client.post(ep.path, { service: ep.service, body, retries: 0 }), {
+        forbidden: 'Blocked by contact policy, or you are not a human user. Run `quox contacts best-channel <id>` to see why.',
+      });
+      if (isJson(program)) return printJson(data);
+      if (data.job) {
+        formatDetail({ job: data.job.id, status: data.job.status, channel: data.job.channel, when: data.job.when, send_at: data.job.send_at });
+        return announce('contacts send', `scheduled ${data.job.id}: ${data.job.when}`);
+      }
+      if (data.status === 'sent') { formatDetail({ lease: data.lease_id, status: 'sent' }); return announce('contacts send', `${options.channel} sent`); }
+      formatDetail({ lease: data.lease_id, status: data.status, error: data.error, reason: data.reason });
+      announce('contacts send', `FAILED: ${data.reason || data.error}`);
+      process.exitCode = 1;
+    });
+
+  const scheduled = contacts.command('scheduled').description('Scheduled sends: what is queued, and cancel one before it goes out');
+  scheduled
+    .command('list')
+    .option('--status <s>', 'comma list of pending,sending,sent,failed,cancelled (default pending,sending)')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.sends.scheduled');
+      const data = await call(() => client.get(ep.path, { service: ep.service, query: options.status ? { status: options.status } : {} }), { forbidden: 'Scheduled sends are for human users.' });
+      if (isJson(program)) return printJson(data);
+      const rows = (data.jobs || []).map((j) => ({ id: j.id, contact: j.contact_id, channel: j.channel, status: j.status, when: j.when || j.finished_at || '', outcome: j.outcome_reason || j.outcome_code || '' }));
+      formatOutput({ columns: ['id', 'contact', 'channel', 'status', 'when', 'outcome'], rows }, { format: program.opts().output });
+      announce('contacts scheduled list', `${rows.length} jobs`);
+    });
+  scheduled
+    .command('cancel')
+    .argument('<id>', 'scheduled send id (ss_...)')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('contactsq.sends.cancel', { id });
+      const data = await call(() => client.post(ep.path, { service: ep.service, body: {} }), { forbidden: 'Cancelling a scheduled send is for human users.' });
+      if (isJson(program)) return printJson(data);
+      formatDetail({ job: data.job.id, status: data.job.status });
+      announce('contacts scheduled cancel', data.job.id);
+    });
+
   contacts
     .command('leases')
     .description('Lease + use ledger for a contact (who was given access, when, why; never the values)')

package/lib/commands/contactsSendAt.js

@@ -0,0 +1,21 @@
+import { QuoxError } from '../core/errors.js';
+
+/** "10am", "10:30", "22:15" -> the next such wall-clock time in tz as a bare local ISO the server reads in that zone. ISO input passes through. */
+export function atToSendAt(at, tz, nowMs = Date.now()) {
+  const raw = String(at).trim();
+  if (/^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(raw) || /(?:Z|[+-]\d{2}:?\d{2})$/i.test(raw)) return raw;
+  const m = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i.exec(raw);
+  if (!m) throw new QuoxError(`--at must be an ISO time (2026-10-25T10:00:00+00:00) or a clock time such as 10am or 14:30, got "${raw}"`, 2);
+  let h = Number(m[1]);
+  const mi = Number(m[2] || 0);
+  if (m[3]) { if (h < 1 || h > 12) throw new QuoxError('--at hour must be 1 to 12 with am/pm', 2); h = (h % 12) + (m[3].toLowerCase() === 'pm' ? 12 : 0); }
+  if (h > 23 || mi > 59) throw new QuoxError('--at is not a valid clock time', 2);
+  const parts = (ms) => Object.fromEntries(new Intl.DateTimeFormat('en-GB', { timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).formatToParts(new Date(ms)).map((p) => [p.type, p.value]));
+  const n = parts(nowMs);
+  const pad = (v) => String(v).padStart(2, '0');
+  let day = Date.UTC(Number(n.year), Number(n.month) - 1, Number(n.day));
+  if (h * 60 + mi <= Number(n.hour) * 60 + Number(n.minute)) day += 86400000; // already passed today: tomorrow
+  const d = new Date(day);
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}T${pad(h)}:${pad(mi)}`;
+}
+