quoxcli 0.2.0 → 0.3.1

package/lib/commands/ask.js

@@ -0,0 +1,144 @@
+/**
+ * `quox ask`: a session puts a fork in front of a human through the Approvals inbox (one inbox item, kind decision).
+ * Who is asking, what, why, the options, the recommendation and the expiry travel with it, so ONE HITL session
+ * can answer for twenty terminals. Not an approval of an action: no step-up PIN unless --high-risk.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+import { readPresence, approvalPresenceFields } from './presence.js';
+import { toRepoRelative, LOOSENING_HINT } from '../core/repoPath.js';
+import { parseOptions, parseDuration, YN_OPTIONS, waitForDecision, EXIT_NO_ANSWER } from '../core/askDecision.js';
+
+function heldSlotFor(session) {
+  try {
+    const all = JSON.parse(readFileSync(join(homedir(), '.quox', 'held-slots.json'), 'utf8'));
+    const want = String(session || '').toLowerCase();
+    return Object.keys(all).find((k) => String(all[k]?.session || '').toLowerCase() === want) || null;
+  } catch { return null; }
+}
+
+export function registerAskCommands(program, { client, auth }) {
+  const err = (s) => process.stderr.write(`${s}\n`);
+
+  async function waitAndPrint(orgId, id, { timeoutSec = null } = {}) {
+    const r = await waitForDecision({
+      poll: (w) => { const ep = resolveEndpoint('inbox.decision.get', { orgId, id }); return client.get(ep.path, { service: ep.service, query: { wait: w }, timeout: (w + 15) * 1000, retries: 0 }); },
+      log: err,
+      maxWaitMs: timeoutSec != null ? timeoutSec * 1000 : null,
+    });
+    if (r.stdout) console.log(r.stdout);
+    process.exitCode = r.code;
+    return r;
+  }
+
+  const ask = program
+    .command('ask')
+    .description('Ask a human a question through the Approvals inbox: who asks, what, why, the options. Use this instead of asking in your own terminal')
+    .option('--session <name>', 'which session is asking (default: $QUOX_SESSION)')
+    .option('--title <text>', 'what you are asking, one line')
+    .option('--why <text>', 'a simple why: what the human needs to know to decide')
+    .option('--justify <text>', 'for a loosening (a check made easier to pass): why it is safe, in plain words; the card shows it on its JUSTIFY line and defaults to No without one')
+    .option('--options <list>', 'the choices: "a: Ship now|b: Wait for review|c: Drop it"')
+    .option('--yn', 'shorthand for a yes/no question (options y and n)')
+    .option('--default <key>', 'the option you would take if nobody answers (shown, never applied for you)')
+    .option('--recommend <key>', 'the option you recommend')
+    .option('--expires <dur>', 'how long it stays open: 30m, 2h, 1d (default 24h, max 30d)')
+    .option('--slot <name>', 'your slot, so the answer is also posted there (default: found from held slots)')
+    .option('--agent <name>', 'the agent asking, when it is an agent rather than a session')
+    .option('--high-risk', 'the answer needs the human step-up PIN')
+    .option('--wait', 'block until answered; prints the chosen option key (and any note) on stdout, exits 2 on expiry or deny')
+    .option('--timeout <dur>', 'with --wait: stop waiting after this long (the question stays open)')
+    .action((options) => fileAsk(options));
+
+  async function fileAsk(options) {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const session = options.session || process.env.QUOX_SESSION;
+      if (!session) throw new Error('say which session is asking: --session <NAME>');
+      if (!options.title) throw new Error('say what you are asking: --title "<what>"');
+      if (options.yn && options.options) throw new Error('use --yn or --options, not both');
+      if (!options.yn && !options.options) throw new Error('give the choices: --options "a: Ship now|b: Wait" (or --yn)');
+      // QUOXON 2026-10-17: a high-risk ask (a loosening, anything the owner must PIN) carries a plain justification
+      // 2026-10-19: three PIN approvals were wasted on loosening asks filed without --high-risk or with unusable paths
+      if (!options.highRisk && /^\s*approve\s+(?:loosening|test)/i.test(options.title)) { err(`A test-edit approval must go through the loosening verb, which sets --high-risk and repo-relative paths for you:\n  ${LOOSENING_HINT}`); process.exitCode = 2; return; }
+      if (options.highRisk && !String(options.justify || '').trim()) { err('High-risk asks need --justify "<2-3 plain lines the owner can judge>"'); process.exitCode = 2; return; }
+      const opts = options.yn ? YN_OPTIONS : parseOptions(options.options);
+      const body = {
+        session, title: options.title, why: options.why, options: opts,
+        ...(options.justify ? { justification: options.justify } : {}),
+        default: options.default, recommend: options.recommend,
+        ...(options.expires ? { expires_in_seconds: parseDuration(options.expires) } : {}),
+        high_risk: Boolean(options.highRisk),
+        slot: options.slot || heldSlotFor(session) || undefined,
+        profile: program.opts().profile || process.env.QUOX_PROFILE || undefined,
+        agent: options.agent,
+      };
+      const ep = resolveEndpoint('inbox.decision.create', { orgId });
+      const data = await client.post(ep.path, { service: ep.service, body });
+      // PRESENCE (owner 2026-10-16): say now whether the human is away, so this session can work on
+      // something else instead of waiting. The question is filed and queued exactly as before.
+      const presence = approvalPresenceFields(await readPresence(client, orgId));
+      const d = { ...data.decision, ...presence };
+      if (program.opts().output === 'json' && !options.wait) { console.log(JSON.stringify(d, null, 2)); return; }
+      err(`asked: ${d.id} (${session}: ${d.title}); it shows in /approvals${d.expires_at ? `, open until ${d.expires_at}` : ''}`);
+      if (presence.owner_away) err(`${presence.owner_away_notice}. Expect a wait: work on something else meanwhile.`);
+      if (!options.wait) { console.log(d.id); return; }
+      await waitAndPrint(orgId, d.id, { timeoutSec: options.timeout ? parseDuration(options.timeout) : null });
+  }
+
+  ask
+    .command('loosening')
+    .description('Ask a human to approve edits to test files (a check made easier to pass). Files a yes/no, high-risk (PIN) ask with repo-relative paths')
+    .option('--paths <files...>', 'every test file the commit edits (absolute, worktree or repo-relative: all are normalised)')
+    .option('--justify <text>', 'why it is safe, in plain words (required)')
+    .option('--why <text>', 'detail: the findings, before and after lines')
+    .option('--session <name>', 'which session is asking (default: $QUOX_SESSION)')
+    .option('--slot <name>', 'your slot')
+    .option('--expires <dur>', 'how long it stays open')
+    .option('--wait', 'block until answered')
+    .option('--timeout <dur>', 'with --wait: stop waiting after this long')
+    .action(async (subOptions) => {
+      // commander lets the parent `ask` swallow flags it shares with this verb (--justify, --why, --session...), so merge both
+      const options = { ...ask.opts(), ...Object.fromEntries(Object.entries(subOptions).filter(([, v]) => v !== undefined)) };
+      if (!String(options.justify || '').trim()) { err('say why it is safe: --justify "<plain words>"'); process.exitCode = 2; return; }
+      const raw = [].concat(options.paths || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
+      let root;
+      try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim(); } catch { root = process.cwd(); }
+      const paths = [...new Set(raw.map(toRepoRelative))];
+      const missing = paths.filter((p) => !p || !existsSync(join(root, p)));
+      if (!paths.length || missing.length) { err(`not found in this repo (${root}): ${missing.join(', ') || '(no paths)'}. Run from the worktree and name files that exist.`); process.exitCode = 2; return; }
+      // 2026-10-19: the server truncates long titles, and the attestation names only paths found in title+body,
+      // so a 7-file ask covered 3. Every path also goes in the body.
+      const files = `Files (${paths.length}):\n${paths.map((p) => `- ${p}`).join('\n')}`;
+      await fileAsk({ ...options, title: `Approve test edits: ${paths.join(' ')}`, why: options.why ? `${files}\n\n${options.why}` : files, yn: true, highRisk: true, justify: options.justify });
+    });
+
+  ask
+    .command('status')
+    .description('Show where a question stands: pending, answered, denied or expired, with the answer')
+    .argument('<id>', 'the id `quox ask` printed')
+    .action(async (id) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('inbox.decision.get', { orgId, id });
+      const d = (await client.get(ep.path, { service: ep.service })).decision;
+      if (program.opts().output === 'json') { console.log(JSON.stringify(d, null, 2)); return; }
+      console.log(`${d.state}${d.answer?.option ? ` ${d.answer.option}` : ''}${d.answer?.note ? ` (${d.answer.note})` : ''}`);
+      if (d.state === 'expired' || d.state === 'denied') process.exitCode = EXIT_NO_ANSWER;
+    });
+
+  ask
+    .command('wait')
+    .description('Block until a question is answered; prints the chosen option key (and note), exits 2 on expiry or deny')
+    .argument('<id>', 'the id `quox ask` printed')
+    .option('--timeout <dur>', 'stop waiting after this long (the question stays open)')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      await waitAndPrint(orgId, id, { timeoutSec: options.timeout ? parseDuration(options.timeout) : null });
+    });
+}

package/lib/commands/assistant.js

@@ -5,6 +5,10 @@
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxError } from '../core/errors.js';
+
+// #1049: auth routes/assistants.js DEPLOYMENT_MODES (the server is the authority).
+const DEPLOY_MODES = ['private', 'shared', 'public'];
 
 export function registerAssistantCommands(program, ctx) {
   const { client, auth } = ctx;
@@ -84,20 +88,71 @@ export function registerAssistantCommands(program, ctx) {
       printSuccess('Assistant deleted.');
     });
 
+  assistant
+    .command('publish')
+    .description('Publish a draft assistant (draft to active), so it can be deployed')
+    .argument('<assistantId>', 'assistant ID')
+    .action(async (assistantId) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      // #1028: create makes a draft and deploy refuses anything not active; this is the step between.
+      const ep = resolveEndpoint('assistants.publish', { orgId, assistantId });
+      await client.post(ep.path, { service: ep.service });
+      printSuccess('Assistant published.');
+    });
+
   assistant
     .command('deploy')
-    .description('Deploy an assistant')
+    .description('Deploy an active assistant to a scope (scope ids: quox org divisions list, quox department list, quox team list)')
     .argument('<assistantId>', 'assistant ID')
-    .option('--target <target>', 'deployment target')
+    .option('--scope <scopeId>', 'scope ID to deploy to (required)')
+    .option('--target <scopeId>', 'alias for --scope')
+    .option('--mode <mode>', `${DEPLOY_MODES.join(', ')} (default shared)`)
     .action(async (assistantId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const body = {};
-      if (options.target) body.target = options.target;
+      // #998: the auth route requires scope_id; the CLI used to send { target }.
+      const scopeId = options.scope || options.target;
+      if (!scopeId) throw new QuoxError('assistant deploy needs --scope <scopeId>.', 1);
+      // #1049: the server's modes (auth routes/assistants.js DEPLOYMENT_MODES); refuse anything else here.
+      if (options.mode && !DEPLOY_MODES.includes(options.mode)) {
+        throw new QuoxError(`--mode must be one of: ${DEPLOY_MODES.join(', ')} (got "${options.mode}").`, 1);
+      }
+      const body = { scope_id: scopeId };
+      if (options.mode) body.mode = options.mode;
       await client.post(resolveEndpoint('assistants.deploy', { orgId, assistantId }).path, { service: resolveEndpoint('assistants.deploy', { orgId, assistantId }).service, body });
       printSuccess('Assistant deployed.');
     });
 
+  assistant
+    .command('undeploy')
+    .description('Remove a deployment of an assistant (by --deployment id, or the active one at --scope)')
+    .argument('<assistantId>', 'assistant ID')
+    .option('--deployment <deploymentId>', 'deployment ID to remove (see quox assistant get)')
+    .option('--scope <scopeId>', 'remove the active deployment at this scope')
+    .action(async (assistantId, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      // #1049: a deployed assistant could not be removed from the CLI.
+      let deploymentId = options.deployment;
+      if (!deploymentId) {
+        if (!options.scope) throw new QuoxError('assistant undeploy needs --deployment <id> or --scope <scopeId>.', 1);
+        const g = resolveEndpoint('assistants.get', { orgId, assistantId });
+        const data = await client.get(g.path, { service: g.service });
+        const deps = (data && data.assistant && data.assistant.deployments) || (data && data.deployments) || [];
+        const live = deps.filter((d) => d.status === 'active');
+        const hit = live.find((d) => d.scope_id === options.scope);
+        if (!hit) {
+          const where = live.length ? live.map((d) => `${d.scope_id} (${d.id})`).join(', ') : 'nowhere';
+          throw new QuoxError(`No active deployment of ${assistantId} at scope ${options.scope}. It is deployed at: ${where}.`, 1);
+        }
+        deploymentId = hit.id;
+      }
+      const ep = resolveEndpoint('assistants.undeploy', { orgId, assistantId, deploymentId });
+      await client.delete(ep.path, { service: ep.service });
+      printSuccess(`Deployment ${deploymentId} removed.`);
+    });
+
   assistant
     .command('fork')
     .description('Fork an assistant')

package/lib/commands/auth.js

@@ -199,7 +199,9 @@ export function registerAuthCommands(program, ctx) {
     .action(async () => {
       auth.requireAuth();
       const data = await client.get(resolveEndpoint('auth.me.list').path, { service: resolveEndpoint('auth.me.list').service });
-      const authData = config.getAuth();
+      // A QUOX_TOKEN_FILE principal (the W4 builder uid) has no stored profile:
+      // render from the server's /me answer rather than crash on null.
+      const authData = config.getAuth() || {};
 
       // quox#463: resident logins carry org_id but no org_name (the
       // bootstrap has only the id), and this rendered a real membership as
@@ -245,8 +247,12 @@ export function registerAuthCommands(program, ctx) {
         org: orgDisplay,
         role: authData.org_role || 'n/a',
         mfa: data.user?.mfa_enabled ? 'enabled' : 'disabled',
+        // Z2H-3c: expires_at is the ACCESS token. With a refresh token the sign-in outlives it, so do not
+        // present it as the session ending (a fresh owner read "expires in 60m" right after logging in).
         session: authData.expires_at
-          ? `expires in ${Math.max(0, Math.round((authData.expires_at - Date.now()) / 60000))}m`
+          ? (authData.refresh_token
+            ? `active, auto-renews (token refresh in ${Math.max(0, Math.round((authData.expires_at - Date.now()) / 60000))}m)`
+            : `expires in ${Math.max(0, Math.round((authData.expires_at - Date.now()) / 60000))}m`)
           : 'unknown',
         profile: config.getActiveProfileName(),
       };

package/lib/commands/backup.js

@@ -59,14 +59,18 @@ export function registerBackupCommands(program, ctx) {
   backup
     .command('create')
     .description('Create a backup')
-    .option('--label <label>', 'backup label')
-    .option('--type <type>', 'backup type: full, incremental', 'full')
+    .option('--label <label>', 'backup label (stored as the backup name)')
+    .option('--type <type>', 'backup type: full, quick, selective', 'full')
     .option('--components <list>', 'comma-separated components to include')
     .action(async (options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const body = { type: options.type };
-      if (options.label) body.label = options.label;
+      // #1017: the server reads backup_type and name (services/auth/routes/backups.js); type/label were dropped,
+      // and a type outside the backups.backup_type CHECK would only fail later inside the server.
+      const TYPES = ['full', 'quick', 'selective'];
+      if (!TYPES.includes(options.type)) throw new Error(`--type must be one of: ${TYPES.join(', ')}`);
+      const body = { backup_type: options.type };
+      if (options.label) body.name = options.label;
       if (options.components) body.components = options.components.split(',').map(c => c.trim());
 
       const ora = (await import('ora')).default;

package/lib/commands/brain.js

@@ -51,6 +51,18 @@ export function titleOverlap(a, b) {
   for (const w of x) if (y.has(w)) hit++;
   return hit / Math.min(x.size, y.size);
 }
+const NEGATIVE_WORDS = new Set(['disable', 'disabled', 'disabling', 'off', 'deny', 'denied', 'block', 'blocked', 'stop', 'stopped', 'remove', 'removed', 'drop', 'dropped', 'abandon', 'abandoned', 'reject', 'rejected', 'exclude', 'excluded', 'not', 'never', 'no', 'dont', 'cannot', 'cant', 'wont', 'without', 'revoke', 'revoked']);
+/** Odd count of negating words = negative polarity ("not", "stop", "disable", "reject", ...). */
+function negativeParity(t) {
+  const toks = String(t || '').toLowerCase().replace(/['\u2019]/g, '').split(/[^a-z0-9]+/).filter(Boolean);
+  let n = 0;
+  for (const w of toks) if (NEGATIVE_WORDS.has(w)) n++;
+  return n % 2;
+}
+/** True when two decision titles read as opposites (enable/disable, on/off, stop X, no longer X...). */
+export function oppositePolarity(a, b) {
+  return negativeParity(a) !== negativeParity(b);
+}
 export const DECIDE_DUPE_THRESHOLD = 0.6;
 export const DISTILL_CAP = 50;
 
@@ -136,6 +148,24 @@ export function scoreRetrievalEval(judgements, searches, k = 8) {
 export function registerBrainCommands(program, ctx) {
   const { client, auth } = ctx;
 
+  // quox#934: read/history/related go through the NotesQ API, which only knows
+  // editable NotesQ notes. A feed note (git_commit, email, ...) that `brain note`
+  // resolves came back as a bare 404. On a NotesQ 404, ask the brain itself;
+  // rethrow the original error when the brain does not know the note either.
+  const brainNoteOn404 = async (noteId, err) => {
+    if (!(err instanceof QuoxApiError) || err.status !== 404) throw err;
+    let note;
+    try {
+      const ep = resolveEndpoint('brain.note.get', { id: noteId });
+      note = await client.get(ep.path, { service: ep.service });
+    } catch {
+      throw err;
+    }
+    if (!note || !note.id) throw err;
+    return note;
+  };
+  const feedReason = (n, what) => `${n.id} is a ${n.kind || 'feed'} note${n.source_type ? ` from the ${n.source_type} source` : ''}, not an editable NotesQ note, so it has no ${what}.`;
+
   const brain = program
     .command('brain')
     .description('Query Quox Qortex (vaults, notes, semantic search)')
@@ -164,10 +194,16 @@ export function registerBrainCommands(program, ctx) {
         console.log(JSON.stringify(data, null, 2));
         return;
       }
+      // quox#853: a keyword-only fallback fooled both the product and a
+      // verifier ("0 hits" read as "does not exist"). Say it in words.
+      const degradedNote = data.retrieval === 'fts' && data.degraded
+        ? '⚠ Semantic search was unavailable for this query, so this is keyword-only: a missing or zero result does not prove the note is absent. Retry shortly.'
+        : '';
       if (insufficient) {
         const legLabel = data.retrieval ? ` · ${data.retrieval}` : '';
         console.log(glyphLine('brain2', `search "${query.slice(0, 40)}"`, { result: `0 relevant hits${legLabel}`, ms: data.tookMs ?? '?' }));
         console.log('⚠ Qortex judged the matches for this query insufficient (no relevant notes). The weak hits are withheld; use -o json to see them with the relevance details.');
+        if (degradedNote) console.log(degradedNote);
         return;
       }
       // BRAIN2-AUDIT: sessions must SEE what Qortex recalled, not just a hit
@@ -176,12 +212,14 @@ export function registerBrainCommands(program, ctx) {
         const results = data.results || [];
         const legLabel = data.retrieval ? ` · ${data.retrieval}` : '';
         console.log(glyphLine('brain2', `search "${query.slice(0, 40)}"`, { result: `${results.length} hits${legLabel}`, ms: data.tookMs ?? '?' }));
+        if (degradedNote) console.log(degradedNote);
         if (results.length === 0) {
           console.log(glyphLine('brain2', 'recall', { result: 'nothing on record for this query' }));
           return;
         }
         for (const r of results) {
-          console.log(`${brandName('🌌 QORTEX')} recall │ "${recallSnippet(r)}" · ${recallSource(r)} · ${r.title || 'untitled'} · note ${r.noteId || '?'}`);
+          const miss = Array.isArray(r.missingEntities) && r.missingEntities.length ? ` · does not mention ${r.missingEntities.join(', ')}` : '';
+          console.log(`${brandName('🌌 QORTEX')} recall │ "${recallSnippet(r)}" · ${recallSource(r)} · ${r.title || 'untitled'} · note ${r.noteId || '?'}${miss}`);
         }
         return;
       }
@@ -191,6 +229,7 @@ export function registerBrainCommands(program, ctx) {
       if (program.opts().output !== 'json') {
         const legLabel = data.retrieval ? ` · ${data.retrieval}` : '';
         console.log(glyphLine('brain2', `search "${query.slice(0, 40)}"`, { result: `${(data.results || []).length} hits${legLabel}`, ms: data.tookMs ?? '?' }));
+        if (degradedNote) console.log(degradedNote);
       }
       formatOutput({
         columns: ['title', 'kind', 'snippet', 'score'],
@@ -300,7 +339,7 @@ export function registerBrainCommands(program, ctx) {
       if (!['private', 'org'].includes(options.scope)) throw new QuoxError('--scope must be private or org.', 2);
       const prov = decisionProvenance();
       const title = `Decision: ${what}`.slice(0, 200);
-      const markdown = decisionMarkdown({ what, why: options.why, rejected: options.rejected, prov });
+      let markdown = decisionMarkdown({ what, why: options.why, rejected: options.rejected, prov });
       const tags = ['decision', ...String(options.tags || '').split(',').map((t) => t.trim()).filter(Boolean)];
       const json = program.opts().output === 'json';
       if (options.dryRun) {
@@ -311,7 +350,15 @@ export function registerBrainCommands(program, ctx) {
       const sp = resolveEndpoint('brain.search.list');
       const found = await client.post(sp.path, { service: sp.service, body: { query: what, limit: 5 } });
       const insufficient = found.insufficient === true || found.relevance?.insufficient === true;
-      const dupe = insufficient ? null : (found.results || []).find((r) => titleOverlap(what, String(r.title || '').replace(/^Decision:\s*/i, '')) >= DECIDE_DUPE_THRESHOLD);
+      const bare = (r) => String(r.title || '').replace(/^Decision:\s*/i, '');
+      const matches = insufficient ? [] : (found.results || []).filter((r) => titleOverlap(what, bare(r)) >= DECIDE_DUPE_THRESHOLD);
+      // An opposite-polarity match is a reversal of the earlier decision, never a duplicate of it.
+      const dupe = matches.find((r) => !oppositePolarity(what, bare(r)));
+      const reversed = dupe ? null : matches[0];
+      if (reversed) {
+        const ref = reversed.noteId || reversed.title;
+        if (ref) markdown = decisionMarkdown({ what, why: options.why, rejected: options.rejected, prov: { ...prov, supersedes: ref } });
+      }
       if (dupe && !options.force) {
         if (json) console.log(JSON.stringify({ saved: false, reason: 'existing_match', match: { noteId: dupe.noteId, title: dupe.title, kind: dupe.kind } }, null, 2));
         else {
@@ -324,9 +371,10 @@ export function registerBrainCommands(program, ctx) {
       }
       const ep = resolveEndpoint('brain.capture.create');
       const data = await client.post(ep.path, { service: ep.service, body: { title, text: markdown.replace(/^# .*\n\n/, ''), tags, scope: options.scope === 'org' ? 'org' : 'user' } });
-      if (json) { console.log(JSON.stringify(data, null, 2)); return; }
+      if (json) { console.log(JSON.stringify(reversed ? { ...data, reverses: { noteId: reversed.noteId, title: reversed.title } } : data, null, 2)); return; }
       const verb = data.status === 'created' ? 'saved' : data.status === 'unchanged' ? 'already saved' : 'updated';
       console.log(glyphLine('brain2', 'decide', { result: `${verb} · note ${String(data.noteId || '?').slice(0, 8)}` }));
+      if (reversed) console.log(`  reverses ${reversed.title || 'untitled'}  (note ${reversed.noteId || '?'})`);
     });
 
   brain
@@ -443,14 +491,14 @@ export function registerBrainCommands(program, ctx) {
         formatDetail(data, { format });
         return;
       }
-      const verdict = (r) => (r.contradicted ? 'contradicted' : r.supported === true ? 'supported' : r.supported === false ? 'unsupported' : 'not measured');
+      const verdict = (r) => (r.fabricated || r.support_method === 'fabricated' ? 'fabricated' : r.support_method === 'unchecked' ? 'unchecked' : r.contradicted ? 'contradicted' : r.supported === true ? 'supported' : r.support_method === 'overlap' ? 'overlap' : r.supported === false ? 'unsupported' : 'not measured');
       formatOutput({
         columns: ['session', 'handle', 'note', 'span', 'rev', 'verdict', 'at'],
         headers: ['Session', 'Handle', 'Note', 'Span', 'Rev', 'Verdict', 'At'],
         rows: (data.records || []).map((r) => ({
           session: r.session || '-',
           handle: r.handle || '-',
-          note: r.note_id,
+          note: r.note_id || '-',
           span: r.char_start != null && r.char_end != null ? `${r.char_start}-${r.char_end}` : '-',
           rev: r.note_hash ? String(r.note_hash).slice(0, 8) : '-',
           verdict: verdict(r),
@@ -509,7 +557,8 @@ export function registerBrainCommands(program, ctx) {
               { metric: 'answers after brain search', week: cw.answers ?? 0, total: ct.answers ?? 0 },
               { metric: 'answers citing a note', week: `${cw.grounded ?? 0} (${pct(cw.grounded ?? 0, cw.answers ?? 0)})`, total: `${ct.grounded ?? 0} (${pct(ct.grounded ?? 0, ct.answers ?? 0)})` },
               ...((cw.supportMeasured ?? 0) + (ct.supportMeasured ?? 0) > 0
-                ? [{ metric: 'answers with supported citations (lexical)', week: `${cw.supportedAnswers ?? 0} (${pct(cw.supportedAnswers ?? 0, cw.supportMeasured ?? 0)})`, total: `${ct.supportedAnswers ?? 0} (${pct(ct.supportedAnswers ?? 0, ct.supportMeasured ?? 0)})` }]
+                ? [{ metric: 'answers with supported citations (entailment)', week: `${cw.supportedAnswers ?? 0} (${pct(cw.supportedAnswers ?? 0, cw.supportMeasured ?? 0)})`, total: `${ct.supportedAnswers ?? 0} (${pct(ct.supportedAnswers ?? 0, ct.supportMeasured ?? 0)})` },
+                   { metric: 'answers with overlap only (not checked for meaning)', week: `${cw.overlapAnswers ?? 0}`, total: `${ct.overlapAnswers ?? 0}` }]
                 : []),
               { metric: 'notes cited / retrieved', week: `${cw.citedNotes ?? 0}/${cw.retrievedNotes ?? 0}`, total: `${ct.citedNotes ?? 0}/${ct.retrievedNotes ?? 0}` },
             ],
@@ -559,7 +608,13 @@ export function registerBrainCommands(program, ctx) {
     .action(async (noteId, options) => {
       auth.requireAuth();
       const ep = resolveEndpoint('notesq.notes.get', { id: noteId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (e) {
+        const bn = await brainNoteOn404(noteId, e);
+        data = { note: bn, source: 'brain', editable: false };
+      }
       const n = data.note || data;
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       if (options.raw) { console.log(n.body ?? n.markdown ?? ''); return; }
@@ -602,11 +657,22 @@ export function registerBrainCommands(program, ctx) {
     .description('Delete a note (recorded as a revision, restorable in NotesQ). Requires --yes.')
     .argument('<noteId>', 'note id')
     .option('--yes', 'confirm deletion')
+    .option('--expected-hash <hash>', "the note's content_hash you read (see `quox brain read`); a stale value is a conflict (409) and nothing is deleted")
     .action(async (noteId, options) => {
       auth.requireAuth();
       if (!options.yes) throw new QuoxError(`Refusing to delete ${noteId} without --yes.`, 2);
+      if (!options.expectedHash) throw new QuoxError(`Refusing to delete ${noteId} without --expected-hash (the content_hash from \`quox brain read ${noteId}\`), so a concurrent edit is never deleted.`, 2);
       const ep = resolveEndpoint('notesq.notes.delete', { id: noteId });
-      const data = await client.delete(ep.path, { service: ep.service });
+      let data;
+      try {
+        data = await client.delete(ep.path, { service: ep.service, query: { expected_hash: options.expectedHash } });
+      } catch (e) {
+        if (e instanceof QuoxApiError && e.status === 409) {
+          const h = e.body && (e.body.currentHash || e.body.current_hash);
+          throw new QuoxError(`Conflict (409): note ${noteId} changed since hash ${options.expectedHash} (current_hash ${h || 'unknown'}). Nothing was deleted. Re-run \`quox brain read ${noteId}\` and retry.`, 1);
+        }
+        throw e;
+      }
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(`Deleted note ${noteId}.`);
     });
@@ -621,7 +687,14 @@ export function registerBrainCommands(program, ctx) {
     .action(async (noteId, options) => {
       auth.requireAuth();
       const ep = resolveEndpoint('notesq.notes.related', { id: noteId });
-      const data = await client.get(ep.path, { service: ep.service, query: { limit: Math.min(Math.max(parseInt(options.limit, 10) || 8, 1), 20) } });
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service, query: { limit: Math.min(Math.max(parseInt(options.limit, 10) || 8, 1), 20) } });
+      } catch (e) {
+        const bn = await brainNoteOn404(noteId, e);
+        data = { related: [], editable: false, reason: `${feedReason(bn, 'similarity links')} Use \`quox brain neighbours ${noteId}\` for its graph links.` };
+        if (program.opts().output !== 'json') console.log(data.reason);
+      }
       const related = data.related || [];
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       console.log(glyphLine('brain2', `related ${noteId.slice(0, 8)}`, { result: `${related.length} notes` }));
@@ -657,11 +730,13 @@ export function registerBrainCommands(program, ctx) {
     .description('Token-budgeted pack of the most relevant cited passages on a topic (what the Cortex brain_context tool returns)')
     .argument('<query>', 'topic or task')
     .option('--budget <n>', 'approximate token budget (200-4000)', '1200')
+    .option('--since <date>', 'only notes dated on or after this ISO date/datetime (e.g. 2026-10-05)')
+    .option('--until <date>', 'only notes dated on or before this ISO date/datetime (a date alone means the whole day)')
     .action(async (query, options) => {
       auth.requireAuth();
       const tokenBudget = Math.min(Math.max(parseInt(options.budget, 10) || 1200, 200), 4000);
       const ep = resolveEndpoint('brain.context.pack');
-      const data = await client.post(ep.path, { service: ep.service, body: { query, tokenBudget } });
+      const data = await client.post(ep.path, { service: ep.service, body: { query, tokenBudget, ...(options.since ? { since: options.since } : {}), ...(options.until ? { until: options.until } : {}) } });
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       const passages = data.passages || [];
       const insufficient = data.insufficient === true || data.relevance?.insufficient === true || passages.length === 0;
@@ -693,7 +768,7 @@ export function registerBrainCommands(program, ctx) {
       if (!data || data.success === false) {
         throw new QuoxError(`brain_check failed: ${(data && (data.error || data.output)) || 'unknown error'}`, 1);
       }
-      const mark = { supported: '✔', contradicted: '✖', unknown: '◐' }[data.verdict] || '';
+      const mark = { supported: '✔', contradicted: '✖', overlap: '◐', unknown: '◐' }[data.verdict] || '';
       console.log(glyphLine('brain2', `check "${claim.slice(0, 40)}"`, { result: `${data.verdict} ${mark}`.trim() }));
       const ev = data.evidence || [];
       for (const e of ev) {
@@ -749,7 +824,14 @@ export function registerBrainCommands(program, ctx) {
         return;
       }
       const ep = resolveEndpoint('notesq.notes.revisions', { id: noteId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let data;
+      try {
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (e) {
+        const bn = await brainNoteOn404(noteId, e);
+        data = { revisions: [], editable: false, reason: feedReason(bn, 'revision history') };
+        if (program.opts().output !== 'json') { console.log(data.reason); return; }
+      }
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       formatOutput({ columns: ['rev', 'action', 'author_kind', 'created_at', 'content_hash'], headers: ['Rev', 'Action', 'Author', 'When', 'Hash'], rows: data.revisions || [] }, { format: program.opts().output });
     });
@@ -770,7 +852,16 @@ export function registerBrainCommands(program, ctx) {
         throw new QuoxError(`Conflict: note ${noteId} changed since hash ${options.expectedHash} (current_hash ${current || 'unknown'}). Nothing was restored. Re-run \`quox brain read ${noteId}\` and try again.`, 1);
       }
       const ep = resolveEndpoint('notesq.notes.restore', { id: noteId });
-      const data = await client.post(ep.path, { service: ep.service, body: { rev } });
+      let data;
+      try {
+        data = await client.post(ep.path, { service: ep.service, body: { rev, expected_hash: options.expectedHash } });
+      } catch (e) {
+        if (e instanceof QuoxApiError && e.status === 409) {
+          const h = e.body && (e.body.currentHash || e.body.current_hash);
+          throw new QuoxError(`Conflict (409): note ${noteId} changed since hash ${options.expectedHash} (current_hash ${h || 'unknown'}). Nothing was restored. Re-run \`quox brain read ${noteId}\` and try again.`, 1);
+        }
+        throw e;
+      }
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       printSuccess(data.unchanged ? `Note ${noteId} already matches revision ${rev}.` : `Restored note ${noteId} to revision ${rev} (new rev ${data.revision?.rev ?? '?'}).`);
     });

package/lib/commands/build.js

@@ -33,10 +33,26 @@ export function registerBuildCommands(program, ctx) {
   // own parsed opts.
   const groupOpt = (options, key) => options[key] ?? build.opts()[key];
 
+  // An org with exactly one dev server needs no --host: use it and say so. With several, name them;
+  // with none, say so (proof cases code/reach-build-status / -targets exited 1 on a one-server org).
+  async function resolveHost(options) {
+    const given = groupOpt(options, 'host');
+    if (given) return given;
+    const listEp = resolveEndpoint('v1.dev.servers.list');
+    const list = await client.get(listEp.path, { service: listEp.service });
+    const ids = (Array.isArray(list?.servers) ? list.servers : []).map((s) => s.host_id).filter(Boolean);
+    if (ids.length === 1) {
+      printWarning(`No --host given; using the only dev server: ${ids[0]}`);
+      return ids[0];
+    }
+    if (ids.length === 0) throw new Error('No dev server is registered for this org (register one with `quox dev enable <hostId>`).');
+    throw new Error(`--host <hostId> is required: this org has ${ids.length} dev servers (${ids.join(', ')}).`);
+  }
+
   async function dispatch(target, options) {
     auth.requireAuth();
     options = {
-      host: groupOpt(options, 'host'),
+      host: await resolveHost(options),
       stream: groupOpt(options, 'stream'),
       phase: groupOpt(options, 'phase'),
       msg: groupOpt(options, 'msg'),
@@ -76,8 +92,7 @@ export function registerBuildCommands(program, ctx) {
     .option('--host <hostId>', 'dev server host_id')
     .action(async (options) => {
       auth.requireAuth();
-      const host = groupOpt(options, 'host');
-      if (!host) throw new Error('--host <hostId> is required');
+      const host = await resolveHost(options);
       const endpoint = resolveEndpoint('v1.dev.build.status', { hostId: host });
       const data = await client.get(endpoint.path, { service: endpoint.service });
       formatDetail(data, { format: program.opts().output, title: `Build status: ${host}` });
@@ -89,8 +104,7 @@ export function registerBuildCommands(program, ctx) {
     .option('--host <hostId>', 'dev server host_id')
     .action(async (options) => {
       auth.requireAuth();
-      const host = groupOpt(options, 'host');
-      if (!host) throw new Error('--host <hostId> is required');
+      const host = await resolveHost(options);
       const endpoint = resolveEndpoint('v1.dev.build.targets', { hostId: host });
       const data = await client.get(endpoint.path, { service: endpoint.service });
       formatOutput(data.targets || [], {