@integrity-labs/agt-cli 0.28.1110 → 0.28.1112

package/dist/mcp/index.js

@@ -18867,7 +18867,7 @@ var require_filters = __commonJS({
       return r.copySafeness(str, res);
     }
     _exports.indent = indent;
-    function join10(arr, del, attr) {
+    function join11(arr, del, attr) {
       del = del || "";
       if (attr) {
         arr = lib.map(arr, function(v) {
@@ -18876,7 +18876,7 @@ var require_filters = __commonJS({
       }
       return arr.join(del);
     }
-    _exports.join = join10;
+    _exports.join = join11;
     function last(arr) {
       return arr[arr.length - 1];
     }
@@ -30673,14 +30673,37 @@ var FLAG_REGISTRY = [
   },
   {
     key: "platform-maintenance-mode",
-    description: 'Platform-wide maintenance mode (ENG-6506): when on, every agent across every team/org auto-replies to admitted human inbound with a "we are offline for maintenance" notice instead of dispatching to the agent \u2014 for whole-platform downtime such as DB upgrades. Read host-side per inbound from the flags cache (no MCP restart). Boolean gate; ships dark \u2014 when off, channels behave exactly as today. (Proactive "back online" follow-up is the ENG-6508 fast-follow, not this flag.)',
-    flagType: "boolean",
-    // Declared safe value is `false` (normal operation). Fail-safe direction: a
-    // flag-DB read error or absent flag map must never silence the fleet on its
-    // own — agents stay responsive unless an operator deliberately flips this on
-    // from the admin Feature Flags page. No envVar: net-new control, no
-    // pre-flags env gate to migrate.
-    defaultValue: false,
+    description: 'Platform-wide maintenance mode (ENG-6506; widened to modes by ENG-11436). off = normal operation (ships dark; channels behave exactly as today). tools-offline = every agent KEEPS conversing but every Augmented tool that WRITES to the control plane refuses with a reason, so nothing is created during a window whose database restore would discard it; reads are untouched. fleet-offline = the previous boolean-true behaviour AND the write gate: admitted human inbound gets a "we are offline for maintenance" notice instead of being dispatched, for whole-platform downtime such as DB upgrades. The modes are CUMULATIVE \u2014 fleet-offline gates writes too, because silencing channel inbound does not stop a /loop or a scheduled task filing work. Read host-side per inbound and per tool call from the flags cache (no MCP restart). (Proactive "back online" follow-up is the ENG-6508 fast-follow, not this flag.)',
+    flagType: "enum",
+    allowedValues: ["off", "tools-offline", "fleet-offline"],
+    // Declared safe value is `off` (normal operation). Fail-safe direction: a
+    // flag-DB read error or absent flag map must never silence the fleet OR take
+    // its write tools away on its own — agents stay fully functional unless an
+    // operator deliberately sets a mode from the admin Feature Flags page. No
+    // envVar: net-new control, no pre-flags env gate to migrate.
+    //
+    // ENG-11436 widened this from a boolean rather than adding a second flag, so
+    // there is ONE operator control whose modes are mutually exclusive by type
+    // instead of two similar booleans with four combinations.
+    //
+    // The host resolver GRANDFATHERS a boolean-shaped cache value
+    // (true -> fleet-offline, false -> off), and the DIRECTION it protects is
+    // narrower than an earlier version of this comment claimed (Obi Wan
+    // `e3f0d2c154b9` on #6903). It said "an older manager still writing a boolean
+    // must not make a central flip a silent no-op". That situation cannot arise:
+    // once this registry change deploys, normalizeFlagValue only ever yields one
+    // of the three strings, feature-flags-host.ts writes the heartbeat map
+    // verbatim, so no manager writes a boolean again. What grandfathering
+    // actually covers is a NEW MCP reading a STALE PRE-DEPLOY cache that still
+    // holds one.
+    //
+    // The direction that DOES happen is not handled and cannot be: an OLD MCP
+    // reads the new string with resolveHostBooleanFlag, gets undefined, and keeps
+    // dispatching. That is a real regression against ENG-6506 until the fleet
+    // converges, and it is why the runbook makes convergence a deploy-order
+    // PRECONDITION rather than offering a boolean fallback — there is none, since
+    // an enum flag rejects `{value: true}` with a 400.
+    defaultValue: "off",
     // Flipping this takes the ENTIRE fleet offline to end users; a mis-flip is a
     // platform-wide availability incident, so mutations require explicit
     // confirmation (the admin flip-reach modal).
@@ -35564,8 +35587,8 @@ function renderKnowledgeBody(content) {
 }
 
 // src/index.ts
-import { homedir as homedir4 } from "os";
-import { basename, isAbsolute as isAbsolute2, join as join9, resolve as pathResolve, sep as sep2 } from "path";
+import { homedir as homedir5 } from "os";
+import { basename, isAbsolute as isAbsolute2, join as join10, resolve as pathResolve, sep as sep2 } from "path";
 
 // src/host-file-path.ts
 var SKILL_BODY_PATH_MAX_BYTES = 512 * 1024;
@@ -46089,6 +46112,192 @@ var StdioServerTransport = class {
   }
 };
 
+// src/flags-cache-read.ts
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join6 } from "path";
+function defaultFlagsCachePath() {
+  return join6(homedir2(), ".augmented", "flags-cache.json");
+}
+function envBoolean(raw) {
+  if (raw === void 0) return void 0;
+  const v = raw.trim().toLowerCase();
+  if (v === "") return void 0;
+  if (v === "1" || v === "true" || v === "yes" || v === "on") return true;
+  if (v === "0" || v === "false" || v === "no" || v === "off") return false;
+  return void 0;
+}
+var MAINTENANCE_FLAG_KEY = "platform-maintenance-mode";
+function parseMaintenanceMode(raw) {
+  if (raw === void 0) return void 0;
+  const v = raw.trim().toLowerCase();
+  if (v === "") return void 0;
+  if (v === "off" || v === "tools-offline" || v === "fleet-offline") return v;
+  const b = envBoolean(raw);
+  if (b === true) return "fleet-offline";
+  if (b === false) return "off";
+  return void 0;
+}
+function cachedMaintenanceMode(path) {
+  try {
+    if (!existsSync2(path)) return void 0;
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    if (!parsed || typeof parsed !== "object") return void 0;
+    const flags = parsed.flags;
+    if (!flags || typeof flags !== "object") return void 0;
+    const value = flags[MAINTENANCE_FLAG_KEY];
+    if (typeof value === "string") return parseMaintenanceMode(value);
+    if (typeof value === "boolean") return value ? "fleet-offline" : "off";
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function resolveMaintenanceMode(opts) {
+  const cached2 = cachedMaintenanceMode(opts?.cachePath ?? defaultFlagsCachePath());
+  if (cached2 !== void 0) return cached2;
+  return "off";
+}
+
+// src/maintenance-tools-offline.ts
+function isToolsOfflineActive(opts) {
+  const mode = resolveMaintenanceMode({ cachePath: opts?.cachePath, env: opts?.env });
+  return mode === "tools-offline" || mode === "fleet-offline";
+}
+var MAINTENANCE_GATED_TOOLS = /* @__PURE__ */ new Set([
+  // Tasks.
+  "kanban_add",
+  "kanban_update",
+  "kanban_move",
+  "kanban_done",
+  "kanban_reopen",
+  "kanban_assign",
+  "kanban_reassign",
+  "kanban_recall",
+  "kanban_respond",
+  "kanban_progress",
+  "kanban_log",
+  "kanban_assign_project",
+  "assign_kanban_to_human",
+  // Canvases. `dashboards_request_refresh` is gated because it enqueues
+  // server-side work, not because it renders anything itself.
+  "dashboards_upsert",
+  "dashboards_persist_widget",
+  "dashboards_request_refresh",
+  // ───────────────────────────────────────────────────────────────────────
+  // FORWARDED writes (ENG-11436 / CodeRabbit on #6903). These reach the agent
+  // through `registerForwardedApiTools()` -> `server.registerTool`, from
+  // `packages/api/src/routes/mcp-tools.ts`, with names resolved at RUNTIME. They
+  // are gated only because index.ts now wraps that method too; before that, this
+  // whole block would have been a list the gate could not see.
+  //
+  // CodeRabbit named five (workflow_update, workflow_run_{start,phase,end},
+  // memory_delete). Enumerating the surface to check them found 37 of the 50
+  // forwarded tools unclassified, so the five were a subset — these are all of
+  // the writes among them. The test now classifies that surface exhaustively, so
+  // the next addition fails CI rather than slipping through.
+  "composio_upload_file",
+  "memory_delete",
+  "memory_save",
+  "onboarding_advance",
+  "onboarding_provision_skills",
+  "onboarding_provision_tasks",
+  "onboarding_record_manager_contact",
+  "request_batch_approval",
+  "request_integration_access",
+  "skill_contribute_fragment",
+  "skill_create",
+  "skill_delete",
+  "skill_improve",
+  "skill_propose_revision",
+  "skill_publish_to_marketplace",
+  "skill_update",
+  "submit_performance_review",
+  "workflow_run_end",
+  "workflow_run_phase",
+  "workflow_run_start",
+  "workflow_update",
+  // CHANNEL-SERVER write (Obi Wan `b3537c1e8495` on #6903). Dispatched by NAME in
+  // slack-channel.ts / telegram-channel.ts / direct-chat-channel.ts, which are
+  // separate processes that never call server.tool — so this one is enforced by
+  // `refuseIfToolsOffline` at each dispatch point, not by the registration
+  // wrapper. It inserts a `pending_interaction` row, the same durable
+  // human-actionable record that gates request_buttons / request_form.
+  "channel_request_input",
+  // `slack.ask_user` is the SAME write under a dotted name, and it was missed
+  // because the test's enumerator could not see dotted names at all (Obi Wan
+  // `122ac55ff278` / `d7245eddd77f` on #6903). handleAskUser calls
+  // runtime.createPendingInteraction -> POST /host/pending-interactions ->
+  // inserts `pending_interaction`. Ungated, an agent on a /loop files the row,
+  // the restore discards it, and the agent blocks forever on a resolution that
+  // no longer exists — the exact failure the entry above is gated for.
+  //
+  // Verified it is the ONLY dotted channel tool that writes: createPendingInteraction
+  // is CALLED once in the three channel servers (slack-channel.ts:8053);
+  // slack-block-kit-runtime.ts only re-exports it.
+  "slack.ask_user",
+  // Workflows. FORWARDED, not local — it reaches the agent through
+  // `server.registerTool` in registerForwardedApiTools, so it is gated only
+  // because that method is now wrapped too (CodeRabbit on #6903).
+  "workflow_create",
+  // Knowledge.
+  "knowledge_add",
+  "knowledge_update",
+  "knowledge_delete",
+  // Projects and project tagging.
+  "projects_create",
+  "projects_update",
+  "artefacts_assign_project",
+  // Routines.
+  "routine_propose",
+  "routine_revise",
+  "routine_retire",
+  "submit_routine_output",
+  // Standing rules.
+  "rule_add",
+  "rule_remove",
+  // Scheduled work.
+  "schedule_create",
+  "schedule_update",
+  "schedule_delete",
+  // Requests that file a durable record a human is expected to act on. Filing
+  // one mid-window is worse than refusing it: the record is discarded by the
+  // restore, so the agent would have promised a human a follow-up that no
+  // longer exists anywhere.
+  "request_approval",
+  "request_buttons",
+  "request_channel_access",
+  "request_form",
+  "request_reconnect",
+  "request_feature",
+  "request_feature_withdraw",
+  // ADR-0025 approval tools, registered by `approval-tools.ts` against the same
+  // server object, so the wrapper in index.ts covers them too.
+  "cancel_approval",
+  // Status / identity.
+  "status_standup",
+  "status_update",
+  "update_identity",
+  "update_timezone",
+  // Fleet changes.
+  "recruit_agent",
+  "integration_improve"
+]);
+function toolsOfflineRefusalText(toolName) {
+  return `Ninjafy is in a control-plane maintenance window, so \`${toolName}\` is unavailable right now. Nothing was created, changed or saved. Do NOT retry this call, and do not try a different Ninjafy tool to work around it \u2014 every tool that writes to the control plane is refusing for the same reason, and the window is short. Tell the person plainly that you cannot save this at the moment and ask them to bring it back afterwards; carry on with anything that does not need saving.`;
+}
+function withMaintenanceGate(name, handler, opts) {
+  if (!MAINTENANCE_GATED_TOOLS.has(name)) return handler;
+  const isActive = opts?.isActive ?? (() => isToolsOfflineActive());
+  const gated = async (...args) => {
+    if (isActive()) {
+      return { content: [{ type: "text", text: toolsOfflineRefusalText(name) }] };
+    }
+    return handler(...args);
+  };
+  return gated;
+}
+
 // src/json-schema-to-zod-shape.ts
 function jsonSchemaToZodShape(schema) {
   if (!schema || schema["type"] !== "object") return {};
@@ -46838,12 +47047,12 @@ function selectIntegrationsToRefresh(input) {
 }
 
 // src/self-restart.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir2 } from "os";
-import { join as join6 } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { join as join7 } from "path";
 import { randomUUID } from "crypto";
 function restartFlagsDir() {
-  return join6(homedir2(), ".augmented", "restart-flags");
+  return join7(homedir3(), ".augmented", "restart-flags");
 }
 function isSelfRestartEnabled(env2) {
   const raw = (env2.AGT_AGENT_SELF_RESTART_ENABLED ?? "").trim().toLowerCase();
@@ -46854,8 +47063,8 @@ function buildAgentRestartFlag(codeName, reason, nowMs) {
 }
 function writeAgentRestartFlag(codeName, reason, nowMs) {
   const dir = restartFlagsDir();
-  if (!existsSync2(dir)) mkdirSync3(dir, { recursive: true });
-  const path = join6(dir, `${codeName}.flag`);
+  if (!existsSync3(dir)) mkdirSync3(dir, { recursive: true });
+  const path = join7(dir, `${codeName}.flag`);
   const flag = buildAgentRestartFlag(codeName, reason, nowMs);
   const tmpPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
   writeFileSync2(tmpPath, JSON.stringify(flag) + "\n", "utf8");
@@ -46864,18 +47073,18 @@ function writeAgentRestartFlag(codeName, reason, nowMs) {
 }
 
 // src/self-restart-confirm.ts
-import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync5 } from "fs";
-import { homedir as homedir3 } from "os";
-import { join as join7 } from "path";
+import { existsSync as existsSync5, readdirSync, readFileSync as readFileSync6 } from "fs";
+import { homedir as homedir4 } from "os";
+import { join as join8 } from "path";
 
 // src/restart-confirm.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync4, renameSync as renameSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync5, renameSync as renameSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3 } from "fs";
 import { dirname as dirname4 } from "path";
 import { randomUUID as randomUUID2 } from "crypto";
 var RESTART_CONFIRM_MAX_AGE_MS = 10 * 60 * 1e3;
 function writeRestartConfirmMarker(filePath, marker) {
   const dir = dirname4(filePath);
-  if (!existsSync3(dir)) mkdirSync4(dir, { recursive: true, mode: 448 });
+  if (!existsSync4(dir)) mkdirSync4(dir, { recursive: true, mode: 448 });
   const tmpPath = `${filePath}.${process.pid}.${randomUUID2()}.tmp`;
   writeFileSync3(tmpPath, JSON.stringify(marker) + "\n", { encoding: "utf8", mode: 384 });
   renameSync3(tmpPath, filePath);
@@ -46884,7 +47093,7 @@ function writeRestartConfirmMarker(filePath, marker) {
 // src/self-restart-confirm.ts
 var SELF_RESTART_PENDING_FRESHNESS_MS = 5 * 60 * 1e3;
 function selfRestartAgentDir(codeName) {
-  return join7(homedir3(), ".augmented", codeName);
+  return join8(homedir4(), ".augmented", codeName);
 }
 function selectFreshestPending(candidates, nowMs, maxAgeMs) {
   let best = null;
@@ -46897,7 +47106,7 @@ function selectFreshestPending(candidates, nowMs, maxAgeMs) {
   return best;
 }
 function readMarkerDir(dir, toCandidate) {
-  if (!existsSync4(dir)) return [];
+  if (!existsSync5(dir)) return [];
   const out = [];
   let entries;
   try {
@@ -46908,7 +47117,7 @@ function readMarkerDir(dir, toCandidate) {
   for (const entry of entries) {
     if (!entry.endsWith(".json") || entry.endsWith(".tmp")) continue;
     try {
-      const parsed = JSON.parse(readFileSync5(join7(dir, entry), "utf8"));
+      const parsed = JSON.parse(readFileSync6(join8(dir, entry), "utf8"));
       if (!parsed || typeof parsed !== "object") continue;
       const candidate = toCandidate(parsed);
       if (candidate) out.push(candidate);
@@ -46918,7 +47127,7 @@ function readMarkerDir(dir, toCandidate) {
   return out;
 }
 function readPendingCandidates(agentDir) {
-  const slack = readMarkerDir(join7(agentDir, "slack-pending-inbound"), (p2) => {
+  const slack = readMarkerDir(join8(agentDir, "slack-pending-inbound"), (p2) => {
     const channel = p2["channel"];
     if (typeof channel !== "string" || channel.length === 0) return null;
     const threadTs = p2["thread_ts"];
@@ -46926,7 +47135,7 @@ function readPendingCandidates(agentDir) {
     if (typeof threadTs === "string" && threadTs.length > 0) reply["thread_ts"] = threadTs;
     return { source: "slack", receivedAtMs: Date.parse(String(p2["received_at"])), reply };
   });
-  const telegram = readMarkerDir(join7(agentDir, "telegram-pending-inbound"), (p2) => {
+  const telegram = readMarkerDir(join8(agentDir, "telegram-pending-inbound"), (p2) => {
     const chatId = p2["chat_id"];
     if (chatId == null || typeof chatId !== "string" && typeof chatId !== "number") return null;
     const reply = { chat_id: chatId };
@@ -46947,17 +47156,17 @@ function captureSelfRestartConfirm(opts) {
     // human, so buildBackOnlineText degrades to the generic copy.
     reply: best.reply
   };
-  const file = best.source === "slack" ? join7(opts.agentDir, "slack-restart-confirm.json") : join7(opts.agentDir, "telegram-restart-confirm.json");
+  const file = best.source === "slack" ? join8(opts.agentDir, "slack-restart-confirm.json") : join8(opts.agentDir, "telegram-restart-confirm.json");
   writeRestartConfirmMarker(file, marker);
   return best.source;
 }
 
 // ../core/dist/integrations/forwarded-tools-report.js
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
-import { join as join8 } from "path";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { join as join9 } from "path";
 var FORWARDED_TOOLS_REPORT_FILENAME = "forwarded-tools.json";
 function forwardedToolsReportPath(agentDir) {
-  return join8(agentDir, FORWARDED_TOOLS_REPORT_FILENAME);
+  return join9(agentDir, FORWARDED_TOOLS_REPORT_FILENAME);
 }
 function writeForwardedToolsReport(agentDir, report) {
   try {
@@ -47972,6 +48181,26 @@ var server = new McpServer({
   name: "augmented",
   version: "0.1.0"
 });
+var wrapRegistration = (original) => (...args) => {
+  const name = args[0];
+  const handlerIndex = args.length - 1;
+  const handler = args[handlerIndex];
+  if (typeof name === "string" && typeof handler === "function") {
+    const rewritten = [...args];
+    rewritten[handlerIndex] = withMaintenanceGate(
+      name,
+      handler
+    );
+    return original(...rewritten);
+  }
+  return original(...args);
+};
+var registerToolUnwrapped = server.tool.bind(server);
+server.tool = wrapRegistration(registerToolUnwrapped);
+var registerToolV2Unwrapped = server.registerTool.bind(server);
+server.registerTool = wrapRegistration(
+  registerToolV2Unwrapped
+);
 if (AGT_AGENT_ID) {
   registerApprovalTools(server, { agentId: AGT_AGENT_ID, apiPost, apiGet });
 }
@@ -50906,9 +51135,9 @@ async function forwardToolCall(toolName, args) {
       // root to its canonical form so both sides of the comparison are real
       // paths. Falls back to the unresolved join if the dir is missing, which
       // then simply refuses (there is nothing to read anyway).
-      agentDir: canonicalAgentDir(join9(homedir4(), ".augmented", AGT_AGENT_CODE_NAME)),
+      agentDir: canonicalAgentDir(join10(homedir5(), ".augmented", AGT_AGENT_CODE_NAME)),
       // agent-dir-allow: immediately realpath-resolved to the ADR-0049 agent_id-keyed dir before use as a containment root
-      path: { isAbsolute: isAbsolute2, resolve: pathResolve, join: join9, sep: sep2 },
+      path: { isAbsolute: isAbsolute2, resolve: pathResolve, join: join10, sep: sep2 },
       // O_NOFOLLOW is the whole point of opening by flags: the path is already
       // symlink-resolved, so a symlink at the final component means it was
       // swapped after the check, and this turns that into an ELOOP.
@@ -51331,7 +51560,7 @@ async function saveArtefactSourceToFile(artefactId) {
     codeName: AGT_AGENT_CODE_NAME,
     turnInitiatorFile: process.env.AGT_TURN_INITIATOR_FILE,
     agentId: AGT_AGENT_ID,
-    homeDir: homedir4()
+    homeDir: homedir5()
   });
   const readOnce = async () => {
     const before = await fetchArtefactRevision(artefactId);
@@ -51346,7 +51575,7 @@ async function saveArtefactSourceToFile(artefactId) {
   };
   let result = await readOnce();
   if (result.revisionState !== "stable") result = await readOnce();
-  const filePath = join9(dir, safeDownloadName(`${artefactId}.html`, `${artefactId}.html`));
+  const filePath = join10(dir, safeDownloadName(`${artefactId}.html`, `${artefactId}.html`));
   await writeFile(filePath, result.html, "utf8");
   return {
     path: filePath,
@@ -51427,7 +51656,7 @@ async function exportArtefactToFile(dir, artefactId, format, item) {
     return { kind: "pending", jobId: outcome.jobId, retryAfterMs: outcome.retryAfterMs };
   }
   const fallback = `${artefactId}${item !== void 0 ? `-item-${item + 1}` : ""}.${format}`;
-  const filePath = join9(dir, safeDownloadName(outcome.body.filename, fallback));
+  const filePath = join10(dir, safeDownloadName(outcome.body.filename, fallback));
   const buf = Buffer.from(outcome.body.base64, "base64");
   await writeFile(filePath, buf);
   return {
@@ -51454,7 +51683,7 @@ async function downloadArtefactText(params) {
     codeName: AGT_AGENT_CODE_NAME,
     turnInitiatorFile: process.env.AGT_TURN_INITIATOR_FILE,
     agentId: AGT_AGENT_ID,
-    homeDir: homedir4()
+    homeDir: homedir5()
   });
   let items;
   let truncatedFrom = null;

package/dist/mcp/origami.js

@@ -44619,14 +44619,37 @@ var FLAG_REGISTRY = [
   },
   {
     key: "platform-maintenance-mode",
-    description: 'Platform-wide maintenance mode (ENG-6506): when on, every agent across every team/org auto-replies to admitted human inbound with a "we are offline for maintenance" notice instead of dispatching to the agent \u2014 for whole-platform downtime such as DB upgrades. Read host-side per inbound from the flags cache (no MCP restart). Boolean gate; ships dark \u2014 when off, channels behave exactly as today. (Proactive "back online" follow-up is the ENG-6508 fast-follow, not this flag.)',
-    flagType: "boolean",
-    // Declared safe value is `false` (normal operation). Fail-safe direction: a
-    // flag-DB read error or absent flag map must never silence the fleet on its
-    // own — agents stay responsive unless an operator deliberately flips this on
-    // from the admin Feature Flags page. No envVar: net-new control, no
-    // pre-flags env gate to migrate.
-    defaultValue: false,
+    description: 'Platform-wide maintenance mode (ENG-6506; widened to modes by ENG-11436). off = normal operation (ships dark; channels behave exactly as today). tools-offline = every agent KEEPS conversing but every Augmented tool that WRITES to the control plane refuses with a reason, so nothing is created during a window whose database restore would discard it; reads are untouched. fleet-offline = the previous boolean-true behaviour AND the write gate: admitted human inbound gets a "we are offline for maintenance" notice instead of being dispatched, for whole-platform downtime such as DB upgrades. The modes are CUMULATIVE \u2014 fleet-offline gates writes too, because silencing channel inbound does not stop a /loop or a scheduled task filing work. Read host-side per inbound and per tool call from the flags cache (no MCP restart). (Proactive "back online" follow-up is the ENG-6508 fast-follow, not this flag.)',
+    flagType: "enum",
+    allowedValues: ["off", "tools-offline", "fleet-offline"],
+    // Declared safe value is `off` (normal operation). Fail-safe direction: a
+    // flag-DB read error or absent flag map must never silence the fleet OR take
+    // its write tools away on its own — agents stay fully functional unless an
+    // operator deliberately sets a mode from the admin Feature Flags page. No
+    // envVar: net-new control, no pre-flags env gate to migrate.
+    //
+    // ENG-11436 widened this from a boolean rather than adding a second flag, so
+    // there is ONE operator control whose modes are mutually exclusive by type
+    // instead of two similar booleans with four combinations.
+    //
+    // The host resolver GRANDFATHERS a boolean-shaped cache value
+    // (true -> fleet-offline, false -> off), and the DIRECTION it protects is
+    // narrower than an earlier version of this comment claimed (Obi Wan
+    // `e3f0d2c154b9` on #6903). It said "an older manager still writing a boolean
+    // must not make a central flip a silent no-op". That situation cannot arise:
+    // once this registry change deploys, normalizeFlagValue only ever yields one
+    // of the three strings, feature-flags-host.ts writes the heartbeat map
+    // verbatim, so no manager writes a boolean again. What grandfathering
+    // actually covers is a NEW MCP reading a STALE PRE-DEPLOY cache that still
+    // holds one.
+    //
+    // The direction that DOES happen is not handled and cannot be: an OLD MCP
+    // reads the new string with resolveHostBooleanFlag, gets undefined, and keeps
+    // dispatching. That is a real regression against ENG-6506 until the fleet
+    // converges, and it is why the runbook makes convergence a deploy-order
+    // PRECONDITION rather than offering a boolean fallback — there is none, since
+    // an enum flag rejects `{value: true}` with a 400.
+    defaultValue: "off",
     // Flipping this takes the ENTIRE fleet offline to end users; a mis-flip is a
     // platform-wide availability incident, so mutations require explicit
     // confirmation (the admin flip-reach modal).