quoxcli 0.0.0-stage → 0.2.0

package/lib/commands/notesBatch.js

@@ -0,0 +1,160 @@
+/**
+ * NotesQ session bulk authoring (AQ-9D P8): pure helpers behind
+ * `quox notes batch` and `quox notes split`. A batch travels as a zip of
+ * markdown files (frontmatter: title, collection, tags, key) and is parsed
+ * server-side by the import pipeline's `batch` format.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { basename, join, relative } from 'path';
+import { QuoxError } from '../core/errors.js';
+
+// Mirrors MAX_BATCH_NOTES in services/collector/lib/notesq/import/index.js.
+export const MAX_BATCH_NOTES = 200;
+const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
+
+// The server's frontmatter reader strips one pair of quotes and does no escape
+// processing, so pick the quote the value does not contain.
+function yamlStr(v) {
+  const s = String(v).replace(/[\r\n]+/g, ' ').trim();
+  if (!s.includes('"')) return `"${s}"`;
+  if (!s.includes("'")) return `'${s}'`;
+  return `"${s.replace(/"/g, "'")}"`;
+}
+
+/** One note as a markdown file with the frontmatter the batch parser reads. */
+export function noteFile({ title, markdown, collection, tags, key }) {
+  const fm = [];
+  if (title) fm.push(`title: ${yamlStr(title)}`);
+  if (collection) fm.push(`collection: ${yamlStr(collection)}`);
+  if (key) fm.push(`key: ${yamlStr(key)}`);
+  const list = (tags || []).map((t) => String(t).trim()).filter(Boolean);
+  if (list.length) { fm.push('tags:'); for (const t of list) fm.push(`  - ${yamlStr(t)}`); }
+  return `${fm.length ? `---\n${fm.join('\n')}\n---\n` : ''}${String(markdown || '')}`;
+}
+
+/** JSONL text -> items. Each line: {title, markdown|body, collection?, tags?, key?}. Key defaults to the title, so a re-run skips. */
+export function parseJsonl(text) {
+  const items = [];
+  String(text || '').split(/\r?\n/).forEach((line, i) => {
+    if (!line.trim()) return;
+    let o;
+    try { o = JSON.parse(line); } catch (e) { throw new QuoxError(`JSONL line ${i + 1} is not valid JSON: ${e.message}`, 2); }
+    const title = typeof o.title === 'string' ? o.title.trim() : '';
+    const markdown = typeof o.markdown === 'string' ? o.markdown : (typeof o.body === 'string' ? o.body : '');
+    if (!title) throw new QuoxError(`JSONL line ${i + 1} has no title.`, 2);
+    if (o.tags !== undefined && !Array.isArray(o.tags)) throw new QuoxError(`JSONL line ${i + 1}: tags must be an array.`, 2);
+    items.push({ title, markdown, collection: typeof o.collection === 'string' ? o.collection : undefined, tags: o.tags || [], key: typeof o.key === 'string' && o.key ? o.key : title });
+  });
+  return items;
+}
+
+function walk(dir, root, out) {
+  for (const name of readdirSync(dir).sort()) {
+    if (name.startsWith('.')) continue;
+    const p = join(dir, name);
+    const st = statSync(p);
+    if (st.isDirectory()) walk(p, root, out);
+    else if (st.isFile()) out.push({ path: relative(root, p).split('\\').join('/'), size: st.size, read: () => readFileSync(p) });
+  }
+  return out;
+}
+
+/**
+ * Build the zip for a batch. `source` is a folder (markdown + any embedded
+ * files, sent as-is), a .jsonl file, or '-' with `stdinText` holding JSONL.
+ * `items` (already-built notes, used by split) bypasses `source`.
+ * @returns {{bytes: Buffer, filename: string, notes: number}}
+ */
+export async function buildBatchArchive({ source, stdinText, items, name }) {
+  const JSZip = (await import('jszip')).default;
+  const zip = new JSZip();
+  let root;
+  let notes = 0;
+  const addItems = (list, rootName) => {
+    root = rootName;
+    list.forEach((it, i) => { zip.file(`${root}/${String(i + 1).padStart(3, '0')}.md`, noteFile(it)); });
+    notes = list.length;
+  };
+  if (items) addItems(items, name || 'batch');
+  else if (source === '-') addItems(parseJsonl(stdinText), name || 'stdin');
+  else {
+    let st;
+    try { st = statSync(source); } catch (e) { throw new QuoxError(`Cannot read ${source}: ${e.message}`, 2); }
+    if (st.isDirectory()) {
+      root = name || basename(source.replace(/[\\/]+$/, '')) || 'batch';
+      const files = walk(source, source, []);
+      let total = 0;
+      for (const f of files) {
+        total += f.size;
+        if (total > MAX_ARCHIVE_BYTES) throw new QuoxError(`${source} is over the 100 MB batch limit.`, 2);
+        zip.file(`${root}/${f.path}`, f.read());
+        if (/\.(md|markdown)$/i.test(f.path)) notes++;
+      }
+    } else if (/\.jsonl$/i.test(source)) {
+      addItems(parseJsonl(readFileSync(source, 'utf8')), name || basename(source).replace(/\.jsonl$/i, ''));
+    } else {
+      throw new QuoxError(`${source} is not a folder or a .jsonl file (use - to read JSONL from stdin).`, 2);
+    }
+  }
+  if (!notes) throw new QuoxError('Nothing to write: the batch has no markdown notes.', 2);
+  if (notes > MAX_BATCH_NOTES) throw new QuoxError(`A batch may create at most ${MAX_BATCH_NOTES} notes (this one has ${notes}). Split it into smaller batches.`, 2);
+  const bytes = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  return { bytes, filename: `${root}.zip`, notes };
+}
+
+const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const FENCE = /^\s*(```|~~~)/;
+// Characters that would break a [[wikilink]] to the child.
+const cleanTitle = (t) => t.replace(/[[\]|#^]/g, '').replace(/\s+/g, ' ').trim();
+
+/**
+ * Cut a note at its headings. Level defaults to the shallowest heading below
+ * the title H1. Headings inside code fences are ignored. Text before the first
+ * cut stays with the parent; deeper headings inside a section are promoted so
+ * the child reads as a note of its own.
+ * @returns {{title:string|null, preamble:string, level:number|null, sections:{title:string, body:string}[]}}
+ */
+export function splitMarkdown(markdown, { level } = {}) {
+  const lines = String(markdown || '').split('\n');
+  const heads = [];
+  let inFence = false;
+  lines.forEach((line, i) => {
+    if (FENCE.test(line)) { inFence = !inFence; return; }
+    if (inFence) return;
+    const m = HEADING.exec(line);
+    if (m) heads.push({ i, level: m[1].length, text: m[2] });
+  });
+  let title = null;
+  let start = 0;
+  const first = heads[0];
+  if (first && first.level === 1 && lines.slice(0, first.i).every((l) => !l.trim())) { title = first.text.trim(); start = first.i + 1; }
+  const below = heads.filter((h) => h.i >= start && (title === null || h.level > 1));
+  const lvl = level ? Number(level) : (below.length ? Math.min(...below.map((h) => h.level)) : null);
+  const cuts = below.filter((h) => h.level === lvl);
+  if (cuts.length < 2) return { title, preamble: '', level: lvl, sections: [] };
+  const preamble = lines.slice(start, cuts[0].i).join('\n').trim();
+  const seen = new Map();
+  const sections = cuts.map((c, k) => {
+    const end = k + 1 < cuts.length ? cuts[k + 1].i : lines.length;
+    let fence = false;
+    const body = lines.slice(c.i + 1, end).map((l) => {
+      if (FENCE.test(l)) { fence = !fence; return l; }
+      if (fence) return l;
+      const m = HEADING.exec(l);
+      return m && m[1].length > lvl ? `${'#'.repeat(Math.max(m[1].length - lvl + 1, 2))} ${m[2]}` : l;
+    }).join('\n').trim();
+    let t = cleanTitle(c.text) || `Part ${k + 1}`;
+    const n = (seen.get(t) || 0) + 1;
+    seen.set(t, n);
+    if (n > 1) t = `${t} (${n})`;
+    return { title: t, body };
+  });
+  return { title, preamble, level: lvl, sections };
+}
+
+/** The parent after a split: its own preamble, then links to every child. */
+export function indexMarkdown({ title, preamble, children }) {
+  const head = `# ${title}\n\n${preamble ? `${preamble}\n\n` : ''}`;
+  return `${head}## Contents\n\n${children.map((c) => `- [[${c}]]`).join('\n')}\n`;
+}

