quoxcli 0.2.0 → 0.4.0

package/lib/commands/motion.js

@@ -5,8 +5,8 @@
 export function registerMotionCommand(program) {
   program
     .command('motion')
-    .description('Play the Quox motion gallery: the Q intro, portal, particle, the Dragon\'s Eye, the status Q, ring and reveals (no server needed)')
-    .argument('[scenes...]', 'only these: orbit portal particle eye hello perpetual ring fx')
+    .description('Play the Quox motion gallery: the Q intro, portal, particle, the Dragon\'s Eye, the status Q, ring, reveals and the living dragon (no server needed)')
+    .argument('[scenes...]', 'only these: orbit portal particle eye hello perpetual ring fx dragon dragon-fire dragon-moods')
     .option('--narrow', 'use the 40-column layout (the compact Q)')
     .option('--slow', 'play three times slower')
     .option('--mono', 'no colour (also honoured: NO_COLOR)')

package/lib/commands/nucleus.js

@@ -23,6 +23,36 @@ import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { resolveOrgId } from './helpers.js';
 
+// codebase_query's schema (collector agentTools.js): question (required),
+// target, max_snippets. quox#836: the CLI used to send query/repo/limit,
+// every call failed "Missing required parameter: question", and the failure
+// printed as "0 hits".
+export function buildNucleusInput(question, options = {}) {
+  const input = { question };
+  if (options.target) input.target = options.target;
+  const n = parseInt(options.limit, 10);
+  if (n > 0) input.max_snippets = n;
+  return input;
+}
+
+// The tool result shape varies by engine version, so normalise rather than
+// assuming: an unexpected shape must still print SOMETHING true. An error
+// body is an error, never an empty result.
+export function readNucleusResult(data) {
+  if (data && data.success === false) return { error: data.error || data.message || 'tool call failed' };
+  // The collector's codebase_query returns agent-friendly text with
+  // file:line citations ({ success, output, resultCount }), not an array.
+  if (typeof data?.output === 'string') return { text: data.output, count: data.resultCount ?? null, result: data };
+  const result = data && (data.result || data.output || data);
+  if (result && result.success === false) return { error: result.error || result.message || 'tool call failed' };
+  if (typeof result?.output === 'string') return { text: result.output, count: result.resultCount ?? null, result };
+  const results = Array.isArray(result?.results) ? result.results
+    : Array.isArray(result?.snippets) ? result.snippets
+    : Array.isArray(result) ? result
+    : null;
+  return { results, result };
+}
+
 export function registerNucleusCommands(program, { client, auth }) {
   const nucleus = program
     .command('nucleus')
@@ -43,33 +73,34 @@ export function registerNucleusCommands(program, { client, auth }) {
       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 body = { tool_name: 'codebase_query', input: buildNucleusInput(question, options) };
       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;
+      const { error, results, result, text, count } = readNucleusResult(data);
 
       if (program.opts().output === 'json') {
         formatDetail(data, { format: 'json' });
         return;
       }
 
+      if (error) {
+        printEvent(glyphLine('repobrain', `query "${question}"`, { result: 'failed', ms }));
+        printWarning(`The query failed: ${error}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (typeof text === 'string') {
+        const hits = count === null ? 'answered' : `${count} hits`;
+        printEvent(glyphLine('repobrain', `query "${question}"`, { result: count === 0 ? '0 hits' : hits, ms }));
+        console.log('');
+        console.log(text.split('\n').map((l) => `  ${l}`).join('\n'));
+        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.');
@@ -85,7 +116,7 @@ export function registerNucleusCommands(program, { client, auth }) {
         const line = r.line || r.start_line || null;
         console.log('');
         console.log(`  ${loc}${line ? `:${line}` : ''}`);
-        const snippet = r.snippet || r.content || r.text || '';
+        const snippet = r.snippet || r.code || r.content || r.text || '';
         for (const l of String(snippet).split('\n').slice(0, 20)) console.log(`    ${l}`);
       }
     });

package/lib/commands/objective.js

@@ -12,9 +12,10 @@
  *                        live loop gate: budget, risk, interval).
  */
 
-import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/output.js';
 import { parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxUserError } from '../core/errors.js';
 
 /**
  * Format a timestamp as a short relative-time string ("5m ago").
@@ -75,6 +76,13 @@ export function registerObjectiveCommands(program, ctx) {
     .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')
+    .option('--observe-every <n>', 'loop mode: emit a status line every N turns while it runs (watch with `quox loop watch <id>`)')
+    .option('--observe-milestones', 'loop mode: lift MILESTONE: lines from the loop output into headline updates')
+    .option('--until <text>', 'loop mode: the done criterion in plain words. The loop runs turn after turn until the model ends a turn with "DONE: <evidence>" (or --max-iterations / --max-duration-ms stops it)')
+    .option('--every-seconds <n>', 'loop mode: the runner waits N seconds (30-3600) between turns; the model is never asked to sleep')
+    .option('--workspace <name>', 'loop mode: name the durable workspace dir, so a follow-up loop can work in the same files (default: one per loop)')
+    .option('--done-file <path>', 'loop mode: DONE only counts once this file exists in the loop workspace; the runner checks it itself (repeatable)', (v, prev = []) => prev.concat(v))
+    .option('--done-command <cmd>', 'loop mode: DONE only counts once this command exits 0 in the loop workspace; must be one the loop scope lets it run (repeatable)', (v, prev = []) => prev.concat(v))
     .action(async (goal, options) => {
       auth.requireAuth();
       const body = { title: goal };
@@ -98,6 +106,28 @@ export function registerObjectiveCommands(program, ctx) {
         if (scope.length > 0) body.capability_scope = scope;
       }
       if (options.systemPrompt) body.system_prompt = options.systemPrompt;
+      if (options.until) body.until = options.until;
+      if (options.everySeconds !== undefined) {
+        const n = Number(options.everySeconds);
+        if (!Number.isInteger(n) || n < 30 || n > 3600) throw new QuoxUserError('--every-seconds needs a whole number of seconds between 30 and 3600.');
+        body.every_seconds = n;
+      }
+      if (options.workspace) body.workspace = options.workspace;
+      const doneChecks = [
+        ...(options.doneFile || []).map((path) => ({ kind: 'file_exists', path })),
+        ...(options.doneCommand || []).map((command) => ({ kind: 'command_ok', command })),
+      ];
+      if (doneChecks.length) body.done_check = doneChecks;
+      if (options.observeEvery !== undefined || options.observeMilestones) {
+        const observe = {};
+        if (options.observeEvery !== undefined) {
+          const n = Number(options.observeEvery);
+          if (!Number.isInteger(n) || n < 1) throw new QuoxUserError('--observe-every needs a whole number of turns (1 or more).');
+          observe.every_turns = n;
+        }
+        if (options.observeMilestones) observe.milestones = true;
+        body.observe = observe;
+      }
 
       const data = await client.post(resolveEndpoint('objectives.create').path, { service: resolveEndpoint('objectives.create').service, body });
       printSuccess(`Objective created: ${data.id}`);
@@ -155,6 +185,17 @@ export function registerObjectiveCommands(program, ctx) {
       printSuccess(`Objective ${id}: ${data.status}${data.message ? ` — ${data.message}` : ''}`);
     });
 
+  objective
+    .command('retry')
+    .description('Retry a failed or partially completed objective: failed and skipped steps are reset and the plan comes back for approval')
+    .argument('<id>', 'objective ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('objectives.retry', { id });
+      const data = await client.post(ep.path, { service: ep.service });
+      printSuccess(`Objective ${id}: ${data.steps_reset ?? 0} step(s) reset, plan is back for approval. Run \`quox objective approve ${id}\` to run them again.`);
+    });
+
   objective
     .command('checkpoints')
     .description('List pending HITL checkpoints across the org (approval queue)')
@@ -191,6 +232,12 @@ export function registerObjectiveCommands(program, ctx) {
       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 });
+      // LOOPQ-HALT: "approved" is not "running". When the server says the loop did not start, say so in words.
+      if (data.started === false) {
+        printWarning(`Checkpoint ${checkpointId}: ${data.status}, but the objective did NOT start (objective ${data.objective_status || 'pending'}).`);
+        if (data.hint) printWarning(data.hint);
+        return;
+      }
       printSuccess(`Checkpoint ${checkpointId}: ${data.status}${data.objective_status ? ` (objective ${data.objective_status})` : ''}`);
     });
 
