quoxcli 0.2.0 → 0.4.0

package/lib/core/commandRegistrars.js

@@ -0,0 +1,130 @@
+/**
+ * The CLI's command groups, in registration order (moved verbatim from bin/quox.js so
+ * one list feeds both the binary and cli/scripts/export-leaf-tree.mjs, which exports the
+ * machine-readable leaf tree the collector's quox_cli tool validates against).
+ * Paths are relative to THIS file; registerCommandGroups resolves them against the
+ * baseUrl it is given (COMMAND_REGISTRARS_BASE).
+ */
+export const COMMAND_REGISTRARS = [
+  ['../commands/auth.js', 'registerAuthCommands'],
+  ['../commands/service.js', 'registerServiceCommands'],
+  ['../commands/status.js', 'registerStatusCommand'],
+  ['../commands/doctor.js', 'registerDoctorCommand'],
+  ['../commands/server.js', 'registerServerCommands'],
+  ['../commands/update.js', 'registerUpdateCommand'],
+  ['../commands/shortcut.js', 'registerShortcutCommand'],
+  ['../commands/open.js', 'registerOpenCommand'],
+  ['../commands/peek.js', 'registerPeekCommand'],
+  ['../commands/aside.js', 'registerAsideCommand'],
+  ['../commands/motion.js', 'registerMotionCommand'],
+  ['../commands/welcome.js', 'registerWelcomeCommand'],
+  ['../commands/config-cmd.js', 'registerConfigCommands'],
+  ['../commands/org.js', 'registerOrgCommands'],
+  ['../commands/invites.js', 'registerInvitesCommands'],
+  ['../commands/team.js', 'registerTeamCommands'],
+  ['../commands/department.js', 'registerDepartmentCommands'],
+  ['../commands/agent.js', 'registerAgentCommands'],
+  ['../commands/tool.js', 'registerToolCommands'],
+  ['../commands/workflow.js', 'registerWorkflowCommands'],
+  ['../commands/objective.js', 'registerObjectiveCommands'],
+  ['../commands/loop.js', 'registerLoopCommands'],
+  ['../commands/assistant.js', 'registerAssistantCommands'],
+  ['../commands/fleet.js', 'registerFleetCommands'],
+  ['../commands/chat.js', 'registerChatCommands'],
+  ['../commands/memory.js', 'registerMemoryCommands'],
+  ['../commands/actions.js', 'registerActionsCommands'],
+  ['../commands/brain.js', 'registerBrainCommands'],
+  ['../commands/entity.js', 'registerEntityCommands'],
+  ['../commands/backup.js', 'registerBackupCommands'],
+  ['../commands/inbox.js', 'registerInboxCommands'],
+  ['../commands/approvals.js', 'registerApprovalsCommands'],
+  ['../commands/vm.js', 'registerVmCommands'],
+  ['../commands/router.js', 'registerRouterCommands'],
+  ['../commands/mail.js', 'registerMailCommands'],
+  ['../commands/calendar.js', 'registerCalendarCommands'],
+  ['../commands/notes.js', 'registerNotesCommands'],
+  ['../commands/blog.js', 'registerBlogCommands'],
+  ['../commands/contacts.js', 'registerContactsCommands'],
+  ['../commands/licence.js', 'registerLicenceCommands'],
+  ['../commands/run.js', 'registerRunCommands'],
+  ['../commands/file.js', 'registerFileCommands'],
+  ['../commands/evidence.js', 'registerEvidenceCommands'],
+  ['../commands/admin.js', 'registerAdminCommands'],
+  ['../commands/aee.js', 'registerAeeCommands'],
+  ['../commands/integration.js', 'registerIntegrationCommands'],
+  ['../commands/consent.js', 'registerConsentCommands'],
+  ['../commands/setup.js', 'registerSetupCommands'],
+  ['../commands/watch.js', 'registerWatchCommands'],
+  ['../commands/tag.js', 'registerTagCommands'],
+  ['../commands/scope.js', 'registerScopeCommands'],
+  ['../commands/notification.js', 'registerNotificationCommands'],
+  ['../commands/prompt.js', 'registerPromptCommands'],
+  ['../commands/plugin.js', 'registerPluginCommands'],
+  ['../commands/powers.js', 'registerPowersCommands'],
+  ['../commands/conversation.js', 'registerConversationCommands'],
+  ['../commands/vault.js', 'registerVaultCommands'],
+  ['../commands/volt.js', 'registerVoltCommands'],
+  ['../commands/governance.js', 'registerGovernanceCommands'],
+  ['../commands/skills.js', 'registerSkillsCommands'],
+  ['../commands/claude.js', 'registerClaudeCommands'],
+  ['../commands/monitoring.js', 'registerMonitoringCommands'],
+  ['../commands/trigger.js', 'registerTriggerCommands'],
+  ['../commands/webhook.js', 'registerWebhookCommands'],
+  ['../commands/sso.js', 'registerSsoCommands'],
+  ['../commands/role.js', 'registerRoleCommands'],
+  ['../commands/domain.js', 'registerDomainCommands'],
+  ['../commands/security.js', 'registerSecurityCommands'],
+  ['../commands/safety.js', 'registerSafetyCommands'],
+  ['../commands/scim.js', 'registerScimCommands'],
+  ['../commands/llm-policy.js', 'registerLlmPolicyCommands'],
+  ['../commands/hat.js', 'registerHatCommands'],
+  ['../commands/rows.js', 'registerRowsCommands'],
+  ['../commands/settings.js', 'registerSettingsCommands'],
+  ['../commands/llm.js', 'registerLlmCommands'],
+  ['../commands/capabilities.js', 'registerCapabilitiesCommands'],
+  ['../commands/provider.js', 'registerProviderCommands'],
+  ['../commands/tips.js', 'registerTipsCommands'],
+  ['../commands/ext.js', 'registerExtCommands'],
+  ['../commands/quoxchat.js', 'registerQuoxchatCommands'],
+  ['../commands/budget.js', 'registerBudgetCommands'],
+  ['../commands/trace.js', 'registerTraceCommands'],
+  ['../commands/mon.js', 'registerMonCommands'],
+  ['../commands/kuma.js', 'registerKumaCommands'],
+  ['../commands/quoxbox.js', 'registerQuoxboxCommands'],
+  ['../commands/plan.js', 'registerPlanCommands'],
+  ['../commands/engagement.js', 'registerEngagementCommands'],
+  ['../commands/done.js', 'registerDoneCommands'],
+  ['../commands/discord.js', 'registerDiscordCommands'],
+  ['../commands/qlarity.js', 'registerQlarityCommands'],
+  ['../commands/fetchAllowlist.js', 'registerFetchAllowlistCommands'],
+  ['../commands/research.js', 'registerResearchCommands'],
+  ['../commands/reach.js', 'registerReachCommands'],
+  ['../commands/inventory.js', 'registerInventoryCommands'],
+  ['../commands/policy.js', 'registerPolicyCommands'],
+  ['../commands/quoxseo.js', 'registerQuoxseoCommands'],
+  ['../commands/voice.js', 'registerVoiceCommands'],
+  ['../commands/awareness.js', 'registerAwarenessCommands'],
+  ['../commands/mind.js', 'registerMindCommands'],
+  ['../commands/lucid.js', 'registerLucidCommands'],
+  ['../commands/hyperion.js', 'registerHyperionCommands'],
+  ['../commands/tg.js', 'registerTgCommands'],
+  ['../commands/dev.js', 'registerDevCommands'],
+  ['../commands/build.js', 'registerBuildCommands'],
+  ['../commands/slot.js', 'registerSlotCommands'],
+  ['../commands/gripe.js', 'registerGripeCommands'],
+  ['../commands/ask.js', 'registerAskCommands'],
+  ['../commands/presence.js', 'registerPresenceCommands'],
+  ['../commands/dashboard.js', 'registerDashboardCommands'],
+  ['../commands/nucleus.js', 'registerNucleusCommands'],
+  ['../commands/onboard.js', 'registerOnboardCommands'],
+  ['../commands/x.js', 'registerXCommands'],
+  ['../commands/linkedin.js', 'registerLinkedInCommands'],
+  ['../commands/facebook.js', 'registerFacebookCommands'],
+  ['../commands/instagram.js', 'registerInstagramCommands'],
+  ['../commands/tiktok.js', 'registerTikTokCommands'],
+  ['../commands/youtube.js', 'registerYouTubeCommands'],
+  ['../commands/image.js', 'registerImageCommands'],
+  ['../commands/offload.js', 'registerOffloadCommands'],
+];
+
+export const COMMAND_REGISTRARS_BASE = import.meta.url;