package/lib/commands/notesBridges.js

@@ -0,0 +1,56 @@
+/**
+ * NotesQ AssistantQ wires (AQ-9D P4), pure helpers. Each wire composes at the
+ * edge: the CLI reads through the other plugin's own governed route (its
+ * licence, access rules and audit) and writes through NotesQ's, so no new
+ * server path reads another plugin's data.
+ */
+
+import { createHash } from 'crypto';
+
+const short = (s) => createHash('sha1').update(s).digest('hex').slice(0, 12);
+
+/** An InboxQ message as a note. Body text preferred; HTML is reduced to text; snippet is the last resort. */
+export function emailToNote(msg) {
+  const subject = String(msg.subject || '').replace(/[\r\n]+/g, ' ').trim() || '(no subject)';
+  const from = msg.fromName && msg.fromAddr ? `${msg.fromName} <${msg.fromAddr}>` : (msg.fromAddr || msg.fromName || 'unknown sender');
+  const date = msg.dateTs ? new Date(Number(msg.dateTs) < 1e12 ? Number(msg.dateTs) * 1000 : Number(msg.dateTs)).toISOString() : null;
+  let body = typeof msg.bodyText === 'string' && msg.bodyText.trim() ? msg.bodyText : null;
+  let bodySource = 'text';
+  if (!body && typeof msg.bodyHtml === 'string' && msg.bodyHtml.trim()) {
+    body = msg.bodyHtml
+      .replace(/<(script|style)[\s\S]*?<\/\1>/gi, '')
+      .replace(/<br\s*\/?>/gi, '\n').replace(/<\/(p|div|li|tr|h[1-6])>/gi, '\n')
+      .replace(/<[^>]+>/g, '')
+      .replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+      .replace(/\n{3,}/g, '\n\n');
+    bodySource = 'html';
+  }
+  if (!body) { body = msg.snippet || ''; bodySource = 'snippet'; }
+  const quoted = String(body).trim().split('\n').map((l) => (l ? `> ${l}` : '>')).join('\n');
+  const markdown = `# ${subject}\n\n**From:** ${from}  \n${date ? `**Date:** ${date}  \n` : ''}**Saved from InboxQ**\n\n${quoted}\n`;
+  const properties = { source: 'inboxq', inboxq_message_id: msg.id, email_from: msg.fromAddr || from, ...(date ? { email_date: date } : {}) };
+  return { title: subject, markdown, properties, bodySource };
+}
+
+/**
+ * Unchecked markdown tasks (`- [ ] text`, `* [ ]`, `1. [ ]`) outside code
+ * fences, each with a stable short hash so a re-run can skip ones already sent.
+ */
+export function extractTasks(markdown) {
+  const out = [];
+  let fence = false;
+  for (const line of String(markdown || '').split('\n')) {
+    if (/^\s*(```|~~~)/.test(line)) { fence = !fence; continue; }
+    if (fence) continue;
+    const m = /^\s*(?:[-*+]|\d+[.)])\s+\[ \]\s+(.+?)\s*$/.exec(line);
+    if (m && m[1]) out.push({ text: m[1].slice(0, 200), hash: short(m[1].trim().toLowerCase()) });
+  }
+  return out;
+}
+
+/** The QuoxPlan stream note for a promoted NotesQ note: title, link, and an excerpt. */
+export function promoteBody(note, link) {
+  const body = String(note.markdown || '').replace(/^\s*#\s+.+\n+/, '').trim();
+  const excerpt = body.length > 1500 ? `${body.slice(0, 1500).trimEnd()}...` : body;
+  return `NotesQ: "${note.title || 'Untitled'}" ${link}${excerpt ? `\n\n${excerpt}` : ''}`;
+}

package/lib/commands/notesLinks.js

@@ -0,0 +1,60 @@
+/**
+ * Pure NotesQ link helpers (AQ-9D P5). The frontend keeps its own copy and a
+ * parity test imports this one, so behaviour here is the contract.
+ */
+
+// Blank (same length) every region where a title must not be linked: front
+// matter, fenced code, inline code, [[wikilinks]] and [text](url) links.
+function maskNonProse(md) {
+  const blank = (m) => m.replace(/[^\n]/g, ' ');
+  return String(md || '')
+    .replace(/^---\r?\n[\s\S]*?\r?\n---(?=\r?\n|$)/, blank)
+    .replace(/(```|~~~)[\s\S]*?(\1|$)/g, blank)
+    .replace(/`[^`\n]*`/g, blank)
+    .replace(/!?\[\[[^\]\n]*\]\]/g, blank)
+    .replace(/!?\[[^\]\n]*\]\([^)\n]*\)/g, blank)
+    .replace(/^#[ \t]+[^\n]*/m, blank); // the note's own title heading
+}
+
+const escapeRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Replace the first plain-text, case-insensitive, word-bounded occurrence of
+ * `title` with `[[title]]` (the title exactly as given).
+ * @returns {{markdown: string, changed: boolean}}
+ */
+export function linkMention(markdown, title) {
+  const md = String(markdown ?? '');
+  const t = String(title ?? '').trim();
+  if (!t) return { markdown: md, changed: false };
+  const re = new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRe(t)}(?![\\p{L}\\p{N}_])`, 'iu');
+  const m = re.exec(maskNonProse(md));
+  if (!m) return { markdown: md, changed: false };
+  return { markdown: `${md.slice(0, m.index)}[[${t}]]${md.slice(m.index + m[0].length)}`, changed: true };
+}
+
+/** Append `- [[title]]` to the `## See also` section, creating it at the end if absent. */
+export function addSeeAlso(markdown, title) {
+  const md = String(markdown ?? '');
+  const link = `[[${title}]]`;
+  const item = `- ${link}`;
+  const lines = md.split('\n');
+  // Lines inside fenced code never count as headings.
+  const fenced = [];
+  let open = null;
+  for (const l of lines) {
+    const f = /^\s*(```|~~~)/.exec(l);
+    if (open) { fenced.push(true); if (f && f[1] === open) open = null; } else if (f) { fenced.push(true); open = f[1]; } else fenced.push(false);
+  }
+  const start = lines.findIndex((l, i) => !fenced[i] && /^## See also\s*$/.test(l));
+  if (start >= 0) {
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) if (!fenced[i] && /^#{1,6}\s/.test(lines[i])) { end = i; break; }
+    if (lines.slice(start + 1, end).some((l) => l.includes(link))) return md;
+    let last = end - 1;
+    while (last > start && lines[last].trim() === '') last--;
+    lines.splice(last + 1, 0, item);
+    return lines.join('\n');
+  }
+  return `${md.replace(/\n+$/, '')}\n\n## See also\n\n${item}\n`;
+}

package/lib/commands/notification.js

@@ -0,0 +1,57 @@
+/**
+ * Notification commands
+ *
+ * quox notification channels list|set
+ */
+
+import { formatOutput, formatDetail } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export function registerNotificationCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const notification = program
+    .command('notification')
+    .description('Manage notification settings');
+
+  const channels = notification
+    .command('channels')
+    .description('Notification channel management');
+
+  channels
+    .command('list')
+    .description('List notification channels')
+    .action(async () => {
+      auth.requireAuth();
+      const data = await client.get(resolveEndpoint('users.me.notification-channels.list').path, { service: resolveEndpoint('users.me.notification-channels.list').service });
+      const chans = data.channels || data || [];
+      formatOutput({
+        // fleet #392: rows carry channel_type and a nested config object;
+        // `type` and a flat `destination` don't exist on them.
+        columns: ['type', 'enabled', 'destination'],
+        headers: ['Type', 'Enabled', 'Destination'],
+        rows: chans.map(c => ({
+          type: c.channel_type ?? c.type,
+          enabled: c.enabled ? 'Yes' : 'No',
+          destination: c.config?.destination ?? c.destination ?? '-',
+        })),
+      }, { format: program.opts().output });
+    });
+
+  channels
+    .command('set')
+    .description('Configure a notification channel')
+    .requiredOption('--type <type>', 'Channel type (email|slack|telegram|...)')
+    .option('--enable', 'Enable channel')
+    .option('--disable', 'Disable channel')
+    .option('--destination <dest>', 'Channel destination (email, webhook URL, chat ID)')
+    .action(async (opts) => {
+      auth.requireAuth();
+      const body = {};
+      if (opts.enable) body.enabled = true;
+      if (opts.disable) body.enabled = false;
+      if (opts.destination) body.config = { destination: opts.destination };
+      const data = await client.put(resolveEndpoint('users.me.notification-channels.update', { type: opts.type }).path, { service: resolveEndpoint('users.me.notification-channels.update', { type: opts.type }).service, body });
+      formatDetail(data, { format: program.opts().output, title: 'Channel Updated' });
+    });
+}

package/lib/commands/nucleus.js

@@ -0,0 +1,92 @@
+/**
+ * `quox nucleus` — QUOXIFY PASS 2 (DEVSUITE phase 15).
+ *
+ * RepoBrain has been the cheap way to answer structural questions about the
+ * Quox repos for a while (targeted snippets instead of whole files), but it
+ * was reachable only through its own standalone binary and, for agents, a raw
+ * tool. The quoxification audit called that out twice: no unified `quox`
+ * verb (S-Q3), and an ungoverned side-path where the agent tool hit the
+ * engine directly while the CLI did not (S-Q5).
+ *
+ * This verb closes the CLI half, and closes it the RIGHT way: it goes through
+ * the collector's governed /api/v1/tools/execute, so the query is org-scoped
+ * and audited exactly like every other tool call, rather than reaching the
+ * engine behind the collector's back.
+ *
+ * Announce convention: RepoBrain surfaces announce themselves with 🧠 (see
+ * the icon registry in CLAUDE.md), so a query is visible in a wall of
+ * terminal output.
+ */
+
+import { formatDetail, printWarning } from '../core/output.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+
+export function registerNucleusCommands(program, { client, auth }) {
+  const nucleus = program
+    .command('nucleus')
+    .description('Ask the codebase a question (RepoBrain, governed and audited)');
+
+  nucleus
+    .command('query', { isDefault: true })
+    .description('Query the codebase and get cited file:line snippets')
+    .argument('<question...>', 'the question, e.g. "where is the slot bridge verified?"')
+    .option('-t, --target <repo>', 'repo to search (default: quox-dashboard)')
+    .option('-n, --limit <n>', 'max snippets to return', '8')
+    .action(async (questionParts, options) => {
+      auth.requireAuth();
+      const question = questionParts.join(' ').trim();
+      if (!question) throw new Error('ask something: quox nucleus "where is X?"');
+
+      printEvent(glyphLine('repobrain', `query "${question}"`));
+      const started = Date.now();
+
+      const ep = resolveEndpoint('v1.tools.execute');
+      const body = {
+        tool_name: 'codebase_query',
+        input: {
+          query: question,
+          ...(options.target ? { repo: options.target } : {}),
+          ...(options.limit ? { limit: parseInt(options.limit, 10) || 8 } : {}),
+        },
+      };
+      const orgId = resolveOrgId(auth, program);
+      if (orgId) body.org_id = orgId;
+
+      const data = await client.post(ep.path, { service: ep.service, body, timeout: 60000 });
+      const ms = Date.now() - started;
+
+      // The tool result shape varies by engine version, so normalise rather
+      // than assuming: an unexpected shape must still print SOMETHING true.
+      const result = data && (data.result || data.output || data);
+      const results = Array.isArray(result?.results) ? result.results
+        : Array.isArray(result?.snippets) ? result.snippets
+        : Array.isArray(result) ? result
+        : null;
+
+      if (program.opts().output === 'json') {
+        formatDetail(data, { format: 'json' });
+        return;
+      }
+
+      if (!results || results.length === 0) {
+        printEvent(glyphLine('repobrain', `query "${question}"`, { result: '0 hits', ms }));
+        printWarning('Nothing matched. Try naming a concrete symbol, filename or behaviour rather than a general description.');
+        // Still show the raw payload when the shape was unexpected, so a
+        // parsing gap here never looks like an empty index.
+        if (result && !results) formatDetail(result, { format: program.opts().output });
+        return;
+      }
+
+      printEvent(glyphLine('repobrain', `query "${question}"`, { result: `${results.length} hits`, ms }));
+      for (const r of results) {
+        const loc = r.file || r.path || r.source || '(unknown file)';
+        const line = r.line || r.start_line || null;
+        console.log('');
+        console.log(`  ${loc}${line ? `:${line}` : ''}`);
+        const snippet = r.snippet || r.content || r.text || '';
+        for (const l of String(snippet).split('\n').slice(0, 20)) console.log(`    ${l}`);
+      }
+    });
+}

package/lib/commands/objective.js

@@ -0,0 +1,229 @@
+/**
+ * Objective commands: create, list, get, start, approve, plus the HITL
+ * checkpoint verbs (checkpoints, approve-checkpoint, deny-checkpoint).
+ *
+ * Objectives are served by the tasks service (port 3104), not the auth
+ * service. Org/user scoping comes from the JWT (org_id/sub claims) rather
+ * than a URL path segment — see services/tasks/middleware/auth.js.
+ *
+ * Two approval gates exist and must not be confused:
+ *   `approve`            resolves a decomposed objective's DAG plan.
+ *   `approve-checkpoint` resolves one HITL checkpoint (pre-start gate or a
+ *                        live loop gate: budget, risk, interval).
+ */
+
+import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { parseJSON } from './helpers.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/**
+ * Format a timestamp as a short relative-time string ("5m ago").
+ *
+ * Checkpoint rows carry SQLite `datetime('now')` values ("2026-08-14
+ * 04:00:00"), which are UTC but have no zone marker, so Node would read them
+ * as local time and skew the age by the offset. Normalise that shape to ISO
+ * UTC first; anything already ISO passes straight through.
+ */
+function relativeTime(ts) {
+  if (!ts) return '—';
+  const iso = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(ts)
+    ? `${ts.replace(' ', 'T')}Z`
+    : ts;
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return '—';
+  const diffSec = Math.max(0, Math.floor((Date.now() - then) / 1000));
+  if (diffSec < 60) return `${diffSec}s ago`;
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.floor(diffHr / 24);
+  return `${diffDay}d ago`;
+}
+
+/**
+ * Accumulate repeated `--capability-scope` flags into one array of raw
+ * strings. Each value may itself be a comma-separated list; splitting and
+ * trimming happen in the action, alongside the other body fields.
+ */
+function collectScope(value, previous) {
+  return (previous || []).concat(value);
+}
+
+export function registerObjectiveCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const objective = program
+    .command('objective')
+    .description('Manage objectives (autonomous multi-step goals)');
+
+  objective
+    .command('create')
+    .description('Create a new objective (DAG plan by default, or a QLoop loop with --execution-mode loop)')
+    .argument('<goal>', 'objective title / goal statement')
+    .option('--description <text>', 'longer description')
+    .option('--team <id>', 'team ID to run the objective under')
+    .option('--max-tokens <n>', 'max token budget')
+    .option('--max-tool-calls <n>', 'max tool call budget')
+    .option('--max-duration-ms <n>', 'max wall-clock duration in ms')
+    .option('--require-approval', 'require approval before starting')
+    .option('--checkpoint', 'checkpoint after each task')
+    .option('--goal-condition <text>', 're-observe loop exit condition')
+    .option('--max-iterations <n>', 'max re-observe loop iterations')
+    .option('--metadata <json>', 'arbitrary metadata as JSON')
+    .option('--execution-mode <mode>', 'dag|loop. A loop runs a QLoop backend instead of a reviewable DAG plan, so it ALWAYS requires a before_start approval (see `quox objective checkpoints` and `approve-checkpoint`)')
+    .option('--loop-backend <backend>', 'claude|codex, loop mode only (default claude)')
+    .option('--capability-scope <tools>', 'comma-separated tool names the loop may call (repeatable); empty scope escalates every tool', collectScope)
+    .option('--system-prompt <text>', 'per-objective system prompt, carried verbatim to the run')
+    .action(async (goal, options) => {
+      auth.requireAuth();
+      const body = { title: goal };
+      if (options.description) body.description = options.description;
+      if (options.team) body.team_id = options.team;
+      if (options.maxTokens) body.max_tokens = Number(options.maxTokens);
+      if (options.maxToolCalls) body.max_tool_calls = Number(options.maxToolCalls);
+      if (options.maxDurationMs) body.max_duration_ms = Number(options.maxDurationMs);
+      if (options.requireApproval) body.require_approval_before_start = true;
+      if (options.checkpoint) body.checkpoint_after_each_task = true;
+      if (options.goalCondition) body.goal_condition = options.goalCondition;
+      if (options.maxIterations) body.max_iterations = Number(options.maxIterations);
+      if (options.metadata) body.metadata = parseJSON(options.metadata, '--metadata');
+      if (options.executionMode) body.execution_mode = options.executionMode;
+      if (options.loopBackend) body.loop_backend = options.loopBackend;
+      if (options.capabilityScope) {
+        const scope = options.capabilityScope
+          .flatMap((raw) => raw.split(','))
+          .map((t) => t.trim())
+          .filter(Boolean);
+        if (scope.length > 0) body.capability_scope = scope;
+      }
+      if (options.systemPrompt) body.system_prompt = options.systemPrompt;
+
+      const data = await client.post(resolveEndpoint('objectives.create').path, { service: resolveEndpoint('objectives.create').service, body });
+      printSuccess(`Objective created: ${data.id}`);
+    });
+
+  objective
+    .command('list')
+    .description('List objectives')
+    .option('--status <status>', 'filter by status')
+    .option('--team <id>', 'filter by team ID')
+    .option('--limit <n>', 'max results', '50')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = { limit: options.limit };
+      if (options.status) query.status = options.status;
+      if (options.team) query.team_id = options.team;
+      const data = await client.get(resolveEndpoint('objectives.list').path, { service: resolveEndpoint('objectives.list').service, query });
+      formatOutput({
+        columns: ['id', 'title', 'status', 'team_id', 'created_at'],
+        headers: ['ID', 'Title', 'Status', 'Team', 'Created'],
+        rows: data.objectives || data,
+      }, { format: program.opts().output });
+    });
+
+  objective
+    .command('get')
+    .description('Get objective details (tasks, checkpoints, DAG)')
+    .argument('<id>', 'objective ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const data = await client.get(resolveEndpoint('objectives.get', { id }).path, { service: resolveEndpoint('objectives.get', { id }).service });
+      formatDetail(data, { format: program.opts().output, title: data.title });
+    });
+
+  objective
+    .command('start')
+    .description('Start an objective (decompose into tasks)')
+    .argument('<id>', 'objective ID')
+    .option('--skip-checkpoint', 'bypass pre-start approval checkpoint')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const body = {};
+      if (options.skipCheckpoint) body.skip_checkpoint = true;
+      const data = await client.post(resolveEndpoint('objectives.start', { id }).path, { service: resolveEndpoint('objectives.start', { id }).service, body });
+      printSuccess(`Objective ${id}: ${data.status}${data.message ? ` — ${data.message}` : ''}`);
+    });
+
+  objective
+    .command('approve')
+    .description('Approve a decomposed objective\'s plan (starts execution)')
+    .argument('<id>', 'objective ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const data = await client.post(resolveEndpoint('objectives.approve-plan', { id }).path, { service: resolveEndpoint('objectives.approve-plan', { id }).service });
+      printSuccess(`Objective ${id}: ${data.status}${data.message ? ` — ${data.message}` : ''}`);
+    });
+
+  objective
+    .command('checkpoints')
+    .description('List pending HITL checkpoints across the org (approval queue)')
+    .option('--include-reviewed', 'include checkpoints that have already been reviewed')
+    .option('--limit <n>', 'max results', '100')
+    .action(async (options) => {
+      auth.requireAuth();
+      const query = { limit: options.limit };
+      if (options.includeReviewed) query.include_reviewed = 'true';
+      const data = await client.get(resolveEndpoint('objectives.checkpoints-pending').path, { service: resolveEndpoint('objectives.checkpoints-pending').service, query });
+      const rows = (data.checkpoints || data || []).map((cp) => ({
+        id: cp.id,
+        objective_title: cp.objectiveTitle,
+        checkpoint_type: cp.checkpointType,
+        age: relativeTime(cp.createdAt),
+        title: cp.title,
+      }));
+      formatOutput({
+        columns: ['id', 'objective_title', 'checkpoint_type', 'age', 'title'],
+        headers: ['Checkpoint', 'Objective', 'Type', 'Age', 'Title'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No pending checkpoints.' });
+    });
+
+  objective
+    .command('approve-checkpoint')
+    .description('Approve one HITL checkpoint (not the DAG plan, see `approve`)')
+    .argument('<objectiveId>', 'objective ID')
+    .argument('<checkpointId>', 'checkpoint ID')
+    .option('--notes <text>', 'review notes recorded against the decision')
+    .action(async (objectiveId, checkpointId, options) => {
+      auth.requireAuth();
+      const body = {};
+      if (options.notes) body.notes = options.notes;
+      const params = { id: objectiveId, checkpointId };
+      const data = await client.post(resolveEndpoint('objectives.checkpoint-approve', params).path, { service: resolveEndpoint('objectives.checkpoint-approve', params).service, body });
+      printSuccess(`Checkpoint ${checkpointId}: ${data.status}${data.objective_status ? ` (objective ${data.objective_status})` : ''}`);
+    });
+
+  objective
+    .command('deny-checkpoint')
+    .description('Reject one HITL checkpoint (not the DAG plan, see `approve`)')
+    .argument('<objectiveId>', 'objective ID')
+    .argument('<checkpointId>', 'checkpoint ID')
+    .option('--notes <text>', 'review notes recorded against the decision')
+    .action(async (objectiveId, checkpointId, options) => {
+      auth.requireAuth();
+      const body = {};
+      if (options.notes) body.notes = options.notes;
+      const params = { id: objectiveId, checkpointId };
+      const data = await client.post(resolveEndpoint('objectives.checkpoint-reject', params).path, { service: resolveEndpoint('objectives.checkpoint-reject', params).service, body });
+      printSuccess(`Checkpoint ${checkpointId}: ${data.status}${data.objective_status ? ` (objective ${data.objective_status})` : ''}`);
+    });
+
+  objective
+    .command('halt')
+    .description('Halt a running QLoop loop ON DEMAND (unconditional human stop; no pending gate needed). Fires the same signed-kill as a gate deny.')
+    .argument('<objectiveId>', 'loop objective ID')
+    .option('--notes <text>', 'reason recorded against the halt')
+    .action(async (objectiveId, options) => {
+      auth.requireAuth();
+      const body = {};
+      if (options.notes) body.notes = options.notes;
+      const params = { id: objectiveId };
+      const data = await client.post(resolveEndpoint('objectives.halt', params).path, { service: resolveEndpoint('objectives.halt', params).service, body });
+      if (data.status === 'halted') {
+        printSuccess(`Loop ${objectiveId} halted (interrupted=${data.interrupted}, objective ${data.objective_status})`);
+      } else {
+        printSuccess(`Loop ${objectiveId}: ${data.status}${data.reason ? ` (${data.reason})` : ''}`);
+      }
+    });
+}