@@ -209,6 +256,17 @@ export function registerObjectiveCommands(program, ctx) {
       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.')

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

@@ -64,7 +64,8 @@ export function inferTargetType(value) {
 /** 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(/\/+$/, '');
-  return `curl -sSL ${base}/install | sudo bash -s -- --host-id ${host}`;
+  // 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 ──────────────────────────────────────────────────────────────

package/lib/commands/org.js

@@ -3,9 +3,11 @@
  */
 
 import { QuoxError } from '../core/errors.js';
-import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/output.js';
+import { otherProfileUsers, listProcs } from '../core/profileUsers.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { numberedOrgLines, pickOrgByInput, sharedSwitchHint } from '../quoxon/orgSwitch.js';
 
 export function registerOrgCommands(program, ctx) {
   const { client, auth, config } = ctx;
@@ -89,9 +91,26 @@ export function registerOrgCommands(program, ctx) {
   org
     .command('switch')
     .description('Switch active organization context')
-    .argument('<orgId>', 'organization ID or slug')
-    .action(async (orgId) => {
+    .argument('[orgId]', 'organization ID, slug, or the number from the list (omit to pick from a numbered list)')
+    .action(async (orgIdArg) => {
       auth.requireAuth();
+      let orgId = orgIdArg;
+      if (!orgId || /^\d+$/.test(orgId)) {
+        const l = await client.get(resolveEndpoint('orgs.list').path, { service: resolveEndpoint('orgs.list').service });
+        const orgs = Array.isArray(l) ? l : (l?.organizations || l?.orgs || l?.data || []);
+        if (!orgs.length) throw new QuoxError('No organisations returned for this login.', 1);
+        if (!orgId) {
+          const curId = (() => { try { return auth.getOrgId(); } catch { return null; } })();
+          for (const line of numberedOrgLines(orgs, curId)) console.log(line);
+          if (!process.stdin.isTTY) throw new QuoxError('Pass a number, slug or ID: quox org switch <number>.', 1);
+          const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout });
+          try { orgId = await rl.question('Switch to which? (number, slug, or Enter to cancel) '); } finally { rl.close(); }
+          if (!orgId.trim()) { console.log('Not switched.'); return; }
+        }
+        const pick = pickOrgByInput(orgId, orgs);
+        if (pick.org) orgId = pick.org.id;
+        else if (/^\d+$/.test(orgId)) throw new QuoxError(`No org numbered ${orgId}. Run \`quox org switch\` to see the list.`, 1);
+      }
       // The server matches memberships by org ID only. Accept a slug (or exact name) by
       // resolving it against the caller's org list first; a 26-char ULID passes through.
       let targetId = orgId;
@@ -120,6 +139,14 @@ export function registerOrgCommands(program, ctx) {
       config.setAuth(authData);
 
       printSuccess(`Switched to ${data.org?.name || orgId}`);
+      // #1034: this changed the SHARED profile. Name the other live sessions that will follow it.
+      try {
+        const name = config.getActiveProfileName?.();
+        const others = name ? otherProfileUsers({ profile: name, defaultProfile: config._data?.activeProfile, procs: listProcs(), selfPids: [process.pid, process.ppid] }) : [];
+        if (others.length) {
+          printWarning(sharedSwitchHint({ name, pids: others.map(p => p.pid) }));
+        }
+      } catch { /* best effort: never fail the switch over the warning */ }
     });
 
   // Members subcommands

package/lib/commands/peek.js

@@ -0,0 +1,28 @@
+/**
+ * quox peek <id>
+ *
+ * Look up an id without knowing what it is: an AEE envelope, inbox (approval) item, objective, workflow
+ * run, WARD receipt or agent. The id's shape picks what to ask; every lookup is an existing read
+ * endpoint; a miss names each kind tried and what it answered. The TUI's /peek prints the same card.
+ */
+import { createPeekFetchers, peekId, peekLines } from '../core/peek.js';
+import { resolveOrgId } from './helpers.js';
+
+export function registerPeekCommand(program, ctx) {
+  const { client, auth } = ctx;
+  program
+    .command('peek')
+    .description('Look up an envelope, inbox item, objective, run, WARD receipt or agent by id (read only)')
+    .argument('<id>', 'the id, e.g. a ULID, a WARD entry UUID or an agent name')
+    .action(async (id) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const r = await peekId(id, createPeekFetchers({ client, orgId: () => orgId }));
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ id: r.id, shape: r.shape, kind: r.hit?.kind || null, data: r.hit?.data || null, also: r.also, tried: r.tried }, null, 2));
+      } else {
+        for (const l of peekLines(r)) console.log(l.text);
+      }
+      if (!r.hit) process.exitCode = 5; // not found (the inbox verbs use 5 for not_found too)
+    });
+}