package/lib/core/config.js

@@ -7,7 +7,7 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, renameSync, openSync, closeSync, statSync, unlinkSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, networkInterfaces, hostname as osHostname } from 'node:os';
 
 function getConfigDir() { return join(homedir(), '.config', 'quox'); }
 function getConfigFile() { return join(getConfigDir(), 'config.json'); }
@@ -94,35 +94,118 @@ function isPrivateHost(hostname) {
   return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
 }
 
-// Pure port-swap derivation, extracted so it is unit-testable without a
-// full config/profile fixture. Given a base URL (normally the ACTIVE
-// profile's own `url`, never a global default), swap in the target
-// service's port and return the origin. See getServiceUrl step 3 for the
-// loopback scheme-downgrade rule this also carries.
+// QUOXON-Z2H lane R (2026-10-14): where the edge (nginx on the profile's base
+// URL) serves each compose service. Mirrors nginx.conf: /api/auth, /api/setup,
+// /api/orgs ... go to auth at the SAME path, so auth's prefix is empty.
+export const EDGE_PATHS = {
+  auth: '',
+  collector: '/collector',
+  memory: '/api/memory',
+  tasks: '/tasks',
+  orchestrator: '/orchestrator',
+  quoxflow: '/quoxflow',
+  quoxbrain: '/api/quoxbrain',
+  files: '/files-api',
+};
+
+// The local edge's default port. A loopback base on this port is the stack on
+// THIS box, whose services are reachable on their plain-http loopback binds.
+// Any other loopback port is a tunnel (ssh -L 13105:vm:3000) to another box.
+const LOCAL_EDGE_PORTS = new Set(['3000']);
+
+function localIdentity(opts = {}) {
+  let localAddrs = opts.localAddrs;
+  if (!localAddrs) {
+    localAddrs = [];
+    try {
+      for (const list of Object.values(networkInterfaces())) {
+        for (const a of list || []) localAddrs.push(a.address);
+      }
+    } catch { /* no interfaces readable: treat nothing as local */ }
+  }
+  let host = opts.hostname;
+  if (host === undefined) { try { host = osHostname(); } catch { host = ''; } }
+  return { localAddrs: new Set(localAddrs), hostname: String(host || '').toLowerCase() };
+}
+
+function isThisMachine(hostname, id) {
+  const h = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (LOOPBACK_HOSTS.has(h) || LOOPBACK_HOSTS.has(`[${h}]`)) return true;
+  if (id.localAddrs.has(h)) return true;
+  return !!id.hostname && (h === id.hostname || h === `${id.hostname}.local`);
+}
+
+/**
+ * True when a service URL lands on THIS machine (loopback bind, or a base whose
+ * host is one of this box's own addresses) rather than another host or a tunnel
+ * to one. Used to keep this box's ambient QUOX_SERVICE_KEY from being offered
+ * to a remote instance.
+ */
+export function isLocalServiceTarget(serviceUrl, opts = {}) {
+  try {
+    const u = new URL(serviceUrl);
+    const id = localIdentity(opts);
+    if (LOOPBACK_HOSTS.has(u.hostname)) {
+      // Loopback is this box when it is the local edge or a compose service
+      // bind; any other loopback port is a tunnel to another box.
+      const port = u.port || (u.protocol === 'https:' ? '443' : '80');
+      return LOCAL_EDGE_PORTS.has(port) || Object.values(SERVICE_PORTS).map(String).includes(port);
+    }
+    return isThisMachine(u.hostname, id);
+  } catch {
+    return false;
+  }
+}
+
+/** Join an absolute or relative path onto a service URL WITHOUT dropping its path prefix (new URL('/x', base) would). */
+export function joinServiceUrl(serviceUrl, path) {
+  const base = new URL(serviceUrl);
+  const prefix = base.pathname.replace(/\/+$/, '');
+  const rel = new URL(String(path).replace(/^\/*/, '/'), 'http://x');
+  base.pathname = `${prefix}${rel.pathname}`;
+  base.search = rel.search;
+  base.hash = '';
+  return base;
+}
+
+// Derivation of a compose service's URL from a profile base URL (normally the
+// ACTIVE profile's own `url`, never a global default).
 //
-// DEVSUITE-GRIPE-P7 / Bug A: this used to be computed from getBaseUrl(),
-// which honours the global QUOX_URL env override BEFORE the active
-// profile's own url. That meant `-p <profile>` picked which profile's
-// token/services were used, but a QUOX_URL left set in the shell silently
-// overrode which HOST every derived service URL (auth, memory, etc.)
-// pointed at — `quox -p vulcan-proof signup ...` derived the auth base
-// from whatever QUOX_URL said, not from vulcan-proof's own url. Deriving
-// directly from the profile url here means -p is authoritative for service
-// URL derivation the same way it already is for auth/services overrides.
-export function deriveServiceUrl(baseUrl, port) {
+// QUOXON-Z2H lane R: the base URL is the single source of truth. Port guessing
+// is ONLY for the stack on this very machine:
+//   - loopback base on the local edge port (:3000): plain-http loopback port
+//     swap (BRAIN2-AUDIT: compose services are plain HTTP);
+//   - private-LAN base whose host is one of THIS box's addresses: the
+//     loopback bind (#572/#623: services bind 127.0.0.1, only :3000 is on LAN).
+// Everything else (another LAN host, a tunnel on a loopback port, a public
+// host) goes through that base's edge at the service's nginx path. The old
+// rule rewrote ANY RFC1918 base to 127.0.0.1:<port>, so `quox -p vm9110 login`
+// against https://192.0.2.68:3000 was sent to this box's own auth service
+// and got 401 invalid_credentials, and a tunnel profile hit local ports.
+//
+// DEVSUITE-GRIPE-P7 / Bug A: computed from the profile url, not getBaseUrl(),
+// so a stale QUOX_URL cannot defeat -p.
+export function deriveServiceUrl(baseUrl, port, service, opts = {}) {
   try {
     const url = new URL(baseUrl);
-    url.port = String(port);
-    if (LOOPBACK_HOSTS.has(url.hostname)) {
-      // Loopback base: force http (compose services are plain HTTP); keep the
-      // hostname as-is (localhost stays localhost — already reachable).
+    const id = localIdentity(opts);
+    const basePort = url.port || (url.protocol === 'https:' ? '443' : '80');
+    if (LOOPBACK_HOSTS.has(url.hostname) && LOCAL_EDGE_PORTS.has(basePort)) {
+      url.port = String(port);
       url.protocol = 'http:';
-    } else if (isPrivateHost(url.hostname)) {
-      // Private-LAN base: the service binds loopback, so point at the reachable
-      // bind (#572/#623). Public/remote hosts fall through unchanged.
+      return url.origin;
+    }
+    if (!LOOPBACK_HOSTS.has(url.hostname) && isPrivateHost(url.hostname) && isThisMachine(url.hostname, id)) {
+      url.port = String(port);
       url.protocol = 'http:';
       url.hostname = '127.0.0.1';
+      return url.origin;
+    }
+    if (service && Object.prototype.hasOwnProperty.call(EDGE_PATHS, service)) {
+      return `${url.origin}${url.pathname.replace(/\/+$/, '')}${EDGE_PATHS[service]}`;
     }
+    // A port-mapped service with no edge route: the old port swap is the only guess left.
+    url.port = String(port);
     return url.origin;
   } catch {
     return baseUrl;
@@ -137,7 +220,7 @@ export function deriveServiceUrl(baseUrl, port) {
 // only correct source for the flag at ctx-build time.
 // Commands whose remaining argv belongs to another program (`quox claude -p
 // "prompt"` is claude's --print, not quox's --profile).
-const WRAPPED_PROGRAM_COMMANDS = new Set(['claude', 'codex', 'gemini', 'wrap']);
+const WRAPPED_PROGRAM_COMMANDS = new Set(['claude', 'codex', 'wrap']);
 
 export function resolveProfileFlagFromArgv(argv) {
   for (let i = 0; i < argv.length; i++) {
@@ -227,6 +310,9 @@ export function loadConfig(profileOverride) {
     // The profile this invocation is using (persisted default, or the -p /
     // QUOX_PROFILE override for this process only). Never written to _data.
     _effectiveProfile: effectiveProfile,
+    // quox#805: a profile passed explicitly to loadConfig(profile) means "act as
+    // that profile's user", same as -p on the CLI (no implicit attach default).
+    _explicitProfile: Boolean(profileOverride),
 
     getActiveProfile() {
       const name = this._effectiveProfile;
@@ -325,6 +411,38 @@ export function loadConfig(profileOverride) {
       this.save();
     },
 
+    // Stale-sign-in fix: another window or `quox login` may have written fresher credentials for this
+    // profile since this process loaded. Re-read ONLY the active profile's auth from disk and adopt it in
+    // place (callers hold profile refs). Returns true when the auth changed. Never logs or returns a token.
+    reloadAuth() {
+      try {
+        const name = this._effectiveProfile;
+        const disk = JSON.parse(readFileSync(getConfigFile(), 'utf-8'));
+        const dAuth = disk?.profiles?.[name]?.auth ?? null;
+        const prof = this._data.profiles?.[name];
+        if (!prof || dAuth == null) return false;
+        if (J(prof.auth) === J(dAuth)) return false;
+        prof.auth = dAuth;
+        // The loaded snapshot now agrees with disk for auth, so save() does not treat it as our change.
+        try {
+          const snap = JSON.parse(this._loadedProfiles[name] || '{}');
+          snap.auth = dAuth;
+          this._loadedProfiles[name] = J(snap);
+        } catch { /* snapshot is advisory */ }
+        this._clearedAuth.delete(name);
+        this._refreshedAuth.delete(name);
+        return true;
+      } catch { return false; }
+    },
+
+    /** mtime (ms) of the credentials file, or 0. A cheap stat for "did anything sign in elsewhere". */
+    credentialsMtime() {
+      try { return statSync(getConfigFile()).mtimeMs; } catch { return 0; }
+    },
+
+    /** Cross-process refresh lock file, next to the credentials. */
+    refreshLockFile() { return `${getConfigFile()}.refresh.lock`; },
+
     setAuth(authData, opts = {}) {
       const profile = this.getActiveProfile();
       if (!profile) throw new Error('No active profile.');
@@ -400,7 +518,7 @@ export function loadConfig(profileOverride) {
       // and the shared services config (step 2) still say exactly what they
       // say, and a remote/non-loopback host keeps its scheme (a real
       // deployment may terminate TLS per port).
-      return deriveServiceUrl(profileUrl, port);
+      return deriveServiceUrl(profileUrl, port, service);
     },
 
     get(key) {

package/lib/core/customHats.js

@@ -0,0 +1,168 @@
+/**
+ * CUSTOM-HATS (owner 2026-10-17): pure helpers that build and edit a custom hat definition.
+ * Shared by `quox hat create|edit` (cli/lib/commands/hat.js) and the quox window's /hat new|edit
+ * (cli/lib/quoxon). No I/O, no chalk: safe to import anywhere.
+ */
+
+/** The two tools an orchestrator needs to reach the agents a hat lists. */
+export const DELEGATION_TOOLS = ['delegate_to_agent', 'agent_directory'];
+export const HAT_MODES = ['permissive', 'restrictive'];
+export const HAT_OFFERS = ['members', 'authorized'];
+const HARD_CAP = 128;
+
+/** "a, b,,c" -> ['a','b','c'] (trimmed, lowercased, deduped, order kept). */
+export function parseList(v) {
+  if (v === undefined || v === null || v === true) return [];
+  const out = [];
+  for (const raw of String(v).split(',')) {
+    const x = raw.trim().toLowerCase();
+    if (x && !out.includes(x)) out.push(x);
+  }
+  return out;
+}
+
+/** Every tool name a hat names: explicit, bundles, on-demand reads. */
+export function memberTools(def) {
+  const t = def?.tools || {};
+  const names = [
+    ...(Array.isArray(t.explicit) ? t.explicit : []),
+    ...(Array.isArray(t.bundles) ? t.bundles.flatMap(b => (Array.isArray(b?.tools) ? b.tools : [])) : []),
+    ...(Array.isArray(t.on_demand_reads) ? t.on_demand_reads : []),
+  ];
+  return [...new Set(names)];
+}
+
+function emptyDefinition() {
+  return {
+    schema_version: 1,
+    purpose: '',
+    agents: { orchestrator: 'quox', specialists: [] },
+    tools: { explicit: [], bundles: [], connector_families: [] },
+    budgets: { initial_tool_target: 12, max_manifest: 32 },
+    transitions: { allowed: 'any', confirm: 'none', privileged: false },
+  };
+}
+
+function ensureDelegationTools(def) {
+  const specialists = def.agents?.specialists || [];
+  if (!specialists.length) return [];
+  const explicit = def.tools.explicit;
+  const added = DELEGATION_TOOLS.filter(t => !explicit.includes(t));
+  explicit.unshift(...added);
+  return added;
+}
+
+function fitBudgets(def) {
+  const b = def.budgets || (def.budgets = {});
+  const need = (def.tools.explicit || []).length;
+  if (!Number.isInteger(b.max_manifest) || b.max_manifest < need) b.max_manifest = Math.min(HARD_CAP, Math.max(32, need));
+  if (!Number.isInteger(b.initial_tool_target) || b.initial_tool_target < 1) b.initial_tool_target = Math.min(12, b.max_manifest);
+  if (b.initial_tool_target > b.max_manifest) b.initial_tool_target = b.max_manifest;
+}
+
+/**
+ * Restrictive = the hat AUTHORIZES only its members (+ the delegation pair); this binds every agent
+ * working under the hat, the hat's own agents included when delegated to. Permissive = the agent's
+ * own grant is the ceiling (the default). A deny list carried from --from is kept either way.
+ */
+export function applyMode(def, mode) {
+  if (mode === undefined || mode === null) return;
+  if (!HAT_MODES.includes(mode)) throw new Error(`--mode must be ${HAT_MODES.join(' or ')} (got '${mode}')`);
+  const deny = Array.isArray(def.authz?.deny) ? def.authz.deny : null;
+  if (mode === 'permissive') {
+    if (deny) def.authz = { mode: 'permissive', deny };
+    else delete def.authz;
+    return;
+  }
+  def.authz = { mode: 'restrictive', allow: [...new Set([...memberTools(def), ...DELEGATION_TOOLS])], ...(deny ? { deny } : {}) };
+}
+
+/**
+ * The definition a new custom hat starts from: a copy of --from (or an empty hat), with
+ * --agents / --tools REPLACING the lists, the delegation tools added when the hat lists agents,
+ * the offer set (default 'members': a custom hat offers its orchestrator only what it lists),
+ * and budgets widened to fit. Pure: never mutates base.
+ */
+export function buildCustomDefinition({ base = null, name = '', purpose, agents, tools, mode, offer } = {}) {
+  const def = base ? JSON.parse(JSON.stringify(base)) : emptyDefinition();
+  def.schema_version = 1;
+  def.agents = { orchestrator: 'quox', ...(def.agents || {}) };
+  if (!Array.isArray(def.agents.specialists)) def.agents.specialists = [];
+  def.tools = { ...(def.tools || {}) };
+  def.tools.explicit = Array.isArray(def.tools.explicit) ? [...def.tools.explicit] : [];
+  if (agents !== undefined) def.agents.specialists = [...agents];
+  if (tools !== undefined) def.tools.explicit = [...tools];
+  const autoAdded = ensureDelegationTools(def);
+  const o = offer === undefined ? 'members' : offer;
+  if (!HAT_OFFERS.includes(o)) throw new Error(`--offer must be ${HAT_OFFERS.join(' or ')} (got '${o}')`);
+  def.tools.offer = o;
+  if (purpose !== undefined && String(purpose).trim()) def.purpose = String(purpose).trim();
+  if (!def.purpose || base) {
+    if (purpose === undefined || !String(purpose).trim()) def.purpose = `${name || 'Custom'} work${def.agents.specialists.length ? ` with ${def.agents.specialists.join(', ')}` : ''}`;
+  }
+  fitBudgets(def);
+  applyMode(def, mode);
+  return { definition: def, autoAdded };
+}
+
+/**
+ * Apply `quox hat edit` options to a copy of a definition. Returns the new definition and a
+ * human list of changes (empty = nothing to do). --agents/--tools replace; --add-* / --remove-*
+ * adjust. A restrictive allow list follows tool adds/removes so the hat keeps authorizing exactly
+ * its members.
+ */
+export function applyHatEdits(current, opts = {}) {
+  const def = JSON.parse(JSON.stringify(current || {}));
+  def.agents = { orchestrator: 'quox', ...(def.agents || {}) };
+  def.tools = { ...(def.tools || {}) };
+  let specialists = Array.isArray(def.agents.specialists) ? [...def.agents.specialists] : [];
+  let explicit = Array.isArray(def.tools.explicit) ? [...def.tools.explicit] : [];
+  const changes = [];
+  const beforeAgents = [...specialists];
+  const beforeTools = new Set(memberTools(def));
+
+  if (opts.agents !== undefined) specialists = [...opts.agents];
+  for (const a of opts.addAgents || []) if (!specialists.includes(a)) specialists.push(a);
+  if ((opts.removeAgents || []).length) specialists = specialists.filter(a => !opts.removeAgents.includes(a));
+  if (opts.tools !== undefined) explicit = [...opts.tools];
+  for (const t of opts.addTools || []) if (!explicit.includes(t)) explicit.push(t);
+  if ((opts.removeTools || []).length) {
+    explicit = explicit.filter(t => !opts.removeTools.includes(t));
+    if (Array.isArray(def.tools.bundles)) def.tools.bundles = def.tools.bundles.map(b => ({ ...b, tools: (b.tools || []).filter(t => !opts.removeTools.includes(t)) }));
+  }
+  def.agents.specialists = specialists;
+  def.tools.explicit = explicit;
+  const autoAdded = (opts.removeTools || []).some(t => DELEGATION_TOOLS.includes(t)) ? [] : ensureDelegationTools(def);
+
+  const agentsAdded = specialists.filter(a => !beforeAgents.includes(a));
+  const agentsRemoved = beforeAgents.filter(a => !specialists.includes(a));
+  if (agentsAdded.length) changes.push(`agents +${agentsAdded.join(', +')}`);
+  if (agentsRemoved.length) changes.push(`agents -${agentsRemoved.join(', -')}`);
+  const afterTools = new Set(memberTools(def));
+  const toolsAdded = [...afterTools].filter(t => !beforeTools.has(t));
+  const toolsRemoved = [...beforeTools].filter(t => !afterTools.has(t));
+  if (toolsAdded.length) changes.push(`tools +${toolsAdded.join(', +')}`);
+  if (toolsRemoved.length) changes.push(`tools -${toolsRemoved.join(', -')}`);
+
+  if (opts.purpose !== undefined && String(opts.purpose).trim() && String(opts.purpose).trim() !== def.purpose) {
+    def.purpose = String(opts.purpose).trim();
+    changes.push('purpose');
+  }
+  if (opts.offer !== undefined) {
+    if (!HAT_OFFERS.includes(opts.offer)) throw new Error(`--offer must be ${HAT_OFFERS.join(' or ')} (got '${opts.offer}')`);
+    if ((def.tools.offer || 'authorized') !== opts.offer) { def.tools.offer = opts.offer; changes.push(`offer ${opts.offer}`); }
+  }
+  const prevMode = def.authz?.mode === 'restrictive' ? 'restrictive' : 'permissive';
+  if (opts.mode !== undefined) {
+    applyMode(def, opts.mode);
+    if (opts.mode !== prevMode) changes.push(`mode ${opts.mode}`);
+  } else if (prevMode === 'restrictive' && Array.isArray(def.authz?.allow) && (toolsAdded.length || toolsRemoved.length)) {
+    const allow = new Set(def.authz.allow);
+    for (const t of toolsAdded) allow.add(t);
+    for (const t of toolsRemoved) allow.delete(t);
+    def.authz = { ...def.authz, allow: [...allow] };
+  }
+  fitBudgets(def);
+  return { definition: def, changes, autoAdded };
+}
+

package/lib/core/doneEngineFetch.js

@@ -145,6 +145,14 @@ export async function fetchEngine({ dest, needsSudo, force, client, execFn, fsOp
   }
 
   const res = await client.get('/download/quoxgauge-bundle.tar.gz', { service: 'collector', raw: true });
+  // #988: a public install's collector has no DoneEngine bundle (dev servers build it from the private quox-gauge
+  // repo), so a 404 is a fact about this install, not a transient failure worth retrying.
+  if (res && res.status === 404) {
+    const err = new Error('DoneEngine is not part of this Quox install: this collector does not carry the DoneEngine bundle '
+      + '(it is delivered to Quox dev servers by `quox dev enable`). Nothing was changed.');
+    err.code = 'DONEENGINE_NOT_SHIPPED';
+    throw err;
+  }
   if (!res || !res.ok) {
     throw new Error(`Bundle download failed (status ${res ? res.status : 'no response'}) from /download/quoxgauge-bundle.tar.gz`);
   }