quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/objective.js

@@ -0,0 +1,240 @@
+/**
+ * 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('cancel')
+    .description('Cancel an objective (pending ones included, e.g. proof leftovers that never started); its open tasks are cancelled too. For a RUNNING loop prefer `halt`, which also kills the live session.')
+    .argument('<objectiveId>', 'objective ID')
+    .action(async (objectiveId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('objectives.cancel', { id: objectiveId });
+      const data = await client.delete(ep.path, { service: ep.service });
+      printSuccess(`Objective ${objectiveId}: ${data?.status || 'cancelled'}`);
+    });
+
+  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})` : ''}`);
+      }
+    });
+}

package/lib/commands/offload.js

@@ -0,0 +1,89 @@
+/**
+ * `quox offload` : run a heavy command on a pool worker VM and behave like running it locally.
+ *
+ *   quox offload [--dir <path>] [--fresh] [--keep] [--cores N --memory-gb N --disk-gb N] -- <command...>
+ *   quox offload status
+ *   quox offload release
+ *
+ * Engine: lib/core/offload.js. The worker is leased through the human pool REST API
+ * (same as `quox vm pool lease`) with a dedicated key at ~/.config/quox/offload_ed25519.
+ */
+
+import path from 'node:path';
+import { printInfo } from '../core/output.js';
+import { makePoolRest } from '../core/vm.js';
+import { OffloadError, realDeps, runOffload, releaseWorker, workerStatus, gitToplevel, WORKER_NAME_RE } from '../core/offload.js';
+
+export function registerOffloadCommands(program, ctx, { deps: injected } = {}) {
+  const { client, auth } = ctx;
+  const json = () => program.opts().output === 'json';
+  const base = () => injected || realDeps({ rest: makePoolRest({ client }) });
+  // --worker <name> / QUOX_OFFLOAD_WORKER: your own worker (state, lease, size), not the box's shared one.
+  const mk = (options = {}) => {
+    const d = base();
+    const name = options.worker ?? d.env?.QUOX_OFFLOAD_WORKER;
+    if (name !== undefined && name !== '' && !WORKER_NAME_RE.test(String(name))) {
+      throw new OffloadError(`worker name must be lowercase letters, digits and dashes (up to 32), got ${JSON.stringify(name)}`);
+    }
+    return name ? Object.assign(Object.create(Object.getPrototypeOf(d)), d, { worker: String(name) }) : d;
+  };
+  const WORKER_HELP = 'use your own named worker (its own lease and size) instead of the shared one; or set QUOX_OFFLOAD_WORKER';
+
+  const off = program
+    .command('offload')
+    .description('Run a heavy command on a pool worker VM (synced dir, cached npm ci, live output, same exit code)')
+    .argument('[command...]', 'command to run remotely (put it after --)')
+    .option('--dir <path>', 'directory to sync (default: git toplevel of the current directory)')
+    .option('--fresh', 'release the current worker, lease a new one and reinstall dependencies')
+    .option('--keep', 'leave the worker leased for reuse (the default; kept for compatibility)')
+    .option('--cores <n>', 'vCPU cores for a newly leased worker')
+    .option('--memory-gb <n>', 'memory in GB for a newly leased worker')
+    .option('--disk-gb <n>', 'disk in GB for a newly leased worker')
+    .option('--worker <name>', WORKER_HELP)
+    .option('--docker', 'also give the worker Docker (user hyp in the docker group) and build the quox-sandbox images from the synced repo when they are missing or changed')
+    .allowExcessArguments(true)
+    .action(async (command, options) => {
+      auth.requireAuth();
+      const cwd = process.cwd();
+      const dir = path.resolve(options.dir || gitToplevel(cwd));
+      try {
+        const code = await runOffload(mk(options), {
+          dir, cwd, command, fresh: !!options.fresh, docker: !!options.docker,
+          cores: options.cores, memoryGb: options.memoryGb, diskGb: options.diskGb,
+        });
+        process.exitCode = code;
+      } catch (e) {
+        if (!(e instanceof OffloadError)) throw e;
+        process.stderr.write(`offload: ${e.message}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  off.command('status')
+    .description('Show your offload worker: vmid, ip, lease expiry, synced dirs')
+    .option('--worker <name>', WORKER_HELP)
+    .action(async (options) => {
+      auth.requireAuth();
+      const s = await workerStatus(mk(options));
+      if (json()) { console.log(JSON.stringify(s, null, 2)); return; }
+      if (!s.worker) { printInfo('no offload worker leased (it is leased on the next `quox offload -- <command>`)'); return; }
+      const w = s.worker;
+      console.log(`worker ${w.vmid}  ${w.ip || '?'}  ${w.state}  lessee ${w.lessee}  lease expires ${w.lease_expires_at || '?'}`);
+      for (const d of s.dirs) console.log(`  synced ${d.local} -> ${d.remote}  ${d.synced_at || ''}`);
+    });
+
+  off.command('release')
+    .description('Release (destroy) your offload worker via the pool')
+    .option('--worker <name>', WORKER_HELP)
+    .action(async (options) => {
+      auth.requireAuth();
+      try {
+        const vmid = await releaseWorker(mk(options));
+        if (json()) console.log(JSON.stringify({ released: vmid }));
+        else printInfo(vmid ? `released worker ${vmid}` : 'no offload worker to release');
+      } catch (e) {
+        process.stderr.write(`offload: release failed: ${e.message}\n`);
+        process.exitCode = 1;
+      }
+    });
+}

package/lib/commands/onboard.js

@@ -0,0 +1,329 @@
+/**
+ * `quox onboard <host>`: guided, idempotent, resumable tenant-onboarding
+ * wizard.
+ *
+ * This is NET-NEW GLUE over verbs that already exist (dev doctor, org create,
+ * plan roadmap create, engagement create/target/verify/gripe-target/schedule,
+ * vault list). It does NOT reimplement any of their logic: every REST call
+ * goes through ctx.client + resolveEndpoint, exactly as the individual verbs
+ * do. The wizard's only job is to run the mechanical steps in the right order,
+ * skip anything already done, and STOP cleanly at the two human-auth gates
+ * (dev-enable + profile-verify, and the GitHub PAT) with the exact copy-paste
+ * command the operator must run before re-running the wizard.
+ *
+ * Design rules baked in here:
+ *   - Idempotent: every step CHECKs before it acts, so a second run creates no
+ *     duplicates and simply resumes at the first incomplete step.
+ *   - Honest gates: a gated step is never reported as done. It prints a WAITING
+ *     banner and the wizard returns (exit 0, since a gate is a pause, not an error).
+ *   - Secret-free: the GitHub PAT is instruct-and-stop in v1. The token never
+ *     enters this process; the operator adds it with `quox vault create
+ *     --credentials-stdin` and re-runs.
+ */
+
+import { resolveEndpoint } from '../api/endpoints.js';
+import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
+
+// ── status line markers ────────────────────────────────────────────────────
+// One line per step. [ok] already there, [+] created/changed, [wait] a human
+// gate blocks progress. Kept as plain console.log (not the chalk helpers) so
+// the markers are trivially assertable in tests and scannable in a wall of
+// tool output.
+function ok(msg) { console.log(`  [ok] ${msg}`); }
+function created(msg) { console.log(`  [+] ${msg}`); }
+function waiting(msg) { console.log(`  [wait] needs you: ${msg}`); }
+
+// ── small pure helpers (exported for unit tests) ───────────────────────────
+
+/** Slug for a display name: lowercase, non-alphanumeric collapsed to '-'. */
+export function slugify(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    || 'tenant';
+}
+
+/**
+ * Infer an engagement target type from its value.
+ *   - an ipv4 or ipv4/cidr        -> 'cidr'
+ *   - a scheme://... or host:port -> 'url'
+ *   - a bare hostname             -> 'domain'
+ * Default for a bare IP is 'cidr' (the engagement scope model treats a single
+ * host as a /32 cidr target).
+ */
+export function inferTargetType(value) {
+  const v = String(value || '').trim();
+  // ipv4 with optional /nn suffix
+  if (/^\d{1,3}(\.\d{1,3}){3}(\/\d{1,2})?$/.test(v)) return 'cidr';
+  // explicit scheme, or a host:port pair
+  if (/:\/\//.test(v) || /^[^\s/]+:\d+$/.test(v)) return 'url';
+  return 'domain';
+}
+
+/** curl install command for a host that is not yet a fleet-enrolled dev server. */
+export function buildOnboardInstallCommand(collectorBase, host) {
+  const base = String(collectorBase || '').replace(/\/+$/, '');
+  // REL-423: fail loud, never `curl | sudo bash` (that pipe reports success when the download fails).
+  return `( f=$(mktemp) && trap 'rm -f "$f"' EXIT && curl -fsSL ${base}/install -o "$f" && sudo bash "$f" --host-id ${host} )`;
+}
+
+// ── the wizard ──────────────────────────────────────────────────────────────
+
+/**
+ * Run the onboarding orchestration. Returns { status: 'COMPLETE' | 'WAITING' }.
+ * Exported so it can be unit-tested directly with an injected fake client, and
+ * so a caller can branch on the outcome.
+ */
+export async function runOnboard(host, options, ctx) {
+  const { client, auth, config } = ctx;
+  auth.requireAuth();
+
+  const name = options.name;
+  const targetValue = options.target || host;
+  const envTier = options.environmentTier || 'dev';
+  const cron = options.scheduleCron || '0 2 * * 3';
+  const tool = options.tool || 'vuln_scan';
+  const slug = slugify(name);
+
+  printEvent(glyphLine('quox', `onboarding ${host}`));
+
+  // ── Step 1: AGENT + DEV-ENABLE gate ──────────────────────────────────────
+  // Read real registry state; never infer readiness from an enable having
+  // returned 200. Not enrolled -> install. Enrolled but not dev-enabled or not
+  // profile_verified -> the enable/seam-key gate.
+  const orgIdForDev = auth.getOrgId(ctx.program?.opts?.().org);
+  const serversEp = resolveEndpoint('v1.dev.servers.list');
+  const serversResp = await client.get(serversEp.path, {
+    service: serversEp.service,
+    query: orgIdForDev ? { org_id: orgIdForDev } : {},
+  });
+  const servers = Array.isArray(serversResp?.servers) ? serversResp.servers : [];
+  const server = servers.find((s) => s.host_id === host);
+
+  if (!server) {
+    const collectorBase = config?.getServiceUrl ? config.getServiceUrl('collector') : '<collector-url>';
+    waiting(`${host} is not a fleet-enrolled dev server. Install the agent, then re-run:`);
+    console.log(`      ${buildOnboardInstallCommand(collectorBase, host)}`);
+    return stop(host);
+  }
+
+  const enabledCaps = Array.isArray(server.enabled_capabilities) ? server.enabled_capabilities : [];
+  if (!server.profile_verified || enabledCaps.length === 0) {
+    const why = !server.profile_verified ? 'profile not verified' : 'no capabilities enabled';
+    waiting(`${host} is enrolled but not ready (${why}). Run (as an owner/admin):`);
+    console.log(`      quox dev enable ${host}`);
+    console.log('      profile_verified needs the seam key plus an agent restart.');
+    console.log(`      Confirm with: quox dev doctor ${host}`);
+    return stop(host);
+  }
+  ok(`${host} is a dev-enabled, profile-verified dev server`);
+
+  // ── Step 2: ORG ──────────────────────────────────────────────────────────
+  const orgsEp = resolveEndpoint('orgs.list');
+  const orgsResp = await client.get(orgsEp.path, { service: orgsEp.service });
+  const orgs = orgsResp?.orgs || orgsResp?.organizations || orgsResp || [];
+  let org = (Array.isArray(orgs) ? orgs : []).find(
+    (o) => o.name === name || o.slug === slug || o.id === name,
+  );
+  let orgId;
+  if (org) {
+    orgId = org.id;
+    ok(`org "${name}" exists (${orgId})`);
+  } else {
+    const createEp = resolveEndpoint('orgs.create');
+    const createResp = await client.post(createEp.path, {
+      service: createEp.service,
+      body: { name, slug },
+    });
+    org = createResp?.organization || createResp?.org || createResp;
+    orgId = org.id;
+    created(`org "${name}" (${orgId})`);
+  }
+
+  // ── Step 3: ROADMAP ───────────────────────────────────────────────────────
+  const roadmapId = slug;
+  const roadmapsEp = resolveEndpoint('quoxplan.roadmaps.list');
+  const roadmapsResp = await client.get(roadmapsEp.path, { service: roadmapsEp.service });
+  const roadmaps = roadmapsResp?.roadmaps || [];
+  const existingRoadmap = roadmaps.find((r) => r.id === roadmapId || r.org_id === orgId);
+  if (existingRoadmap) {
+    ok(`roadmap "${existingRoadmap.id}" exists for this tenant`);
+  } else {
+    const rmCreateEp = resolveEndpoint('quoxplan.roadmaps.create');
+    await client.post(rmCreateEp.path, {
+      service: rmCreateEp.service,
+      body: { org_id: orgId, id: roadmapId, name: `${name} delivery`, actor: 'quox-cli' },
+    });
+    created(`roadmap "${roadmapId}" for org ${orgId}`);
+  }
+
+  // ── Step 4: ENGAGEMENT ────────────────────────────────────────────────────
+  const engagementName = `${name} security`;
+  const engListEp = resolveEndpoint('engagement.list');
+  const engListResp = await client.get(engListEp.path, { service: engListEp.service });
+  const engagements = engListResp?.engagements || [];
+  let engagement = engagements.find((e) => e.name === engagementName);
+  let engagementId;
+  if (engagement) {
+    engagementId = engagement.id;
+    ok(`engagement "${engagementName}" exists (${engagementId})`);
+  } else {
+    const engCreateEp = resolveEndpoint('engagement.create');
+    const engResp = await client.post(engCreateEp.path, {
+      service: engCreateEp.service,
+      body: { name: engagementName, environment_tier: envTier, risk_ceiling: 'safe_active' },
+    });
+    engagement = engResp.engagement;
+    engagementId = engagement.id;
+    created(`engagement "${engagementName}" (${engagementId})`);
+  }
+
+  // ── Step 5: TARGET ────────────────────────────────────────────────────────
+  const engGetEp = resolveEndpoint('engagement.get', { id: engagementId });
+  const engDetail = await client.get(engGetEp.path, { service: engGetEp.service });
+  const currentEngagement = engDetail?.engagement || engagement;
+  const targets = Array.isArray(engDetail?.targets) ? engDetail.targets : [];
+  let target = targets.find((t) => t.value === targetValue);
+  let targetVerified = false;
+
+  if (!target) {
+    const type = inferTargetType(targetValue);
+    const addEp = resolveEndpoint('engagement.target.create', { id: engagementId });
+    const addResp = await client.post(addEp.path, {
+      service: addEp.service,
+      body: { type, value: targetValue, verification_method: 'quoxagent_install' },
+    });
+    target = addResp.target;
+    created(`target ${targetValue} (${type}) added`);
+    const verEp = resolveEndpoint('engagement.target.verify', { id: engagementId, targetId: target.id });
+    const verResp = await client.post(verEp.path, { service: verEp.service, body: {} });
+    targetVerified = verResp?.target?.verification_status === 'verified';
+    if (targetVerified) created(`target ${targetValue} verified`);
+    else waiting(`target ${targetValue} did not verify (status: ${verResp?.target?.verification_status || 'unknown'})`);
+  } else if (target.verification_status === 'verified') {
+    targetVerified = true;
+    ok(`target ${targetValue} already verified`);
+  } else {
+    const verEp = resolveEndpoint('engagement.target.verify', { id: engagementId, targetId: target.id });
+    const verResp = await client.post(verEp.path, { service: verEp.service, body: {} });
+    targetVerified = verResp?.target?.verification_status === 'verified';
+    if (targetVerified) created(`target ${targetValue} verified`);
+    else waiting(`target ${targetValue} did not verify (status: ${verResp?.target?.verification_status || 'unknown'})`);
+  }
+
+  // ── Step 6: GITHUB PAT gate ───────────────────────────────────────────────
+  // The repo is only meaningful if a customer GitHub connector token exists to
+  // file into it. Check the org vault for a github credential; if absent, STOP
+  // with the exact instruct-and-stop command (secret via --credentials-stdin,
+  // NEVER argv), and do NOT touch gripe target or schedule.
+  const repo = options.repo;
+  if (repo) {
+    const vaultEp = resolveEndpoint('vault.list', { orgId });
+    const vaultResp = await client.get(vaultEp.path, {
+      service: vaultEp.service,
+      query: { type: 'github' },
+    });
+    const creds = vaultResp?.credentials || vaultResp || [];
+    const githubCred = (Array.isArray(creds) ? creds : []).find((c) => c.integration_type === 'github');
+    if (!githubCred) {
+      waiting(`no GitHub connector credential in org ${orgId}. Add the fine-grained PAT, then re-run:`);
+      console.log(`      printf '%s' '<PAT>' | quox vault create --org ${orgId} --type github --label "${name} github" --credentials-stdin`);
+      console.log(`      (the JSON on stdin is {"token":"<PAT>"}; scope the PAT to ${repo} with Issues read/write)`);
+      return stop(host, { orgId, roadmapId, engagementId, targetValue, targetVerified });
+    }
+    ok(`GitHub connector credential present in org ${orgId}`);
+
+    // ── Step 7: GRIPE TARGET ────────────────────────────────────────────────
+    const wantRepo = repo;
+    const wantConnector = orgId;
+    if (currentEngagement.gripe_repo === wantRepo && currentEngagement.gripe_connector_org_id === wantConnector) {
+      ok(`gripe target already ${wantRepo} via org ${wantConnector}`);
+    } else {
+      const gtEp = resolveEndpoint('engagement.gripe_target.set', { id: engagementId });
+      await client.patch(gtEp.path, {
+        service: gtEp.service,
+        body: { gripe_repo: wantRepo, gripe_connector_org_id: wantConnector },
+      });
+      created(`gripe target -> ${wantRepo} via org ${wantConnector}`);
+    }
+  } else {
+    ok('no --repo given; skipping GitHub connector and gripe target');
+  }
+
+  // ── Step 8: SCHEDULE ──────────────────────────────────────────────────────
+  const schedListEp = resolveEndpoint('engagement.schedule.list', { id: engagementId });
+  const schedResp = await client.get(schedListEp.path, { service: schedListEp.service });
+  const schedules = Array.isArray(schedResp?.schedules) ? schedResp.schedules : [];
+  let schedule = schedules.find((s) => s.target_value === targetValue && s.tool === tool);
+  if (schedule) {
+    ok(`schedule for ${tool} on ${targetValue} exists (next: ${schedule.next_run_at || 'n/a'})`);
+  } else {
+    const schedCreateEp = resolveEndpoint('engagement.schedule.create', { id: engagementId });
+    const createResp = await client.post(schedCreateEp.path, {
+      service: schedCreateEp.service,
+      body: { target_value: targetValue, tool, schedule_kind: 'cron', cron_expression: cron },
+    });
+    schedule = createResp.schedule;
+    created(`schedule ${tool} on ${targetValue} @ "${cron}" (next: ${schedule?.next_run_at || 'n/a'})`);
+  }
+
+  // ── Step 9: SUMMARY ───────────────────────────────────────────────────────
+  // Every human gate that could stop the wizard has already returned by here,
+  // so the only thing left that can hold onboarding open is an unverified
+  // target (verification is best-effort and can legitimately not land yet).
+  const complete = targetVerified;
+  printSummary({
+    status: complete ? 'COMPLETE' : 'WAITING',
+    host,
+    orgId,
+    roadmapId,
+    engagementId,
+    targetValue,
+    targetVerified,
+    gripeRepo: repo || null,
+    schedule: schedule ? { cron, next: schedule.next_run_at } : null,
+    remainingGate: targetVerified ? null : 'target not verified',
+  });
+  return { status: complete ? 'COMPLETE' : 'WAITING' };
+}
+
+/** Shared gate-stop: print the WAITING banner + resume hint, return WAITING. */
+function stop(host, partial) {
+  console.log('');
+  console.log('  ===== WAITING on a human gate =====');
+  console.log(`  Do the step above, then re-run: quox onboard ${host} ... to continue.`);
+  if (partial) {
+    console.log(`  Progress so far: org ${partial.orgId}, roadmap ${partial.roadmapId}, engagement ${partial.engagementId}, target ${partial.targetValue} (verified: ${partial.targetVerified}).`);
+  }
+  return { status: 'WAITING' };
+}
+
+function printSummary(s) {
+  console.log('');
+  console.log(`  ===== onboarding ${s.status} =====`);
+  console.log(`  host:        ${s.host}`);
+  console.log(`  org:         ${s.orgId}`);
+  console.log(`  roadmap:     ${s.roadmapId}`);
+  console.log(`  engagement:  ${s.engagementId}`);
+  console.log(`  target:      ${s.targetValue} (verified: ${s.targetVerified})`);
+  console.log(`  gripe repo:  ${s.gripeRepo || '(none)'}`);
+  if (s.schedule) console.log(`  schedule:    "${s.schedule.cron}" (next: ${s.schedule.next || 'n/a'})`);
+  if (s.remainingGate) console.log(`  remaining:   ${s.remainingGate}`);
+}
+
+export function registerOnboardCommands(program, ctx) {
+  program
+    .command('onboard <host>')
+    .description('Guided, idempotent, resumable wizard to onboard a customer site as a governed Quox tenant')
+    .requiredOption('--name <customerName>', 'the org display name')
+    .option('--repo <owner/name>', 'the customer GitHub repo for auto-filed security issues')
+    .option('--target <hostOrIp>', 'the scan target (defaults to <host>)')
+    .option('--environment-tier <tier>', 'dev | staging | production', 'dev')
+    .option('--schedule-cron <expr>', 'cron cadence for the recurring scan', '0 2 * * 3')
+    .option('--tool <name>', 'capability tool to schedule', 'vuln_scan')
+    .option('--yes', 'run non-interactively: do every automatable step and print gate instructions without pausing')
+    .action(async (host, options) => {
+      await runOnboard(host, options, ctx);
+    });
+}