package/lib/commands/plan.js

@@ -137,6 +137,23 @@ function renderRoadmapsList(roadmaps) {
   return lines;
 }
 
+function renderSearchResults(data) {
+  const results = data.results || [];
+  if (results.length === 0) return [chalk.dim(`  No streams match "${data.q}".`)];
+  const lines = [''];
+  for (const r of results) {
+    const g = statusGlyph(r.status);
+    const where = [...new Set((r.matches || []).map((m) => m.where))].join(', ');
+    const first = (r.matches || []).find((m) => m.snippet) || {};
+    lines.push(
+      `  ${g.color(g.glyph)} ${pad(truncate(r.id, ID_WIDTH), ID_WIDTH)} ${pad(truncate(r.name, NAME_WIDTH), NAME_WIDTH)} `
+      + `${pad(r.status, 15)} ${pad(where, 18)} ${chalk.dim(truncate(first.snippet || '', 60))}`
+    );
+  }
+  lines.push('', chalk.dim(`  ${results.length} stream${results.length === 1 ? '' : 's'} matched "${data.q}"`));
+  return lines;
+}
+
 function streamLine(s, { indent = 0, showReasons = false } = {}) {
   const prefix = indent > 0 ? '  '.repeat(indent) + '└ ' : '  ';
   const g = statusGlyph(s.status);
@@ -546,6 +563,27 @@ export function registerPlanCommands(program, ctx) {
       printSuccess(`Created roadmap ${created.id || options.id} for org ${orgId}`);
     });
 
+  // ── search ───────────────────────────────────────────────────────────
+
+  plan
+    .command('search <text...>')
+    .description('Search streams by text (id, name, notes, plan, phase titles)')
+    .option('--roadmap <id>', 'limit to one roadmap')
+    .option('--status <status>', `limit to one status (${VALID_STATUSES.join(', ')})`)
+    .action(async (textParts, options) => {
+      auth.requireAuth();
+      if (options.status && !VALID_STATUSES.includes(options.status)) {
+        throw new Error(`invalid --status "${options.status}" (expected ${VALID_STATUSES.join(', ')})`);
+      }
+      const query = { q: textParts.join(' ') };
+      if (options.roadmap) query.roadmap = options.roadmap;
+      if (options.status) query.status = options.status;
+      const ep = resolveEndpoint('quoxplan.search');
+      const data = await client.get(ep.path, { service: ep.service, query });
+      if (isJsonOutput(program)) return printJson(data);
+      console.log(renderSearchResults(data).join('\n'));
+    });
+
   // ── list ─────────────────────────────────────────────────────────────
 
   plan

package/lib/commands/plugin.js

@@ -2,10 +2,12 @@
  * Plugin commands: org-scoped plugin install registry (PD-1..PD-8)
  *
  * quox plugin list|get|install|update|uninstall|mine
+ * quox plugin enable <id>   (PLUGIN-IMG #1012: prebuilt private image, licence first)
  * quox plugin data list|get|set|delete
  * quox plugin secrets list|set|reveal|delete
  * quox plugin assign list|add|remove
  * quox plugin trusted-keys list|add|remove
+ * quox plugin revocations list|add|remove
  *
  * Backend: services/auth/routes/plugins.js, mounted org-scoped at
  * `/api/orgs/:orgId/...` (server.js). Install/update/uninstall and all
@@ -18,6 +20,9 @@ import { readFileSync } from 'node:fs';
 import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
 import { resolveOrgId, parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { enablePlugin, entitlementFrom } from '../server/pluginEnable.js';
+import { resolveInstall, readEnvKeys } from '../server/install.js';
+import { createSys } from '../server/sys.js';
 
 /** Read + JSON.parse a file, wrapping errors with the file path for context. */
 function readJsonFile(filePath, label) {
@@ -113,6 +118,56 @@ export function registerPluginCommands(program, ctx) {
       }, { title: `Licence: ${pluginId}` });
     });
 
+  // ── plugin enable (PLUGIN-IMG #1012) ────────────────────────────────────────
+  // Starts a licensed plugin from its prebuilt private image on this
+  // self-hosted install. Licence first: unlicensed means nothing runs.
+
+  plugin
+    .command('enable')
+    .description('Start a licensed plugin from its prebuilt image on this self-hosted install (QuoxPlan for now). Unlicensed: refused, nothing pulled.')
+    .argument('<pluginId>', 'plugin id, e.g. quoxplan')
+    .option('--dir <path>', 'the install directory (default: the one Getting started recorded)')
+    .action(async (pluginId, opts) => {
+      auth.requireAuth();
+      const deps = ctx.serverDeps || {};
+      const env = deps.env || process.env;
+      const sys = deps.sys || createSys();
+      const checkEntitlement = async (id) => {
+        const ep = resolveEndpoint('setup.licensing.entitlements.list');
+        const data = await client.get(ep.path, { service: ep.service });
+        return entitlementFrom(data, id);
+      };
+      // Licence before anything that touches the box: an unlicensed enable must not even look for the install.
+      let ent;
+      try { ent = await checkEntitlement(pluginId); } catch (err) { ent = err; }
+      const resolveFirst = !(ent instanceof Error) && ent && ent.entitled;
+      let install = null;
+      if (resolveFirst) {
+        const i = await resolveInstall({ dir: opts.dir, env, sys, journey: deps.journey });
+        if (i.error) { const e = new Error(i.error); e.exitCode = 2; throw e; }
+        install = i;
+      }
+      const tag = install ? (env.QUOX_IMAGE_TAG || readEnvKeys(install.repoDir, ['QUOX_IMAGE_TAG']).QUOX_IMAGE_TAG || '') : '';
+      const result = await enablePlugin({
+        pluginId,
+        checkEntitlement: async () => { if (ent instanceof Error) throw ent; return ent; },
+        install: install || { repoDir: '' },
+        sys,
+        tag,
+        ...(deps.getPullCredential ? { getPullCredential: deps.getPullCredential } : {}),
+        ...(deps.sleep ? { sleep: deps.sleep } : {}),
+        log: (l) => printInfo(l),
+      });
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ plugin: pluginId, ok: result.ok, stage: result.stage, message: result.message }, null, 2));
+      } else if (result.ok) {
+        printSuccess(result.message);
+      } else {
+        printWarning(result.message);
+      }
+      if (!result.ok) process.exitCode = result.stage === 'licence' ? 3 : 1;
+    });
+
   // ── plugin list ─────────────────────────────────────────────────────────────
 
   plugin
@@ -536,4 +591,59 @@ export function registerPluginCommands(program, ctx) {
       await client.delete(ep.path, reqOpts);
       printSuccess('Trusted key removed.');
     });
+
+  // ── plugin revocations (SDK-TEAM W5) ────────────────────────────────────────
+
+  const revocations = plugin
+    .command('revocations')
+    .description('Revoke a plugin signer key or one bundle digest for this org (admin only). A revoked plugin cannot be installed and stops loading on the next page load.');
+
+  revocations
+    .command('list')
+    .description('List revocations')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.revocations.list', { orgId });
+      const result = await client.get(ep.path, { service: ep.service });
+      const rows = result.revocations || result || [];
+      formatOutput({
+        columns: ['id', 'kind', 'value', 'reason', 'revoked_by', 'revoked_at'],
+        headers: ['ID', 'Kind', 'Value', 'Reason', 'Revoked By', 'Revoked'],
+        rows,
+      }, { format: program.opts().output, emptyMessage: 'No revocations.' });
+    });
+
+  revocations
+    .command('add')
+    .description('Revoke a signer key or a bundle digest')
+    .option('--signer-key <hex>', 'raw Ed25519 public key (64 hex), as in signature.json public_key_hex')
+    .option('--bundle-digest <hex>', 'sha256 of plugin.esm.js (64 hex), as shown by quox plugin list')
+    .option('--reason <text>', 'why (kept in the audit trail)')
+    .action(async (options) => {
+      auth.requireAuth();
+      if (!!options.signerKey === !!options.bundleDigest) {
+        throw new Error('Specify exactly one of --signer-key or --bundle-digest.');
+      }
+      const orgId = resolveOrgId(auth, program);
+      const body = options.signerKey
+        ? { kind: 'signer_key', value: options.signerKey, reason: options.reason }
+        : { kind: 'bundle_digest', value: options.bundleDigest, reason: options.reason };
+      const ep = resolveEndpoint('plugins.revocations.create', { orgId });
+      const result = await client.post(ep.path, { service: ep.service, body });
+      printSuccess('Revoked.');
+      formatDetail(result.revocation || result, { format: program.opts().output });
+    });
+
+  revocations
+    .command('remove')
+    .description('Lift a revocation')
+    .argument('<revocationId>', 'revocation ID')
+    .action(async (revocationId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('plugins.revocations.delete', { orgId, revocationId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess('Revocation lifted.');
+    });
 }